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).

Mango Blog plugins are CFML components (.cfc files) placed inside the /plugins/ directory. They hook into the engine lifecycle by listening to events (like beforePostUpdate, afterCommentAdd, etc.) or by adding custom admin UI.

1. Plugin Folder Structure

Inside your Mango Blog installation:

/components/plugins/user/

└── MyFirstPlugin/

├── MyFirstPlugin.cfc

└── plugin.json

plugin.json → metadata (name, description, version, author, etc.)
MyFirstPlugin.cfc → your plugin code (extends the Mango Plugin base class). A ColdFusion component that implements the required plugin methods

In your custom folder you can also add any other file your plugin needs, such as other components, images, etc.

2. Create `plugin.json`

{
  "id": "asfusion.MyFirstPlugin",
  "name": "My First Plugin",
  "version": "1.0",
  "provider": "AsFusion",
  "class":"MyFirstPlugin.MyFirstPlugin",
  "description": "Sample plugin.",
  "requires": [
    {
      "engine": {
        "version": 2.0,
        "match": "greaterOrEqual"
      }
    }
  ]
}

3. Create the Plugin CFC

Example MyFirstPlugin.cfc

component extends="org.mangoblog.plugins.BasePlugin" {

    variables.package = "plugin/myfirstplugin";

    this.events = [ { 'name' = 'dashboardPod', 'type' = 'sync', 'priority' = '5' }];

    // --------------------------------------------------
    public function init( mainManager, preferences ){
       super.init( arguments.mainManager, arguments.preferences );
       return this;
    }

    // --------------------------------------------------
    public function processEvent( required event ){
       if ( arguments.event.name EQ "dashboardPod" and variables.mainManager.isCurrentUserLoggedIn() ) {

          var pod = { title = "Sample Pod", content = "some pod content" };
          arguments.event.addPod( pod );
       }

       return arguments.event;
    }
}

4. Install & Activate

Drop your plugin folder (MyFirstPlugin/) into /plugins/.
Log in to the Mango Blog Admin Panel.
Go to Plugins → you’ll see “My First Plugin.”
Click Activate.

Now, when you:

Go to the admin dashboard → you will see a new pod

Common Events You Can Hook Into

Posts: beforePostAdd, afterPostUpdate, afterPostUpdate
Comments: beforeCommentAdd, afterCommentAdd
System: dashboardPod, settingsNav

With this model you can:

Inject custom markup into posts
Modify comment workflows (e.g., spam filters)
Add widgets to sidebars
Integrate third-party services (analytics, newsletters, etc.)

The plugin.json file

The plugin 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 structure:

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

type: either "sync" or "async". Use "sync" 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