Anatomy of a Display Object
In addition to understanding how Mura's display objects are constructed, Mura developers may use the information below to create their own, custom display objects.
Mura automatically scans the following directories for display objects, and will use the first one it locates, in the order listed below.
{RegisteredDisplayObjectsDirectory}/{context}/plugins/{PluginName}/display_objects/{context}/{SiteID}/includes/themes/{ThemeName}/display_objects/{context}/{SiteID}/includes/display_objects/custom/
To register a custom "display_objects" directory, use the following syntax:
m.siteConfig().registerDisplayObjectDir( dir='/path/to/your/display_objects/' );
The directory path should be a logical path to a CFML directory, and is usually registered in the onApplicationLoad() event.
Directory Structure
First, create a directory under a known or registered "display_objects" directory. For example, ../display_objects/mydisplayobject/. Within the {displayobject} directory, you may have the following files and/or directories:
| File or Directory | Req/Opt | Description |
|---|---|---|
| index.cfm | Required | This is the body or view used by Mura for display file itself. See example "index.cfm" file section below. |
| config.xml.cfm | Optional | This is the configuration file for the display object itself. This file also allows you to include custom image sizes, class extensions, and more. See example "config.xml.cfm" file section below. Also visit the Elements Of The "config.xml.cfm" File section for information about available elements and attributes. |
| configurator.cfm | Optional | This file allows developers to include a form with configuration options which appear on the display object panel when using the Inline Edit feature. See example "configurator.cfm" file section below. |
| /model/ | Optional | If you wish to leverage Mura ORM, the display object could have its own "model" directory, which in turn could also include a "beans" and/or "handlers" directory too. See Mura ORM Configuration section for more information about the "model" directory. |
| /content_types/ | Optional | You may also include custom content types. This is useful for keeping content types directly related to specific display object(s) together, in a unified directory structure. See Content Types section for more information. |
| /display_objects/ | Optional | You may also include custom display objects. This is useful for keeping related display objects together, under one, unified display object itself. One caveat is that if you choose to display the nested object on the parent object, Content Managers will not be able to access the nested object's configurator, if it has one. Because of this, you may wish to either omit the "contenttypes" attribute from your config.xml.cfm's <mura ...> node, or explicitly add contenttypes="" so that the nested object will not appear in the display object panel's UI. If you need configurable options for the nested object, you should include the options on the parent object's configurator. To include the nested object in the view of the parent object, use the following syntax: #m.dspObject(object='{objectName}', objectparams=objectparams)#. |
Example "index.cfm" File
The example below illustrates what an "index.cfm" file could contain. However, you may include your own custom markup, code, and more.
<cfparam name="objectparams.mytext" default="" />
<cfoutput>
<h2>My Object</h2>
<cfif Len(objectparams.mytext)>
<p>
This object has a configurator, and the value of "objectparams.mytext" is:<br>
<strong>#esapiEncode('html', objectparams.mytext)#</strong>
</p>
<cfelse>
<!--- No value entered for "objectparams.mytext" --->
</cfif>
</cfoutput>
If you wish to add any CSS or JavaScript to the browser for your display object, you'll need to use MuraJS to help you. The example below leverages the loader() method to load both CSS and JavaScript. Simply add this code to your "index.cfm" file. You may have to change the path(s) to match your specific directory structure, and needs.
<!--- Add the following to your "index.cfm" file --->
<script>
Mura(function(m) {
m.loader()
.loadcss(m.themepath + '/display_objects/myobject/my.css')
.loadjs(
m.themepath + '/display_objects/myobject/my.js',
m.themepath + '/display_objects/myobject/other.js',
function() {
// Do something with the loaded JS, if desired
}
);
});
</script>
Visit the MuraJS section to learn more about Mura.loader() capabilities.
Rendering Via JavaScript
If your display object will be rendered using only JavaScript, your index.cfm file should only contain the following code:
<cfset objectparams.render="client">
Choosing this option means you'll have to load your JavaScript by using a custom event handler method, as shown below.
// ../yourdisplayobject/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>');
}
}
Please also see the Display Objects With Mura.js section, for more information on rendering display objects via JavaScript.
Example "config.xml.cfm" File
The example below illustrates a simple example of the "config.xml.cfm" file. Visit the Elements Of The "config.xml.cfm" File section for more details on available elements and attributes.
<?xml version="1.0" encoding="UTF-8"?> <mura name="My Object" contenttypes="*" iconclass="mi-rebel"> <!-- May also include other elements here --> </mura>
Example "configurator.cfm" File
The example below illustrates an example "configurator.cfm" file.
<cfparam name="objectparams.mytext" default="" />
<cfoutput>
<div class="mura-control-group">
<label class="mura-control-label">My Text</label>
<input type="text"
name="mytext"
class="objectParam"
value="#esapiEncode('html_attr', objectparams.mytext)#" />
</div>
</cfoutput>
Visit the Custom Display Object Configurators section for information on proper markup conventions.
More Information & Examples
For more information, check out the Super Fast Application Development with Mura 7 on-demand webinar. The presentation slides and code samples can be found at https://github.com/stevewithington/cfsummit-2016.
You may also be interested in checking out the Intro to Mura 7 Display Objects session from MuraCon 2017.