Blog

Creating a Display Object Configurator

In Mura 5.6, plugins now have the ability to create display object configurators that work the same way as Mura system display objects do. This allows plugin-based display objects to have per-instance parameters, enabling on-the-fly configuration of any Mura Display Object created for plugins.

For example, one might create a plugin to display photo galleries or videos from an external source. That external source might require the passing in of a specific, unique ID for that gallery that wouldn't make sense to include in the global plugin settings. Using the new configurator functionality, this ID can be passed in at the time the object is placed on the page.

Registering Your Configurator

There are two XML attributes that you add to your plugin’s plugin/config.xml file:

  1. ConfiguratorJS: The plugin path (root-relative) to where your display object's JavaScript file lives.
  2. ConfiguratorInit: The name of your display object initialization function.

EXAMPLE DISPLAY OBJECT ELEMENT WITH CONFIGURATOR

<displayobjects location="global"><displayobject name="Configured Object" displaymethod="dspConfiguredObject" component="displayObjects.displayObjects" configuratorInit="initExampleConfigurator" configuratorJS="displayObjects/configurators/configuredObject/configurator.js" persist="false" /</displayobjects>

Example Directory Structure of a Plugin with a Display Object Configurator

Creating Your Configurator Init Function

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

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

Creating the Markup for Your Configurator

Mura CMS posts relevant information to the display object’s configurator URL. Here are some things to consider:

  • 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 object's configuration and its 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.
  • Any UI initialization would need to be added to your JS initConfigurator() call.
  • Mura configurators currently have a fixed width. We will enable flexible widths in a future release.


EXAMPLE CONFIGURATORS

An example of a simple configurator:

<cfscript> $=application.serviceFactory.getBean("MuraScope").init(session.siteID); params=$.event("params"); if(isJSON(params)){ params=deserializeJSON(params); } else { params=structNew(); } if(not structKeyExists(params,"exampleParam")){ params.exampleParam=""; }</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>

This is what the end user wil see:

Access Your Your Per-Instance Configuration Parameters within your Display Object


Once you've completed building your base plugin (as shown above) you will then have the ability to reference your per-instance configuration parameters during the rendering of the display object. They are available as the “objectParams” struct in the current display object’s event.

An example of a very simple configured display objects:

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

Get The Code!

You can get the plugin described above from github.com.

There is also a slightly more complicated example that allows user to create single instance components.

Update: Matt gives a walkthrough of this process in Mura Show #74.

Comments

Brimard

Very cool...

January 13, 2012, 2:29 AM
Reply
Flag as Spam
John Eikens

Hey,

Could you guys post the Mura Show about display object configurators? I'm running into some trouble incorporating configurators into a FW/1-based plugin, and I could use some step-by-step instructions...

January 20, 2012, 6:16 AM
Reply
Flag as Spam
Sean Schroeder

Sorry about the lag, John. That episode is up and a link has been posted above.

January 20, 2012, 7:33 AM
Reply
Flag as Spam
Post a Comment

Required Field