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.

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.

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.

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.

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>

Example Plugin Event Handlers

Plugin event handlers should "mura.plugin.pluginGenericEventHandler". The example below illustrates how to register the event handler using the onApplicationLoad event, so that any other Mura events may also be included in the file, and Mura will automatically invoke them when announced, using the pluginConfig.addEventHandler(this) method.

component extends='mura.plugin.pluginGenericEventHandler' output=false {

    public any function onApplicationLoad(required struct m) {
        // Register all event handlers/listeners of this .cfc with Mura CMS
        variables.pluginConfig.addEventHandler(this);
    }

    // Add any event handlers here

}

If you wish to register another event handler .CFC file, you can follow the example below.

component extends='mura.plugin.pluginGenericEventHandler' output=false {

    public any function onApplicationLoad(required struct m) {
        // Register all event handlers/listeners of this .cfc with Mura CMS
        variables.pluginConfig.addEventHandler(this);

        // Register another event handler
        // Assumes you have a customHandler.cfc located under the same directory.
        var anotherEventHandler = new customHandler();
        variables.pluginConfig.addEventHandler(anotherEventHandler);
    }

    // Add any event handlers here

}

Register a Custom Model Directory

This example shows how to register a custom "model" directory.

component extends='mura.plugin.pluginGenericEventHandler' output=false {

    public any function onApplicationLoad(required struct m) {
        // Register all event handlers/listeners of this .cfc with Mura CMS
        variables.pluginConfig.addEventHandler(this);

        // Register a custom 'model' directory
        variables.pluginConfig.registerModelDir(
          dir='path/from/plugin/to/model/dir'
        );
    }

    // Add any event handlers here

}

Register a Custom Modules Directory

This example shows how to register a custom "modules" directory.

component extends='mura.plugin.pluginGenericEventHandler' output=false {

    public any function onApplicationLoad(required struct m) {
        // Register all event handlers/listeners of this .cfc with Mura CMS
        variables.pluginConfig.addEventHandler(this);

        // Register a custom 'module' directory
        variables.pluginConfig.registerModuleDir(
          dir='path/from/plugin/to/modules/'
        );
    }

    // Add any event handlers here

}

Register a Custom Content Types Directory

This example shows how to register a custom "content_types" directory.

component extends='mura.plugin.pluginGenericEventHandler' output=false {

    public any function onApplicationLoad(required struct m) {
        // Register all event handlers/listeners of this .cfc with Mura CMS
        variables.pluginConfig.addEventHandler(this);

        // Register a custom 'content_types' directory
        variables.pluginConfig.registerContentTypeDir(
          dir='path/from/plugin/to/content_types/'
        );
    }

    // Add any event handlers here

}

The "plugin.cfc" File

If this file exists, Mura will attempt to invoke specific methods during various phases of the plugin deployment, update, and/or deletion lifecycles. This allows developers to do things such as create custom database tables, connect to your custom API for authentication, and more.

The example code below illustrates a basic plugin.cfc file.

component extends='mura.plugin.plugincfc' output=false {

    // pluginConfig is automatically available as variables.pluginConfig

    public void function install() {
        // Do custom installation stuff
    }

    public void function update() {
        // Do custom update stuff
    }

    public void function delete() {
        // Do custom delete stuff
    }

    public void function toBundle(pluginConfig, bundle, siteid) output=false {
        // Do custom toBundle stuff
    }

    public void function fromBundle(bundle, keyFactory, siteid) output=false {
        // Do custom fromBundle stuff
    }

}

The "config.cfm" File

This file is completely optional. However, if you have an ultra-simple plugin, this file can come in handy. In short, it simply contains a few variables you can share across the administrative pages of your plugin using the "cfinclude" method.

The Mura Scope Variable

As a Mura developer, you probably want a way to access the Mura Scope. Since your plugin is running under the Mura application itself, you will have access to its application scope variables and methods. However, when accessing the plugin directly, the Mura Scope itself will not be defined. So, using the information we learned from the Custom Instance of the Mura Scope section, we can easily create a variable to reference the Mura Scope using the code shown below to place in our config.cfm file.

// ./plugin/config.cfm

    // Mura Scope
    if ( !IsDefined('m') ) {
        siteid = session.keyExists('siteid') ? session.siteid : 'default';
        m = application.serviceFactory.getBean('m').init(siteid);
    }

The pluginConfig Variable

Now that we have a reference to the Mura Scope, as a Mura plugin developer, we'll also want access to the pluginConfig. By having access to the pluginConfig, the following methods are available to you.

myPluginApplication = pluginConfig.getApplication();
myPluginAppication.set('colors', ['Red','White','Blue']);
pluginColors = myPluginApplication.get('colors');

// 'true' = purge the plugin's application variables
myPluginApplication = pluginConfig.getApplication(true);

myPluginSession = pluginConfig.getSession();
myPluginSession.set('fruit', ['Grapes','Oranges']);
pluginFruit = myPluginSession.get('fruit');

// 'true' = purge the plugin's session variables
myPluginSession = pluginConfig.getSession(true);

<cfset rsSites = pluginConfig.getAssignedSites()>

<ul>
  <cfloop query="rsSites">
    <li>#siteid#</li>
  </cfloop>
</ul>

Let's add some code to our config.cfm file to give us access to a variable named pluginConfig.

// ./plugin/config.cfm

    // Mura Scope
    if ( !IsDefined('m') ) {
        siteid = session.keyExists('siteid') ? session.siteid : 'default';
        m = application.serviceFactory.getBean('m').init(siteid);
    }

    // Plugin Config
    if ( !IsDefined('pluginConfig') ) {
        pluginConfig = m.getBean('pluginManager').getConfig('{YourPluginPackagNameGoesHere}');
    }

Restricting Access

Finally, in most cases, you'll want to make sure that groups which do not have access to the plugin's administrator area will not be able to access it. The pluginConfig variable has a special method labeled currentUserAccess, which checks the currently logged in user to see if any of the groups they belong to have been granted access or not. If it returns true, then they have been granted access. If false, then they have not been granted permissions to the plugin itself.

Using this method, we can easily add one more line of code to our config.cfm file, and redirect unauthorized users to the login screen. As a developer, you can probably come up with other options as well.

// ./plugin/config.cfm

    // Mura Scope
    if ( !IsDefined('m') ) {
        siteid = session.keyExists('siteid') ? session.siteid : 'default';
        m = application.serviceFactory.getBean('m').init(siteid);
    }

    // Plugin Config
    if ( !IsDefined('pluginConfig') ) {
        pluginConfig = m.getBean('pluginManager').getConfig('{YourPluginPackagNameGoesHere}');
    }

    // Check User Access ~ Redirect if Not Authorized
    if ( !pluginconfig.currentUserAccess() ) {
        location(
          url=m.globalConfig('context') & '/admin/index.cfm?muraAction=clogin.main'
          , addtoken=false
        );
    }

Summary

If you have a fairly simple plugin, the config.cfm file is a pretty easy way to include common variables and logic throughout your plugin's administrative pages. For more complex plugins, you may wish to use an Application.cfc file instead. An example may be found at https://github.com/stevewithington/MuraPlugin/blob/develop/Application.cfc. If you would like to use a front-end controller framework, be sure to check out MuraFW1, which is a base Mura CMS plugin using Framework One (FW/1) as its application framework.

The "index.cfm" File

While technically optional, it is highly recommend to include the "index.cfm" file in the root of your plugin. The primary reason behind this is because when an administrator navigates to your plugin via the back-end administration area, this is the file that will be rendered. So, if it doesn't exist, administrators will be presented with an error.

Also, the "index.cfm" file is the primary view for your plugin in general, not just for administrators. For example, if your plugin is installed under {context}/plugins/yourplugin/, when a user navigates directly to your plugin's directory, such as http://www.yourdomain.com/plugins/yourplugin/, the "index.cfm" file will be presented to the user.

In other words, you may essentially put whatever you want in this file. For example:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <title>YourPlugin</title>
    </head>
    <body>
        <h1>Hello from YourPlugin!</h1>
    </body>
</html>

In some rare cases, this may be exactly what you want to happen. Maybe you merely want to host your application alongside Mura on the same server, and if it's a completely separate and independent site, then this might be as far as you take it. However, this is not the typical scenario.

Your Application Entry Point

Often, developers will want to use the plugin's "index.cfm" as the entry page to their application, while also being able to work with Mura CMS functionality, or extending its capabilities.

You may also use the "index.cfm" file as part of your front-end controller application. For example, maybe you're using a CFML framework such as Framework One (FW/1). If you're interested in doing this, please check out MuraFW1, a base Mura CMS plugin using FW/1 as its application framework.

While you can easily add display objects and custom content types, you may also want to register a custom event handler, and then register a custom "model" directory. To do this, please see The "config.xml.cfm" File section. 

Administration Area Layout Template

If you would like your plugin's administration area to have the same look and feel of Mura's back-end administration area, you can do that fairly easily using the pluginManager bean's helper method labeled "renderAdminTemplate".

The example below illustrates how to use renderAdminTemplate in your "index.cfm" file. See The "config.cfm" File section for information about the first line of code.

<cfinclude template="plugin/config.cfm" />

<cfsavecontent variable="pluginBody">
    <cfoutput>
        <h1>#esapiEncode('html', pluginConfig.getName())#</h1>
        <p>Hello from YourPlugin!</p>
    </cfoutput>
</cfsavecontent>

<cfoutput>
    #m.getBean('pluginManager').renderAdminTemplate(pluginBody)#
</cfoutput>

Using the above code, if an administrator views your plugin, they would see something similar to the following image.

However, using the renderAdminTemplate method does not "protect" your plugin from being accessed by people who are not authorized to do so. In other words, your plugin is still publicly accessible. In fact, if you're attempting to follow along, and wish to test it out, log out of the administration area, then navigate to your plugin's URL. For example, http://www.yourdmain.com/plugins/yourplugin/. You should see something similar to the following image.

Restricting Access to Your Plugin

If you wish to restrict access to your plugin's entry page, you'll want to include a custom Application.cfc file, and then include your desired logic. A sample Application.cfc with example code may be found at https://github.com/stevewithington/MuraPlugin/blob/develop/Application.cfc. In the example file, you'll note how some of Mura's application methods have been included into the standard CFML lifecycle events, as briefly mentioned in The "appcfc" Directory section. 

In the end, as a Mura plugin developer, it's your responsibility to come up with a solution to restrict access to the plugin.

The "license.txt" File

If this file exists in the root of the plugin, or under {context}/plugins/{YourPlugin}/plugin/license.txt, the content of the text file will be used as an End-User License Agreement (EULA) or software license agreement. When an administrator deploys the plugin, they will be presented with the EULA, and have to "accept" the terms before continuing to install and deploy the plugin.

Via Back-End UI

To install a plugin via the back-end UI, follow the steps below.

1. From the back-end administration area, select Global Settings, then click Plugins.
   
2. You should see the Global Settings screen, with the Plugins tab enabled.
   
3. Under "Install Plugin", you have two (2) options for deploying a plugin:
   • Via Upload
     
     • Select this option if you have the .zip file on your local machine.
     • Select the "Choose File" or "Browse" button, and locate your desired plugin file.
       
     • When ready to upload and deploy the plugin, select the "Deploy" button, then continue to the next step.
       
   • Via URL
     • Select this option if you have a URL to the .zip file. For example, if your desired plugin is hosted on Github, you may select to copy the link to the .zip file, and use that as the URL.
     • Click the Via URL button.
       
     • Then, enter the full link to the plugin. For example, https://github.com/stevewithington/MuraPlugin/archive/develop.zip
       
     • When ready to deploy the plugin, select the "Deploy" button, then continue to the next step.
       
4. After you select "Deploy", if your plugin includes an End User License Agreement (EULA), the license will be displayed. In order to use the plugin, you will need to select "I Accept" in order to see the rest of the plugin installation and configuration settings.
   
5. You may need to scroll down to see the rest of the installation/configuration form. The main form fields are outlined below. However, plugins may include a number of additional configuration settings, and vary by plugin.
   
   • Plugin Name (Alias)
     • The default value entered by the developer will be used here. However, administrators also have the ability to rename the plugin to something more meaningful, if desired.
   • Load Priority
     • This setting is used only during Mura's "onApplicationLoad" event. This is useful for plugin dependency issues that may arise. For example, Plugin2 might be dependent upon Plugin1 functionality, and so Plugin1 should have a higher Load Priority than Plugin2.
   • Site Assignment
     • Select which site(s) you wish to enable the plugin for.
   • Event Handlers
     • In most cases, only one Event Handler is listed, "onApplicationLoad". However, all of the plugin's registered event handler methods will be listed here.
6. When finished completing the plugin's configuration settings information, simply click "Update" to save the changes.
   
7. The plugin should now be listed under "Current Plugins".
   

Via Auto-Discovery

Most Mura plugin developers select deploying their plugins via auto-discovery, especially if the plugin is being created by the developer conducting the installation. To deploy your plugin via auto-discovery, follow the steps outlined below.

1. First, you need to make sure auto-discovery of plugins is enabled for your Mura installation. Open the file located under {context}/config/settings.ini.cfm. Locate the setting for "autodiscoverplugins" and make sure it is set to "true". If not, set it to "true", then reload Mura.
   
2. The next step in the auto-discovery process is to either create a simple plugin, as described in the Plugin Anatomy section, or download a starter plugin from Github, such as MuraPlugin, or MuraFW1.
3. Then, instead of using a ".zip" file, you would simply place your plugin under the plugins directory. For example: {context}/plugins/yourPlugin/
4. Next, reload Mura, and it should now discover your new plugin. Mura then automatically deploys the plugin.
5. To continue the installation process, select Global Settings, then click Plugins.
   
6. You should now see your new plugin under the "Current Plugins" listing.
   
7. Select the three-dot menu to the left of the plugin's name.
   
8. Then, click "Edit" from the options menu.
   
9. You will then be taken to the Plugin Settings screen.
   
10. Select your desired options, as described in the Installing Plugins Via Back-End UI section.
11. When finished, click Update to save your new settings.