Plugins

<< Back to Dashboard

ColdBox's Plugins Guide

Introduction

Welcome to the ColdBox plugins guide. This guide will give you a brief overview of what 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 workins. If not, please read some of the guides in this wiki.

What Are Plugins?

What are plugins? Plugins are cfc's that are built to extend the core framework or application functionality without hindering system performance. The main distribution of ColdBox 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, but ColdBox maintains their persistence for you and can do cleanup on those objects for you. Via metadata (annotations) you can tell how the plugin behaves and persists. ColdBox detects that and it will cache and persist them in its built in cache manager. You don't even have to worry about creating them, you just worry about how to use them.

Another important aspect of plugins, is that you can configure them to use simple or complex settings from your configuration file and we will see some samples below.

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.

The main core plugins are used in order to provide several functions to your applications a part from the MVC methodology. Below is a table and brief description of each core plugin:

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 them is via one method getPlugin() which is dissected below:

Method : getPlugin([string plugin], [boolean customPlugin="false"], [boolean newInstance="false"])

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.

The other method you can use is the getMyPlugin method for retrieving only custom plugins, which internally calls the getPlugin() method with the appropriate customPlugin argument set to true.

Method : getMyPlugin([string plugin])

Once you do a getPlugin call, the framework will verify that the plugin is valid, it will then check if it is in cache, if it is, it retrieves it and returns it. If the object is not in cache, it will then go ahead and instantiate it and configure it by calling the init method on it. Once this is done, the plugin will be inspected for the caching metadata, if found, it will cache it and if not, it will just return the plugin ready for usage. This is great because with one single getPlugin() call, I can create, configure and execute a method on my plugin. Just look at the sample below:

<cffunction name="preHandler" access="public" output="false" returntype="void">
  <cfargument name="Event" type="coldbox.system.beans.requestContext">
  <cfscript>
    getPlugin("logger").logEntry("information","I am just inside the pre-handler method. #logger.getHash()#");
  </cfscript>
</cffunction> 

What have I done? Well, I have created a preHandler event that will log something to a ColdBox log file via the logger plugin. With one line, I create, configure, cache and execute the logEntry method on the logger plugin. The next time I call it, I will only retrieve from cache and execute to increase performance. You can now start to see the power behind plugins and how they can be easily brought in to your application for usage.

Code Samples

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

<---  Use the fileUtilities plugin to read a file, the file is actually retrieved via the logger plugin to get the log file. --->
<cfset rc.LogFileContents = getPlugin("Utilities").readFile(getPlugin("logger").getlogFullPath())>

<---  Prepare the i18n Locale --->
<cfset getPlugin("i18n").setfwLocale(getSetting("DefaultLocale"))>

<---  Change Locale --->
<cfset getPlugin("i18n").setfwLocale(Event.getValue("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")>

There are so many that I cannot list them all here, but if you look at the sample applications, you will get a feel of how to use them. The best place to learn about the functionalities of the core plugins is to visit the Online API.

Custom Plugins

You can also create your own plugins to expand the framework and application functionality. You can take a look at the following guide for an in depth view of how to create: My First Custom Plugin. This guide will give you a very practical way of how to create and use custom plugins. The great thing about the conventions in ColdBox is that you don't even have to declare the plugins in order to use them. Just drop them in the appropriate locations and they will be searched for and configured. No extra labor in declaring them, just use them.

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.

Custom Plugins 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. However, you can also change this convention via the Dashboard or settings.xml file. All of the framework's conventions can be customized to your liking. Please see Naming Conventions Guide

|ApplicationRoot
|----+ plugins (Custom Plugins Directory)

Custom Plugins External Location

You can also declare a MyPluginsLocation 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.

How to Use Them

You can call a custom plugin by using the following methods:

• getMyPlugin( plugin, [newInstance:boolean=false] )
• getPlugin( plugin, [customPlugin:boolean=false], [newInstance:boolean=false] )

So to used them it would be:

<cfset getMyPlugin('datePlugin').getToday()>

//or

<cfset getPlugin('datePlugin',true).getToday()>

Rules and Anatomy of a Custom Plugin

• First of all, these cfc's must extend the coldbox plugin base cfc: coldbox.system.plugin
• They must have an init method implemented as shown below.
• They must exist in the correct plugins directory under your application. See Directory Structure or wherever you have pointed your external library to be.

Sample Custom Plugin Component Declaration

Below is a sample component declaration which can exhibit some caching parameters discussed below:

<cfcomponent name="mySecurityPlugin" hint="This is my security plugin" extends="coldbox.system.plugin" cache="true" cachetimeout="50">

  <-------------------------------------------- CONSTRUCTOR ------------------------------------------->

  <cffunction name="init" access="public" returntype="mySecurityPlugin" output="false">
	<cfargument name="controller" type="any" required="true">
	<cfset super.Init(arguments.controller) />
	<cfset setpluginName("My Security Plugin")>
	<cfset setpluginVersion("1.0")>
	<cfset setpluginDescription("A Very cool security plugin.")>

        <---  My Custom Constructor code goes here --->

        <---  Return instance --->
	<cfreturn this>
  </cffunction>

  <---  All my methods go below --->

</cfcomponent>

The Caching Parameters

Since ColdBox is built with a solid cache foundation, your plugins can also be cached if needed. You will do this by adding meta data attributes to the cfcomponent tag. By default, plugins WILL NOT BE cached, unless you specifically use the cache meta data attributes to tell the framework to cache it. Caching of plugins simulates persistence, so remember this if you are planning plugins that can maintain their own persistence. This is a true flexible and awesome feature. Persistence controlled by the framework for you.

Plugin Reserved Words & Methods

For a full list of reserved words and methods for interceptors, please visit our Reserved Guide.

Autowiring your plugins

You can easily autowire your plugins with objects coming from the IoC plugin or the coldbox cache by using the autowire interceptor. For a full hands on guide, please read the Autowire Guide.

Advanced OO Features: UDF Injections

ColdBox provides you with a way to actually inject your plugins with custom UDF's so you can change the behavior or expand on the behavior a plugin already has. This is called mixin methods and can be done via the includeUDF() method provided to every custom plugin. The method is a provided way for you to dynamically load UDF's into your plugins at runtime. You can do this in a specific method or at the initialization of the plugin via the init() method. The sample below is using the init method:

  <cffunction name="init" access="public" returntype="mySecurityPlugin" output="false">
	<cfargument name="controller" type="any" required="true">
	<cfset super.Init(arguments.controller) />
	<cfset setpluginName("My Security Plugin")>
	<cfset setpluginVersion("1.0")>
	<cfset setpluginDescription("A Very cool security plugin.")>

        <---  My Custom Constructor code goes here --->
        <---  Load my special UDF's for my tools .---> 
        <cfset includeUDF('includes/toolsUDF.cfm')>

        <---  Return instance --->
	<cfreturn this>
  </cffunction>
	

The includeUDF method call will find the template and inject it to the custom plugin.

There you go, that is dynamic loading of methods in your custom plugins. A truly enhancing feature.

Best Practices

Organization

Always try to package your handlers in logical directories in order for you to have a good and extensible foundation. Plugins are also objects and therefore they should have their specific identity and function. So you need to map them in the best logical way according to their functions. If you need more flexibility you can even create directories (packages) and place them in logical buckets. This is mostly used in large applications as mentioned above. So think of them as entities and how they would do tasks for you, whether programmatic or visual. Once you do this, you can come up with a very good cohesive and reusable plugin or helper model for your applications.

Init Method

Every plugin must have its own init method with its own identity and constructor code. Also, please try to add all the metadata you can.

Conclusion

So how do you code them, well for that look at the next guides, My First Plugin Guide and also look at the Reserved Words & Methods Guide. This guide has briefly covered what ColdBox plugins are and how you can use them. For an in depth view of what each plugin can do, I suggest looking at the different guides in this wiki, the sample applications and most importantly the Plugins API. The API is the best way to see what a plugin can do for you since they are highly documented.

Related Guides

• The ColdBox Configuration File
• Event Handlers
• The ColdBox Request Context
• Layouts & Views
• URL Mapping & Rewriting
• Model Integration
• ColdBox Plugins
• ColdBox Interceptor
• Extending The Request Context
• ColdBox Unit Testing & Integration Testing
• ColdBox Proxy: Powering Flex/AIR/Remote Applications
• ColdBox-Ajax Integration