Creating a Display Object Configurator - Mura Docs v6

Creating a Display Object Configurator

With plugins you have the ability to create display object configurators. Configurators allow you include a 'setup' form when adding the display object to a page. In other words, every time you add a display object, it can have per-instance settings.

Registering Your Configurator

Configurators are based upon the object version of display objects. There are several xml attributes that you will add to your plugin's plugin/config.xml on top of what a regular object-based display object requires:

ConfiguratorJS The plugin root relative path to where your display objects JS lives.
ConfiguratorInit The name of the display object initialization function.

/plugin/config.xml.cfm

<plugin>
...
<OrmCFCLocation>/orm</OrmCFCLocation>
<CustomTagPaths>customtags</CustomTagPaths>
<displayobjects location="global">
<displayobject
name="Configured Object"
displaymethod="dspConfiguredObject"
component="displayObjects.displayObjects"
configuratorInit="initExampleConfigurator"
configuratorJS="displayObjects/configurators/singleInstanceComponent/configurator.js"
persist="false" />
</displayobjects>
...
</plugin>

Directory Structure

Below is an example of the directory structure we are using for this plugin.

Creating Your Configurator.js Init() Function

The configurator's javaScript's init() function tells Mura where the configurator's markup is located. This allows developers to register functions to handle the configurator's init(), destroy() and validate() events. The basic concept is to simply provide arguments to Mura's system initConfigurator() function.

/displayObjects/configurators/singleInstanceComponent/configurator.js

function initExampleConfigurator(data){
initConfigurator(
data,
{
url:'../plugins/ConfiguratorExample/displayObjects/configurators/singleInstanceComponent/configurator.cfm',
pars:'',
title: 'Example Configured Object',
init: function(){},
destroy: function(){},
validate: function(){
return true;
}
}
);
return true;
}

/displayObjects/configurators/singleInstanceComponent/configurator.cfm

<cfscript>
$=application.serviceFactory.getBean('$').init(session.siteID);
params = {};
if ( IsJSON($.event('params')) ) {
params = DeserializeJSON($.event('params'));
};
defaultParams = {
exampleParam = 'something'
, anotherParam = 'something else'
};
StructAppend(params, defaultParams, false);
</cfscript>
<cfoutput>
<div id="availableObjectParams"
data-object="plugin"
data-name="Example Configured Object"
data-objectid="#$.event('objectID')#">
<dl class="singleColumn">
<dt>Example Parameter</dt>
<dd>
<input name="exampleParam"
class="objectParam"
value="#HTMLEditFormat(params.exampleParam)#"/>
</dd>
</dl>
</div>
</cfoutput>

Creating the Markup for Your Configurator

Mura posts relevant information to the display object's configurator URL (in this example, the configurator.cfm file). Here is a simple example of rendering a basic configurator's markup.

Key Points:

  • The value of any form field that has a class of 'objectParam' and is inside an element with an id of 'availableObjectParams' is automatically considered a part of this display objects configuration and it's value will be available to your display object.
  • The display object's current configuration is passed as a form variable named objectParams that is a struct serialized as JSON. So you must deserialize it and ensure that all required attributes exist.
  • If there are multiple form fields with the same name their values will be stored as an Array.
  • Any UI initialization would need must be added to your JS initConfigurator() call.
  • Mura configurators have a fixed display width. This will be addressed in a future release.

Accessing Configuration Parameters

You will have the ability to reference configuration parameters during the rendering of the display object. They are available via the 'objectParams' structure.

An example of a configured display object:

/displayObjects/displayObjects.cfc

component extends="mura.plugin.pluginGenericEventHandler" {
public any function dspConfiguredObject($) {
var params = deserializeJSON($.event('objectParams'));
return 'Example Parameter: ' & params.exampleParam;
}
}