Blog

Mura CMS 7: New Display Object Conventions

May 3, 2016

Display objects have been modified heavily in Mura CMS 7.0. They're easier to manage, and more powerful and extensible than before. Here's a quick guide to what's new (look for full documenation on this coming soon). 

Display objects are now exclusively managed (when editing your site) from the front-end, and are not accessible via the back-end admin any longer.

The reason for this is two-fold: 1) Adding display objects to a page changes the layout of that page, so editing display objects from the back end in a non-visual manner was a matter of "set it, then check to see how it looks", which was a pretty poor workflow, and 2) managing the development of Mura CMS in both paradigms (front-end and back-end) added a lot of overhead and complexity, and reduced our ability to be creative with Mura CMS functionality. 

There's a new directory based format: 

You can register a new display object directory with:

<cfscript>
  $.siteConfig()
.registerDisplayObjectDir(
dir='/siteid/path/to/objects'
);
</cfscript>

Register directories override core display objects: 

/path/to/custom/objects 

/{siteid}/includes/themes/{theme}/display_objects 

/{siteid}/includes/display_objects

You can even only override a single file within a display object.

/path/to/custom/objects/{object_dir}/index.cfm

/{siteid}/includes/themes/{theme}/display_objects/ {object_dir}/config.xml.cfm

/{siteid}/includes/display_objects/{object_dir}/ configurator.cfm

Deprecated Display Objects

  • Feeds
  • Related content
  • Folder specific listing objects 
  • Gallery specific listing objects 
  • Calendar specific listing objects

There are three primary files in a new display object directory:

  • config.xml.cfm
  • configurator.cfm
  • index.cfm

Example config.xml.cfm:

<displayobject
name="Example Display Object"
contentTypes="Page/Blog,Page/Article"
condition="($.content('title')=='example')"
displayObjectFile="index.cfm"
iconClass="mi-bullseye"
/>

The Name Attribute sets the name to be used

<displayobject
name="Example Display Object"
...
/>

The contentTypes Attribute sets what content type the it will be available for use

<displayobject
...
contentTypes="*"
/>

"*" = all content types

The condition Attribute sets an expression to be evaluated for conditional use

<displayobject
...
condition="($.content('title')=='example')"
/>

The displayObjectFile Attribute sets the actual runtime display object file

<displayobject
...
displayObjectFile="index.cfm"
/>

Default= "index.cfm"

The iconClass Attribute allows for the assignment of a custom icon

<displayobject
...
iconClass="mi-bullseye"
/>

Basic config.xml.cfm:

<displayobject
name="Example Display Object"
contentTypes="*"
/>

You can nest custom class extensions and image sizes

<displayobject
name="Example Display Object"
contentTypes="*">
<extensions>...</extensions>
<imagesizes>...</imagesizes>
</displayobject>

Example display object rendering file:

<cfset objectParams.render="server">
<cfset objectParams.async="true">
<cfparam name="objectParams.text" default="">
<cfoutput>
#esapiEncode('html',objectParams.text)#
</cfoutput>

Example configurator.cfm:

<cfparam name="objectParams.text" default="">
<cfset objectParams.render="server">
<cfset objectParams.async="true">
<cf_objectconfigurator>
<cfoutput>
<div class="mura-control-group">
<label class="mura-control-label">Example Display Object</label>
<input type="text" name="text"
class="objectParam span12"
  value="#esapiEncode('html_attr',objectparams.text)#">
</div>
</cfoutput>
</cf_objectconfigurator>

Display objects can be configured to be rendered in the client via js templates

<cfset objectParams.render="client">

Display objects can be configured to not request data from server

<cfset objectParams.async="false">

You can also place a "model" directory in within your display object directory and Mura will automatically register it with the bean factory

/display_object_dir
/model
/entities/widget.cfc
/services/widgetService.cfc
/event_handlers/widgetHandler.cfc

The directory name is the display object key

#$.displayObject(
object='directoryName',
objectParams={...}
)#

You can now register your own custom display object directory

<cfscript>
$.siteConfig()
.registerDisplayObjectDir(
dir='/siteid/custom/path/'
);
</cfscript>

Display look up locations are cached

If you make a change to your display object location you will need to do an application reload

More Mura CMS 7 Info

Please take a few minutes to read the two other blog posts in this series, as they'll give you a quick overview of what's new and how things work: 

Mura CMS 7 Release Candidate Available for Download

Comments

Boris Schwarz

How does this work within a plugin? The configuratorJS-Approach doesn't seem to work anymore.

May 23, 2016, 2:01 AM
Reply
Flag as Spam
Daniel Budde

So, to customize existing display objects in Mura 7, I assume we copy them from '/{siteID}/includes/display_objects/page/*' to '/{siteID}/includes/display_objects/custom/page/*'? If we want to create one that is sub type specific, do we do '/{siteID}/includes/display_objects/custom/extensions/page_article/*'?

Since the display objects have changed, it would be good to have this info as well.

Daniel

May 23, 2016, 12:53 PM
Reply
Flag as Spam
Matt Levine

The content type body rendering are now essentially the same as display objects. So you place theme where normal display objects go. There's no longer any need for the /{siteid}/includes/display_objects/custom/extensions directory. If you want to override a content type in your site you can use

/{siteid}/includes/display_objects/custom/{type}/index.cfm

/{siteid}/includes/display_objects/custom/{type}_{subtype}/index.cfm

/{siteid}/includes/themes/[theme}/display_objects/{type}/index.cfm

/{siteid}/includes/themes/[theme}/display_objects/{type}_{subtype}/index.cfm

OR

/{custom display object dir}/{type}/index.cfm

/{custom display object dir}/{type}_{subtype}/index.cfm

The configuratorJS approach has been deprecated in favor of the new directory based conventions. I theory is should still work, but if you're starting on a new project I wouldn't use it.

With in a plugin eventHandler you can register display object directory with this in you onApplicati[INVALID] function:

pluginConfig.registerDisplayObjectDir(dir='path/from/plugin/root');

It will handle registering the the directory with each site that the plugin has been assigned to. Otherwise within a single site you can use this in your site or themes eventHandler.onApplicati[INVALID] function:

$.siteConfig().registerDisplayObjectDir(dir='/path/to/dir/');

-Matt

May 26, 2016, 1:45 PM
Reply
Flag as Spam
tom chiverton

Is there a simple worked example ? Like where do I put these three files ?

If I put them in {siteid}/themes{mytheme}/display_objects/{somesting}/ then they don't appear in the inline editor as dropable items, which I expected ?

September 20, 2016, 9:05 AM
Reply
Flag as Spam
Post a Comment

Required Field