Mura 10: Mura Rendering

Define with Admin UI

Follow the steps below to create a custom class extension. For example purposes, we'll create a Page/Location, as mentioned in the introduction to Class Extensions.

1. From Mura's back-end administration area, select Site Settings, click Class Extensions, and select Add Class Extension.
   
2. You should be taken to the Add Class Extension screen.
   
   • Base Type
     • Please refer to the Extendable Bean Objects section of the Class Extensions page for details on each option.
   • Description
     • You may enter your desired description of the class extension here. This is merely information for anyone else who may edit or manage the class extension in the future, and is not displayed anywhere else by default.
   • Status
     • Active
       • If selected, the defined Class Extension will appear as an option for content managers when creating new content items.
     • Inactive
       • If selected, the defined Class Extension will not appear as an option for content managers when creating new content items.
3. From the Add Class Extension screen, click the Base Type menu, and choose your desired option, (e.g., Page).
4. Once you've made a selection, additional form fields may appear. If you select one of the content types, (e.g., Page, Folder, etc.), additional form fields will appear.
   
   • Sub Type
     • You may choose to leave the initial setting of "Default" so that any Extended Attribute Sets and/or Related Content Sets will apply to all content items sharing the same Type. Or, you may enter your own, unique Subtype.
   • Icon
     • The icon you select here, will appear in the Select Content Type dialog window, when content managers create new content items.
   • Show "Summary" field when editing?
     • Select whether you wish to display the "Summary" field.
   • Show "Body" field when editing?
     • Select whether you wish to display the "Body" field.
   • Show "Associated Image" field when editing?
     • Select whether you wish to display the "Associated Image" field.
   • Allow user to add only specific Subtypes?
     
     • If Yes, you may select one, or more options from the available list. This will restrict what appears in the Select Content Type dialog window, when content managers add new content items as children on this specific type of content.
5. When finished, click the Add button, so save your new Class Extension.
6. You should now be taken to the Class Extension screen, where you may view/create Extended Attribute Sets, and Related Content Sets.
   

Define with XML

In the Define with Admin UI section, we covered creating Class Extensions, Extended Attribute Sets, and Related Content Sets using Mura's back-end administrator user interface. In addition to using the administrator's UI, Mura can parse a special XML file to create Class Extensions, as well as create custom image sizes, and more.

config.xml.cfm

Whenever Mura experiences an application reload, it scans for the config.xml.cfm file, and if found, will attempt to parse the file to create any pre-defined Class Extensions and custom image sizes. As you'll see in the Mura Modules section and Plugins section, if the file is located under a modules or plugin directory, Mura uses the file to obtain various settings and information about the module or plugin too.

Convention-Based Lookup

The config.xml.cfm file will be discovered in any theme directory, module directory, content type directory, or plugin directory.

For example:

• {context}/themes/{ThemeName}/
• {context}/themes/{ThemeName}/content_types/{Type}/
• {context}/themes/{ThemeName}/content_types/{Type}_{Subtype}/
• {context}/themes/{ThemeName}/modules/{Module}/
• {context}/sites/{SiteID}/themes/{ThemeName}/
• {context}/sites/{SiteID}/themes/{ThemeName}/content_types/{Type}/
• {context}/sites/{SiteID}/themes/{ThemeName}/content_types/{Type}_{Subtype}/
• {context}/sites/{SiteID}/themes/{ThemeName}/modules/{Module}/
• {context}/plugins/{PluginName}/plugin/
• {context}/plugins/{PluginName}/modules/{Module}/
• {context}/plugins/{PluginName}/content_types/{Type}_{Subtype}/

As covered in the Mura Rendering section, you can nest additional module directories and content type directories within each other, and Mura will automatically search for the config.xml.cfm file in those too.

Please refer to the Elements of the "config.xml.cfm" File section for details about the file itself.

<mura name="My Display Object" contenttypes="*" iconclass="mi-book">
  ...
</mura>

<mura>
    <imagesizes>
    </imagsizes>
    <extensions>
    </extensions>
</mura>

<imagesize name="yourimagesizename" width="600" height="100"/>

<extension type="Page" subType="Product" hasSummary="1" hasBody="1" isActive="1">
	...
</extension>

<attributeset name="Mobile Options" container="Basic" orderno="1">
    ...
</attributeset>

<?xml version="1.0" encoding="UTF-8"?>
    <mura>
        <!-- Image Sizes -->
        <imagesizes>
          <imagesize
            name="locationimage"
            width="600"
            height="400"/>
        </imagesizes>

        <!-- Class Extensions -->
        <extensions>
            <extension 
                adminonly="0" 
                availablesubtypes="Page/Location" 
                description="" 
                hasassocfile="0" 
                hasbody="0" 
                hasconfigurator="0" 
                hassummary="0" 
                iconclass="mi-map-o" 
                subtype="Locations" 
                type="Folder"/>

            <extension 
                availablesubtypes="" 
                description="" 
                hasassocfile="1" 
                hasbody="0" 
                hasconfigurator="0" 
                hassummary="1" 
                iconclass="mi-map-pin" 
                subtype="Location" 
                type="Page">

                <attributeset 
                    container="Basic" 
                    name="Location Options" 
                    orderno="1">

                    <attribute 
                        adminonly="0" 
                        defaultvalue="" 
                        hint="" 
                        label="Location Street" 
                        message="Please enter a Location Street" 
                        name="locationstreet" 
                        optionlabellist="" 
                        optionlist="" 
                        orderno="1" 
                        regex="" 
                        required="true" 
                        type="TextBox" 
                        validation=""/>

                    <attribute 
                        adminonly="0" 
                        defaultvalue="" 
                        hint="" 
                        label="Location City" 
                        message="Please enter a Location City" 
                        name="locationcity" 
                        optionlabellist="" 
                        optionlist="" 
                        orderno="2" 
                        regex="" 
                        required="true" 
                        type="TextBox" 
                        validation=""/>

                    <attribute 
                        adminonly="0" 
                        defaultvalue="" 
                        hint="" 
                        label="Location State" 
                        message="Please enter a Location State" 
                        name="locationstate" 
                        optionlabellist="" 
                        optionlist="" 
                        orderno="3" 
                        regex="" 
                        required="true" 
                        type="TextBox" 
                        validation=""/>

                    <attribute 
                        adminonly="0" 
                        defaultvalue="" 
                        hint="" 
                        label="Location Postal Code" 
                        message="" 
                        name="locationpostalcode" 
                        optionlabellist="" 
                        optionlist="" 
                        orderno="4" 
                        regex="" 
                        required="false" 
                        type="TextBox" 
                        validation=""/>

                </attributeset>
            </extension>
        </extensions>
    </mura>

Export Definitions via Admin UI

Mura is able to export Class Extensions as an XML file via the back-end administration UI. This is the recommended method for creating XML Class Extension definitions, as opposed to writing the XML by hand. By using this method, you're able to reduce the likelihood of typos or introducing errors when Mura attempts to parse your XML file(s).

There are two methods for exporting Class Extensions. You can export them individually, or select multiple extensions to export as a single XML file.

Import Definitions via Admin UI

To import Class Extensions, you will first need a properly formatted XML file, preferably exported via Mura's admin UI. Once you have a properly formatted XML file, follow the steps below to import the Class Extensions.

1. From the back-end administration area of Mura, select Site Settings, click Class Extensions, then select Import Extensions.
   
2. Or, from the Class Extensions screen, select the Actions button, and click Import.
   
3. You should be directed to the Import Class Extensions screen.
   
4. Click the Browse or Choose File button, then select navigate to the exported XML file.
   
5. When ready, click the Import button.
   
6. Mura will then upload, and attempt to parse the submitted XML file. When the import has completed, your new Class Extensions should appear in the list on the Class Extensions screen.
   

Displaying Extended Attributes

There are a few ways to display the attributes of Class Extensions, and it really depends on where you're attempting to display them. That said, the most important thing to keep in mind is that you'll need to know your attribute's name property, in order to display it.

In short, a Class Extension's attribute is treated as a property of the bean it's associated with. So, for example, if a Class Extension's Base Type is Content, then you could use the same getter and setter methods when working with any other attribute of a Content Bean.

Basic Syntax

The basic syntax is shown in the example below.

someBean.get('attributeName')
someBean.get{AttributeName}()
someBean.getValue('attributeName')

Examples

The examples listed below demonstrate the most common method for accessing attributes of a Class Extension. In addition, the recommended best practice is to use esapiEncode when outputting attributes.

Via Layout Template

This example assumes the Base Type is "Content", and you merely want to display the attribute on a layout template.

<cfoutput>
  <h2>
    #esapiEncode('html', m.content('attributeName'))#
  </h2>
</cfoutput>

Via HTML Editor

This example assumes you wish to output an attribute in the body of a HTML Editor.

[m]esapiEncode('html', m.content('attributeName'))[/m]

Via Content Bean

This example assumes you load a Content Bean, and then want to retrieve the data for whatever reason.

contentBean = m.getBean('content').loadBy(title='Home');
// assumes we have a custom attribute labeled `locationstreet`
street = contentBean.get('locationstreet');

Via Iterator

You can easily pull out attributes of Class Extensions while looping inside of a Mura Iterator.

<!--- get an iterator of the content item's children --->
<cfset it = m.content().getKidsIterator()>
<ul>
<cfloop condition="it.hasNext()">
  <cfset item = it.next()>
  <li>
    #esapiEncode('html', item.get('attributeName'))#
  </li>
</cfloop>
</ul>

Making Attributes Editable

When displaying an extended attribute in a layout template, you may want to make the attribute editable by content managers when they're using front-end editing features. This is accomplished by using m.renderEditableAttribute.

Note: This feature only works on extended attributes with its Input Type set to TextBox or HTMLEditor.

Function Syntax

m.renderEditableAttribute(
  attribute
  , type
  , required
  , validation
  , message
  , label
  , value
  , enableMuraTag
)

Parameters

Example

The following example demonstrates how to use m.renderEditableAttribute for an attribute with its Input Type set to HTMLEditor.

<cfoutput>
  <div>
    #m.renderEditableAttribute(
      attribute='attributeName'
      type='HTMLEditor'
      label='Attribute Label'
    )#
  </div>
</cfoutput>

Modifying Mura's Modules

Mura's base modules (display objects) are located under the following directory:

{context}/core/modules/v1/

As illustrated in the image below, there are more modules than the ones listed.

You shouldn't modify any of the files in these directories directly. If you choose to do so, you run the risk of your changes being overwritten whenever Mura is updated to the latest version.

Instead, copy the desired directory and all of its files, then paste it under one of the locations listed in the "Lookup Hierarchy" section below. Then, you can safely make your modifications without fear of losing any of your changes the next time Mura is updated.

Registering a Custom "modules" Directory

While Mura automatically scans for modules in the directories specified in the "Lookup Hierarchy" section below, you may register a custom "modules" directory using the code example below.

m.siteConfig().registerModuleDir(
  dir='/path/to/your/modules/'
);

The directory path should be a logical path to a CFML directory, and is usually registered in the onApplicationLoad() event.

Lookup Hierarchy

As mentioned under "The 'Modules' Directory" section, Mura uses the following lookup hierarchy when searching for modules, and aborts the lookup process once the target module has been located:

• Registered Module Directory
  • {RegisteredModuleDirectory}/
  • A pre-registered module directory path. See "Registering a Custom 'Modules' Directory" section above.
• Module
  • ../{module}/modules/
  • A nested "modules" directory nested within a known module.
• Theme
  • ../themes/{ThemeName}/modules/
  • Theme modules are only used when the specified theme is actively assigned to a site. Keep in mind themes may be located under either the global themes directory ({context}/themes/{ThemeName}), or under a site ({context}/sites/{SiteName}/themes/{ThemeName}).
• Site
  • {context}/sites/{SiteName}/modules/
  • Site modules are shared across all themes within the specific site.
• Global
  • {context}/modules/
  • Global modules are shared across all sites under a single Mura instance.
• Core
  • {context}/core/modules/v1/core_assets/modules/
  • These are the "core" modules or display objects which may be copied and placed into any of the directories above to be safely modified.

Note: You should not edit the "core" modules directly. If you do, you run the risk of losing your edits or changes whenever you update Mura to the latest version.

Anatomy of a Module

Mura's default modules follow a specific directory structure and file naming convention. These conventions also apply to the development of custom modules (including those known as Mura "display objects" in prior versions).

Directory Structure

First, create a subdirectory using the name of the module, under any standard or registered "modules" directory within the Mura file structure. For example, ../sites/mysite/modules/mymodule/ or  ../themes/mytheme/modules/{module}/. 

Inside of the{module} directory, you may use the following files and directories as applicable:

Example "index.cfm" File

The example below shows the contents of a basic "index.cfm" file for a module.
For custom modules, you may include your own code or markup as needed.

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

Use MuraJS to add any CSS or JavaScript to your module. The example below leverages the loader() method to load both CSS and JavaScript. Simply add this code to your "index.cfm" file, changing file paths to match your specific directory structure and filenames as needed.

<!--- Add the following to your "index.cfm" file --->
<script>
  Mura(function(m) {
    m.loader()
      .loadcss(m.themepath + '/modules/myobject/my.css')
      .loadjs(
        m.themepath + '/modules/myobject/my.js',
        m.themepath + '/modules/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 module 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.

// ../yourmodule/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 Modules and Display Objects and Mura JS sections for more information on rendering modules via JavaScript.

Example "config.xml.cfm" File

This is one example of a standard "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 Module" contenttypes="*" iconclass="mi-rebel">
    <!-- May also include other elements here -->
  </mura>

Example "configurator.cfm" File

This is very basic example of a module's "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>

See the Module Configurators for more on proper markup conventions.

Custom Keys

As previously documented, Mura searches for custom ".properties" files, under the directories listed in the "Lookup Hierarchy" section.

You don't have to include all of the key-value pairs from the original files. You only have to include the key-value pairs you wish to override. In addition, if you have any custom keys you would like to use in your site, you can simply include them in your custom ".properties" files.

Displaying Custom Keys

To output a custom key-value from your ".properties" file, simply use m.rbKey({keyName}).

So, for example, to output a key of "myCustomString", use the following syntax.

<cfoutput>
  #m.rbKey('myCustomString')#
</cfoutput>

Custom Factories

Mura allows you to create your own resource bundle factories, and fall back to Mura's original lookup hierarchy when a requested key-value is not found. This is especially useful when creating plugins, or integrating a custom application.

The code example below demonstrates how you could go about creating a custom resource bundle factory.

customResourceBundleDirectory = ExpandPath('#m.globalConfig('context')#/path/to/your/RBFactory/');

customFactory = new mura.resourceBundle.resourceBundleFactory(
  parentFactory = m.siteConfig('rbFactory')
  , resourceDirectory = customResourceBundleDirectory
  , locale = m.siteConfig('JavaLocale')
);

You could wrap this up into a custom method to obtain a reference to your custom factory using something similar to the following example.

public any function getResourceBundleFactory(required struct m) {
  var resourceDirectory = ExpandPath('#arguments.m.globalConfig('context')#/plugins/MyPlugin/rb/');
  return new mura.resourceBundle.resourceBundleFactory(
    parentFactory = arguments.m.siteConfig('rbFactory')
    , resourceDirectory = resourceDirectory
    , locale = arguments.m.siteConfig('JavaLocale')
  );
}

Once you've created your custom resource bundle factory, simply use {yourCustomFactoryVariableName}.getKey({yourKey}). 

So, for example, to output a key of "myCustomString", with a custom factory variable named "customFactory", use the following syntax.

<cfoutput>
  #customFactory.getKey('myCustomString')#
</cfoutput>

How to Enable/Disable Site Caching

Follow the steps below to enable and/or disable site caching.

1. From the back-end administrator, on the main navigation, click Site Settings, then select Edit Settings
2. From the Site Settings screen, select the Basic tab.
3. Scroll down to Site Caching.
   • Select On to enable site caching.
   • Select Off to disable site caching.
4. After making your selection, click Save Settings.

Cache Free Memory Threshold

By default, when Site Caching is enabled, Mura will only store data into memory when the Java virtual machine (JVM) has at least sixty percent (60%) available memory. You may choose to set an alternate minimum desired percentage by following the steps outlined below.

1. From the back-end administrator, on the main navigation, click Site Settings, then select Edit Settings.
   
2. From the Site Settings screen, select the Basic tab.
   
3. Scroll down to Cache Free Memory Threshold (Defaults to 60%), and enter in your desired percentage amount. If you enter zero (0), Mura will revert to using its default setting of sixty percent (60%).
   
4. After entering your desired amount, click Save Settings.
   

cf_CacheOMatic Tags

One of the easiest ways to improve the performance of your site, is to use proven caching techniques. In addition to the native caching strategies for CFML, Mura also offers a special, custom tag, <cf_CacheOMatic>, to use for expensive database transaction code, or other time-consuming CFML code that doesn't need to be executed during each request.

Using Mura's <cf_CacheOMatic> tag allows you to add data to Mura's cache. The tag only works when Site Caching is enabled, which is a great reason to use it since you can easily disable it, if necessary.

The custom tag is located under {context}/core/mura/customtags/CacheOMatic.cfm if you would like to inspect the file to see how it works under the hood.

Tag Syntax

<cf_CacheOMatic>
  Code or data to cache.
</cf_CacheOMatic>

Attributes

Usage

Use this custom tag to cache inline content or data within layout templates.

Examples

Using the "key" Attribute

This example uses the ContentID of the content item as the key with prefix of "page-".

<cf_CacheOMatic key="page-#m.content('contentid')#">
  <h2 class="page-title">#esapiEncode('html', m.content('pagetitle'))#</h2>
</cf_CacheOMatic>

Using the "nocache" Attribute

The following example demonstrates how you could use the nocache attribute to see an "un-cached" version of the output by simply appending ?nocache=true to the URL.

<cf_CacheOMatic 
     key="example-timestamp1" 
     nocache="#m.event('nocache')#">
  <p>The time is now: #LSTimeFormat(Now())#</p>
</cf_CacheOMatic>

Using the "timespan" Attribute

In this example, we're setting the cache to expire in five (5) hours.

<cf_CacheOMatic
     key="example-timestamp2"
     nocache="#m.event('nocache')#"
     timespan="#CreateTimeSpan(0,5,0,0)#">
  <p>The time is now: #LSTimeFormat(Now())#</p>
</cf_CacheOMatic>

Programmatic Caching

As covered in the cf_CacheOMatic Tags section, Mura allows developers to add data to Mura's cache. One thing to keep in mind is your data or code may be either intentionally or even inadvertently wrapped by cf_CacheOMatic tags, subjecting your output to the settings of the tag.

However, as a developer, you may have data or code you wish to either explicitly exclude from being added to Mura's cache. Or, you may wish to set a specific duration of time the data or code may be cached for. Mura also allows developers to achieve this using the code snippets described below.

request.cacheItem

This code snippet controls whether the code or data will be cached if wrapped by cf_CacheOMatic tags. If true, the code or data will be cached according to the settings of the containing cf_CacheOMatic tags. If false, the code or data will not be cached.

Note: A side-effect of setting request.cacheItem to false is none of the code or data within the containing cf_CacheOMatic tags will be cached at all.

Syntax

request.cacheItem = {true || false}

Example

<cfset request.cacheItem = false />
<!--- The following timestamp will NOT be cached --->
<cfoutput>
  <p>The date/time is #Now()#</p>
</cfoutput>

request.cacheItemTimeSpan

This code snippet controls the duration of time the code or data will be cached for.

Syntax

request.cacheItemTimeSpan = {TimeSpan Object}

Example

<cfset request.cacheItemTimeSpan = CreateTimeSpan(0, 0, 5, 0) />
<!--- The following timestamp will be cached for 5 minutes, if wrapped by cf_CacheOMatic tags --->
<cfoutput>
  <p>The date/time is #Now()#.</p>
</cfoutput>