Extending Mura CMS with Plug-Ins
Posted At : June 24, 2009 10:42 AM | Posted By : Bob Silverberg
Related Categories:
ColdFusion,Mura CMS
I've been using Mura CMS on and off for the past few months, trying to integrate a bunch of functionality from an existing site into a Mura installation. At first it was a fairly daunting task, as although Mura is an excellent tool which is easily extendible, it is also quite complicated and there is not a heck of a lot of documentation available for back end development. I was lucky enough to get some help from Matt Levine, the architect and lead developer, who helped me get an understanding of the plug-in architecture, after which I was able to integrate much of my existing functionality into Mura.
Blue River has made a start at producing some back end development documentation, and I decided to attempt to help the cause by documenting what I've learned about developing plug-ins for Mura. To that end I'm starting a series about extending Mura with plug-ins. This first entry will be an introduction to plug-ins. I plan to follow it up with articles containing much more detail. As I'm about to head off for three week's vacation in beautiful British Columbia, those additional articles will not appear until some time in July.
Now I'm no expert when it comes to all things Mura, so if I've made any mistakes here I'm hoping that someone from Blue River will step in and correct me.
What is a Plug-In?
Plug-ins allow you to add your own custom code into a Mura install in an encapsulated manner. You can think of them as mini-applications that run in the context of Mura. A plug-in can be as simple as a single cfm template that displays custom information, or as complex as a complete application using frameworks. For example, you could build an application using Model-Glue, Coldspring and Transfer, and then install that as a plug-in inside of Mura. These plug-ins can the be accessed via Mura to display content and perform actions. From what I've seen thus far, there doesn't appear to be much you cannot do with a plug-in.
Creating a Plug-In
To create a plug-in you simply take your application (again, it can be a single cfm template or a complete application with nested folders) and add a "plugin" folder (the contents of that folder are discussed below) to the root folder of your application. You also need an index.cfm file in the root which will be displayed whenever a user clicks on your plug-in's name from within the Mura admin. This can contain things like credits and instructions. Take that whole folder structure and zip it up. The resulting zip file is your plug-in.
Note that the documentation states that you should have a displayObjects folder and a eventHandlers folder, but from what I can tell, these aren't actually necessary as you can define the location for your files in the config.cml file discussed below. Perhaps these are just suggestions for best practices for plug-in development.
What's in the Plugin Folder?
There are a couple of sample plug-ins available at the Mura site, each of which contain a plugin folder that can be examined. The plugin folder should contain three files:
- config.cfm - The documentation states "This may be removed or depreciated, so leave it in, but disregard."
- plugin.cfc - This component contains events that are fired when the plug-in is insatlled, updated or deleted. For example, you may want to copy files to another location or create a ColdFusion datasource when your plug-in is installed, or you may need to run a SQL script to update a database when a plug-in is updated. For simple plug-ins you probably won't have to add anything to this file.
- config.xml - This file is what defines your plug-in to Mura. You can provide information such as the plug-in name, the author, how the plug-in directory should be named, etc. You can also specify custom attributes for your plug-in. These are values that the user of your plug-in can provide via the Plugin Settings screen. This is also where you define what events your plug-in can intercept, and what display objects your plug-in makes available to Mura.
Installing a Plug-In
Plug-ins are installed from within Mura. From the Mura admin screen, click on "Site Settings", on the right-hand side of the yellow menu bar. You should see two tabs, "Current Sites" and "Plug-Ins". Click the "Plug-Ins" tab and you will see a list of any installed plug-ins, above which is a form that allows you to browse for a zip file on your local machine. Choose a file and click the "Deploy" button and you should see a "Plugin Settings" screen which displays some information about the plug-in and allows you to choose which sites should be allowed access to the plug-in. Check off the sites you want and click the "Update" button and voila, your plug-in is installed and ready to be used.
If a new version of the plug-in is developed you can update an existing plug-in by returning to the Plug-Ins tab on the Site Settings screen and clicking the edit icon (the little pencil) for the plug-in. The Plugin Settings screen will now include a link near the top that says "Update Plugin Version", which will take you to a form that will allow you to select a new zip file from your local machine and deploy it.
Note that clicking on the plug-in's name from the Plug-Ins tab will display the index.cfm file from the root of your plug-in.
Using a Plug-In
There are many different ways of making use of a plug-in, so I'm not going to cover any of them right now. I will be discussing different ways in which I'm using plug-ins in future articles.
One thing I noticed when writing this post is that there is some inconsistency regarding how to refer to plug-ins. In the documentation they are referred to as "plug-ins", but within the Mura screens themselves they alternate between "plug-in" and "plugin". Not a big deal, but maybe something Blue River might want to look at cleaning up and standardizing on one convention.
In the next article I'll create a simple plug-in and walk through using it to display content on a Mura page.
Thanks,
Darren
I don't know of any existing examples of Model-Glue apps as plugins.
I might just try to throw together an example for Steve Good's CFThrowdown Mura Plugins contest. If I do I'll add a comment here.