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
<plugin> <name>My First Plugin</name> <package>MyFirstPlugin</package> <loadPriority>5</loadPriority> <version>1.0</version> <provider>Blue River Interactive Group</provider> <providerURL>http://www.blueriver.com</providerURL> <category>Utility</category> <directoryFormat>packageOnly</directoryFormat> <ormCFCLocation>/orm</ormCFCLocation> <customTagPaths>customtags</customTagPaths> <autoDeploy>true</autoDeploy> <siteID>siteA,siteB</siteID> <mappings>...</mappings> <settings>...</settings> <eventHandlers>...</eventHandlers> <displayobjects>...</displayobjects> <extensions>...</extensions> </plugin>
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 |
|
| Settings | Optional. Install settings for the plugin. These operate similarly to Class Extensions, and are described in much the same way. |
| DirectoryFormat |
|
| 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)
<settings> <setting name="FirstName" label="Your First Name" hint="Enter your first name." type="text|radioGroup|textArea|select|multiSelectBox" required="true" validation="email|date|numeric|regex" regex="" message="You did not enter a value" defaultvalue="1" optionlist="1^2^3" optionlabellist="One^Two^Three" /> <settings>
| 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 |
|
| Required |
|
| Validation |
|
| 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:
MyFirstPluginConfig = $.getPlugin('MyFirstPlugin');
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:
<cfscript>
include template="#ExpandPath('/MyFirstPlugin')#/includes/myfile.cfm";
var object = CreateObject('component', 'MyFirstPlugin.objects.myObject');
var anotherObj = new MyFirstPlugin.objects.myObject();
</cfscript>
Display Objects
<displayobjects location="global"> <displayobject name="Say Hello (cfc)" displaymethod="sayHello" component="display.sayHello" persist="false" /> <displayobject name="Say Hello (cfm)" displaymethod="sayHello" displayobjectfile="display/sayHello.cfm" /> </displayobjects>
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.
/MyFirstPlugin/display/Hello.cfc /MyFirstPlugin/display/Hello.cfm
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:
component extends='mura.plugin.pluginGenericEventHandler' {
function sayHello($) {
return 'Hello from My First Plugin!';
}
}
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:
<mappings> <mapping name="requiredProject" directory="resources/requiredProject" /> </mappings>
Note that these mappings will automatically be bound to the directory your plugin is installed in, so the above would refer to the directory:
{context}/plugins/MyFirstPlugin/resources/requiredProject/