The Plugin's "config.xml.cfm" File - Mura Docs v7.0
Mura Digital Experience Platform
Mura Docs v7.0
Return to getmura.com

The Plugin's "config.xml.cfm" File

This file is where you create the required plugin setup variables. In addition to that, you can optionally register custom event handlers, class extensions, custom image sizes, custom tag paths, custom mappings, and more.

If you haven't already done so, you should familiarize yourself with the Elements Of The "config.xml.cfm" File section. Each of the subordinate elements within the <mura> element apply to plugins. However, instead of a top level <mura> element, the document should contain the mandatory <plugin> element. There are no attributes available for this element.

Plugin-Specific Subordinate Elements

In addition to the elements available to the standard config.xml.cfm file, there are many other elements available for plugins. Please review the list below for details, and examples.

Element Req/Opt Description
name Req This is the default "Name (Alias)" of the plugin. When an administrator installs/deploys the plugin, they are given the opportunity to update this value.
package Req This should be a unique, variable-safe string to use as way to reference the plugin. This value is used for the directory name when the directoryFormat element is set to the recommended value of 'packageOnly'.
directoryFormat Req This setting controls the naming format for the plugin directory itself. Valid options are 'default' (names your plugins as {packageName}_{autoIncrement}) or 'packageOnly' (names your plugins using the value entered in package element. The recommended value to use is 'packageOnly'.
loadPriority Req This setting determines the order plugins will be invoked during the onApplicationLoad event. This allows plugins to use other plugins as services or dependencies. However, this does not affect the order in which regular events are triggered. Valid options are 1 through 10.
version Req May contain any versioning values you wish. This is merely meta data for users of your plugin to identify which version they are currently using.
provider Req The name of the creator or organization who developed the plugin.
providerURL Req The URL of the creator or organization who developed the plugin.
category Req Most plugins fall under either 'Application' or 'Utility'. However, you may enter any string value desired. If anything other than 'Application' or 'Utility', a new tab will be displayed with the category name when viewing a site's applied plugins.
eventHandlers Req See eventHandlers Element below.
ormCFCLocation Opt May contain a list of paths where Mura should look for custom ColdFusion ORM components. This does not pertain to Mura ORM.
customTagPaths Opt May contain a list of paths where Mura should look for ColdFusion custom tags.
autoDeploy Opt This setting works with Mura's plugin auto-discovery feature. If true, whenever Mura reloads, it will auto-install the plugin, and apply it to any sites identified in the siteID element. If false, or if it's not defined, Mura will simply deploy the plugin with the default setting values, and a Super Admin will need to log in and manually complete the deployment process.
siteID Opt This setting works in conjunction with the autoDeploy element. May contain a comma-delimited list of SiteIDs that you would like to assign the plugin to during the auto-deploy process.
settings Opt See Settings Element below.
mappings Opt See Mappings Element below.

eventHandlers Element

This is where you register your event handlers.

<eventHandler> is a sub-element of <eventHandlers>

The following table describes  available attributes of the <eventHandler> element. Technically speaking, developers really only have to register one (1) event, onApplicationLoad. Then, within the onApplicationLoad event, you can register any other handlers you wish, including the .CFC that the onApplicationLoad event is in.

Note: See the Example Plugin Event Handlers section for more information on plugin event handler files themselves.

Attribute Req/Opt Description
event Req The name of the Mura event you wish to register. For example, onApplicationLoad.
component Req The dotted-notation path to where the .CFC file resides. The path is relative to the plugin directory. So, if the .CFC file is located under {context}/plugins/yourplugin/model/handlers/eventHandler.cfc, the value would be "model.handlers.eventHandler".

Example <eventHandler> Element

<eventHandlers>
<eventHandler event="onApplicationLoad"
  component="model.handlers.eventHandler" />
</eventHandlers>

Settings Element

Settings allows you to collect additional data for your plugin. For example, if you wish to collect an API key that you issued to the user, you can do that using a custom setting.

<setting> is a sub-element of <settings>

The following table describes  available elements of the <setting> element.

Element Req/Opt Description
name Req This is the variable name of your attribute, which you will be able to then access using the pluginConfig.getSetting('{name}') syntax.
label Req The text value entered here will be displayed as the label for the form field.
hint Opt The string entered here will be used to display help text to end users when completing the form field.
type Req Determines the type of form field to be displayed. Valid options are:
  • text
  • radioGroup
  • textArea
  • select
  • multiSelectBox
required Req If true, the form field will be required.
validation Req Determines the type of validation to apply to the form field. Valid options are:
  • none
  • email
  • date
  • numeric
  • regex
regex Opt If the value for validation is regex, enter a JavaScript regular expression here.
message Opt The string entered here will display if the form field fails validation or is required and no value has been entered.
defaultvalue Opt The value entered here will be used as the default value for the form field.
optionlist Opt If the form field type is a radioGroup, select, or multiSelectBox, you may enter a carat ("^") delimited list of values to use as the value to be stored in the database. For example: <optionlist>true^false</optionlist>
optionalabellist Opt If the form field type is a radioGroup, select, or multiSelectBox, you may enter a carat ("^") delimited list of values to use as the labels to be used for display. These should coordinate with the values entered in optionlist. For example <optionlabellist>Yes^No</optionlabellist>

Example <settings> Element

<settings>
    <setting>
        <name>country</name>
        <label>Country</label>
        <hint>The country where you live</hint>
        <type>select</type>
        <required>true</required>
        <validation>none</validation>
        <regex></regex>
        <message>Please select a Country</message>
        <defaultvalue>US</defaultvalue>
        <optionlist>US^UK^FR</optionlist>
        <optionlabellist>United States^United Kingdom^France</optionlabellist>
    </setting>
</settings>

Mappings Element

Mappings allow you to create custom ColdFusion mappings.

<mapping> is a sub-element of <mappings>

The following table describes  available attributes of the <mapping> element.

Attribute Req/Opt Description
name Req The name to use for the CFML mapping.
directory Req A plugin-relative path to your desired directory.

Example <mappings> Element

<mappings>
<mapping name="yourmapping" directory="somedir/anotherdir" />
</mappings>

Mappings will automatically be bound to the directory your plugin is installed, so the above example would refer to: {context}/plugins/{package}/somedir/anotherdir/. 

Example config.xml.cfm

<?xml version="1.0" encoding="UTF-8"?>
    <plugin>
        <name>Your Plugin</name>
        <package>yourplugin</package>
        <directoryFormat>packageOnly</directoryFormat>
        <loadPriority>5</loadPriority>
        <version>0.0.1</version>
        <provider>Blue River</provider>
        <providerURL>http://blueriver.com</providerURL>
        <category>Application</category>
        <!-- Event Handlers -->
        <eventHandlers>
            <eventHandler event="onApplicationLoad"
                          component="model.handlers.muraplugin" />
        </eventHandlers>
        <!-- CFML Mappings -->
        <mappings>
          <mapping name="yourmapping" directory="somedir/anotherdir" />
        </mappings>
        <!-- Settings -->
        <settings>
            <setting>
                <name>country</name>
                <label>Country</label>
                <hint>The country where you live</hint>
                <type>select</type>
                <required>true</required>
                <validation>none</validation>
                <regex></regex>
                <message>Please select a Country</message>
                <defaultvalue>US</defaultvalue>
                <optionlist>US^UK^FR</optionlist>
                <optionlabellist>United States^United Kingdom^France</optionlabellist>
            </setting>
        </settings>
        <!-- Image Sizes -->
        <imagesizes>
          <imagesize name="myimage"
            width="600"
            height="400" />
        </imagesizes>
        <!-- Class Extensions -->
        <extensions>
            <!-- <extension> elements -->
        </extensions>
    </plugin>