<< Back to Dashboard

ColdBox's Plugins Guide

Introduction

Welcome to the ColdBox plugins guide. This guide will give you a brief overview of what ColdBox plugins are, what are the core plugins, how you can extend them and how you can create your own custom plugins. This guide expects that you at least have a working knowledge of ColdBox and some of its internal workings.

ForgeBox Plugins

Please remember that in our ColdBox developer community site, ForgeBox, you can find a big collection of Plugins and so much more. Anybody can contribute and automatically all contributions will be accessible via our ColdBox application templates and via ColdFusion Builder.

What Are Plugins?

Plugins are CFC's that are built to extend the core framework or application functionality without hindering system performance. The ColdBox Platform contains several useful plugins that not only makes ColdBox a framework, but also a developer toolkit. The idea behind the plugin concept is to create a reusable and extensible architecture for developers to build applications or framework specific tasks that could be easily shared and loaded on demand within your applications and keeping true to the framework's regulations and part of the framework life cycle.

This means that you can easily code plugins, completely extend your application and even share them with your friends. You can create as many plugins as you want and build a plugins' library that can be used in your applications by just specifying it on the configuration file or by using the conventions. You will then be able to get the custom plugin and use it on any of your ColdBox applications. Not only can you use them, ColdBox can maintain persistence for you and even help you do dependency injection via WireBox.

Core Plugins

In this section I will cover the core plugins that come pre-bundled with ColdBox and have a brief explanation of each. In the next sections we will cover usage and techniques:

These are the core plugins that are shipped with ColdBox and as you can see they are highly configurable and will help you build your applications faster. What is also important to note, is that you can extend these plugins and create your own versions of them. I know I have!! The possibilities are endless.

How do I use plugins?

The easiest way to use core plugins in your handlers/layouts/views and interceptors is via one method getPlugin() which is dissected below:

getPlugin([string plugin], [boolean customPlugin="false"], [boolean newInstance="false"], [module=''])  

Arguments:

• plugin : string : The name of the plugin to create or retrieve
• customPlugin : [boolean = false] : The boolean flag if this is a core or custom plugin.
• newInstance : [boolean = false] : The boolean flag if the factory should create a new instance of the named plugin.
• module : string : The name of the module where the plugin is located

The other method you can use is the getMyPlugin method for retrieving only custom plugins:

getMyPlugin(string plugin, string module="") 

Injecting Plugins

You can also inject plugins into other plugins, handlers, interceptors or model objects using our WireBox Injection DSL:

property name="logger" inject="coldbox:plugin:Logger";
property name="zipUtil" inject="coldbox:plugin:Zip";

Code Samples

Below you can see some code snippets of useful plugin calls:

function preHandler(event, rc, rc, action){
    getPlugin("Logger").info("I am just inside the pre-handler method executing #arguments.action#");  
    getPlugin("Timer").start("Executing #arguments.action#");
}


<---  Switch the i18n Locale --->
<cfset getPlugin("i18n").setfwLocale( rc.locale )>

<---  Java loader setup --->
<cfset getPlugin("JavaLoader").setup("includes/helloworld.jar")>

<---  Set a message Box --->
<cfset getPlugin("MessageBox").setMessage("error","Error retrieveing news feed")>
<cfset getPlugin("MessageBox").setMessage("warning","Warning message")>
<cfset getPlugin("MessageBox").setMessage("info","User created successfully")>

<---  Get a Web Service Object declared in your config --->
<cfset wsObj = getPlugin("Webservices").getWsobj("newsfeed")>

<---  Clear ClientStorage News --->
<cfset getPlugin("ClientStorage").deleteVar("newsfeed")>

<---  Clean XSS attacks --->
<cfset rc.title = getPlugin("AntiSamy").clean( rc.title )>

The best place to learn about the functionalities of the core plugins is to visit the Online API.

Custom Plugins

So what Can I use custom plugins for:

• As helper classes, loaded on demand and used on demand
• UI elements for reusable tasks
• For reusable tasks
• Security
• AJAX enhancing features
• Query related
• ANT
• Anything you can imagine.

Conventions Location

All custom plugins should be placed in the plugins directory of your application. This is the location where ColdBox will look for custom plugins.

|ApplicationRoot
|--+ plugins (Custom Plugins Directory)
   |--+ DateUtil.cfc

// Reference
var util = getMyPlugin("DateUtil");

External Location

You can also declare a coldbox.PluginsExternalLocation setting in your configuration file. This will be a dot notation path or instantiation path where more external custom plugins can be found (You can use coldfusion mappings). So this way you can bring in an entire library of plugins for your usage on-demand. You can share plugins with your entire server and even create packages for them. Once you declare the setting and you inject or call for a plugin, the ColdBox plugin service will search your local conventions first and then your external location for the plugin object.

Full Path Location

You can also call the getMyPlugin() with the full instantiation path to the plugin object as well:

var util = getMyPlugin("myapp.model.util.plugins.MyUtil");

Injecting Custom Plugins

You can also inject custom plugins using our WireBox Injection DSL into other plugins, interceptors, handlers and/or model objects:

property name="logger" inject="coldbox:myPlugin:DateUtil";
property name="zipUtil" inject="coldbox:myPlugin:package.Zip";

Anatomy Of A Plugin

• Can be simple CFCs or inherit from our base coldbox.system.Plugin
  • If they inherit from our base, then they must have a specific init() signature
• You can call some setter methods to describe your plugin:
  • setPluginName()
  • setPluginAuthor()
  • setPluginAuthorURL()
  • setPluginVersion()
  • setPluginDescription()

Component Declaration

With Inheritance:

component extends="coldbox.system.Plugin"{
  
    function init(){
      setPluginName("My Awesome Plugin");
      setPluginAuthor("Luis Majano");
      setPluginAuthorURL("http://www.luismajano.com");
      setPluginVersion("1.0");
      setPluginDescription("A very cool plugin");

      return this;
    }

}

No Inheritance:

component{
  
    function init(){
      // ANYTHING YOU LIKE HERE
      return this;
    }

}

When using the no-inheritance approach, calling the setter methods for the plugin properties is absolutely optional but recommended.

Persistence

Persistence for Plugins is done via our dependency injection framework WireBox, so any persistence annotation or configuration via the configuration binder will apply to the plugin. However, by default, all plugins are not cached. Here are some of those annotations:

// Singleton plugin
component singleton{}

// Cached Plugin
component cache="true"{}

// Transient Plugin
component{}
component cache="false"{}

// Cached with timeouts
component cache="true" cacheTimeout="5"{}

// Cached with timeouts in a named cache
component cachebox="cluster" cacheTimeout="10"{}

// Cached in request scope
component scope="request"{}

So what are you waiting for? Let's get cooking with custom plugins!

Extending/Overriding Core Plugins

You can very easily override the functionality of core plugins without touching them and you can also add more plugins to the core by using our new ColdBox Extensions configuraiton setting. You can create a setting called coldbox.ColdBoxExtensionsLocation that points to a location in your server where the ColdBox extensions will be stored. This setting is a dot notation path or ColdFusion mapping path.

coldbox = {
  coldboxExtensionsLocation = "shared.extensions"
};

The folder extensions must have a plugins folder in it. Any plugin you place here will take preference than the core plugins. So if you wanted to override our JSON plugin for example, you can drop one here called JSON:

/shared
  /extensions
     /plugins
       JSON.cfc