Never alter the Mura CMS core.
If you've ever gone through one of our training courses, you have heard our instructors utter this line. Multiple times, would be my guess. It is the most important tenant of developing inside of Mura CMS: do not break the Mura CMS upgrade path! This happens when you alter a template or component that is part of the Mura CMS core, i.e. the base code that is the lifeblood of Mura CMS. By altering any core files directly, you break the ability to auto-update Mura CMS as it is possible your changes would be overwritten. This is an unenviable position to put yourself in, as you will lock yourself out of the latest and greatest the Mura has to offer.
The good news is, you will never have to put yourself in this position! Mura CMS has multiple ways of allowing you to customize, extend and replace base functionality. The custom templates folder, themes, and the event model are all available to you, as are plugins. It is this last feature that we are going to examine in detail, across a number of blog posts. The series is planned as follows:
Plugins are 'encapsulated' i.e. self-contained applications that are designed to integrate into the Mura CMS platform. They allow developers to extend base Mura functionality in the administrator or front end, or add a whole new set of functionality. There is really no limit to the size and scope of a plugin, and many very large scale applications have been built upon Mura CMS in this way.
Plugins have several advantages, chief among them being:
The most basic Mura CMS plugin involves only two files. The example file structure of a very basic plugin would look like this:
The index.cfm page will become the landing page for the plugin's administrator (in other words, when you are in the Mura admin section, if you go to the plugin it will be this page that is loaded).
As an example, you could put a welcome message in here, as in:
Welcome to my first plugin!
We can also get a little "fancy" by wrapping our welcome message inside the Mura CMS administrator, like so:
<cfscript> // get the current siteid mySiteid = StructKeyExists(session, 'siteid') ? session.siteid : 'default'; // get the Mura scope $ = StructKeyExists(request, 'muraScope') ? request.muraScope : application.serviceFactory.getBean('muraScope').init( mysiteid ); // get my plugin's configuration myPluginConfig = $.getBean('pluginManager').getConfig("MyFirstPlugin"); </cfscript> <cfoutput> <cfsavecontent variable="mybody"> <p>Welcome to my first plugin!</p> </cfsavecontent> #$.getBean('pluginManager').renderAdminTemplate(body=mybody,pageTitle=myPluginConfig.getName())# </cfoutput>
The config.xml.cfm page is the configuration information for the plugin. Here's an example of what it might contain:
<plugin> <name>My First Plugin</name> <package>MyFirstPlugin</package> <directoryFormat>packageOnly</directoryFormat> <provider>Grant Shepert</provider> <providerURL>http://www.blueriver.com</providerURL> <loadPriority>5</loadPriority> <version>0</version> <category>Application</category> <customtagpaths /> <mappings /> <settings /> <eventHandlers /> <displayobjects /> <extensions /> </plugin>
Let's take a look a the basic settings:
We'll look at the other config settings in future posts.
That's it! Admittedly the plugin isn't going to do much other than welcome people, but it's a start. To make this an installable plugin, you simply have to 'zip' up the files, ensuring that the index.cfm is in the zip root, and then choose Modules > Plugins > Add Plugin in the Mura CMS administrator and install the plugin.
In my next post I'll be discussing some of the other installation options like adding a licensce agreement and install/update/delete functionality. I'll also be adding a number of Mura CMS integration points, including display objects (which let you render content on the front end), events (which let you tap into Mura CMS functionality like saving pages or filling out forms), adding class extensions, and more.