Seb Duggan

In Mango 1.3 the functionality of plugins has been extended to simplify matters for plugin developers.

The key new features are auto-installation, auto-copying of plugin assets files (scripts, images etc.) and a BasePlugin component with a bunch of useful functions in it.

Auto-installation

The Add-ons admin page now has the ability to install a plugin simply by entering its download URL.

Developers do not need to do anything special to take advantage of this – simply provide a URL to a .zip file containing your plugin.

The installer is intelligent about the structure of your zip archive. The plugin files can be at the root of your zip archive, or in a sub-directory; the installer looks within the archive for your plugin.xml file, and installs everything that’s in the same directory (including sub-directories). The destination directory is determined from the plugin class attribute in plugin.xml.

Plugin updating: if the plugin is already installed, it will be de-activated, the new version installed, and then reactivated (if the plugin was originally inactive, it will remain so).

Plugin version checking: the installer will only update a plugin if it has a higher version number than an existing version of the plugin. So, if you update your plugin, make sure you update the version number in plugin.xml!

Mango version checking: the installer checks your current version of Mango against the requiresVersion attribute in plugin.xml, and will not install if it requires a newer version of Mango.

Note: once you’ve created a plugin, never change the plugin’s class or id attributes, even if you’re only changing the text case – this will cause problems on case-sensitive file systems such as Linux, and with the auto-installer process.

Auto-copying of plugin assets

In the future, there will be no public access to the components directory; so, if your plugin requires additional files (images, scripts, etc.) they should be copied to the {mango_root}/assets/plugins/ directory.

This process is now automated, by simply adding a few lines to plugin.xml. Add an <assets> element as a child of the main plugin element:

<assets>
	<asset file="assets/script1.js" />
	<asset file="assets/script2.js" dest="js" />
	<asset dir="assets/images" />
	<asset dir="assets/images" dest="img" />
</assets>

The code above shows the 4 different syntax options. Each <asset> element requires either a file or dir attribute, and takes an optional dest attribute.

file or dir specifies a path within the plugin directory to the file or directory to be copied.

If a dest attribute is specified, the files will be copied t o a subdirectory of that name.

So, in the above example, when my plugin (called “examplePlugin”) is activated:

• assets/script1.js will be copied to {mango_root}/assets/plugins/examplePlugin/script1.js gt;
• assets/script2.js will be copied to {mango_root}/assets/plugins/examplePlugin/js/script2.js
• The entire directory assets/images will be copied to {mango_root}/assets/plugins/examplePlugin/images
• The entire directory assets/images will also be copied to {mango_root}/assets/plugins/examplePlugin/img/images

When the plugin is deactivated, the files will be deleted.

There is also an <assetsAdmin> element, which works in exactly the same way, but copies files to {mango_root}/admin/assets/plugins/ – these files are only accessible within the admin area.

The BasePlugin component provides methods which will return the publicly accessible path to your auto-installed assets.

BasePlugin.cfc

This is a base plugin component which all plugins should extend, and which I will detail in another post.