Custom ColdBricks Modules

The ColdBricks application is based on a modular architecture that has been designed so that it can be easily extended by custom modules or sections. By creating custom modules for different tasks you can present a unified managment platform for a website or portals. This section covers the basics of how to create your own custom ColdBricks modules.

Internal vs External Modules

The first thing you need to decide when you create a module, if it is going to be an internal or an external module. The main difference between them is where they are located in regards to the main ColdBricks source tree.

• Internal modules are located inside the main ColdBricks directory, in the modules subdirectory. In fact almost all of ColdBricks features are implemented as internal modules. The benefit of this type of module is that they are contained within  ColdBricks and do not depend on external directories. You may use Internal modules if you are create a customized version of ColdBricks that you want to distribute.
• External modules are located outside the main ColdBricks directory. When ColdBricks is being initialized, it looks for a directory on the webroot named /ColdBricksModules, and treats any subdirectory it finds there as an external module. The benefit of external modules is that since they are not contained within the ColdBricks directory you do not have to take any extra steps to preserve them when you do an upgrade or reinstall of ColdBricks.

Besides the located of the module code, both internal and external modules are pretty much the same in terms of what they can do or how they communicate with the ColdBricks platform.

 

Module Structure

All modules, regardless of their type, are implemented as a single directory. The directory name is the module name.

The module must have the following structure:

• handlers/ (directory) - required
• views/ (directory) - required
• init.cfm - optional

Modules follow an MVC style architecture. All HTTP requests must contain an event variable (either via POST or GET) that is used to identify a particular  event handler. This event handler in turn processes any operation that must be done, or requests any required data and then either sets a view template to be displayed or redirects to another HTTP request for another event handler.

Event handlers are contained within ColdFusion Components (CFCs) located in the handlers directory of the module. Each method of the cfc is an event handler.

Views are simple CFML templates located in the views directory.

init.cfm is a special template that is called automatically by ColdBricks when it is being initialized. The purpose of this file is to register the module with ColdBricks, and if necessary perform any intialization or setup tasks. The file is only called if it exists.

The following sections explain in more detail each of the elements in a module.

 

Event Handlers

As mentioned before, event handlers are methods in components located in the handlers directory.

Every request must always include an event variable that identifies which event handler to execute. If a request does not contain the event variable, it will take the user back to the initial page of ColdBricks.

For internal modules, the event parameter must use the following format:

    module.cfcname.handler

Where module is the name of the module, cfcname is the name of the component containing the event handler, and handler is the name of the method that implements the event handler.

For external modules use:

    my.module.cfcname.handler

Where 'my' is a fixed value that is used to indicate that it is an external module.
 

Event handler components must extend ColdBricks.handlers.ehColdBricks. This base component provides several general purpose methods.

Method	Description
reloadSite()	Forces a reload of the current site's configuration
setView( string viewName )	Sets the name of the view to display after the event handler finishes. The viewName is the name of a template inside the views directory of the module, without the .cfm extension.
setLayout( string layoutName )	Sets the name of a layout to use when displaying a view. Layouts are general to the entire ColdBricks application. They are contained within the /layouts directory in /ColdBricks. Use this function only to override the default layout.
setNextEvent( string eventName )	Does an HTTP redirect requesting a new event. It is recommended to perform a setNextEvent() after any event handler that performs any change, so that if a user reloads the browser the action will not be applied twice.
getValue( name, [default] )	Use this method to retrieve a value that has been submitted on the HTTP request (either via URL or FORM). If the value is not present, then returns either an empty string or the value given as the 'default' argument.
setValue( name, value )	Sets a value to be used in a view template. Values set with setValue() will be available in view via the request.requestState structure.
getSetting( name )	Returns the value of a global ColdBricks setting. Settings are defined in /ColdBricks/config/config.xml
getService ( name )	Returns a reference to a global service provided by ColdBricks. Services are singleton instances of components that are available to all modules. The available services are defined in /ColdBricks/config/config.xml
setMessage( type, msg )	Use this function to provide short status messages to the user from within an event handler. These messages will be displayed even if the event handler does not specify a view to display or if it does a setNextEvent(). The 'type' argument is used to indicate the type of message. Values are: info, warning and error.

The following code illustrates a sample event handler component:

 <cfcomponent extends="ColdBricks.handlers.ehColdBricks">

    <cffunction name="dspMain" access="public" returntype="void">
        <cfscript>
            try {
               setValue("coldbricks","rocks");
               setView("vwMain");               
                setValue("cbPageTitle", "My Sample Module");
                setValue("cbPageIcon", "images/configure_48x48-2.png");
                setValue("cbShowSiteMenu", true);            

            } catch(any e) {
                getService("bugTracker").notifyService(e.message, e);
                setMessage("error", e.message);
            }
        </cfscript> 
    </cffunction>

    <cffunction name="doSomething" access="public" returntype="void">
        <cfscript>
            try {

                // do something                 

                setMessage("info","Something has been done");
                setNextEvent("my.someModule.ehGeneral.dspMain");

            } catch(any e) {
                setMessage("error", e.message);
                getService("bugTracker").notifyService(e.message, e);
                setNextEvent("my.someModule.ehGeneral.dspMain");
            }
        </cfscript>
    </cffunction>
</cfcomponent>

Special Values

There are some special values that can be set with setValue() that will be used by ColdBricks to customize the view output:

• cbPageTitle: Use this to provide a title or heading for the current view
• cbPageIcon: Provides the location of an image to display next to the page title
• cbShowSiteMenu: Boolean value to indicate whether to show links to the main screens for site management.

Global Services

ColdBricks provides access to a few service components that provide several commonly used functionality to modules. Handles to service instances are obtained using the getService() method. ColdBricks contains several global services and many of them are only used internally; however a few provide access to functionality that modules may require. These are:

• sessionContext:  provides access to the current ColdBricks session. This includes information about the logged in user, and the current site loaded. For example to obtain a reference to the HomePortals environment for the current site, you would use: getService("sessionContext").getContext().getHomePortals()
• bugTracker: this service allows event handlers to submit bug reports whenever exceptions occurr. To enable the bugtracker it must be configured with sender and recipient email addresses on the main config file.
• configManager: provides access to a service used to manipulate HomePortals configuration objects.
• permissions: use this service to check whether a user has access to a particular event handler; or also to configure event handler access for users.
• UIManager: use this service to add module icons to the dashboard screens

Views

All views are contained on the views directory of a module. They are implemented as simple CFML templates. View do not have access to the special methods and functonality available on the event handlers.

All values passed to a view from an event handler are available in request.requestState structure as key of the structure. For example, if an event handler does setValue("websitename","coldbricks.com"); then, in the view you can reference to that value via #request.requestState.websiteName#

 

init.cfm

This template is optional, and is used to intialize and register the module with ColdBricks.

The code within init.cfm will be executed within an event handler, so all even handler methods are available.

Typically modules will need to do at least two things in their init.cfm:

• Register the module with a dashboard using getService("UIManager").regiserSiteModule() or registerServerModule()
• Setup the access permissions to the module using getService("permissions).addResource()