Context Navigation

ColdBox Overview

What is ColdBox?

ColdBox is an event-driven conventions based ColdFusion Development Platform. It provides you with a set of reusable code and tools that you can use to increase your development productivity, and it provides you with a development standard when working in a team environment. ColdBox is comprehensive and modular which helps you address most infrastructure concerns of typical ColdFusion applications. It also goes places that other frameworks don't.

In this article you will have an overview of the main components of this Object Oriented Framework. Below are some good resources for you to read about design patterns and some object orientation goodness. Having some basic object oriented knowledge will help you tremendously during your initial stages of ColdBox development. However, if you are not an OO guru, no worries, the guides contained in this wiki will help you and take you to several learning paths of object orientation and software development. This is just an introductory guide, so you might encounter new terminology or features of the framework that you might have no clue about. I urge you to continue reading the guides in order to find a cohesive outlook of what is ColdBox

ColdBox Service To Worker Diagram

Features & Capabilities

Please see the Features and Capabilities Guide for an in depth overview.

System Requirements

Below is a quick overview:

Supported CFML Engines are

Adobe ColdFusion 7.X and greater
BlueDragon 7.X and greater
Railo 2.0 and greater

Supported OS

Any OS that ColdFusion can run

Please see the System Requirements Guide for an in depth overview.

What are some of ColdBox's Novel Features

Documentation

We are firm believers in developer education. We have over 30 step by step guides and over 550 pages worth of documentation right in this wiki. We believe that by empowering the user with knowledge, the adaptation rate will increase and the ability of the developer to find what they need will make their productivity increase.

Custom Conventions

Conventions over configurations is our motto. We get rid of verbosity of xml logic and use ColdFusion? and a set of conventions for our applications. With ColdBox you can even define your own application layouts and conventions. This gives great flexibility to developers who are used to their own application layouts and conventions. Conventions are also used for registering events, interceptors, plugins and much more. The use of conventions over configurations is what makes ColdBox unique.

Coldfusion Controllers instead of XML Controllers

ColdBox doesn't rely on xml declarative logic where you have to define an event, what it does and where does it go. ColdBox is a conventions based framework that will let you program in ColdFusion to get things done. You basically expose methods on event handler CFC's (Controllers) by turning their access to public or remote. The framework then will auto-register the handler CFC's and now you are able to use the methods as ColdBox Events. So the declarative logic is now placed within the methods, where you can place method exit points, what business logic to call and what view to render or what event to surrender execution to or whatever you like, in CODE. This is how ColdBox can help you create multi-layered applications with one single skeleton and configuration file. So instead of working with a long and complex configuration file all the time, you are mostly working with ColdFusion code all the time. You would use the configuration file to setup your project or maybe tweak some settings.

Aspect programming

ColdBox comes bundled with an extensive set of plugins and interceptors that will help you on every day software application tasks like bug reports and notifications, AOP file logging with auto-archiving, per-environment settings, storage facilities for cluster environments, object caching, datasource declarations, web services integrations, internationalization, IoC integrations, application security, pretty URL's via SES and so much more. ColdBox is not only an MVC framework but a development platform.

ColdBox Dashboard

The ColdBox Dashboard is a visual application that helps you configure your framework installation and has tools for code generation. It is also a self-documenting application that will help you learn about the framework. You can modify all of the framework configurations, read documentation and it is tightly integrated to this site for you to search the wiki, svn repository, and ticket reports, and much more. (Different License than The ColdBox Framework)

ColdBox Caching

ColdBox has an advanced memory aware and configurable caching engine. You have several tuning parameters for the cache and also visual cache reports in the debugging panel. You can actually see how many objects and what type of objects are in your cache, the efficiency of your cache and the tuning parameters. This feature will help developers save time and actually not have to worry about persistence. ColdBox also allows for event caching, in which the HTML output events produce will be cached by the framework and presented to users. This will enhance applications and system stability. The best part of it is that you use metadata in the cfcomponent and cffunction tags to actually declare caching parameters. ColdBox also allows for extensive view caching and on-demand render and cache capabilities. To top it off, the caching engine has an event broadcaster model built-in that can advice you off new objects and object removals.

Unit Testing

ColdBox is a framework based on objects and Unit Testing is an integral part of development, then why shouldn't you be able to unit test your handlers and provide you with integration testing? Well, Unit Testing is part of ColdBox. ColdBox includes a unit testing feature to let you do integration testing and test the entire application by testing your event handlers. You can event test relocations and re-routing.

ColdBox Proxy: Flex/Air/Remote Integration

The ColdBox proxy enables remote applications like Flex and AIR to communicate with ColdBox and provide an event model for those applications. Not only that, but you can reinitialize the entire application, get settings, and yes, announce custom or core interceptions. You can create custom interceptor chains for your model that can be executed asynchronously when a user hits a save record button for example. You can create a Service Layer with built-in environmental settings, logging, error handling, event interception and chaining, you name it, and the possibilities are endless.

Not only that, but this enables you to actually create any amount of front ends using the same reusable ColdBox and model code. The code is the same, you create event handlers, you interact with a request collection, with core and custom plugins, but you don't set views or layouts because the framework is now a remote framework for your model. So what do you do, well, return data, arrays, xml, and value objects. Anything, right from within the event handlers or setup a configuration setting that tells the framework to always return the request collection.

How ColdBox Works?

ColdBox uses both implicit and explicit invocation methods to execute events and render content; ColdBox is an event driven framework. You have one single xml configuration file: coldbox.xml.cfm, from where you can configure your entire application (No logic, just configuration data). You can use ColdSpring, Transfer, Remoting, CRUD, Bean/DAO Factories or any other technology and/or pattern that you can think off with ColdBox. However, ColdBox does make you adhere to an application directory structure based on conventions that are fully customizable. This is done with the purpose of creating a standard for all developers in the same team to share and for ColdBox to find what it needs. Remember that this framework will not solve your problems. It is a standard, a foundation on which to develop on and thanks to its software programming aspects that it provides, this framework can also be a development toolkit. However, it is up to you to create GOOD code, this is not a magical framework that will make your code better. It will help you, but at the end of the day, it is your responsibility.

ColdBox makes use of the Front Controller design pattern as its means of operation while in MVC mode. This means that every request comes in through a single template, usually index.cfm. Once a request is received by the framework through this front controller, it will parse the request and re-direct appropriately to the correct execution paths. The way events are detected are via a URL/FORM or remote variable named by default event or by using the default SES routing techniques in ColdBox. This event variable holds a specific pattern that lets the framework know what to execute. This is called ColdBox event syntax:

NON SES MODE [handler|package].[action]

SES MODE /index.cfm/{package}/{handler}/{action}

The handler is the name of the event handler CFC and the action is the name of the public or remote method to execute. You can also pre-pend package names (directories) of where event handlers can be found. Please note that our recommendation is to use SES routing so you can create meaningful URI's and abstract out the real names of the handlers and locations.

You are only limited by your ingenuity

Implicit & Explicit Invocations

ColdBox Events can be registered for execution in two different ways. Events can be registered for the following events via the configuration file, which are run implicitly (No need for you to call them):

Request Start Handler (simulates onRequestStart)
Request End Handler (simulates onRequestEnd)
Application Start Handler (simulates onApplicationStart)
Session Start Handler (simulates onSessionStart)
Session End Handler (simulates onSessionEnd)
defaultEvent (The default event to execute)
onException (The event to execute when an exception occurs)
onInvalidEvent (The event to execute when an invalid event is detected)

There are also some more implicit convention method declarations that can be executed by just writing the following methods inside of a handler CFC:

preHandler	Executes before the requested event (In the same handler CFC)
postHandler	Executes after the requested event (In the same handler CFC)
onMissingAction	Executes if an action was requested from this handler but the method does not exist (In the same handler CFC)

The other method to execute events is via explicit declarations from within your code using the runEvent() method. From these events, you declare what business actions to invoke, what view to render, call/use plugins, and if more events need to be executed (chaining). All these actions are done explicitly, you define them in CF code and not in XML Dialect. The ColdBox controller then implicitly renders layouts/views that were set by the event handlers and finalizes execution.

One thing to note, is that the event handler's events (methods) are very loosely coupled to each other. They interact on their own and do what they need to do and surrender execution to the framework. As you can see, due to the nature of event handlers written in ColdFusion, you have explicit declarations that would otherwise be implicit if done in an XML based dialect. Thus, the cohesion between implicit and explicit event executions can exist in a ColdBox application. At the end of the day, ColdBox is based on events and cannot function without them.

Below is a quote by Oscar Arevalo concerning ColdBox's functionality:

ColdBox takes a more direct approach to determine what gets called and when; yes, this adds some coupling between the views and the event handlers, but the benefit is that the amount of indirection and obfuscation is reduced; resulting in what I think is one of the biggest benefits of ColdBox: that you actually program in coldfusion, and not in some XML dialect. This results in applications that are very easy to follow, even if the framework is not there." by Oscar Arevalo

The request lifecycle

Please see the application life cycle guide to understand the basics of ColdBox's request life cycles.

Configuration File (coldbox.xml)

ColdBox is configured for operation via a single xml file. You can define the major settings for your application, what features to use, etc. You need to read the following guide to understand much better the possibilities with ColdBox

Event Handlers (Controllers)

ColdBox Event handlers are CFC's that act as your application controllers. Most of this topic is covered in the Event Handlers Guide. Here is a brief introduction:

First of all, these CFC's must extend the coldbox eventhandler base CFC: coldbox.system.eventhandler
If they implement an init method, then they must call the base class constructor using the super method. Remember that if you implement an init method in an event handler. All the methods executed from this handler will run the constructor code.
The CFC's must be placed in the handlers directory under your application (Conventions). See cbDirectoryStructure
Then you need to create methods that will respond to events. ColdBox uses the event action variable on form submits and url parameters to determine what event to execute.
Handlers will be cached by the framework and cache metadata can be attached to their cfcomponent declaration.

The format of this event variable is {package}.{event_handler CFC}.{method}

The framework on initialization will read your handler directory and register the available handlers. Once an event is detected to execute, the framework will validate both the handler and the method. Therefore, in order to expose an event to the framework, just create a method in your CFC with public or remote access.

Event handlers can also be called from remote applications such as Ajax and Flex via the ColdBox Proxy. You can even determine if an incoming request is an MVC or Remote request and react accordingly. In remote mode, your event handlers can actually return data.

Request Collection

ColdBox also uses a request collection data structure where all variables can be stored and shared among an execution request. The Request Collection is a central repository of information that is refreshed on every user request with the request's information. This is how data gets moved around from event handlers to views and layouts to plugins and anything running inside of the framework and in the MVC layers. The object containing the request collection is the request context object found at coldbox.system.beans.requestContext.(See ColdBox API). Not only can you use the request context object but you can decorate it! You can expand its functionality according to your needs with the introduction of ColdBox 2.5.0, please read the Request Context Decorator Guide to help you learn more. The request context is not a mere data structure where you get and set values, but an object that is used to set views or layouts for rendering, caching views, getting event metadata, determining what is being executed and so much more.

Plugins

Another important ColdBox feature is the use of a plugin library of CFC's that extend the normal usage of ColdBox to application specific tasks but without hindering system performance. These plugins are reusable components that your applications can use and can be loaded on demand via the ColdBox Plugin Factory. Some samples are: i18n, resource bundles, refresh a webservice stub, Bug Reports, java file utilities, etc. This is a major difference between ColdBox and any other framework, in that it gives you a set of reusable on-demand components for tedious or repeatable application-specific tasks. Thus, the toolkit aspect of ColdBox.

Also, not only can you use and modify the plugins that come with every ColdBox installation, but you can create your own. You are not limited anymore, you can extend the framework to your needs. You can create as many plugins as you want and build a plugins library that can be located by just specifying it on the configuration file or loaded up via conventions. You will then be able to get the plugin and use it on any of your ColdBox applications. The best part of it all, is that the plugin will inherit all of the framework's functionality, so you have everything that you need to be able to code.

How easy is it? well, you just do the following:

Make your plugin CFC extend coldbox.system.plugin
Create an init method with the following standard code:

<cffunction name="init" access="public" returntype="coldbox.system.plugin" output="false" cache="{true or false}" cachetimeout="{x in minutes}">
        <cfargument name="controller" type="any" required="true">
        <cfscript>
        //Set controller reference
        super.Init(arguments.controller);
        //Plugin Name
        setpluginName("Name of the plugin");
        //Version of the plugin
        setpluginVersion("1.0");
        //Small description
        setpluginDescription("I am a simple bean factory");
        return this;
        </cfscript>
</cffunction>

Create your methods and WALLAH!!! You are done and you can call any of the inherited methods from coldbox.system.plugin.cfc
You can also declare caching metadata in the cfcomponent declaration, so ColdBox will persist your plugins.

Please see the Creating My First Plugin Guide for more information

Interceptors

ColdBox interceptors increase functionality for applications and framework alike, without touching the core functionality, and thus encapsulating logic into separate objects. This pattern wraps itself around a request in specific execution points in which it can process, pre-process, post-process and redirect requests. These interceptors can also be stacked to form interceptor chains that can be executed implicitly. The chaining is all about positioning in the configuration file. The order of declaration is very important. These stacked interceptor chains form a chain of separate, declaratively-deployable services to an existing web application or framework without incurring any changes to the main application or framework source code. This is a powerful feature that can help developers and framework contributors share and interact with their work.

Interceptors are a great compliment to ColdBox plugins, in which now they can be used alongside of them and implicitly add functionality to a ColdBox application. Another important aspect to note is that Interceptors have full access to a request's lifecycle and the framework. Thus, they can get application settings, redirect control, execute events, use the cache manager, get plugins, transform views, adapt views for certain protocols and much more. Please read the full Interceptor's Guide for an in-depth tutorial.

Interceptor Class Diagram

Interceptor Sequence Diagram

For what can I use them

Below are just a few applications of ColdBox Interceptors:

Security
Event based Security
Method Tracing
AOP Interceptions
Publisher/Consumer operations
Implicit chain of events
Content Appending or Pre-Pending
View Manipulations
Custom SES support
Cache advices on insert and remove
Much more...

Much more than Interceptors

However, we went a step further with interception points and created the hooks necessary in order to implement an observer/observable pattern into the entire interceptor service. Ok ok, what does this mean? It means, that you are not restricted to the pre-defined interception points that ColdBox provides, you can create your own WOW! Really? Yes, you can very easily declare execution points via the configuration file or register at runtime, create your interceptors with the execution point you declared (Conventions baby!!) and then just announce interceptions in your code via the interception API. The power of conventions. However, not only can you intercept at an execution point, but you can actually send a structure of intercepted data right into the interceptor. You can use these custom interceptors as a set of listeners waiting for broadcast information. You can even create chains of listeners for the same message.

Conclusion

I hope that this overview gave you an insight into how powerful ColdBox is for building your web applications. It is a new generation framework based on conventions that will increase your productivity and adaptability in a team environment. Welcome to the ColdBox Platform.