config.xml{.cfm}

When a plugin is first loaded into Mura CMS, the application will open the /plugin/config.xml file and read out the settings it contains. The config.xml is a configuration file that tells Mura what it needs to know about the custom extension. Note that this file can be named either /plugin/config.xml or /plugin/config.xml.cfm, though the latter is preferable as it keeps the settings information hidden from prying eyes.

/MyFirstPlugin/plugin/config.xml.cfm

The required fields are highlighted.

Name The name of the plugin, i.e. "My First Plugin"
Package A unique, variable-safe name for the plugin
LoadPriority 1-10. The loadPriority determines the order that the plugins will file the onApplicationLoad event. This allows plugins to use other plugins as services. Note: this does not affect the order in which regular events are fired.
Version Meta Information. This can contain any versioning value you wish to display.
Provider Meta Information. This is the name of the creator or organization that developed the plugin.
ProviderURL A URL that links to the landing page for the plugin.
Category
  • Application
  • Utility
  • [Custom]
  • Meta Information that Mura CMS will use to organize the plugin. You can provide a custom category name and Mura will display the plugin(s) with that category in a similarly-named tab.
Settings Optional. Install settings for the plugin. These operate similarly to Class Extensions, and are described in much the same way.
DirectoryFormat
  • default
  • packageOnly
  • Optional. Sets the format the plugin directory will be named. Defaults to "/{package}_{autoincrement}". packageOnly will change this to "/{package}".
OrmCFCLocation Optional, 5.5+. For plugins using ORM, this is a list of paths where Mura should look for custom ORM components.
CustomTagPaths

Optional, 5.5+. A list of paths where Mura should look for custom tags.

AutoDeploy Optional. Boolean (default=false) The autoDeploy attribute works with Mura's automatic plugin discovery. If true, every time Mura loads it will look into your /plugins directory for new plugins and install them. If false or is not defined, Mura will register the plugin with the default setting values, but a super admin will need to login to the Mura admin and manually complete the plugin deployment
SiteID Optional. A comma-delimited list. The siteID attribute works in conjunction with the autoDeploy attribute. It is a list of siteIDs that you would like to assign the plugin to during auto deployment process.
Mappings Optional. See the Custom Mappings description that follows.
Settings Optional. Install settings for the plugin. These operate similarly to Class Extensions, and are described in much the same way.
EventHandlers Optional. EventHandlers enable developers to explicitly map either a script file or a component method to Mura events. The event that are mapped can be either core Mura events or custom events that are announced within your plugin.
DisplayObjects Optional. Display Objects allow developers to provide widgets that end users can apply to a content node's display regions when editing a page (using the Content Objects tab).
Extensions Optional. Allows your install to create defined Class Extensions of any type.

Settings

The settings element contains the individual settings that the plugin requires in or to function. They are basically the same as the attributes in the Mura Class Extension Manager.

/MyFirstPlugin/plugin/config.xml(.cfm)

Name The variable name the setting will be available under.
Label The label that will be displayed on the form.
Hint A tooltip hint for the form field.
Type
  • text
  • radioGroup
  • textArea
  • select
  • MultiSelectBox
Required
  • true
  • false
  • Whether or not the user must enter a value for the field.
Validation
  • email
  • date
  • numeric
  • regex
  • A URL that links to the landing page for the plugin.
Regex If the Validation value is "Regex", this should contain the regular expression that the content will be evaluated against.
Message The error message returned if validation fails.
DefaultValue Optional. The default value for the field.
OptionList Carat-delimited List (^). Used when the Type is "select" or "MultiSelectBox". A list of values.
OptionLabelList Carat-delimited List (^). Used when the Type is "select" or "MultiSelectBox". A list of labels that matches the corresponding list in OptionList.

A Plugin Package Name

The Package value is very important for your plugin. First of all, your Package name must be unique; Mura will not allow you to install two plugins with the same package name (this means the same plugin cannot be installed twice).

It is also the easiest way for you to access your plugin. We will soon be looking at a special Mura object known as the PluginConfig, which contains not only all of the plugin's install settings but a host of important helper objects as well. We can load this by calling:

When your plugin is installed, the package name automatically becomes an available mapping. For instance, if your package name was "MyFirstPlugin", you would be able to use:

Display Objects

Display Objects allow developers to provide widgets that end users can apply to a content node's display regions when editing a page (they will be listed and available under the Content Objects tab of a page you are editing in the Site Manager). The "persist" attribute for component based displayObjects determine whether they are cached or instantiated on a per-request basis.

In the above example, it is expected you would have the corresponding folder and files in your plugin.

The Hello.cfm file is simply "included" for the display. Remember that you will have full access to the Mura Scope ($) on the Hello.cfm page.

In the case of the Hello.cfc, the file would contain a function called sayHello(), as illustrated below:

The display object CFC must extend mura.plugin.pluginGenericEventHandler for it to be registered and used as a display object. Also, the Mura Scope ($) is passed in automatically, and the pluginConfig is also available within the display object's function via variables.pluginConfig.

Any content the function outputs or returns via a return statement will be displayed when the display object is added to a Mura CMS page (Site Manager > [Edit Page] > Content Objects (tab)).

Custom Mappings

To define custom mappings, add a Mappings attribute to your /plugin/config.xml.cfm:

Note that these mappings will automatically be bound to the directory your plugin is installed in, so the above would refer to the directory: