Photo from Chile

Extending Mura CMS with Plug-Ins - Part II - Hello World

In my previous post about Extending Mura CMS (an open source ColdFusion CMS) with plugins, we looked at what plugins are and how one creates and installs a plugin. In this post we'll look at a very simple plugin, and then add new features to the plugin in future posts.

There are already a couple of sample plug-ins that can be found on the Mura site. This example is loosely based on the Hello World example found there. This simple plugin won't do anything useful (yet), it will simply display the message "Hello World" on a page. So let's get started.

You may recall from the previous post that a plugin is simply a folder of files that has been zipped up, so to start our plugin we'll create a new folder, called "HelloWorld1". Inside this folder we'll create three new folders:

  • plugin
  • displayObjects
  • eventHandlers

The plugin folder will contain files that Mura needs to install your plugin, the displayObjects folder will contain files that generate output that your plugin provides and the eventHandlers folder will contain files that describe different actions that your plugin will perform when certain events fire. As mentioned in the previous article, this structure (the displayObjects and eventHandlers folders) is not mandatory, but I think it provides a good illustration of the fact that, at a basic level, a plugin is able to do two things:

  1. Display output
  2. Perform actions

Many plugins will be designed to display output. For example, you may want to include a summary of what is in a user's shopping cart on each page, or provide a news ticker. The plugin architecture will allow you to create a display object in your plugin, and then use Mura's Site Manager to define where that content should appear in your CMS rendered pages.

As your plugins get more complex, you will also want them to perform actions to respond to certain events. There is a long list of events that your plugin can respond to, some examples are:

  • onApplicationLoad - You would use this if your plugin needs to initialize itself when Mura is loaded or reloaded.
  • onGlobalRequestStart - You would use this if your plugin needs to perform some action (e.g., setting a variable) whenever a request is started.
  • onRenderStart - You would use this if your plugin needs to perform some action just before the content is rendered by Mura. You can use this to change the way that Mura renders your page, while having access to all of the content that is about to be rendered.

There are a lot more events available, and I imagine that new ones will being added as identified. The bottom line is that there are a whole lot of "plugin points" that you as a developer can hook into, which allow you to control and change the way that Mura behaves.

In our simple HelloWorld plugin we don't need to respond to any events, so we won't be putting anything into the eventHandlers folder. All we need is a single display object, which will display our message to the world. So let's create a file in the displayObjects folder called dspHelloWorld.cfm. That file will contain the following super complicated code:

view plain print about
1<h1>Hello World!</h1>

Next we have to let Mura know that we have a display object for it. We do that by defining a display object in our config.xml file, so let's create that now. We'll create a file called config.xml in the plugin folder, which will contain the following code:

view plain print about
2    <name>Hello World Plugin Step 1</name>
3    <package>HelloWorldPluginStep1</package>
4    <version>1.0</version>
5    <provider>SilverWare Consulting</provider>
6    <providerURL></providerURL>
7    <category>Sample Application</category>
8    <settings>
9    </settings>
10    <displayobjects location="global">
11        <displayobject name="Hello World Message"
12            displayobjectfile="displayObjects/dspHelloWorld.cfm"/>

13    </displayobjects>

The first set of elements in the xml file (everything from name to category) define the settings for your plugin. Let's take a moment to walk through them:

  • name is the name of your plugin. This is how it will appear in the list of installed plugins that you see via Site Settings in the Mura Administrator.
  • package is used to name the directory where the plugin gets installed by Mura. Mura will create a new directory for each plugin that you install, using the package name and appending a number to it. This makes it easier to find your plugin's directory after it has been installed. It also means, however, that you cannot count on the plugin being installed to a specific location (because of the numeric portion). If your plugin needs to know where it is installed there are a number of ways of doing that, which I plan to cover in a future post.
  • version is the version number of your plugin.
  • provider is you, silly. This will appear both in the listing of installed plugins and on the Plugin Setting page in the Mura Administrator.
  • providerURL is a URL that points to your web site. It too will appear both in the listing of installed plugins and on the Plugin Setting page in the Mura Administrator.
  • category can be used to describe the type of plugin that you have created. From what I can tell this is only used for display purposes (again both in the listing of installed plugins and on the Plugin Setting page) and does not affect how Mura interacts with your plugin. I suppose it would make managing plugins easier if you had a large number installed.

The next section consists of the settings element, which would include any user-customizable settings that your plugin would provide. As we don't have any of those we'll leave that element empty for now.

The final section in this file is the displayobjects element, which is where you tell Mura what display objects your plugin will make available. In our example, as all we're doing is displaying a message, we have one display object, so there is one displayobject element inside the displayobjects collection. We give our display object a name, in this case "Hello World Message", and we tell Mura where in our plugin structure it can find the code that generates the output for the display object. In this case the code is in displayObjects/dspHelloWorld.cfm, which is the file that we created above.

I mentioned in the previous article that, in addition to the config.xml file we need two other files in our plugin folder; config.cfm and plugin.cfc. After speaking with Matt Levine about the purpose of and need for these files, I must now correct myself and state that neither of those files is actually required. Here's a brief description of what purpose they serve:


This is an optional file that one may choose to include (via a cfinclude tag) into one's plugin if one is creating a plugin with an administrative interface. In this Hello World sample plugin there is no administrative interface, so this file is not needed. Later on in the series, when we look at creating a plugin with an administrative interface we'll look more closely at this file.


This file defines actions that are to be performed when the plugin itself is altered via the Mura Administrator. For example, if you need to perform an action, such as copying files to a specific location, or running a query to update a database table, when your plugin is installed, you'd define those actions in the install function of this component. Actions that should be performed whenever your plugin is updated would reside in the update function, and actions that should be performed when your plugin is deleted would reside in the delete function. Because our simple plugin does not require any of those actions to be performed we can leave this component out of our plugin package.

Note, however, that the requirement for the plugin.cfc file was dropped in a recent version of Mura (version 5.1.542 to be exact). If you are running an older version, you will still need to include a plugin.cfc file in your plugin folder, and it will need to contain the following minimum of code in it:

view plain print about
1<cfcomponent output="false">
3<cfset variables.config=""/>
5<cffunction name="init" returntype="any" access="public" output="false">
6    <cfargument name="config" type="any" default="">
7    <cfset variables.config = arguments.config>
10<cffunction name="install" returntype="void" access="public" output="false">
13<cffunction name="update" returntype="void" access="public" output="false">
16<cffunction name="delete" returntype="void" access="public" output="false">

The final file that we need in our plugin structure is an index.cfm file which will sit in the root of our folder structure. We'll create one with the following code:

view plain print about
1This is the HelloWorld Plugin. It doesn't do much. Thanks for taking a peek.

This file, the index.cfm in the root, is what will be executed when an administrator clicks on the plugin's name from the list of installed plugins. You can put anything you want in here, such as a message, credits, instructions for the plugin, etc. You could even make it the entry point for an entire application (for example a Model-Glue application), if you want that application to be available to the administrator.

So that completes our simple plugin. At this point you should have a directory structure resembling the following:

To create a plugin that you can deploy into Mura, just zip up the entire contents of the HelloWorld1 folder. You can then follow the instructions in the previous post to deploy the plugin into an existing Mura installation. Once that's done you can use the display object in any of your pages. How, you ask? Read on.

Go to the Site Manager in the Mura Administrator and choose a page to edit. When you are editing the page, choose the Content Objects tab. You should see a select box that reads "Select Object Type". Choose Plugins, and the select box should populate with display objects from any plugin that is currently installed in your site. You should see a heading (an optgroup, in fact) in the select box for Hello World Plugin Step 1, and below that you should see an item for Hello World Message. Choose that and use one of the buttons to place it into one of your content areas and then click the Publish button. If you now view the page that you just edited you should see the Hello World message in the content area that you specified.

And that's pretty much all there is to it. Of course, this sample plugin doesn't do anything interesting yet, but we'll build upon it in future posts, exploring some of the ways that we can make plugins that are a lot more useful.

If you want to try out this plugin without having to create folders and type code, a complete copy of the plugin zip file is attached to this post.

I just want to close by saying that I think that Mura really is a very well designed product. I've been building a plugin that will be replacing an entire e-commerce site and I've had a number of pretty complicated requirements to fulfill. I have yet to come across a use case that I cannot address with Mura and its plugin architecture.

Bob, this is great, thanks a bunch for sharing! I just starting using Mura CMS a couple months ago and I'm really liking it so far. I haven't had time to get to the more interesting use cases where I'll be integrating much more customized app behavior, but it's very promising to hear such good reviews like this.

If you're not already aware, Clever Technology has shared some info on Mura plugins as well, both on the company blog and on Grant Shepert's blog:
# Posted By Jamie Krug | 8/4/09 9:25 PM
Yeah, so far I'm really liking working with Mura. Thanks for those links.
# Posted By Bob Silverberg | 8/4/09 10:55 PM

Thank you very much for this series... I have been DYING to implement other open source CF applications into Mura (like, and this is getting me closer and closer.

I am really interested in the next post where you mention you will be talking about incorporating an admin interface.

Keep em coming!

# Posted By Ronnie | 9/16/09 4:47 PM
Great post. I am still confused about whether I should be using a plugin, a Component, or a Content Collection in order to create a db driven master/detail pages.
# Posted By JP Revel | 9/30/09 6:22 PM
Thanks Bob. I can't wait for the next part to this series which will hopefully dive into integration with the Mura admin!


# Posted By Brian H. | 11/27/09 12:09 AM
To anyone who subscribed to this post and is eagerly awaiting the next instalment, I'm sorry that I've left it so long between posts. I do hope to pick up this series again in the future, but right now I have a bunch of unrelated stuff on my plate, some of which I have been blogging about, and some of which I hope to blog about sometime soon.
# Posted By Bob Silverberg | 11/27/09 12:16 AM
Thanks Bob. This was a big help for me.
# Posted By Jonathan | 12/15/09 2:20 PM
Can I add a plugin as a coponent? I want to move
my plugin to the top of my content object. Right now it appears
at teh bottom. I was thining if I could add a plugin in a
component I could put it in my content object.
# Posted By Jonathan Perret | 12/16/09 10:16 AM
@Jonathan: I don't believe you can add a display object from a plugin into a component, but there are some more complex ways to access a plugin from a component.

I actually had to do the exact same thing, and what I did was to edit my content template and put a reference to the plugin in there. You can add code like:


into your template and it will then render that plugin display object at that exact location.
# Posted By Bob Silverberg | 12/16/09 12:27 PM
Thanks Bob. Another dumb question.

What is B877C041-1517-0AA5-64D89D1B6093D66F?
# Posted By Jonathan Perret | 12/16/09 2:03 PM
other thing I forgot was if I edit the template won't it show
up on every page? I only want this plugin to appear on a single
# Posted By Jonathan | 12/16/09 2:07 PM
That really long value is the id of the display object, which you can find by looking in one of Mura's database tables.

Regarding your second point, yes, that will only work if you want it to show up on every page that uses that template (which is what I needed).
# Posted By Bob Silverberg | 12/16/09 3:06 PM
I realise that this is an old post. But I wanted to know, is it possible to insert a plugin at a specific position on the page.

In your example we add it from the content objects tab and there is no way to specify the location of the object. Eg: top of page or in the middle.
# Posted By Mohit Nayak | 1/9/13 3:12 PM