yet another coldfusion blog

As a brief sidebar in my Advanced Plugin Development series I'm going to explore the PluginConfig and PluginApplication objects, two very essential components in developing your Mura plugins. The "best practices" methodology of accessing PluginConfig has also recently changed, so if you are developing plugins there are a few important bits of information in here. Also, make sure you've read or have a copy of the programmer's guide to Mura CMS handy as I'll be referring to that document occasionally.

PluginConfig

PluginConfig is the configuration object for your Mura plugins. First, it contains the base configuration information for your plugin (i.e. the settings that an admin would have entered when installing your plugin). For instance, if I dumped out the results of PluginConfig.getSettings() in my Meld Gallery plugin, I'd see:

PluginConfig has a very rich and deep set of functions as well. I'm certainly not going to go through them all, but some of the more fequently used ones will be:

• getDirectory(): your plugin's installed directory name
• getPackage(): the package name for your plugin
• getPluginID()
• addEventHandler()/removeEventHandler(): which allows you to add/remove event handler's (apart from "onApplicationLoad", I would recommend using this rather than hard-coding your events into your /plugins/config.xml)
• getApplication(): your PluginApplication object (see below), and where your plugin's application-scoped information can reside
  
• getSession(): a session-specific version of the PluginApplication object

I'd suggest using good old <cfdump> to explore your PluginConfig, as this will reveal all sorts of goodies.

PluginApplication

At first it might appear that PluginApplication is just an object for getting/setting your plugin's application-wide variables, but there is much more to this little gem.

As mentioned above, one way to get your PluginApplication object is using PluginConfig.getApplication(). This gives you a thread safe getValue()/setValue()/getAllValues() function set for managing your plugin's Application-scoped variables. The same is true for the when using PluginConfig.getSession() (which returns an instance of the PluginApplication object in the current session scope).

Also, PluginApplication includes a lightweight auto-wiring mechanism similar to ColdSpring. The details of this can be found in the programmer's guide to Mura CMS (under "Session and Application Object Autowiring", I won't quote a page since this will have likely changed by the time you read this blog). I'll explore this in a little more depth in a moment.

Accessing and Maintaining PluginConfig

This is a recently 'refreshed' topic in the Mura plugin realm, one that was becoming urgent as more sophisticated plugins are being developed for Mura. The previous/current method is to use the request.pluginConfig variable that is created in the current set of "base" Mura plugin examples. The problem with this is it quickly sets up a "wild west" scenario where plugin's are stepping on top of each others configurations.  In a recent conversation with Matt of Blue River, he noticed this behavior in a set of plugins we're developing at Meld Solutions and quickly came up with a solution to resolve this using PluginApplication.  I in turn looked through his updates/examples and developed a version of this when working with ColdSpring.  The results of this work are as follows:

PluginConfig via PluginApplication Auto-Wiring

This example builds upon the standard Mura FW/1 "Hello World" plugin.  This method relies upon using PluginApplication as the bean factory for your application (again, this is detailed in the programmer's guide to Mura CMS docs).

First, make sure you are using a recent version of Mura (5.2.2381 or later).  Next, install the base "Hello World" plugin.  Open the plugin's Application.cfc, and modify the code to set your FW/1 bean factory to use PluginApplication (/Application.cfc):

<cffunction name="setupApplication" output="false"> <cfif not structKeyExists(request,"pluginConfig")> <cfinclude template="../../config/settings.cfm"> <cfinclude template="plugin/config.cfm" /> </cfif> <!--- ADD THE LINE BELOW ---> <cfset setBeanFactory(request.pluginConfig.getApplication())> </cffunction>

The next step is to update our FW/1 controller (/controllers/main.cfc):

<cfcomponent extends="mura.cfobject" output="false"> <!--- initialize our variables ---> <cfset variables.pluginConfig=""> <cfset variables.userManager=""> <!--- FW/1 auto-wiring in conjunction with PluginApplication will wire this up for us automatically ---> <cffunction name="setPluginConfig" output="false"> <cfargument name="pluginConfig"> <cfset variables.pluginConfig=arguments.pluginConfig> </cffunction> <!--- using the FW/1 "before" function ensures this runs before any of our other service functions, ensuring variables.pluginConfig is in our request context (rc) ---> <cffunction name="before" output="false"> <cfargument name="rc"> <cfset rc.pluginConfig=variables.pluginConfig> </cffunction> </cfcomponent>

A couple things are happening here.  First we are using setPluginConfig() to allow FW/1 to auto-wire our PluginConfig into our FW/1 application.  Second, using the FW/1 "before" function puts the PluginConfig into our request context so that we can use it in our FW/1 application.

PluginConfig with ColdSpring

This second example builds upon the Meld Gallery example from my Mura Plugin series.  I've updated that download to use this methodology, so if you download it you will see the following changes already in place.

The PluginApplication example illustrated above does work perfectly, but if you need (or prefer) to use ColdSpring or a bean factory other than Mura's, hope is not yet lost.  One way to resolve this is simply to extend the FW/1 application by adding PluginConfig to our application scope

Where Matt used PluginApplication as his FW/1 bean factory, that option isn't available to me as I want to instead use ColdSpring.  To accomplish this I have added the following to Application.cfc:

<cfcomponent extends="framework" output="false"> <cffunction name="setupApplication" output="false"> ... <!--- ensure that we have PluginConfig in the request scope, and that it is 'ours' ---> <cfif not structKeyExists(request,"pluginConfig") or request.pluginConfig.getPackage() neq variables.framework.applicationKey> <cfinclude template="plugin/config.cfm" /> </cfif> ... <!--- set the pluginConfig for our plugin into the fw1 application scope ---> <cfset setPluginConfig( request.pluginConfig )> ... </cffunction> <!--- this is not auto-wired, we set it manually in setupApplication() ---> <cffunction name="setPluginConfig" output="false"> <cfargument name="pluginConfig" type="any" required="true"> <cfset application[ variables.framework.applicationKey ].pluginConfig = arguments.pluginConfig> </cffunction> <cffunction name="getPluginConfig" output="false"> <cfreturn application[ variables.framework.applicationKey ].pluginConfig> </cffunction> </cfcomponent>

Here I have added a set of setPluginConfig()/getPluginConfig() functions to Application.cfc.  These set the PluginConfig into the same FW/1 application-scoped structure that FW/1 resides in.  Because FW/1 is based upon the Application.cfc, this essentially makes the functions part of FW/1.  By calling setPluginConfig() function in setupApplication(), we are ensuring that the PluginConfig object is *our* PluginConfig object.

In our FW/1 controller, we do pretty much the same thing as the previous example (/main/controllers/controller.cfc):

<!--- this central controller must be extended by all section controllers ---> <cfcomponent displayname="controller" output="false" extends="mura.cfobject"> <!--- do not remove the init ... it is crucial ---> <cffunction name="init" access="public" returntype="any" output="false"> <cfargument name="fw" type="struct" required="false" default="#StructNew()#"> <cfset variables.fw = fw /> <cfreturn this /> </cffunction> <!--- runs before every controller request ---> <cffunction name="before" access="public" returntype="void" output="false"> <cfargument name="rc" type="struct" required="false" default="#StructNew()#"> ... <cfset rc.pluginConfig = fw.getPluginConfig()> ... </cffunction> </cfcomponent>

In the "init()" I establish access to the FW/1 application via variables.fw (this is a standard FW/1 practice).  In my "before()" function, I use my new fw.getPluginConfig() function to set PluginConfig into my request context (rc).

This example gives you the same results, but I still have my ColdSpring bean factory.  If I need PluginApplication, I can still easily access this via PluginConfig.getApplication().

Conclusion

So, there's an introduction to PluginConfig and PluginApplication, and a few methodologies for accessing PluginConfig in a thread-safe manner. As mentioned, I've already updated the "Part I" Meld Gallery example to use the new (second) method.

Downloads

MeldGallery "Core" Installable Plugin Base (Part I)