Creating a plugin

Plugins can be used for several different purposes. They can simply do things behind the curtains (such as send a notification email) or show output in the templates (such as showing a captcha image in the comment form).

Registering a plugin requires at least two files that must be placed in a custom folder inside the components/plugins/user folder (in your custom folder you can also add any other file your plugin needs):

1. plugin.xml It defines what is the plugin main component class to call, what events it wants to listen to and a general description to show the blog user when he or she wants to activate your plugin.

2. A ColdFusion component that implements the required "plugin" methods

The plugin.xml file

<?xml version="1.0" encoding="UTF-8"?>
<plugin id="com.asfusion.mango.plugins.akismet" name="PLUGIN NAME" version="1.0" provider-name="YOUR NAME" class="akismet.Handler">
   <description><![CDATA[ Description of the plugin the user will see in the admin ]]></description>
   <listens>
      <event name="beforeCommentAdd" type="synch" priority="5" />
      <event name="settingsNav" type="synch" priority="5" /
      <event name="showAkismetSettings" type="synch" priority="5" />

   </listens>
</plugin>

The plugin tag attributes:

id: a unique id for your plugin. It is recommended to use a package structure such as com.yourdomain.yourplugin

name: User friendly name the user will see in the admin. Examle: name="YouTube"

class: the name of the ColdFusion component that will handle the events. It must contain the package structure from your custom folder. Example: yourPluginFolder.yourCFplugin

version: version number for your plugin. Example: version="1.5"

provider-name: Your name or your company name

Your plugin won't do anything until it listens to some event. You specify what events to listen to with the "listens" tag. Inside that tag, there should be one or more "event" tags:

The event tag attributes:

name: the event name to listen to. This can be a Mango built-in event or your own custom event.

type: either "synch" or "asynch". Use "synch" when you need to show information to the user or you need to process the event synchronously (not on the background)

priority: priority number for this plugin. When an event is dispatched, plugins are called in order of priority, higher numbers first.

Your Plugin ColdFusion component

You can call your component anything you want. The best practice is to extend org.mangoblog.plugins.BasePlugin.

Refer to the list of events you can listen to. In addition to the built-in events, you can listen to custom events. You can dispatch custom events from custom tags that you add to your skin templates or from links in the form of: ?event=YourCustomEventName