yet another coldfusion blog

After many requests (and a few promises) I am finally putting together a series of blog posts on building a complex plugin for the Mura CMS. Plugins are basically stand-alone applications that take advantage of Mura's extensibility hooks to integrate themselves into the CMS and web site. This feature set has matured greatly over the last year, and allows developers a great deal of latitude over how they can achieve this and in what tools they can use. This series of posts will be as much about building the plugin as introducing developers to the many facets of Mura extensibility.

In this series I'm going to explore in depth the topic of building a plugin that integrates directly into the Mura CMS. Specifically, I'll be building the Meld Gallery application using FW/1 and ColdSpring. Once complete, the plugin will include the following functionality:

• The ability to install the plugin (including its database) into any current version of Mura
• The ability to upload images and arrange and organize them into any number of image "sets"
• The ability to display these image "sets" in a wide variety of formats via configurable "displays"
• The ability to easily build and add custom "displays" to the plugin (i.e. jQuery slide shows, Flash slide shows, ShadowBox ... you get the picture)
  

The process will expose developers to some of the more intricate details of Mura plugin development, including the PluginManager and general Mura API, the creation of configurable display objects, use of Mura events (broadcast and interception), and the process of building an installable plugin that requires a database. It should offer something to anybody interested in developing plugins for Mura, but generally the more experience you have with ColdFusion, FW/1 and ColdSpring the more you will get out of it.  Also, you may want to review the programmer's guide to Mura CMS.

What this series won't do is explore FW/1 or ColdSpring in any depth beyond how they apply specifically to the plugin. Just as important, I should note that this is not intended to be an 'introductory' series, as several good resources already exist on that topic. Instead, I will be discussing the actual process far more than the code itself, though everything in the downloadable examples will be heavily commented.

Finally, Meld Gallery will be a fully functional application when it is complete, licensed under the GPL 2 license. It will be licensed this way because it will be using code from the Meld Solutions Meld Manager plugin.

The Core

The beginning of our new Meld Gallery plugin is going to be based upon what I call the "core". This is essentially an installable, empty plugin that includes all of the foundation elements that I will be building upon (download the core for MeldGallery). The core we will be working with is based upon the FW/1 plugin template originally developed by Bob Silverberg and the Mura team. Typically I begin creating a new plugin by:

1. Copying the blank 'core' plugin to a new directory (Directory A)
   
2. Updating the basic identity/name settings for the plugin
3. 'Zipping' up the entire contents of the directory (this creates my installable plugin package)
   
4. Installing this into a current, virgin copy of Mura
5. Making the directory of the newly installed plugin (Directory B) my work environment for the project (it should be found in /[mura]/plugins/MeldGallery_1/ or similar)
   
6. Deleting the original directory (Directory A) as it will no longer be used
   

This allows you to start your development in a working environment that you can immediately test and play with. Now, there is one very important issue with doing you development this way: the dreaded "delete plugin" button. The thought of having a single, easily clickable button that can nuke all of my hard work is disconcerting, so I typically either a) delete the 'delete' link or b) delete the 'delete me' code in the PluginManager function. Also, the best practice of using version control like SVN or Git will protect your work should the worst happen.

Identity

To establish the unique identity for your plugin, there are several files you will have to update. The first, config.xml, is found in the /plugin directory. If you open this page, you will find the following block of code at the top (/plugins/config.xml):

<plugin> <name>Meld Gallery</name> <package>MeldGallery</package> <loadPriority>5</loadPriority> <version>0.1</version> <provider>Meld Solutions Inc.</provider> <providerURL>http://meldsolutions.com</providerURL> <category>Application</category> ... </plugin>

The most important value to remember is the Package value. The Package value is the unique identifier for your application, and we will refer to it many times in our code to identify both our application in the Mura Scope as well as the 'root' for our application.

Below this you will also see a series of settings (/plugins/config.xml):

<plugin> ... <settings> <setting> <name>dsntype</name> <label>Database Type</label> <hint>The type of database</hint> <type>select</type> <required>true</required> <validation></validation> <regex></regex> <message></message> <defaultvalue>mysql</defaultvalue> <optionlist>mysql^mssql</optionlist> <optionlabellist>MySQL^MS SQL</optionlabellist> </setting> <setting> <name>dsn</name> <label>Datasource</label> <hint>Enter the name of the *existing* datasource you will use for the plug-in</hint> <type>text</type> <required>true</required> <validation></validation> <regex></regex> <message></message> <defaultvalue></defaultvalue> <optionlist></optionlist> <optionlabellist></optionlabellist> </setting> <setting> <name>dsnusername</name> <label>Datasource username</label> <hint>Username for the plug-in datasource</hint> <type>text</type> <required>true</required> <validation></validation> <regex></regex> <message></message> <defaultvalue></defaultvalue> <optionlist></optionlist> <optionlabellist></optionlabellist> </setting> <setting> <name>dsnpassword</name> <label>Datasource password</label> <hint>Password for the plug-in datasource</hint> <type>text</type> <required>true</required> <validation></validation> <regex></regex> <message></message> <defaultvalue></defaultvalue> <optionlist></optionlist> <optionlabellist></optionlabellist> </setting> <setting> <name>dsnprefix</name> <label>Datasource Table Prefix</label> <hint>Add a prefix to the table names. (optional)</hint> <type>text</type> <required>false</required> <validation></validation> <regex></regex> <message></message> <defaultvalue></defaultvalue> <optionlist></optionlist> <optionlabellist></optionlabellist> </setting> </settings> ... </plugin>

These settings are in the 'core' because they provide the five key values we will use in connecting to our database. DSNType is used in our code to customise our queries to the appropriate engine, DSNPrefix lets users install the plugin's database tables in an existing DSN without having to worry about over-writing existing tables, and the rest of the values are for the DSN identity/permissions. The final block of code in the config.xml that is key is the onApplicationLoad event handler. This initiates the setup for our FW/1 plugin, and really is the only event that has to be hard-coded into our setup.

The next file we have to alter is the configuration settings at the top of the /Application.cfc file (/Application.cfc):

<cfscript> variables.framework = { applicationKey = "MeldGallery", base="/MeldGallery", home="main.default", usingsubsystems=true, defaultSubsystem = 'main', action="action", reload = 'reload', reloadApplicationOnEveryRequest=true }; </cfscript>

You will notice that the applicationKey and Package values are identical; this is crucial. The "base" value is the basically the root mapping for our plugin and again is based upon the Package value. Now, our plugin might not use "SubSystems", but for the purpose of this series we are going to assume that we are. These can be handy for isolating your display objects, for making your plugin itself more modular, and just generally for organizing your plugin application code. Finally, we have set reloadApplicationOnEveryRequest to 'true' so that our changes during development will be reflected immediately.

Packaging & Install

You can now go ahead and install this plugin in your Mura site. To create the "installable" package, select all of the files/directories in the plugin directory (i.e. everything inside of MeldGallery) and zip it up into a Zip archive. A very common mistake is to include the root directory as well, which will cause Mura to throw an error. In other words, in your zip file you should see /plugin, /assets, /Application.cfc etc. as opposed to a single directory that contains them.

Now that you have your install package, go to Mura Admin > Site Settings and click on the "Plugins" tab, then select and "Deploy" your plugin. The setup screen should display the values entered in the config.xml, and ask for your DSN information (you can fill out junk for now). Make sure and check off the "Default" site, then click "Update". The plugin is now installed!

SUGGESTED ACTION: at this time you should create your own 'core' plugin by renaming the values in the downloaded example and installing it into Mura.

Towards the Future

Admittedly we haven't covered much new ground so far, but have at least established the foundation we will be building upon. In the next post of the series I'll be putting the first part of the core ColdSpring service into place. The post will cover adding our base services, reviewing how they are integrated into the FW/1 framework, and taking a closer look at the Mura / FW/1 relationship. In the coming weeks we'll be adding a lot of functional code, remote proxies, resource bundles for internationalization, jQuery administrative tools, fully 'pluggable' and configurable display objects, and finally building our install package so that others can easily use our new application.

Downloads

MeldGallery "Core" Installable Plugin Base