Mura Demystified: Mura JS

Mura JS is a Javascript Library similar in functionality to jQuery.

We developed Mura JS for several reasons. First, Mura CMS often lives in the midst of complex corporate IT infrastructures and legacy applications. In order to ease integration with these systems, we have to ensure that we don't add complexity to these systems by introducing things like 3rd-party Libraries that might not be compatible. As close to "vanilla" as we can make Mura CMS, the better it is for our clients.

Secondly, by building our own library we are able to introduce a bunch of Mura-specific functionality to the mix. Mura JS doesn't only offer a familiar set of DOM selectors and related tools, but also integrates things like a request endpoint (via the JSON API), iterators, user actions like logging in/out and more.

Installation

In case you haven't guessed it yet, another very powerful aspect of the Mura JS Library is it can be installed and used remotely! This makes functionality like single sign-on and remote reuse of content on different (or completely vanilla html) platforms very straight forward.

To install, reference your Mura CMS instance like so:

<script src="https://domain.com/core/vendor/mura.js/dist/mura.min.js"></script>

You can find further details on the integration on the Mura JS GitHub page, including packaging and usage in technology like AMD and Node.js.

How To

Here is a simple example of how you can call a custom Mura ORM object via Mura JS:

Mura
    .getEntity(entityname)
    .new()
    .then(
        //resolve
        function(entity) {
            // fun with the response
        },
        //reject
        function(entity) {
            // entity with errors
        }
);

 

Then: A Bit About Promises

If you have been following the latest JavaScript trends, you probably already know a bit about Promises. Promises are a way of simplifying the complexity of asynchronous requests, like requesting data from a remote source before an application can continue. A Promise involves passing a function that includes both resolve and reject arguments. When the remote/asynchronous action completes, it either calls the "resolve" function in a successful transaction, or reject when it fails.

Mura JS relies heavily on the use of Promises to insure that you can control the flow of your application synchronously even when asynchronous calls are involved. In the above example, we initiate the promise by calling ".then()" and pass it our two resolve/reject functions. These functions are not called until the remote, asynchronous request completes and it triggers one (and only one) of the passed resolve/reject functions.

The wonderful thing about this model is it allows you to chain requests in a synchronous fashion. For instance:

Mura
    .getEntity(entityname)
    .new()
    .then(
        //resolve
        function(entity) {
              entity.get('properties').then(
             //resolve
             function(properties) {
             
             },
             //reject...
        },
        //reject...
        
);

Example, Please

Lets look at a practical example:

<script src="https://www.getmura.com/core/vendor/mura.js/dist/mura.min.js"></script>

<script>
Mura.init(
  {
    siteid:'default',
    rootpath:'http://www.getmura.com'
  }
);

Mura(function(Mura){
  Mura.addEventHandler(
    {
      asyncObjectRendered:function(event){
        alert(this.innerHTML);
      }
    }
  );

  Mura.getEntity('content').loadBy('contentid','D3563327-BA21-CAA2-AC1E6AA4DEB1B41A')
    .then(
    // resolve
    function(item){
      console.log("The title of this blog is: " + item.get('title'));
      },
    //reject
    function(item) {
        console.log('there was an error');
    }
  );

});

</script>

If you open up your browser's console, you should see the title of this blog post there. Once you have installed the Mura JS package (GitHub), you should be able to run the above request (edited to match your domain) remotely, even from an html page!

That should be enough to get you exploring. In my next Demystifying Mura blog post, I'll be breaking out a few more practical examples of Mura JS in action.