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.
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?
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 http://www.getmura.com/forum/
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.