Seb Duggan

Following on from my previous post, I’ll now expand on the BasePlugin.cfc component provided with Mango 1.3.

BasePlugin.cfc contains a number of commonly used, unchanging functions which will remove the need to specify them every time you write a plugin.

These include getters and setters, preference handling and saving, and access to the plugin’s assets directory.

The easiest way to show you what’s going on is with an example. The following is a plugin handler cfc:

<cfcomponent extends="BasePlugin">

	<cffunction name="init" access="public" output="false" returntype="any">
		<cfargument name="mainManager" type="any" required="true" />
		<cfargument name="preferences" type="any" required="true" />
		
		<cfset setManager(arguments.mainManager) />
		<cfset setPreferencesManager(arguments.preferences) />
		<cfset setPackage("com/sebduggan/mango/plugins/examplePlugin") />
		
		<!--- Default preferences --->
		<cfset initSettings(
				myName = "Seb",
				favouriteBlogEngine = "Mango"
			) />
			
		<cfreturn this/>
	</cffunction>

	<cffunction name="setup" hint="This is run when a plugin is activated" access="public" output="false" returntype="any">
		<cfreturn "Plugin activated." />
	</cffunction>
	
	<cffunction name="unsetup" hint="This is run when a plugin is de-activated" access="public" output="false" returntype="any">
		<cfreturn />
	</cffunction>

	<cffunction name="handleEvent" hint="Asynchronous event handling" access="public" output="false" returntype="any">
		<cfargument name="event" type="any" required="true" />		
		<cfreturn />
	</cffunction>

	<cffunction name="processEvent" hint="Synchronous event handling" access="public" output="false" returntype="any">
		<cfargument name="event" type="any" required="true" />
		<!--- Plugin logic goes here --->
		<cfreturn arguments.event />
	</cffunction>

</cfcomponent>

This is the simplest of plugins, and doesn’t actually do anything! But it shows the structure nicely.

First, we extend the BasePlugin component. Because you can’t extend a component either by navigating up the directory tree, or by using a dynamic path, it is a requirement that a copy of BasePlugin.cfc be included in your plugin distribution. Here, it is located in the same directory as the plugin handler cfc.

You can find the current version of BasePlugin.cfc in {mango_root}/components/plugins/.

init()

The three set…() calls should be made at the start of the init() method. The first two set the manager components into the variables scope, which can then be retrieved with the corresponding get…() method.

setPackage() defines the XML path that will be used to store any preferences for the plugin.

You don’t need to set the plugin name or ID manually; these are set automatically using values from your plugin.xml file when the plugin is activated. BasePlugin.cfc contains getId() and getName() methods to retrieve these values.

Settings (plugin preferences)

initSettings() provides an easy way to provide default settings and retrieve stored ones. For example, here I am telling the plugin to retrieve stored settings for myName and favouriteBlogEngine – if no stored values are found, the defaults (”Seb” and “Mango”) will be used.

At any point in the plugin, you can access one of your settings using the getSetting() method. So:

<cfset favBlog = getSetting("favouriteBlogEngine") />

would return “Mango”.

If you wish to update settings, use the setSettings() method:

<cfset setSettings(
		myName = "Ray",
		favouriteBlogEngine = "BlogCFC"
	) />

This would set new values in the plugin’s memory; to save these, call persistSettings().

Plugin assets

BasePlugin.cfc also provides methods to return the paths for the directories where any auto-installed plugin assets have been stored. These methods should always be used rather than trying to work out the path for yourself.

getAssetPath() returns the publicly accessible assets directory: {mango_root}/assets/plugins/examplePlugin/

getAdminAssetPath() returns the private admin assets directory: {mango_root}/admin/assets/plugins/examplePlugin/

I hope these additions make it simpler for you to develop plugins for Mango – they’ve definitely made my life easier!