Blog

Mura Plugins Boot Camp: Day 2 - Plugin Interaction and Configuration

April 23, 2015 by Grant Shepert

In Day One of this series, we took a look at the basics of a Mura CMS Plugin. In Day Two, we are going to see what's involved in getting our plugin to interact with Mura itself. This will cover the concepts of display objects, events, and custom class extensions.

In the attached sample plugin, you will find a much-extended version of the config.xml file. This file is known as the "configuration" file as it contains all the installation/setup information the plugin will need when it is first installed (or when it is updated, for that matter). This is the file that provides all the basic "wiring in" information that lets you integrate your plugin code with Mura.

/plugin/config.xml{.cfm}

Lets take a look at a more fleshed out version of the config.xml file than we looked at in Day One:

<plugin>
    <name>Event Register</name>
    <package>eventregister</package>
    <directoryFormat>packageOnly</directoryFormat>
    <provider>Grant Shepert</provider>
    <providerURL>http://www.blueriver.com</providerURL>
    <loadPriority>5</loadPriority>
    <version>0</version>
    <category>Application</category>
    <displayobjects>
        <displayobject
            name="Event Info"
            displayobjectfile="display_objects/display_eventinfo.cfm"
        />
    </displayobjects>
    <eventHandlers>
        <eventHandler event="onApplicationLoad" component="lib.handler.eventHandler" persist="false"/>
    </eventHandlers>
    <extensions>
        <extension type="Page" subType="Event">
            <attributeset name="Default">
                <attribute
                    name="allowRegistration"
                    label="Allow Registration"
                    hint=""
                    type="checkbox"
                    defaultValue="1"
                    required="false"
                    validation=""
                    regex=""
                    message=""
                    optionList=""
                    optionLabelList="" />
                <attribute
                    name="attendeeLimit"
                    label="Attendee Limit"
                    hint=""
                    type="textbox"
                    defaultValue="10"
                    required="true"
                    validation="numeric"
                    regex=""
                    message=""
                    optionList=""
                    optionLabelList="" />
                <attribute
                    name="location"
                    label="Location"
                    hint=""
                    type="textbox"
                    defaultValue=""
                    required="false"
                    validation=""
                    regex=""
                    message=""
                    optionList=""
                    optionLabelList="" />
            </attributeset>
        </extension>
    </extensions>
    <settings>
        <attribute
            name="enabled"
            label="Enabled"
            hint=""
            type="checkbox"
            defaultValue="1"
            required="false"
            validation=""
            regex=""
            message=""
            optionList=""
            optionLabelList="" />
    </settings>
</plugin>

While I won't rehash what is already extensively covered in the existing Mura CMS documentation on this file, let me recap quickly what each of these newly configured settings are, and what they are doing.

<displayobjects />

Display Objects are the most common way of displaying content generated from your plugin onto a Mura CMS page.

Here I've added a reference to a display object called "Event Info", which refers to a file in my plugin found at [plugin root]/display_objects/display_eventinfo.cfm

<displayobjects>
  <displayobject
    name="Event Info"
    displayobjectfile="display_objects/display_eventinfo.cfm" />
</displayobjects>

If you look in the display object file, you will see the following:

<cfoutput>
<cfif $.content().getValue('allowRegistration') eq true>
<ul class="er-eventinfo">
    <li>
        <b>Attendee Limit: </b> #$.content().getValue('attendeeLimit')#
    </li>
    <li>
        <b>Location: </b> #$.content().getValue('location')#
    </li>
</ul>
</cfif>
</cfoutput>

In this example, we are outputting any values that were entered for our plugin's Class Extensions (see below). Once the plugin is installed, you can add this display object to a page by selecting Plugins > Event Register > Event Info on the Layout & Objects tab. In other words, it's now exactly like every other Mura display object!

<eventHandlers />

When Mura does practically anything (loads a page, logs out a user, processes a form, etc.) it fires off an 'event'. These events can be intercepted by your plugin so that you can interact with the relevant data.

In the above code, I've registered an Event Handler that refers to a file in the [plugin root]/lib/hander/eventHandler.cfc file. This will 'register' the cfc as an event handler, and also any appropriately named event listeners (onApplicationLoad, onPageDefaultBodyRender, etc.) as well.

<eventHandlers>
  <eventHandler event="onApplicationLoad" component="lib.handler.eventHandler" persist="false"/>
</eventHandlers>

If you look in the cfc, you will see the following functions:

public void function onApplicationLoad(required struct $) {
  variables.pluginConfig.addEventHandler(this);
}
public string function onPageEventBodyRender(required struct $) {
  var content = arguments.$.event('contentBean');
  var urlStem = $.getURLStem(filename=content.getFileName(),siteID=content.getSiteID());
  return content.getBody() & "<p><a href='#urlStem#register/'>Register</a>";
}

The first event 'listener', onApplicationLoad, acts to register all of the other listener functions in the cfc. The secent listener, onPageEventBodyRender, will fire whenever a page of type "Page/Event" is loaded on the front end (again, see our Class Extension below).

<extensions />

This refers to Mura Class Extensions. If you don't know what Class Extensions are, feel free to read up on them in the Mura CMS documentation.

In the above example, I've added a new class extension of type "Page / Event", as well as a few new fields associated with it. When the plugin is installed, it will create (or update) this Class Extension and add the class extension fields.

<extensions>
   <extension type="Page" subType="Event">
     <attributeset name="Default">
       <attribute
         name="allowRegistration"
         label="Allow Registration"
         hint=""
         type="checkbox"
         defaultValue="1"
         required="false"
         validation=""
         regex=""
         message=""
         optionList=""
         optionLabelList="" />
       <attribute
         name="attendeeLimit"
         label="Attendee Limit"
         hint=""
         type="textbox"
         defaultValue="10"
         required="true"
         validation="numeric"
         regex=""
         message=""
         optionList=""
         optionLabelList="" />
       <attribute
         name="location"
         label="Location"
         hint=""
         type="textbox"
         defaultValue=""
         required="false"
         validation=""
         regex=""
         message=""
         optionList=""
         optionLabelList="" />
     </attributeset>
   </extension>
</extensions>

<settings />

Settings are the configuration options you want to set when the plugin is first installed. In other words, usually only the administrator who installed (or is updating) the plugin will see these, and only at the time of installation (or update).

They are defined almost exactly as class extensions are. In the above example, I've added a single setting called "enabled". This value could be used to enable or disable the plugin globally (you'd have to code that into your plugin, of course, as it is only a setting).

<settings>
  <attribute
    name="enabled"
    label="Enabled"
    hint=""
    type="checkbox"
    defaultValue="1"
    required="false"
    validation=""
    regex=""
    message=""
    optionList=""
    optionLabelList="" />
</settings>

You can download and install the plugin to experience these objects in action. In the next blog in this series, we'll begin wiring all of these together into a functional plugin!

Download: EventRegister.zip

Additional Resources

Mura CMS Documentation: Plugins http://docs.getmura.com/v6/back-end/plugins

This Mura CMS Blog entry is part of the "Mura Plugins Boot Camp" series by Grant Shepert:

Comments

Post a Comment

Required Field