Photo from Chile

Extending Mura CMS with Plug-Ins

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.

I just picked up your post on twitter and landed on this blog. I to have been hacking my way through the Mura CMS system for about 3 months now and have managed to decode much of the plugin methodology. This is an excellent article. We need more support behind Mura. Keep up the good work.
# Posted By Corvus382 | 6/24/09 12:38 PM
Great post, Bob! Thanks a lot for taking the time to do this. We'll be addressing those inconsistencies in the use of plug-in et al. Thanks for pointing them out. Look forward to seeing where you take this series. As always, if you need anything from us, let us know.
# Posted By Sean Schroeder | 6/24/09 1:20 PM
Very cool! I'm in the process of evaluating Mura and this is very helpful. I'm looking forward to more Mura related articles!
# Posted By Jose | 6/25/09 9:33 AM
Thanks, just getting started with Mura. Excellent system, but there's an awful lot to learn. Your article has really helped point me in the right direction.
# Posted By Jim Cumming | 9/23/09 5:49 AM
Great article. I'm very interested in the fact that entire model glue applications can be installed as plugins. Are there any examples of this anywhere that you know of? Specifically referring to a model glue app being installed as a plugin.


# Posted By Darren | 1/4/10 5:54 PM

I don't know of any existing examples of Model-Glue apps as plugins.
# Posted By Bob Silverberg | 1/4/10 11:10 PM

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.
# Posted By Bob Silverberg | 1/6/10 8:59 AM
I too would be interested in how one would implement a Model-Glue application (or an application using any CF framework) as a Mura plugin. In my own experience with the ColdBox framework, it wasn't too hard to integrate a ColdBox app into Mura as a COMPONENT (and I blogged about that here However, when I tried to make a Mura PLUGIN from a ColdBox app, I ran into issues that I still haven't resolved (although I haven't been working on it too hard due to other projects on my plate). Pat Santora from Blue River sent me some code for a separate plugin to integrate ColdBox applications into Mura, but I haven't been able to get it to work (been meaning to contact Pat about it). But it's not really what I was looking for, since it seems to me that plugin was made to integrate external stand-alone ColdBox apps into Mura, whereas my ultimate goal would be to package up a self-contained Mura plugin which uses the ColdBox framework (which is what it looks like Darren is looking for with Model-Glue).
# Posted By Tony Garcia | 1/6/10 1:37 PM
I've done this twice now and thought I would mention it here. I use WinRAR for my rar/zip application. When making a new plugin, I create a folder ("myPlugin"), setup the files, then I zip the "myPlugin" folder. When I try to load it Mura throws an error that it can't find my config file. It is looking in: /plugins/3/plugin/config.xml

however what it installed is: /plugins/3/myPlugin/plugin/config.xml

I went through the pluginManager.cfc file to see what it is doing. I see in the getConfigXml function that it is missing the package name in the string. At first I attempted to update that file to add the package name to the path, but then realized I could just zip my file differently. So I opened the "myPlugin" folder, selected all the files, right clicked and zipped it that way. It still makes a zip file named myPlugin, but now Mura made directory under the main plugins directory called 'myPlugin_4' and finds the file correctly.

So is this an issue others have come across or is this just an isolated issue with how WinRar zips folders of files? If other have the issue, should the pluginManager.cfc be updated to handle getting a folder with plugin files inside instead of a zip of just the root files? Thoughts?
# Posted By molaro | 5/20/10 12:13 PM
I just got Mura installed and I'm trying to integrate data from another database (property listings - search form and results/detail pages) whats the best approach? Plugin?
# Posted By Dusty Carr | 5/17/11 8:14 PM
@Dusty, I do believe that a plugin would be a good way to go. It seems like a nice way of encapsulating your new code without having to worry about future upgrades to Mura.

Having said that, I have unfortunately been away for Mura for some time (due to being busy with other things), so I may not be the best person to ask. You may want to try the Mura forums at
# Posted By Bob Silverberg | 5/17/11 8:29 PM
It depends on how you want to "integrate" the other information. If you want to intermingle outside data with Mura site content (ie pages you create in Mura), then perhaps a web service is a better way to go. You would make calls and pull in only the content you need when you need it.

If you want a section of your mura site that is all about your outside data, then yes a plugin is the way to go. Read Bob's series on setting up plugins. His posts are a really good resource for new plugin developers. If you use Eclipse, then install the Mura Tools as well. They give you 3 menu items to generate the plugin files and then to bundle them once you're done. Also, if you've never developed a plugin before, one obvious/not-so-obvious trick is to install a plugin shell (default folders/files) and then start developing on the installed files. That way you can literally load your plugin over and over in your site as you develop to see if things work or not.

Finally, just because your data is on a different database doesn't mean you can't use it in Mura. You can still make query calls to outside databases as long as you have the datasource. Just keep in mind that you would not be able to directly use it in built in Mura displays such as Portals, Galleries or Feeds. I say directly, because you could always call your data, build it into objects that mimic native Mura objects and pass those into a custom display to simulate a Portal, or whatever. I've done that before for navigation menus. It works but is sometimes a big pain.

Hope that helps.
# Posted By molaro | 5/17/11 8:41 PM