Mura Plugins Boot Camp: Day 1 - Plugin Basics

Plugin Bootcamp: Day One

Never alter the Mura CMS core.

If you've ever gone through one of our training courses, you have heard our instructors utter this line. Multiple times, would be my guess. It is the most important tenant of developing inside of Mura CMS: do not break the Mura CMS upgrade path! This happens when you alter a template or component that is part of the Mura CMS core, i.e. the base code that is the lifeblood of Mura CMS. By altering any core files directly, you break the ability to auto-update Mura CMS as it is possible your changes would be overwritten. This is an unenviable position to put yourself in, as you will lock yourself out of the latest and greatest the Mura has to offer.

The good news is, you will never have to put yourself in this position! Mura CMS has multiple ways of allowing you to customize, extend and replace base functionality. The custom templates folder, themes, and the event model are all available to you, as are plugins. It is this last feature that we are going to examine in detail, across a number of blog posts. The series is planned as follows:

• Day One: Introduction to Plugins (that's this post, btw!)
• Day Two: Events and Configuration
• Day Three: Display Objects
• Day Four: Security
• Day Five: Permissions
• Day Six: Frameworks

What are Mura plugins?

Plugins are 'encapsulated' i.e. self-contained applications that are designed to integrate into the Mura CMS platform. They allow developers to extend base Mura functionality in the administrator or front end, or add a whole new set of functionality. There is really no limit to the size and scope of a plugin, and many very large scale applications have been built upon Mura CMS in this way.

Plugins have several advantages, chief among them being:

• Encapsulated: a plugin is a self-contained application, so it is easy to maintain and develop without having to alter Mura CMS itself
• Distributable: plugins can be distributed as packaged zip files and are easy to install and update
• Uniquely Licensed: the Mura CMS open source license specifically excludes plugins as having to participate in its own GPL 2.0 license. This means that plugin developers can choose to distribute them under any license they so choose, including closed source/commercial licenses

The Basics

The most basic Mura CMS plugin involves only two files. The example file structure of a very basic plugin would look like this:

/index.cfm
/plugin/config.xml.cfm

The index.cfm page will become the landing page for the plugin's administrator (in other words, when you are in the Mura admin section, if you go to the plugin it will be this page that is loaded).

As an example, you could put a welcome message in here, as in:

Welcome to my first plugin!

We can also get a little "fancy" by wrapping our welcome message inside the Mura CMS administrator, like so:

<cfscript>
    // get the current siteid
    mySiteid = StructKeyExists(session, 'siteid') ? session.siteid : 'default';
    // get the Mura scope
    $ = StructKeyExists(request, 'muraScope') ? request.muraScope : application.serviceFactory.getBean('muraScope').init( mysiteid );
    // get my plugin's configuration
    myPluginConfig = $.getBean('pluginManager').getConfig("MyFirstPlugin");
</cfscript>
<cfoutput>
<cfsavecontent variable="mybody">
    <p>Welcome to my first plugin!</p>
</cfsavecontent>
#$.getBean('pluginManager').renderAdminTemplate(body=mybody,pageTitle=myPluginConfig.getName())#    
</cfoutput>

The config.xml.cfm page is the configuration information for the plugin. Here's an example of what it might contain:

<plugin>
    <name>My First Plugin</name>
    <package>MyFirstPlugin</package>
    <directoryFormat>packageOnly</directoryFormat>
    <provider>Grant Shepert</provider>
    <providerURL>http://www.blueriver.com</providerURL>
    <loadPriority>5</loadPriority>
    <version>0</version>
    <category>Application</category>
    <customtagpaths />
    <mappings />
    <settings />
    <eventHandlers />
    <displayobjects />
    <extensions />
</plugin>

Let's take a look a the basic settings:

• name: The name of your plugin, as it will appear in the Mura CMS administrator
• package: This is the application "package" name and must be unique to the plugin (i.e. two installed plugins cannot have the same package name). It should be a variable-safe name (no spaces, etc.)
• directoryFormat: There are options for how the plugin directory name is created. "packageOnly" is the preferred one as it makes it easy to identify the plugin
• provider: The name of the provider, i.e. you or your company
• providerURL: A url to the provider (again, you or your company)
• loadPriority: A number that tells Mura where in the load order the plugin should be loaded upon restart. The lower the number, the earlier it will be loaded
• version: The version of the installed plugin
• category: Standard choices are "Application" or "Utility", however you can enter any new category name here and Mura will automatically create a new tab folder for the plugin(s)

We'll look at the other config settings in future posts.

That's it! Admittedly the plugin isn't going to do much other than welcome people, but it's a start. To make this an installable plugin, you simply have to 'zip' up the files, ensuring that the index.cfm is in the zip root, and then choose Modules > Plugins > Add Plugin in the Mura CMS administrator and install the plugin.

In my next post I'll be discussing some of the other installation options like adding a licensce agreement and install/update/delete functionality. I'll also be adding a number of Mura CMS integration points, including display objects (which let you render content on the front end), events (which let you tap into Mura CMS functionality like saving pages or filling out forms), adding class extensions, and more.

Download MyFirstPlugin.zip