Anatomy of a Display Object - Mura Docs v7.0

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.

  1. {RegisteredDisplayObjectsDirectory}/
  2. {context}/plugins/{PluginName}/display_objects/
  3. {context}/{SiteID}/includes/themes/{ThemeName}/display_objects/
  4. {context}/{SiteID}/includes/display_objects/custom/

To register a custom "display_objects" directory, use the following syntax:


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="" />
<h2>My Object</h2>
  <cfif Len(objectparams.mytext)>
  This object has a configurator, and the value of "objectparams.mytext" is:<br>
<strong>#esapiEncode('html', objectparams.mytext)#</strong>
  <!--- No value entered for "objectparams.mytext" --->

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 --->
Mura(function(m) {
  .loadcss(m.themepath + '/display_objects/myobject/my.css')
  m.themepath + '/display_objects/myobject/my.js',
  m.themepath + '/display_objects/myobject/other.js',
  function() {
  // Do something with the loaded JS, if desired

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 -->

Example "configurator.cfm" File

The example below illustrates an example "configurator.cfm" file.

<cfparam name="objectparams.mytext" default="" />
    <div class="mura-control-group">
        <label class="mura-control-label">My Text</label>
        <input  type="text"
                value="#esapiEncode('html_attr', objectparams.mytext)#" />

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

You may also be interested in checking out the Intro to Mura 7 Display Objects session from MuraCon 2017.