yet another coldfusion blog

I recently ran a Mura CMS training seminar in London, UK and thought one of the exercises was valuable enough to share with the community in general, that of building a Mura CMS Plugin from scratch. I mentioned this to Sean at Blue River, and ended up doing a Mura Show on the topic, and thought it would be helpful to create a blog post as well. I highly recommend you view the Mura Show topic first, as it contains a great deal more content than this post.

Plugins are just one of many ways to extend the Mura CMS, though in my opinion they are also the only way to do it. They are self-contained and designed to be update-friendly, and there is a powerful API that makes development very straight forward. When combined with frameworks like FW/1, it is easy to build very complex, very powerful enhancements to Mura. But we're not going there, not today. For this post I'm going to stick to the basics and describe how to build a plugin from scratch, starting with an empty folder. I'll build this out to include both event handlers and display objects, and get into the advanced stuff just a little.

Step 1: An empty directory called "MyFirstPlugin"

Create a directory (preferably in a non-web directory) called "MyFirstPlugin". Then,

1. Create a file called index.cfm with the content "Hello from my first plugin!"
2. Create a folder called plugin
3. Inside of "plugin" create a file called config.xml.cfm

Inside of config.xml.cfm, put the following contents:

<cfoutput> <plugin> <name>My First Plugin</name> <package>MyFirstPlugin</package> <directoryFormat>packageOnly</directoryFormat> <loadPriority>5</loadPriority> <version>0</version> <provider>Grant Shepert</provider> <providerURL>http://grantshepert.com</providerURL> <category>Application</category> <settings> </settings> <eventHandlers> </eventHandlers> <displayObjects location="global"> </displayObjects> </plugin> </cfoutput>

You can find the definitions for all of these values in the excellent Mura CMS Programmer's Guide. Update the provider and providerURL values to match your own information, then save the file.

Okay, we're done. All that's left to do is zip up the file to create the installable package. To do this, select the index.cfm file and plugin directory and create a zip file called MyFirstPlugin.zip. Note: DO NOT zip the MyFirstPlugin folder, only the contents of the folder. In other words, the 'root' of the zip file should be the plugin files themselves, not the "MyFirstPlugin" folder.

To install the plugin, open up a Mura administrator and click on "Site Settings", then on the "Plugins" tab. Select the "MyFirstPlugin.zip" file you just created and click on Deploy. After filling out the setup form, your plugin will be fully installed. Clicking on the name of the plugin should display "Hello from my first plugin!". From this point forward we will be editing the installed plugin directly. This is the easiest way of expanding and testing your plugin's functionality. You can forget about your original "MyFirstPlugin" folder now, and navigate to your [MuraRoot]/plugins/MyFirstPlugin folder for the rest of this lesson.

MyFirstPlugin.zip (initial)

Step 2: Wiring yourself into the API

Now, you're probably looking a the plain white background of your "Hello from my first plugin!" and feeling a little underwhelmed. Because we haven't wired our plugin into Mura yet, we don't have access to the API or any of the great functions it will hand to us ... including wrapping our plugin in the pretty Mura Administrator.

To do this, we are going to connect our plugin using a new file we'll call config.cfm. Because this is going to be a pretty standard file in all of our plugins, we'll put it in the /plugin folder with the config.xml.cfm file. The contents will be pretty straight-forward, too.

<cfsilent> <cfif not isDefined("$")> <cfset $=application.serviceFactory.getBean('muraScope').init('default')> </cfif> <cfif not isDefined("variables.pluginConfig")> <cfset variables.pluginConfig=$.getBean('pluginManager').getConfig('MyFirstPlugin')> </cfif> </cfsilent>

The first part of this file connects us to the Mura Scope, the core tool in accessing the Mura API and a wealth of helper functions. If you are unfamiliar with the Mura Scope, you might want to read through the Programmer's Guide to completely familiarize yourself with it.

The second part of our config.cfm connects us to our plugin configuration. The pluginConfig is also packed with a number of helper objects and gives you access to your plugin's own Session and Application scope.

Once we have these in place, open up the plugin's index.cfm and replace it with the following:

<cfinclude template="plugin/config.cfm"> <cfset local = StructNew() /> <cfsavecontent variable="local.newBody"> <cfoutput> Mura Scope? #isDefined("$")#<br /> Plugin Config? #isDefined("variables.pluginConfig")#<br /> Hello from my first plugin: <b>#variables.pluginConfig.getName()#</b>! </cfoutput> </cfsavecontent> <cfoutput>#$.getBean('pluginManager').renderAdminTemplate(body=local.newBody,pageTitle=variables.pluginConfig.getName())#</cfoutput>

Reload your plugin page and you should see a dramatic change. What we've done is put the contents of our file into a variable (local.newBody) and passed that into Mura's PluginManager renderAdminTemplate() method. This wraps the contents of our plugin in the standard Mura Administrator.

I'll stop there for now. I'll do a follow-up post that covers hooking into Events and using Display Objects later this week. If you're impatient, though, visit the Mura Show and watch my Building Plugins From Scratch demo. I've also included a link to the plugin from that show below.

MyFirstPlugin.zip