Mura 10: Mura API

Mura ORM With Mura.js

Mura.js enables JavaScript developers to interact with Mura ORM, exposing access to its ORM Feed API, and allows for common CRUD (Create, Read, Update, and Delete) functionality.

Mura.js CRUD Functionality

Outlined below are code examples for performing basic CRUD operations on Mura ORM objects/entities via Mura.js. For developers who are primarily used to working with server-side languages, it may take a little time to adjust to working on the client side, because we need to "wait" until the object/entity is loaded in order to work with it. For this reason, it may be helpful to review how to work with JavaScript Promises.

Loading/Reading Mura ORM Objects/Entities

This example simply illustrates how to load a Mura ORM entity, using Mura.js.

<script>
var personid = 'some-uuid';

Mura.getEntity('person')
    .loadBy('personid', personid)
    .then(function(person) {
        console.log(person);
    })
    .catch(function(err) {
        console.log(err.get('errors'));
    });
</script>

Creating/Updating Mura ORM Objects/Entities

This example drives home how to segregate your Ajax calls using JS Promises, and avoid nesting or stacking your Mura.js methods.

<script>
var getPersonByID = function(personid) {
    return new Promise(function(resolve, reject) {
        Mura.getEntity('person').loadBy('personid', personid)
          .then(function(person) {
            resolve(person);
          })
          .catch(function(err) {
            reject(err);
            console.log(err.get('errors'));
          });
    });
};

var savePerson = function(person) {
    return new Promise(function(resolve, reject) {
        person.save()
            .then(function(result) {
                resolve(result);
            })
            .catch(function(err) {
                reject(err);
            });
    });
}

getPersonByID('some-uuid')
    .then(function(person) {
        person.set('namelast', 'Withington');
        return savePerson(person);
    })
    .then(function(result) {
        console.log(result);
    })
    .catch(function(err) {
        console.log(err);
    });
</script>

Deleting Mura ORM Objects/Entities

This is another example of how to segregate your Ajax calls using JS Promises to avoid nesting your Mura.js methods.

<script>
var getPersonByID = function(personid) {
    return new Promise(function(resolve, reject) {
        Mura.getEntity('person').loadBy('personid', personid)
          .then(function(person) {
            resolve(person);
          })
          .catch(function(err) {
            reject(err);
            console.log(err.get('errors'));
          });
    });
};

var deletePerson = function(person) {
    return new Promise(function(resolve, reject) {
        person.delete()
            .then(function(result) {
                resolve(result);
            })
            .catch(function(err) {
                reject(err);
            });
    });
}

getPersonByID('some-uuid')
    .then(function(person) {
        return deletePerson(person);
    })
    .then(function(result) {
        console.log(result);
    })
    .catch(function(err) {
        console.log(err);
    });
</script>

Mura.js Feed API

The following example illustrates how to obtain a feed of Mura ORM objects/entities, and then loop over the returned recordset. As you'll see, it's quite similar to using Mura's ORM Feed syntax.

var person;

Mura
  .getFeed('person')
  .where() //optional
  .prop('namelast')
  .isEQ('Levine')
  .orProp('namelast')
  .beginsWith('Withing')
  .getQuery()
  .then(function(people) {
    // handle success
    people.each(function(person, idx) {
      result = person.get('namefirst') + ' ' + person.get('namelast');
      console.log(result);
    });
  })
  .catch(function(err) {
    // handle error
    console.log(err);
  });

This example demonstrates how to use the aggregate method for a Mura.js Feed.
The example assumes a custom ORM object named "widget" exists, and has a property of "price".

var widget;

Mura
  .getFeed('widget')
  .aggregate('count', '*')
  .aggregate('sum', 'price')
  .aggregate('min', 'price')
  .aggregate('max', 'price')
  .aggregate('avg', 'price')
  .getQuery()
  .then(function(widgets) {
    // handle success
    console.log(widgets.getAll());
  })
  .catch(function(err) {
    // handle error
    console.log(err);
  });

See the "Key Methods" area of the Feed Bean section, for details on the Mura.js Feed API Methods.

Loading JavaScript and CSS Files With Mura.js

Mura.js allows JavaScript developers to load their JS and CSS files synchronously or asynchronously. This is especially useful for modules rendered via CFML.

Note: This is NOT recommend for modules rendered via JavaScript. See the Anatomy of a Module's Rendering Via JavaScript section for more information.

Mura.loader()

The Mura.loader() method is for JavaScript and CSS parallel loading with dependencies management. Using this method also prevents duplicate JavaScript and/or CSS files from being loaded.

There are two primary methods associated with Mura.loader(), loadjs() and loadcss() described below.

loadjs(url, cb)

loadcss(url, attrs, cb)

Examples

This example illustrates the basic syntax for loading a JavaScript file, with a desired callback function.

<script>
Mura(function(m) {
    m.loader()
        .loadjs(m.themepath + '/js/mylibrary.js', function() {/* callback */});
});
</script>

The example below illustrates loading some scripts in parallel with another batch of scripts being loaded in order. In the example below, the first loadjs() will be executed in parallel of the second loadjs(). However, in the second loadjs(), the myDependentLib.js file won't be loaded until myRequiredLib.js has finished loading. Then, when they've finished loading, the callback function will execute.

<script>
Mura(function(m) {
    m.loader()
        .loadjs(m.themepath + '/myLib.js')
        .loadjs(
          m.themepath + '/myRequiredLib.js', 
          m.themepath + '/myDependentLib.js', 
          function() {
            // callback
          });
});
</script>

The example below illustrates loading multiple CSS & JavaScript files, and includes a callback function that runs after the script files have all been loaded.

<script>
Mura(function(m) {
    m.loader()
        .loadcss(m.themepath + '/path/to/all.css', { media: 'all' })
        .loadcss(m.themepath + '/path/to/print.css', { media: 'print' })
        .loadjs(
            m.themepath + '/path/to/script1.js',
            m.themepath + '/path/to/script2.js',
            function() {
                // Now do something with the loaded JS
            });
});
</script>

Modules With Mura.js

As introduced in the Anatomy of a Module section, developers may choose to render their modules using purely JavaScript. When doing so, the module's index.cfm file should only contain the following line of code, which informs Mura it has nothing to render via server-side processing, and all rendering will occur via the "client" or browser.

<cfset objectparams.render="client">

Then, in order to load your script(s), you'll need to use a custom event handler, and register the onRenderStart event to dynamically load your script file(s), as illustrated below.

// ../yourmodule/model/handlers/yourhandler.cfc

component extends='mura.cfobject' {

  function onRenderStart(m) {
    // if script should be included in the <head>
    arguments.m.addToHTMLHeadQueue('<script src="/path/to/script.js"></script>');

    // OR

    // if script should be included before closing </body> tag
    arguments.m.addToHTMLFootQueue('<script src="/path/to/script.js"></script>');
  }

}

By using addToHTMLHeadQueue and/or addToHTMLFootQueue, your scripts will only be loaded once, regardless of how many times your module has been applied to the layout.

The Custom JavaScript File

Assuming you've followed the instructions above to get your custom script file included into either the "head" portion of your theme, or before the closing "body" tag, you will most likely want to control when your script(s) are executed. However, you may also simply allow your scripts to run at all times.

Running Scripts on Every Request

If you merely wish for your script(s) to execute, regardless of whether or not your module has been applied to the layout, then you may simply include any JavaScript you wish. In other words, since your script files are being added on every request via your custom event handler's onRenderStart method, your scripts will automatically execute. This is useful for merely adding a utility script, such as a tracking script, etc.

The content of your script file may look as simple as the following example.

// your-script.js
console.log('Hello from your module!');

Running Scripts Only If Your Module Has Been Applied

Unless your scripts are utilities, such as tracking scripts, developers will most often wish their scripts to execute only when the module has been applied to the layout. In addition, when the module includes a configurator, each instance of the module will have access to its own configuration information.

First, it's important to understand that modules rendered via the client, are automatically registered to Mura's namespace under Mura.Module.YourModuleDirectoryName. Also, Mura will automatically invoke a "renderClient" method via Mura.UI, on each request. By defining your own "renderClient" method, you're able to pretty much do whatever you want.

The example below illustrates a skeleton script. You should substitute "yourModuleDirectoryName" with the actual directory name of your display object.

// your-script.js
Mura.Module.YourModuleDirectoryName = Mura.UI.extend({
  renderClient: function() {
    // Your code goes here ...
    return this;
  }
});

You can also defined a "renderServer" method if defined will be used in universal node js frameworks like NextJS and NuxtJS

// your-script.js
Mura.Module.YourModuleDirectoryName = Mura.UI.extend({
	    renderClient: function() {
	        // Your code goes here ...
	        return this;
	    },

	   renderServer: function() {
	        // Your code goes here ...
	        return this;
	    }
	});

this.context

When using JavaScript to render a Mura "Module" via the client, developers are most interested in two (2) primary pieces of information:

1. How to target the container element of where the module has been applied to the layout.
2. How to access "objectparams", or the data collected via a configurator.

You can easily access either of these by using "this.context" in your custom script.

• this.context.targetEl
  • Use this to target the container element of where the module has been applied to the layout. Keep in mind, each instance of the module in the layout will have its own, unique container element.
• this.context.{yourObjectParam}
  • Use this to access any "objectparams", or data collected via a configurator. Each instance of the module will have access to its own, unique configuration data.

The example below illustrates how to use the above information, and may be used as a starter file in your own projects.

// your-script.js
Mura.Module.YourModuleDirectoryName = Mura.UI.extend({

  renderClient: function() {
    // reference to the container element
    this.container = Mura(this.context.targetEl);
    
    // assuming you have an objectparam named 'mytext'
    var txt = this.context.mytext || 'mytext is empty';

    // Having fun by replacing the content of the container
    // Remember, using Mura.js, we can do jQuery-esque DOM manipulation
    this.container.html('<h3>Hello from yourDisplayObject</h3>');
    this.container.append('<h4>' + txt + '</h4>');

    // The rest of your code goes here ...
    return this;
  }

});

If you're interested in seeing what else is available via Mura.UI, feel free to review the code found at https://github.com/blueriver/MuraJS/blob/master/src/core/ui.js.

To see an example of how to use Mura.js along with Mura ORM, Grunt, and Handlebars, visit https://github.com/stevewithington/muracontacts/tree/js.

Forms & Mura.js

Mura forms are loaded asynchronously. So, if you wish to run some scripts, you need to use a special method to "reopen" the form, and then add your scripts. This can be done by leveraging a special Mura.js method: Mura.DisplayObject.Form.reopen({});.

Once the form has been "reopened," simply leverage one or more of the predefined events from the code example below to inject any custom logic.

NOTE: If not using deferred Mura.js then you do not need to reopen the display object classes within a Mura.preInit() method. The option to defer the loading of Mura.js is controlled by the this.deferMuraJS theme value in the contentRenderer.cfc file.

Mura.preInit(function(m) {

	Mura.DisplayObject.Form.reopen({
		// triggered after the form has rendered on the browser
		onAfterRender: function() {
			var form_container = this.context.targetEl
				, the_form = m(form_container).find('form');

			console.log('afterRender triggered');

			// This is where you register your custom form listeners, 
                        // for example ...
			m('button.form-submit').on('click', function(event) {
				console.log('Form button clicked!')
				console.log(event.target.form);
			});
		}

		// triggered when the form has been submitted, 
                // before processing/validation begins
		, onSubmit: function () {
			var the_button = event.target
				, the_form = the_button.form;

			console.log('onSubmit triggered');
			console.log(the_button);
			console.log(the_form);

			// you could run a script here (obviously) ... then,
			// return true if you want to continue, 
                        // or false if you wish to stop processing
			return true;
		}

		// triggered after submit, and form has errors
		, onAfterErrorRender: function() {
			var resp = JSON.parse(event.currentTarget.response)
				, errors = resp.data.errors;

			console.log('afterErrorRender triggered');
			console.log(errors);
		}

		// triggered after successful form submit (no errors)
		, onAfterResponseRender: function () {
			var response_container = this.context.targetEl;

			console.log('afterResponseRender triggered');
			console.log(response_container);
		}
	});

});

FindCalendarItems

Get calendar content items.

Endpoint

GET https://yourdomain.com/{context}/index.cfm/_api/json/v1/?method=findcalendaritems&siteid={siteid}&calendarid={calendarid}&start={start}&end={end}&format={format}

Request & Query Parameters

Example "Default" Response

If multiple entities are found, an items array will be present in the data object.

{
	"data": {
    	"items": [
			{
				"contentid": "2C91A3B0-E375-9383-0B05636E6926868D",
				"title": "Event 1",
				...
			},
			{
				"contentid": "6C92F953-E042-CBF6-42F66BD74A4BEC0B",
				"title": "Event 2",
				...
			},
			...
		]
	}
}

If only one entity is found, the data object will contain the entity's keys and corresponding values.

{
	"data": {
		"contentid": "2C91A3B0-E375-9383-0B05636E6926868D",
		"title": "Event 1",
		...
	}
}

Example "FullCalendar" Response

An events array will be returned.

{
	"events": [
		{
			"contentid": "2C91A3B0-E375-9383-0B05636E6926868D",
			"title": "Event 1",
			...
		},
		{
			"contentid": "6C92F953-E042-CBF6-42F66BD74A4BEC0B",
			"title": "Event 2",
			...
		},
		...
	]
}

FindMany

Get multiple entities.

Endpoint

GET https://yourdomain.com/{context}/index.cfm/_api/json/v1/{siteid}/{entityname}/{ids}

OR

GET https://yourdomain.com/{context}/index.cfm/_api/json/v1/?method=findmany&siteid={siteid}&entityname={entityname}&ids={ids}

Request & Query Parameters

Example Response

If multiple entities are found, an items array will be present in the data object.

{
	"data": {
		"items": [
			{
				"id": "2C91A3B0-E375-9383-0B05636E6926868D",
				"name": "Example",
				"links": {
					"relatedentitylink1": "http://...",
					"relatedentitylink2": "http://..."
				}
			},
			{
				"id": "6C92F953-E042-CBF6-42F66BD74A4BEC0B",
				"name": "Another Example",
				"links": {
					"relatedentitylink1": "http://...",
					"relatedentitylink2": "http://..."
				}
			},

		]
	}
}

If only one entity is found, the data object will contain the entity's keys and corresponding values.

{
	"data": {
		"id": "2C91A3B0-E375-9383-0B05636E6926868D",
		"name": "Example",
		"links": {
			"relatedentitylink1": "http://...",
			"relatedentitylink2": "http://..."
		}
	}
}

FindNew

Gets a new entity.

Endpoint

GET https://yourdomain.com/{context}/index.cfm/_api/json/v1/{siteid}/{entityname}/new

OR

GET https://yourdomain.com/{context}/index.cfm/_api/json/v1/?method=findnew&siteid={siteid}&entityname={entityname}

Request & Query Parameters

Example Response

{
	"data": {
		"id": "2C91A3B0-E375-9383-0B05636E6926868D",
		"name": "Example",
		"links": {
			"relatedentitylink1": "http://...",
			"relatedentitylink2": "http://..."
		}
	}
}

FindOne

Find an entity.

Endpoint

GET https://yourdomain.com/{context}/index.cfm/_api/json/v1/{siteid}/{entityname}/{id}

OR

GET https://yourdomain.com/{context}/index.cfm/_api/json/v1/?method=findone&site={siteid}&entityname={entityName}&id={id}

Request & Query Parameters

Example Response

The data object will contain the entity's keys and corresponding values.

{
  "data": {
    "targetparams":"",
    "path":"00000000000000000000000000000000001,2C91A3B0-E375-9383-0B05636E6926868D",
    "menutitle":"Testing",
    "releaseDate":"",
    "fileid":"",
    "responsesendto":"",
    "id":"2C91A3B0-E375-9383-0B05636E6926868D",
    "type":"Page",
    "lastupdatebyid":"AD771D5C-BE0A-D43D-47F4E201B378BD7A",
    "forceSSL":0,
    "responsemessage":"",
    "subtype":"Default",
    "remoteurl":"",
    "contenttype":"",
    "childtemplate":"",
    "keypoints":"",
    "moduleid":"00000000000000000000000000000000000",
    "inheritobjects":"Inherit",
    "searchExclude":0,
    "featureStop":"",
    "newfile":"",
    "remotesourceurl":"",
    "displayStop":"",
    "remotesource":"",
    "remotePubDate":"",
    "tags":"",
    "majorVersion":0,
    "extendautocomplete":true,
    "contentsubtype":"",
    "url":"/index.cfm/testing/",
    "sortby":"orderno",
    "displayTitle":0,
    "approvalstatus":"",
    "credits":"",
    "oldfilename":"",
    "featureStart":"",
    "siteid":"default",
    "doCache":1,
    "imagesize":"small",
    "imagewidth":"AUTO",
    "target":"_self",
    "minorVersion":0,
    "approvalgroupid":"",
    "assocfilename":"",
    "lastUpdate":"2015-01-29T15:45:51",
    "summary":"",
    "images":{},
    "template":"",
    "moduleassign":"",
    "displayStart":"",
    "isFeature":0,
    "filesize":"",
    "approvingchainrequest":false,
    "categoryid":"",
    "tcontent_id":"0",
    "isLocked":0,
    "isNav":1,
    "newstags":"",
    "orderno":1,
    "htmltitle":"Testing",
    "urltitle":"testing",
    "approvalchainoverride":false,
    "body":"",
    "requestid":"",
    "restrictgroups":"",
    "active":1,
    "metadesc":"",
    "audience":"",
    "links":{
      "site":"http://docs.getmura.com:8080/index.cfm/_api/json/v1/default?method=findOne&entityName=site&siteid=default",
      "categoryassignments":"http://cf11:8080/index.cfm/_api/json/v1/default?method=findQuery&siteid=default&entityName=contentCategoryAssign&contenthistid=2C92F953-E042-CBF6-42F66BD74A4BEC0B",
      "parent":"http://docs.getmura.com:8080/index.cfm/_api/json/v1/default?method=findOne&siteid=default&entityName=content&id=00000000000000000000000000000000001",
      "stats":"http://docs.getmura.com:8080/index.cfm/_api/json/v1/default?method=findOne&siteid=default&entityName=stats&id=2C91A3B0-E375-9383-0B05636E6926868D",
      "crumbs":"http://docs.getmura.com:8080/index.cfm/_api/json/v1/default?method=findCrumbArray&siteid=default&entityName=content&id=2C91A3B0-E375-9383-0B05636E6926868D",
      "comments":"http://docs.getmura.com:8080/index.cfm/_api/json/v1/default?method=findQuery&siteid=default&entityName=comment&contentid=2C91A3B0-E375-9383-0B05636E6926868D",
      "relatedcontent":"http://docs.getmura.com:8080/index.cfm/_api/json/v1/default?method=findRelatedContent&siteid=default&id=2C91A3B0-E375-9383-0B05636E6926868D",
      "renderered":"http://docs.getmura.com:8080/index.cfm/_api/json/v1/v10/_path/testing",
      "kids":"http://cf11:8080/index.cfm/_api/json/v1/default?method=findQuery&siteid=default&entityName=content&parentid=2C91A3B0-E375-9383-0B05636E6926868D"
    },
    "restricted":0,
    "metakeywords":"",
    "nextN":10,
    "fileext":"",
    "notes":"",
    "display":1,
    "created":"2015-01-29T15:45:51",
    "contenthistid":"2C92F953-E042-CBF6-42F66BD74A4BEC0B",
    "responsedisplayfields":"",
    "expires":"",
    "imageheight":"AUTO",
    "filename":"testing",
    "relatedcontentsetdata":"",
    "sortdirection":"asc",
    "contentid":"2C91A3B0-E375-9383-0B05636E6926868D",
    "changesetid":"",
    "displayinterval":"Daily",
    "sourceiterator":"",
    "mobileExclude":0,
    "extendsetid":"",
    "remoteid":"",
    "parentid":"00000000000000000000000000000000001",
    "preserveid":"2C92F953-E042-CBF6-42F66BD74A4BEC0B",
    "title":"Testing",
    "lastupdateby":"Steve Withington",
    "approved":1,
    "extenddata":"",
    "blogtags":"",
    "responseChart":0
  }
}

FindQuery

Get an array of entity items.

Endpoint

GET https://yourdomain.com/{context}/index.cfm/_api/json/v1/{siteid}/{entityname}/?

OR

GET https://yourdomain.com/{context}/index.cfm/_api/json/v1/?method=findquery&siteid={siteid}&entityname={entityname}/?

Request & Query Parameters

Custom Query Parameters

Filter results by passing an attribute name of your entity, and the value to search for. Use the star (*) to denote wildcard.

The following example assumes the entity has an attribute named title:

GET https://yourdomain.com/{context}/index.cfm/_api/json/v1/?method=findquery&siteid={siteid}&entityname={entityname}&title=about*

This should return any entities with a title attribute that starts with about, such as "about, About, About Us, About Time."

Example Response

If one or more entities are found, an items array will be present in the data object.

{
	"data": {
		"endindex": 1,
		"startindex": 1,
		"totalpages": 1,
		"totalitems": 1,
		"links": {
			"self": "http://domain/index.cfm/_api/json/v1/v10/?&sort=title&entityname=content&siteid=default&fields=title,summary,contentid&itemsperpage=10&maxitems=50&method=undefined&pageIndex=1"
		},
		"itemsperpage": 10,
		"items": [
			{
				"entityname": "content",
				"images": {},
				"contentid": "00000000000000000000000000000000001",
				"siteid": "default",
				"url": "/",
				"links": {
					"renderered": "http://domain/index.cfm/_api/json/v1/v10/_path/",
					"categoryassignments": "http://domain/index.cfm/_api/json/v1/default?method=findQuery&siteid=default&entityName=contentCategoryAssign&contenthistid=14CA1DCF-41A8-4D04-861AFE9D4162CD7C",
					"relatedcontent": "http://domain/index.cfm/_api/json/v1/default?method=findRelatedContent&siteid=default&entityName=content&id=00000000000000000000000000000000001",
					"crumbs": "http://domain/index.cfm/_api/json/v1/default?method=findCrumbArray&siteid=default&entityName=content&id=00000000000000000000000000000000001",
					"stats": "http://domain/index.cfm/_api/json/v1/default?method=findOne&siteid=default&entityName=stats&id=00000000000000000000000000000000001",
					"self": "http://domain/index.cfm/_api/json/v1/v10/_path/",
					"comments": "http://domain/index.cfm/_api/json/v1/default?method=findQuery&siteid=default&entityName=comment&contentid=00000000000000000000000000000000001",
					"site": "http://domain/index.cfm/_api/json/v1/default?method=findOne&entityName=site&siteid=default",
					"parent": "http://domain/index.cfm/_api/json/v1/default?method=findOne&siteid=default&entityName=content&id=00000000000000000000000000000000END",
					"kids": "http://domain/index.cfm/_api/json/v1/default?method=findQuery&siteid=default&entityName=content&parentid=00000000000000000000000000000000001"
				},
				"id": "00000000000000000000000000000000001",
				"title": "Home",
				"summary": ""
			}
		],
		"pageindex": 1
	},
	
	"method": "findQuery",
	"apiversion": "v1"
}

FindRelatedEntity

Gets a related entity.

Endpoint

GET https://yourdomain.com/{context}/index.cfm/_api/json/v1/{siteid}/{entityname}/{id}/{relatedentity}/?

OR

GET https://yourdomain.com/{context}/index.cfm/_api/json/v1/?method=findquery&siteid={siteid}&entityname={relatedentity}&entitynamefk={id}

Request & Query Parameters

Example Response

If multiple entities are found, an items array will be present in the data object.

{
	"data": {
		"items": [
			{
				"id": "2C91A3B0-E375-9383-0B05636E6926868D",
				"name": "Example",
				"links": {
					"relatedentitylink1": "http://...",
					"relatedentitylink2": "http://..."
				}
			},
			{
				"id": "6C92F953-E042-CBF6-42F66BD74A4BEC0B",
				"name": "Another Example",
				"links": {
					"relatedentitylink1": "http://...",
					"relatedentitylink2": "http://..."
				}
			},

		]
	}
}

If only one entity is found, the data object will contain the entity's keys and corresponding values.

{
	"data": {
		"id": "2C91A3B0-E375-9383-0B05636E6926868D",
		"name": "Example",
		"links": {
			"relatedentitylink1": "http://...",
			"relatedentitylink2": "http://..."
		}
	}
}

GenerateCSRFTokens

Get a CSRF (Cross-Site Request Forgery) token. The CSRF token is required for special API methods such as delete and save.

Endpoint

GET https://yourdomain.com/{context}/index.cfm/_api/json/v1/?method=generateCSRFTokens&siteid={siteid}&context={entityid}

Request & Query Parameters

Example Response

{
	"data": {
		"csrf_token": "469153A8855FFA7ECB5A11BC8EB3F3C4",
		"csrf_token_expires": "42041.6270023"
	}
}

Register Custom API Method

This is an example of how to register a custom JSON API method:

<cfscript>
var APIUtility = getBean('settingsManager').getSite({siteid}).getAPI('json', 'v1');
APIUtility.registerMethod(methodName='applyProperty', method=applyProperty);

public any function applyProperty() {
  // do something
}
</cfscript>

Register Custom API Linking Method

Within the API, all entities contain a "link" attribute that contains HREFs to access related entities. For example, a content entity would have a a value set to access the content children with entity.link.kids. By default, Mura will read through the entity's properties and auto populate its links for you. However, sometimes you will want to add custom link logic.

<cfscript>
var APIUtility=getBean('settingsManager').getSite({siteid}).getApi('json','v1');
APIUtility.registerLinkMethod(method=myCustomLinkMethod);

public any function myCustomLinkMethod(entity,links){
  if ( entity.getEntityName()=='targetEntity' ) {
    arguments.links['runs']='#getEndPoint()#?method=myCustomMethod&siteid=#arguments.entity.getValue('siteid')#';
  } 
}
</cfscript>

Creating API methods with Module Beans

You can create components within a module's {moduleDir}/model/beans directory that extend eithermura.bean.bean or mura.bean.beanORM. Within these components any method set to remote access with be availabe via the JSON/REST API.

component extends="mura.bean.bean" {

    remote function mymethod(){
        return "Hello!";
    }
}

You can then call the method like this https://www.domain.com/index.cfm/_api/json/v1/{siteid}/{beanName}/{methodName} .

Register Custom Mura ORM Entity

This is an example of how to register a custom Mura ORM entity:

<cfscript>
var APIUtility = getBean('settingsManager').getSite({siteid}).getAPI('json', 'v1');
APIUtility.registerEntity(entityName='myCustomEntity', config={});
</cfscript>

Mura ORM Entity Config Options

Example Mura ORM Entity Config

<cfscript>
myConfig = {
  fields = 'domain,siteid',
  allowfieldselect = false
};

var APIUtility = getBean('settingsManager').getSite({siteid}).getAPI('json', 'v1');
APIUtility.registerEntity(entityName='myCustomEntity', config=myConfig);
</cfscript>

Creating Mura ORM Entities from within Modules

You can create components within a module's {moduleDir}/model/beans directory that extend mura.bean.beanORM. Then do a manual application reload with the ?applydbupdates url variable.

component
	extends="mura.bean.beanORM"
	entityname="widget"
	displayname="Widget"
	table="widget"
	orderby="name"
	bundleable=false
	scaffold=true
	public=false
	{
		property name="widgetid" fieldtype="id";
		property name="siteid" default="default" required=true datatype="varchar" length="25";
		property name="name" required=true datatype="varchar";
		property name="description" datatype="text";
}

You can then call the it's endpoint like this https://www.domain.com/index.cfm/_api/json/v1/{siteid}/{beanName} . (Learn more about Mura ORM)

Save

Save an entity.

Endpoint

POST https://yourdomain.com/{context}/index.cfm/_api/json/v1/{siteid}/{entityname}/?csrf_token={csrf_token}&csrf_token_expires={csrf_token_expires}

OR

POST https://yourdomain.com/{context}/index.cfm/_api/json/v1/?method=save&siteid={siteid}&entityname={entityname}&csrf_token={csrf_token}&csrf_token_expires={csrf_token_expires}

Request & Query Parameters

Example Response

The data object will contain the entity's keys and corresponding values.

{
	"data": {
		"id": "2C91A3B0-E375-9383-0B05636E6926868D",
		"name": "Example",
		"links": {
			"relatedentitylink1": "http://...",
			"relatedentitylink2": "http://..."
		}
	}
}

Delete

Delete an entity.

Endpoint

DELETE https://yourdomain.com/{context}/index.cfm/_api/json/v1/{siteid}/{entityname}/{id}/?csrf_token={csrf_token}&csrf_token_expires={csrf_token_expires}

OR

DELETE https://yourdomain.com/{context}/index.cfm/_api/json/v1/?method=delete&siteid={siteid}&entityname={entityname}&id={id}&csrf_token={csrf_token}&csrf_token_expires={csrf_token_expires}

Request & Query Parameters

Example Response

The data element will be an empty string.

{
  "data": ""
}

Login

Login a user.

Endpoint

POST https://yourdomain.com/{context}/index.cfm/_api/json/v1/{siteid}/login/?username={username}&password={password}

OR

POST https://yourdomain.com/{context}/index.cfm/_api/json/v1/?method=login&siteid={siteid}&username={username}&password={password}

Request & Query Parameters

Example Response

{
  "data": {
	"status": "success"
  }
}

data object

Logout

Logout the current user.

Endpoint

POST https://yourdomain.com/{context}/index.cfm/_api/json/v1/{siteid}/logout

OR

POST https://yourdomain.com/{context}/index.cfm/_api/json/v1/?method=logout&siteid={siteid}

Request & Query Parameters

Example Response

{
  "data": {
    "status": "succes"
  }
}

data object

Vanilla JavaScript

The MuraDecoupled GitHub project is an example of building a Mura Decoupled website using standard JavaScript and Mura JS. The project is a Docker repository, so you will need that installed on your computer. This will allow you to quickly spin up the example and begin exploring a vanilla Mura / Javascript  integration.

Initial Setup

You will need a couple of items installed on your test machine. The latest version of Node, as well as Docker.

Next you will need the project itself. You should download MuraDecoupled to a working directory (i.e. a directory where the code can be deployed).

Next you need to start Mura up:

git clone https://github.com/murasoftware/mura-decoupled.git
cd mura-decoupled
git checkout master
docker-compose up

Then go to http://localhost:8888 to initialize Mura's install. You can login with the default (admin/admin) and edit the default site's settings:

• Domain= The domain of the remote site that the the content will be served on. (localhost)
• Is Remote = true
• Remote Context = The directory structure off of the remote site's web root that the site lives (Leave Empty)
• Remote Port = The port of the remote site (80)
• Resource Domain = The domain that Mura will use the access resource like css and js scripts that are dynamically loaded. (localhost)

You can now visit the site at http://localhost

And finally go to your Mura admin (http://localhost:8888/admin) and reload Mura one more to and it will see the mura.config.json from the ./app directory.

For the rest of the details on this project, you can view the ReadMe file on the MuraDecoupled project itself.

Key Project Files

There are several key project files you will want to examine and/or modify while exploring this example project.

let currentContent;

Mura.preInit(function(){

   // your init code here

}

Mura.Module.Examplejs = Mura.UI.extend({
    renderClient: function() {
        this.context.mytitle = this.context.mytitle || "The 'Title' param has not been assigned";
        this.context.targetEl.innerHTML=`<h2>${Mura.escapeHTML(this.context.mytitle)}</h2>`;
        return this;
    }
});

Mura.Module.Header = Mura.UI.extend({
   //...
});

const crumbCollection=await currentContent
    .get('crumbs')
    .then((crumbs)=>{
        return crumbs;
    });

Mura.Module.Examplecollectionlayout = Mura.UI.extend({
   renderClient: function() {
// ... rendering code here
   }

});

Mura(function(){

});

const templates={
    default:`
        <nav id="primary-nav">
            <ul class="mura-primary-nav"></ul>
        </nav>
        <div class="mura-region-container" data-region="primarycontent"></div>
        <footer>
            <!-- Create a component named "Footer" and it will render here-->
            <div class="mura-object" data-object="component" data-objectid="footer"></div>
        </footer>
        <div class="mura-html-queues"></div>
        `
 };

<footer>
   <!-- Create a component named "Footer" and it will render here-->
   <div class="mura-object" data-object="component" data-objectid="footer"></div>
</footer>

let hash= location.hash || '#';

let query=Mura.getQueryStringParams();

Mura.renderFilename(
    hash.split('#')[1],
    Mura.extend(Mura.getQueryStringParams(),{expand:"crumbs"})
).then(function(content){

  currentContent=content;

});

{
    "global":{
        "rendererProperties":{
            "templateArray":["Default"],
            "collectionLayoutArray":["Examplecollectionlayout"],
            "hashurls":true,
            "primaryContentTypes":"Page,Link,File",
            "spacingoptions":[
                {"name":"Tight","value":"tight"},
                {"name":"Normal","value":"normal"},
                {"name":"Loose","value":"loose"}
            ],
            "modulethemeoptions":[
                {"name":"Brand Default","value":"module-brand"} // ...
            ],
            "coloroptions":[
                {"name":"White","value":"#ffffff"} // ...
            ],
            "ckeditor":{
                "contentcss":"http://localhost/app/css/editor.css",
                "templates":"",
                "stylesset":"",
                "customconfig":""
            }
        },
        "modules":{
            "Examplejs":{
                "name":"Examplejs",
                "contenttypes":"*",
                "configurator":[
                    {"type":"text","name":"mytitle","label":"My Label"}
                ]
             },
            "Examplecollectionlayout":{
                "name":"Example Collection Layout",
                "contenttypes":""
            },
            "Header":{
                "name":"Header",
                "contenttypes":"*"
            }
        },
        "entities":{
        },
    "sites":{
        "default":{
            "rendererProperties":{
            },
            "modules":{

            }
        }
    }
  }
}

Angular

The MuraAngularDecoupled GitHub project is an example of building a Mura Decoupled website using Angular as your JS framework. The project is a Docker repository, so you will need that installed on your computer. This will allow you to quickly spin up the example and begin exploring the Mura JS / Angular integration.

The latest up-to-date instructions are provided with the repository.

React & NextJS

The MuraNextJSDecoupled GitHub project is an example of building a Mura Decoupled website using the React framework NextJS as your JS framework. The project is a Docker repository, so you will need that installed on your computer. This will allow you to quickly spin up the example and begin exploring the Mura JS / React - NextJS integration.

The latest up-to-date instructions are provided with the repository.

Vue & NuxtJS

The MuraNuxtJSDecoupled GitHub project is an example of building a Mura Decoupled website using the Vue framework NuxtJS as your JS framework. The project is a Docker repository, so you will need that installed on your computer. This will allow you to quickly spin up the example and begin exploring the Mura JS / Vue - NuxtJS integration.

The latest up-to-date instructions are provided with the repository.