yet another coldfusion blog

In part II of Advanced Plugin Development for the Mura CMS we looked at a basic FW/1 plugin framework that used SubSystems as display objects.  In Part III we are going to discuss integrating a datasource and ColdSpring into your plugin.  This datasource could be one that is completely separate from your Mura DSN, or it could involve custom tables within the Mura DSN itself.  I should note that this tutorial isn't going to include creating your datasource upon plugin installation, as that will be part of a future tutorial (and contains Mura code that I'll have to get permission for sharing).  Also, the example code in the ColdSpring beans is currently setup for use in a MySQL database ... if you are working with a different type of database you will have to massage the queries in the ColdSpring CFC's a little bit.

To follow along, you should download and install the APD III plugin (bottom of post) into an updated version of Mura CMS.  Next add this table to a datasource that ColdFusion will have access to:

CREATE TABLE `color` ( `colorID` int(10) unsigned NOT NULL AUTO_INCREMENT, `color` varchar(45) NOT NULL, PRIMARY KEY (`colorID`) ); INSERT INTO `color` (`colorID`,`color`) VALUES (1,'Blue'), (2,'Green'), (3,'Orange'), (4,'Red'), (5,'Purple'), (6,'Pink'), (7,'Blue'), (8,'White'), (9,'Black'), (10,'Yellow');

Mura Plugins and a Datasource

Incorporating a datasource into your plugin involves a couple of steps. We're going to be using five arguments for our DSN: type (i.e. MySQL or MS SQL), name, username, password and prefix (the last being important if you are putting your custom tables in an existing DSN, such as your Mura install).

First, if you have added custom tables to the existing Mura install, you will be able to use the DSN settings that were created when Mura was installed. In this case, we can access the DSN settings using the Mura scope:

$.globalConfig().getSetting('datasource') $.globalConfig().getSetting('dbusername')

If you are adding tables to your Mura DSN, I highly recommend you prefix them with something unique, i.e. "pluginX_".  This way you won't have to worry about future updates to Mura or other plugins creating table conflicts.

If the datasource is external to your Mura DSN, you will need to let users identify the datasource and its particular attributes. This is easily done in the setup process by including a few settings attributes in the /plugin/config.xml document:

<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^mssql</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>

This will add the settings for DSN type (MySQL/MSSQL), name, username, password and prefix. These settings fields will appear whenever a user is installing or updating your plugin.  Note that this is only necessary when your datasource is external to your Mura DSN.  I would personally recommend having your datasource external, if only to keep your plugin more portable and isolated, but this isn't always possible.

ColdSpring

The next step in integrating our database is to make sure our ColdSpring beans have the information needed to access it.  To do this in our example plugin, I use the FW/1 setupApplication() function in the Application.cfc (/myuplugin/Application.cfc):

<cffunction name="setupApplication" output="false"> <cfset var beanFactory = "" /> <cfset var coldspringXml = "" /> <cfset var coldspringXmlPath = "" /> <cfset var displayPath = "" /> <cfset var defaultProperties = StructNew()> ... <cfset coldspringXmlPath = "#expandPath('/plugins')#/#variables.pluginConfig.getDirectory()#/coldspring/coldspring.xml.cfm" /> <cfif fileExists( coldspringXmlPath )> <!--- read in coldspringXml ---> <cffile action="read" file="#coldspringXmlPath#" variable="coldspringXml" /> <!--- parse the coldspringXml and replace all [plugin] with the plugin mapping path, and |plugin| with the physical path ---> <cfset coldspringXml = replaceNoCase( coldspringXml, "[plugin]", "plugins.#variables.pluginConfig.getDirectory()#.", "ALL") /> <cfset coldspringXml = replaceNoCase( coldspringXml, "|plugin|", "plugins/#variables.pluginConfig.getDirectory()#/", "ALL") /> <!--- set the default values ---> <cfset defaultProperties.dsn = variables.pluginConfig.getSetting( "dsn" )> <cfset defaultProperties.dsnusername = variables.pluginConfig.getSetting( "dsnusername" )> <cfset defaultProperties.dsnpassword = variables.pluginConfig.getSetting( "dsnpassword" )> <cfset defaultProperties.dsnprefix = variables.pluginConfig.getSetting( "dsnprefix" )> <cfset defaultProperties.dsntype = variables.pluginConfig.getSetting( "dsntype" )> <!--- build CS factory ---> <cfset beanFactory=createObject("component","coldspring.beans.DefaultXmlBeanFactory").init( defaultProperties=defaultProperties ) /> <!--- load beans ---> <cfset beanFactory.loadBeansFromXmlRaw( coldspringXml ) /> <!--- set the FW/1 bean factory as our new ColdSpring bean factory ---> <cfset setBeanFactory( beanFactory ) /> <!--- push the ColdSpring factory into plugin application scope ---> <cfset variables.pluginConfig.getApplication().setValue( "beanFactory", beanFactory ) /> </cfif> ... </cffunction>

If you are using the Mura DSN, the setup is slightly different:

<cffunction name="setupApplication" output="false"> ... <!--- set the default values ---> <cfset defaultProperties.dsn = $.globalConfig("datasource")> <cfset defaultProperties.dsnusername = $.globalConfig("dbusername")> <cfset defaultProperties.dsnpassword = $.globalConfig("dbpassword")> <cfset defaultProperties.dsntype = $.globalConfig("dbtype")> <!--- identify the prefix you used! ---> <cfset defaultProperties.dsnprefix = "PluginX_"> ... </cffunction>

Note that for the "dsnprefix" you could still use the /plugin/config.xml" settings to identify this value.

Next, our actual ColdSpring file:

<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd"> <beans default-autowire="byName"> <bean id="Utility" class="[plugin]com.grantshepert.adp.utility.utility"> </bean> <bean id="ColorDAO" class="[plugin]com.grantshepert.adp.color.ColorDAO"> <constructor-arg name="dsn"><value>${dsn}</value></constructor-arg> <constructor-arg name="dsnusername"><value>${dsnusername}</value></constructor-arg> <constructor-arg name="dsnpassword"><value>${dsnpassword}</value></constructor-arg> <constructor-arg name="dsnprefix"><value>${dsnprefix}</value></constructor-arg> <constructor-arg name="dsntype"><value>${dsntype}</value></constructor-arg> </bean> <bean id="ColorGateway" class="[plugin]com.grantshepert.adp.color.ColorGateway"> <constructor-arg name="dsn"><value>${dsn}</value></constructor-arg> <constructor-arg name="dsnusername"><value>${dsnusername}</value></constructor-arg> <constructor-arg name="dsnpassword"><value>${dsnpassword}</value></constructor-arg> <constructor-arg name="dsnprefix"><value>${dsnprefix}</value></constructor-arg> <constructor-arg name="dsntype"><value>${dsntype}</value></constructor-arg> </bean> <bean id="ColorService" class="[plugin]com.grantshepert.adp.color.ColorService"> <constructor-arg name="ColorDAO"> <ref bean="ColorDAO"/> </constructor-arg> <constructor-arg name="ColorGateway"> <ref bean="ColorGateway"/> </constructor-arg> </bean> </beans>

There are a couple of Mura-specific items in here.  The use of [plugin] (and |plugin|) are needed to integrate the base Mura path into your CFC calls.  If you look at the code in the Application.cfc, above, you will see that [plugin] is replaced with the relative CFC-mapped path, and that |plugin| is replaced with a physical path (useful for AOP).

That should be about it! If everything is set up correctly, you should be able to go to the APD Example III plugin in your Mura install and see the following (for reference this page is generated by the FW/1 SubSystem 'admin' using '/admin/controllers/main.cfc' & '/admin/views/main/default.cfm'):

Conclusion

Adding your own datasource and the powerful ColdSpring bean factory ... or any bean factory, for that matter ... will definitely increase the magnitude of what you can accomplish with Mura plugins, as well as making them more flexible and extensible.  You might also want to read my PluginConfig and PluginApplication post for using the PluginApplication as your plugin's bean factory.

Hopefully I haven't missed anything in the "Datasource & ColdSpring" overview of Advanced Plugin Development for the Mura CMS, but if I have an exploration of the example plugin should answer your questions.

Download: APD III Example Plugin