1 of 100

4.x

Introduction

   ____      _     _ ____            
  / ___|___ | | __| | __ )  _____  __
 | |   / _ \| |/ _` |  _ \ / _ \ \/ /
 | |__| (_) | | (_| | |_) | (_) >  < 
  \____\___/|_|\__,_|____/ \___/_/\_\

ColdBox Manual - v4.x.x

ColdBox is a conventions-based HMVC development framework for ColdFusion (CFML). It provides a set of reusable code and tools that can be used to increase your development productivity as well as a development standard for working in team environments.

ColdBox is natively based on modular architecture which helps address most infrastructure concerns of typical web applications and thus called an HMVC framework.

Versioning

ColdBox is maintained under the Semantic Versioning guidelines as much as possible.Releases will be numbered with the following format:

<major>.<minor>.<patch>

And constructed with the following guidelines:

Breaking backward compatibility bumps the major (and resets the minor and patch)
New additions without breaking backward compatibility bumps the minor (and resets the patch)
Bug fixes and misc changes bumps the patch

License

The ColdBox Platform is open source and licensed under the Apache 2 License. If you use ColdBox, please try to make mention of it in your code or web site or add a Powered By Coldbox icon.

Copyright by Ortus Solutions, Corp
ColdBox is a registered trademark by Ortus Solutions, Corp

Info: The ColdBox Websites, Documentation, logo and content have a separate license and they are a separate entity.

Discussion & Help

The ColdBox help and discussion group can be found here: https://groups.google.com/forum/#!forum/coldbox

Reporting a Bug

We all make mistakes from time to time :) So why not let us know about it and help us out. We also love pull requests, so please star us and fork us: https://github.com/coldbox/coldbox-platform

By Email: bugs@coldbox.org
By Jira: https://ortussolutions.atlassian.net/browse/COLDBOX

Professional Open Source

ColdBox is a professional open source software backed by Ortus Solutions, Corp offering services like:

Custom Development
Professional Support & Mentoring
Training
Server Tuning
Security Hardening
Code Reviews
Much More

Resources

Official Site: https://www.coldbox.org
Source Code: https://github.com/coldbox/coldbox-platform
Bug Tracker: https://ortussolutions.atlassian.net/browse/COLDBOX
Twitter: @coldbox
Facebook: https://www.facebook.com/coldboxplatform
Google+: https://www.google.com/+ColdboxOrg
Vimeo Channel: https://vimeo.com/channels/coldbox

HONOR GOES TO GOD ABOVE ALL

Because of His grace, this project exists. If you don't like this, then don't read it, it's not for you.

"Therefore being justified by faith, we have peace with God through our Lord Jesus Christ: By whom also we have access by faith into this grace wherein we stand, and rejoice in hope of the glory of God." Romans 5:5

Intro

Introduction

ColdBox Manual - v5.0.0

Versioning

And constructed with the following guidelines:

Breaking backward compatibility bumps the major (and resets the minor and patch)
New additions without breaking backward compatibility bumps the minor (and resets the patch)
Bug fixes and misc changes bumps the patch

License

Copyright by Ortus Solutions, Corp
ColdBox is a registered trademark by Ortus Solutions, Corp

Info: The ColdBox Websites, Documentation, logo and content have a separate license and they are a separate entity.

Discussion & Help

Reporting a Bug

Professional Open Source

Custom Development
Professional Support & Mentoring
Training
Server Tuning
Security Hardening
Code Reviews

Resources

HONOR GOES TO GOD ABOVE ALL

Because of His grace, this project exists. If you don't like this, then don't read it, it's not for you.

"Therefore being justified by faith, we have peace with God through our Lord Jesus Christ: By whom also we have access by faith into this grace wherein we stand, and rejoice in hope of the glory of God." Romans 5:5

What's New With 4.3.0

ColdBox 4.3.0 is a minor release that addresses several issues and introduces some enhancements. You can see below the release notes.

Module Parent Settings

We have now introduced a standardized approach to defining/overriding module settings in your module and overrides via the parent application. You can now define a moduleSettings structure in your config/ColdBox.cfc which will hold all the override settings for any modules you have installed in your system.

Module developers can then create defaults for those settings in a modules's ModuleConfig.cfc via the settings structure.

// myModule/ModuleConfig.cfc
component {
  function configure() {
    settings = {
      someSetting = "default",
      anotherSetting = "default"
    };
  }
}

// config/ColdBox.cfc
component {
  function configure() {
    moduleSettings = {
      myModule = {
        someSetting = "overridden" 
      }
    };
  }
}

// end result
{
  someSetting = "overridden",
  anotherSetting = "default"
}

Global `invalidHTTPMethodHandler`

You can now define a global invalid HTTP method handler in your coldbox configuration structure:

coldbox = {
  invalidHTTPMethodHandler = "main.invalidHTTP"
}

This will provide your application with error consistency when building RESTFul services.

New `allowedMethods` annotation for handlers

Your event handler actions can now define their allowed HTTP methods of execution via the allowedMethods annotation:

function index( event, rc, prc) allowedMethods="GET,POST"{
...
}

New convention `modules_app`

With the introduction of CommandBox we can now have tracked modules and un-tracked modules in a ColdBox application. The default convention for modules called modules is now the default location of tracked CommandBox modules. The new convention modules_app is for your own custom un-tracked modules.

What is tracked? Modules that are tracked by CommandBox and usually not added to source control. CommandBox controls their installation, updating, etc.

Interceptors get `rc` and `prc` references

All interceptor methods now receive a reference to rc and prc for convenience:

function preProcess( event, rc, prc, interceptData, buffer )

String Builders

Internal concatenation tools and interceptor response buffers have been migrated to Java String Builders for a more awesome performance updates.

Binary HTTP Content

You can now receive and decode binary HTTP content when doing RESTFul services

Models in Modules accept aliases now

Models in Modules can now have name aliases via the alias annotation or binder alias definitions.

HTTP Method Spoofing

Although we have access to all these HTTP verbs, modern browsers still only support GET and POST. With ColdBox and HTTP Method Spoofing, you can take advantage of all the HTTP verbs in your web forms.

By convention, ColdBox will look for an _method field in the form scope. If one exists, the value of this field is used as the HTTP method instead of the method that was made. For instance, the following block of code would execute with the DELETE action instead of the POST action:

<cfoutput>
<form method="POST" action="#event.buildLink('posts/#prc.post.getId()#')#">
    <input type="hidden" name="_method" value="DELETE" />
    <button type="submit">Delete</button>
</form>
</cfoutput>

You can manually add these _method fields yourselves, or you can take advantage of ColdBox's HTML Helper.

<cfoutput>
#html.startForm( action = "posts.#prc.post.getId()#", method="DELETE" )#
    #html.submitButton( name = "Delete", class = "btn btn-danger" )#
#html.endForm()#
</cfoutput>

Release Notes

Bugs

[COLDBOX-479] - onInvalidHTTPMethod not firing with SES Interceptor
[COLDBOX-512] - ColboxProxy.cfc has reference to method tracer - which no longer exists in that component.
[COLDBOX-515] - Exception handling broken for customErrorTemplate when application relative path used
[COLDBOX-517] - CF mapping's for modules don't get created for proxy requests
[COLDBOX-520] - Only remove the scriptname from the pathinfo if it is the first element in the pathinfo
[COLDBOX-521] - afterAspectsLoad was missing from core
[COLDBOX-527] - bug report view is not thread safe
[COLDBOX-528] - Coldbox Event Cache discards the Content-Type when caching non renderdata results
[COLDBOX-529] - Object in RC or PRC causes async interceptors to fail
[COLDBOX-534] - getHTMLBaseURL returns with a double slash at the end,
[COLDBOX-537] - ColdBox Cache Flash not discovering session/cookie as app has not loaded first
[COLDBOX-539] - Private event actions are no longer executable (regression)

New Features

[COLDBOX-371] - Convention to override a module's settings in an application or parent module
[COLDBOX-505] - New coldbox directive: invalidHTTPMethodHandler that will fire globally if an action is called with an invalid HTTP Method
[COLDBOX-511] - New action annotation "allowedMethods" so you can allow inline annoation for allowed HTTP Verbs thanks to Nic Tunney
[COLDBOX-522] - Add rc and prc available directly to custom error templates
[COLDBOX-525] - HTTP Method Spoofing for Forms
[COLDBOX-530] - Add 'modules_app' as a default external location instead of manually adding it.
[COLDBOX-540] - Interception points get reference to rc and prc now.
[COLDBOX-541] - invokerasync was not passing the buffer

Improvements

[COLDBOX-502] - RequestBuffers now leverage string builders.
[COLDBOX-513] - Calling processState from within an interceptor clears buffer
[COLDBOX-531] - execute() in BaseTestCase now uses the default event (defined in config/ColdBox.cfc) if / is passed in as the route
[COLDBOX-532] - event.getHTTPContent() doesn't work on binary encoding
[COLDBOX-536] - Rendered output has ALWAYS a precedent empty line, delete it!
[COLDBOX-538] - Alises in module models aren't picked up

What's New With 4.2.0

ColdBox 4.2.0 is a minor release that addresses several issues and introduces some enhancements. You can see below the release notes.

Release Notes

Bugs

[] - Bundling Modules w/ module excludes does not respect excludes
[] - API docs have broken links
[] - adobe CF incompatibillty on restful template response object
[] - addAsset does not recognize urls that ends with say "app.js?123" as js, not css.
[] - fix for tomcat 8 not removing repeating slashes on path info
[] - HTML Helper's startForm() doesn't pick up if current request is HTTPS
[] - doctype default switch case was on the wrong type, thanks to Hector Cruz
[] - _counter does not increment in rendering query-based view collections
[] - Bean Populator not working correctly when ORM entity inherits from other
[] - Bean populator errors on null values in JSON string
[] - syntax and wrong argument type matching on exception bean object
[] - double forward slash generated in buildLink
[] - SES interceptor has poor query string parsing, updated to new algorithm

New Features

Improvements

What's New With 4.1.0

ColdBox 4.1.0 is a minor release that addresses several issues and introduces some enhancements. You can see below the release notes.

Release Notes

Bugs

[] - Controller loc.args is referenced and not existing in pre{Actions}
[] - Module routing was not respecting package resolving within handlers
[] - onError handler doesn't work
[] - abstractFlashScope getKeys() doesn't work

Improvements

[] - Modules that include applicationhelpers are incompat with modules.autoReload setting, add recognition
[] - Add x-forwarded-proto checks on isSSL() verifications to allow for proxy configuraitons
[] - Better locking naming technique to avoid server-wide collisions
[] - Ability to test ORM entities with base cases if loading ColdBox or using entity injection

New Features

[] - Update application templates to use new logo
[] - Add session and application timeouts to testing harnesses
[] - Create a new testing annotation to control if application should be teardown in integration tests
[] - Create REST application template for ColdBox

What's New With 4.0.0

Introduction

ColdBox 4 is a major release in our ColdBox Platform series and includes a new revamped MVC core and all extra functionality has been refactored into modules. We have pushed the modular architecture to a 1st class citizen even in the core itself. There are several compatibility updates that you must do in order to upgrade your ColdBox 3.X applications to ColdBox 4 standards. You will notice that the source and download of ColdBox 4 has been reduced by almost 75% in size. This is now due to our modular approach where functionality can just be brought in dynamically. How you might say?

CommandBox

CommandBox, our new ColdFusion (CFML) command line interface, package manager and REPL. You can now use CommandBox to install dependencies, modules and even ColdBox itself, all from our centralized code repository: ForgeBox. To install ColdBox 4 Bleeding Edge you can just type:

box install coldbox-be

You can even use CommandBox to generate ColdBox applications, modules, handlers, etc. It has a plethora of commands to get you started on a fantastic ColdBox Adventure:

// Get help on all the ColdBox commands
coldbox help

// create a ColdBox app with TestBox support
coldbox create app MyFirstApp --installTestBox

Internal Library Updates

ColdBox is composed of three internal libraries: WireBox (DI & AOP), CacheBox (Caching) and LogBox (Logging). Below you can find what's new with this release for each library:

WireBox 2.0.0
CacheBox 2.0.0
LogBox 2.0.0

Major Updates

Performance Updates

The core has been completely revamped by removing ColdFusion 7/8 code, decoupled from many features that are now available as modules and rewrites to pure cfscript syntax. The end result is the fastest ColdBox release since our 1.0.0 days. In our initial vanilla load tests, normal requests take around 4-6ms to execute.

RunEvent Caching

The runEvent method has been extended to include caching capabilities very similar to what has previously been available to the renderView methods. This will allow folks to execute internal or widget-like events and be able to use the built-in caching capabilities of ColdBox to cache the results according to the arguments used. Below is the new signature of the method:

/**
* Executes events with full life-cycle methods and returns the event results if any were returned.
* @event The event string to execute, if nothing is passed we will execute the application's default event.
* @prePostExempt If true, pre/post handlers will not be fired. Defaults to false
* @private Execute a private event if set, else defaults to public events
* @defaultEvent The flag that let's this service know if it is the default event running or not. USED BY THE FRAMEWORK ONLY
* @eventArguments A collection of arguments to passthrough to the calling event handler method
* @cache.hint Cached the output of the runnable execution, defaults to false. A unique key will be created according to event string + arguments.
* @cacheTimeout.hint The time in minutes to cache the results
* @cacheLastAccessTimeout.hint The time in minutes the results will be removed from cache if idle or requested
* @cacheSuffix.hint The suffix to add into the cache entry for this event rendering
* @cacheProvider.hint The provider to cache this event rendering in, defaults to 'template'
*/
function runEvent(
    event="",
    boolean prePostExempt=false,
    boolean private=false,
    boolean defaultEvent=false,
    struct eventArguments={},
    boolean cache=false,
    cacheTimeout="",
    cacheLastAccessTimeout="",
    cacheSuffix="",
    cacheProvider="template"
){

Please note that the default cache provider used for event caching is the template cache, so it must be a valid ColdBox Enabled Cache Provider. So if we execute our sample widget below, we will be able to leverage its caching arguments:

<!--- Render with default cache timeouts --->
#runEvent( event="widgets.users", cache=true )#

<!--- Render with specific cache args --->
#runEvent( event="widgets.users", cache=true, cacheTimeout=60 )#

<!--- Render with specific event args --->
#runEvent( event="widgets.users", eventArguments={ filter:true }, cache=true, cacheTimeout=60 )#

Info : Internally ColdBox creates an internal hash of the passed in event and eventArguments arguments for the cache key. It also leverages the template cache for event caching.

Model called Models

The convention has been updated so it matches the other conventions. You now must create a models folder instead of a model folder.

onInvalidHTTPMethod Handler Convention

We have created a new action convention in all your handlers called onInvalidHTTPMethod which will be called for you if a request is trying to execute an action in your handler without the right HTTP Verb. It will then be your job to determine what to do next:

function onInvalidHTTPMethod( faultAction, event, rc, prc ){
    return "Yep, onInvalidHTTPMethod works!";
}

HTTP Content Auto Marshalling

The getHTTPContent method on the Request Context now takes in two boolean arguments:

json
xml

If set, ColdBox will auto-marshall the HTTP Body content from JSON or XML to native ColdFusion data types.

myStruct  = event.getHTTPContent( json=true );
xmlObject = event.getHTTPContent( xml=true );

SES regex route placeholders

You can now define a-la-carte regex matching on route placeholders. If the route matches with that regex in the placeholder the value will now be stored in the RC as well:

addRoute( pattern = 'format/:extension-regex:(xml|json)' );

New Global View Helper

You now have a new ColdBox core setting viewsHelper which is a template that will be injected and binded to any layout/view that is rendered. This means that finally you have a template that can be globally available to any view/layout in your system.

coldbox = {
    viewsHelper = "includes/helpers/ViewHelper.cfm"
};

Application Template Java Support

All the new ColdBox application templates have been updated to include a folder called lib which is automatically wired for you to class load Java classes and jars. All you have to do is drop any jar or class file into this folder and it will be available via createobject(“java”) anywhere in your app.

New Core Modules

All internal plugins, and lots of functionality, have been refactored out of the ColdBox Core and into standalone Modules. All of them are in ForgeBox and have their own Git repositories. Also, all of them are installable via CommandBox; Our ColdFusion (CFML) CLI and Package Manager. This has reduced the ColdBox Core by over 75% in source size and complexity. Not only that, but it allows us to be able to release patches and updates for feature functionality without releasing an entire framework release, but just 1 or more modules.

ColdBox Debugger

box install cbdebugger

Storages

box install cbstorages

Feeds

box install cbfeeds

Commons

box install cbcommons

i18n

box install cbi18n

box install cborm

box install cbioc

JavaLoader

box install cbjavaloader

AntiSamy

box install cbantisamy

MailServies

box install cbmailservices

MessageBox

box install cbmessagebox

Soap

box install cbsoap

Security

box install cbsecurity

Validation

box install cbvalidation

New Anti-Forgery Module

We have created a nice anti-forgery module called csrf which can be found in ForgeBox and in GitHub: https://github.com/ColdBox/cbox-csrf. This module will enhance your ColdBox applications with Anti-Cross Site Request Forgery capabilities. You can also install it via CommandBox

box install csrf

ORM Module Updates

As you know by now, all the ColdBox ORM features are available as a module that can be installed in your application via CommandBox or downloaded separately. We have done several updates to the ORM extensions like:

Lucee multi-datasource support
Expanded createAlias() method to allow for a criteria argument
which leverages hibernate's ability to do a where statement on a
join
Script updates

New System Renderer

The ColdBox Renderer plugin has been removed and it is now part of the core as the system renderer (coldbox.system.web.Renderer).

It has been migrated to full script and optimized for ColdFusion 9+
syntax
We have also created a new DSL to inject it via WireBox: coldbox:renderer
You can also add mixins or alter its behavior by talking to its
WireBox mapping (Renderer@coldbox)
All handlers/interceptors/views/layouts have access to the renderer
by calling the getRenderer() method in the super type
The main ColdBox controller has a new method called getRenderer() to retrieve the system renderer

New Error Template

By default, we are now not showing any exceptions in the ColdBox default error template for security and encapsulation. You now have to specify the full exception bug template if you would like to see the exceptions via the CustomErrorTemplate setting:

coldbox = {
    customErrorTemplate = "/coldbox/system/includes/BugReport.cfm"
};

This is to be secure by default. The default template used is /coldbox/system/includes/BugReport-Public.cfm

Remote Proxies Autowired

You've always been able to get models in a remote proxy (web-accessible CFC that extends coldbox.system.remote.ColdBoxProxy) using the getModel() method. Now you can also autowire your remote proxies using cfproperties just like you do in handlers and WireBox-managed models.

/remote/myProxy.cfc

component extends="coldbox.system.remote.ColdBoxProxy" {
    property name='myService' inject='myService';

    remote function doRemote() {
        variables.myService.doSomething();
    }
}

Note The autowiring only works for web-accessible remote proxies being directly invoked. You can extend the ColdBoxProxy by another manually-created CFC (such as an ORM eventHandler) but it won't be autowired.

Handlers Are Now Singletons

In pre-4.0.0 applications, all event handlers were cached in CacheBox with specific timeouts. We have found that this just created extra noise and complexity for handler CFCs. So now all event handlers will be cached as singletons by default (unless specified in the ColdBox.cfc).

Bootstrap Enhancement

The ColdBox application bootstrapper, the one used in Application.cfc has been completely updated and renamed to Bootstrap instead of Coldbox. This brings in lots of performance enhancements and faster startup times to your applications. Just use the included application templates or just update the Coldbox reference to Bootstrap.

// Inheritance
component extends="coldbox.system.Bootstrap"{

}

// Non-Inheritance
component{
    public boolean function onApplicationStart(){
        application.cbBootstrap = new coldbox.system.Bootstrap( COLDBOX_CONFIG_FILE, COLDBOX_APP_ROOT_PATH, COLDBOX_APP_KEY, COLDBOX_APP_MAPPING );
        application.cbBootstrap.loadColdbox();
        return true;
    }
}

Module Enhancements

There has been tremendous focus on modules in this release as we have moved completely to a modular architecture in the core as well. First of all, we have moved almost 75% of the source into modules so they can be installed a-la-carte by developers. Here are some major updates:

New getModuleSettings() & getModuleConfig() super type methods.
This allows you to get access to any module setting or configuration
property rather easily and directly.
All module properties are NOT required anymore except the name.
Modules no longer register their models folder as scan locations
to increase performance.
try/catch around module unloads, so if a module throws an exception
during unload it will be intercepted, unloaded and then throw an
exception. This way it will allow developers to fix the unloading
issues instead of basically restarting the entire CFML engine to
make it work.

Module Inception

We have altered the module services to now allow you to nest modules within modules up to the Nth degree. Our final move to hierarchical MVC is complete. Now you can package a module with other modules that can even contain other modules within. It really opens a great opportunity for better packaging, delivery and a further break from monolithic applications. To use, just create a modules folder in your module and drop the modules there as well.

Module Config New Properties

The ''ModuleConfig.cfc'' has been updated with several new properties:

this.autoMapModels = true;
this.modelNamespace = "store";
this.aliases = [ "store", "ecommerce", "shop" ];
this.cfmapping = "cbstore";
this.dependencies = [ "JavaLoader", "CFCouchbase" ];

Module Dependencies

Modules can now declare other module dependencies. This means that before the declared module is activated, the dependencies will be registered and activated FIRST and then the declared module will load.

Module Aliases

In pre-4.0.0 ColdBox applications, the way that you executed module handlers was via its registered module name, which had to be the name of the module folder on disk. This was ok to a certain point, but it would cause issues as it was very restrictive to the name on disk. On ColdBox 4 you can now give the module different execution aliases so you can execute the handler events via the aliases and the module folder name as well.

Module CF Mappings

Every module can now tell ColdBox what ColdFusion mapping to register for it that points to the module root location on disk when deployed. This is a huge feature for portability and the ability to influence the ColdFusion mappings for you via ColdBox.

Module Models Auto Mapped

The entire models folder will now be automatically mapped for you in WireBox via the mapDirectory call with a namespace attached to the objects (the name of the module). This way, all models are automatically mapped for you so you can just use them. Let's say you have a module called store:

property name="orderService" inject="OrderService@store";

As you can see it adds a @moduleName to discover models that come from a module directly.

Hint You can alter this behavior by setting the this.autoMapModels configuration setting to false. You can also alter the namespace used via the this.modelNamespace configuration property.

Module Bundles

You can now bundle your modules into an organizational folder that has the convention name of {name}-bundle. This is mostly for organizational purposes.

coldbox-bundle
  * cbstorages
  * cborm
  * cbsecurity

WireBox 2.0.0

Introduction

WireBox 2.0.0 is a major release of our Dependency Injection and AOP library with some major fixes and some cool new updates.

Release Notes

You can find the release version information here: https://ortussolutions.atlassian.net/browse/WIREBOX/fixforversion/12300

Bugs

[WIREBOX-31] -Builder.buildDSLDependency does not use the custom DSL correctly as the default namespace kicks in

Improvements

[WIREBOX-32] -binder.mapDirectory now skips hidden dirs
[WIREBOX-35] -Remove coldbox:cacheManager DSL reference, it is no longer valid

New Features

[WIREBOX-2] -allow mapDSL to be altered at runtime by modules via new wirebox method: registerDSL()
[WIREBOX-30] -Support wiring new injection DSL = byType, which leverages the type to match to an implementation
[WIREBOX-33] -Add a force argument to the map functions so you can override if a mapping already exists
[WIREBOX-36] -New coldbox dsl to get a renderer reference: coldbox:renderer

Major Enhancements

All LogBox libraries updated
All CacheBox libraries updated

ColdBox DSL Updates

The ColdBox injection DSL has had major updates to get to the ColdBox 4 standards.

All ocm injections have been removed in preference to
cachebox injection DSL
The coldbox:cachemanager DSL has been removed in preference to
cachebox injection DSL
All plugin injections have been deprecated in preference to
model/object injections
New coldbox:renderer dsl to inject the new ColdBox system
renderer

Forced Mappings

The map() function on the Configuration Binder now has a force argument which allows you to map no matter if the mapping exists or not already.

map( alias="MyService", force=true )
    .to( "model.MyService" );

Dynamic Custom DSL Registration

Injectors allow you to register custom DSLs at runtime by using the registerDSL() method on any injector. This feature was mostly done for modules, so they could enhance WireBox in a ColdBox context. However, this also allows you to leverage this in any non-ColdBox applications.

// Register Custom DSL
controller.getWireBox()
    .registerDSL( namespace="javaloader", path="#moduleMapping#.model.JavaLoaderDSL" );

Injection By Type: byType DSL

We have expanded our custom DSL and injectors to allow you to do injection by ColdFusion types. This feature is more in-line with features from Java or static languages were you can tell injectors to inject by argument or property type. Let's say you have a package of interfaces with subpackages of implementations:

/app/pkg/ISomeObject.cfc // <- interface
/app/pkg/adb/SomeObject.cfc // <- component implementing the above interface.
/app/pkg/odb/SomeObject.cfc // <- component implementing the above interface.

You then want to rely on the interface type field of properties in my dependent CFCs and leveraging the byType injection DSL. You would first map the right implementation using the alias as the name of the Interface.

// mappings...
map( "app.pkg.ISomeObject" ).to( "app.pkg.adb.SomeObject" );

// Injection
component {

    /**
     * @inject byType
     */
    property app.pkg.ISomeObject object;

}

CacheBox 2.0.0

Introduction

CacheBox 2.0.0 is a major release, mostly aligned to support our ColdBox 4 release.

Release Notes

You can find the release version information here: https://ortussolutions.atlassian.net/browse/CACHEBOX/fixforversion/12303

Improvements

[CACHEBOX-25] - Deprecate Cachebox xml config support

LogBox 2.0.0

Introduction

LogBox 2.0.0 is a major release, mostly aligned to support our ColdBox 4 release.

Release Notes

You can find the release version information here: https://ortussolutions.atlassian.net/browse/LOGBOX/fixforversion/12302

Bug

[LOGBOX-14] - Truncating of category data to avoid error on insertion on DB Appender

Improvement

[LOGBOX-13] - deprecate logbox xml support

New Feature

[LOGBOX-15] - Ability to asynchronize any logger via new 'async' property

Upgrading to ColdBox 4

The major compatibility issues will be covered as well as how to smoothly upgrade to this release from previous ColdBox versions. You can also check out the What's New guide to give you a full overview of the changes.

ColdBox 3.x Compatibility Module

If you want to convert a larger ColdBox 3.x site over piece by piece, we have created a ColdBox Compat module you can install that will give you much of the 3.x functionality back including plugins, ColdBox OCM, UDFLibraryFile setting, and WireBox DSL namespaces. You quickly install this module using CommandBox with the following command:

box install cbcompat

For more information and a full list of features, visit the ForgeBox page.

ColdFusion 8 Support Dropped

ColdFusion 8 support has been dropped.

Application.cfc Bootstrap changed

The bootstrap CFC used by Application.cfc has been updated from coldbox.system.Coldbox to coldbox.system.Bootstrap. This is basically just a rename-- all other functionality is the same so a simple find/replace in your Application.cfc should fix it up. This is the first change you'll need to make and is mandatory.

Sample Application.cfc using inheritance

// Old code
component extends='coldbox.system.Coldbox' { }

// New code
component extends='coldbox.system.Bootstrap' { }

Async Loggers Dropped

The Asynchronous loggers in LogBox have been removed in preference to the new async property that can be used in any logger. The affected loggers are:

AsyncDBAppender -> DBAppender
AsyncFileAppender -> FileAppender
AsyncRollingFileAppender -> RollingFileAppender

You can just declare each appender but add an async=true property to each when declaring:

logBox = {
    // Define Appenders
    appenders = {
        coldboxTracer = { class="coldbox.system.logging.appenders.ConsoleAppender",properties={async:true} }
    },
    // Root Logger
    root = { levelmax="INFO", appenders="*" },
    // Implicit Level Categories
    info = [ "coldbox.system" ]
};

Plugins Removed

ColdBox Plugins have graduated to become just models. The plugins convention has been removed and all references to plugin injection or DSL's are gone. You must now place all your plugins in your models directory and request them via getInstance() or getModel() calls.

Plugins are an old ColdBox convention but their baggage doesn't really serve a purpose now that we have modules for easy packaging of libraries and WireBox for easy creation of CFCs. Neither of those existed back when Plugins were birthed. It's time to say goodbye to the concept of plugins, but all their functionality will still be here, just with a slightly different (and more standardized) way of creating them.

// old
getPlugin("MyPlugin")
property name="myPlugin" inject="coldbox:plugin:myPlugin";

// new
getInstance( "MyPlugin@module" ) or getModel( "MyPlugin@module" )
property name="myPlugin" inject="model:myPlugin@module";

Plugin Base Class

With the removal of plugins, coldbox.system.Plugin no longer exists. If you have custom-written plugins that used some of the convenience variables such as controller, logbox, or wirebox that came from this base class, you'll need to inject them using the appropriate injection DSL. If you were using any of the convenience methods such as getRequestContext() or getRequestCollection() should be delegated to the appropriate service or the ColdBox controller.

Any variables or methods related to instance.pluginName, instance.pluginVersion, etc serve no purpose now and can be removed from the code.

New Core Modules

All internal plugins and lots of functionality has been refactored out of the ColdBox Core and into standalone Modules. All of them are in ForgeBox and have their own Git repositories. Also, all of them are installable via CommandBox; Our ColdFusion (CFML) CLI, and Package Manager.

You can find each of these modules in the main GitHub repo. Check out the instructions.md files inside the root of each module with additional information on configuration and installation.

Storages

Session Storage Plugin
Application Storage Plugin
Client Storage Plugin
Cluster Storage Plugin
Cookie Storage Plugin

All of these plugins have been refactored into the cbstorages module.

box install cbstorages

Instead of using:

getPlugin( 'SessionStorage' )
getPlugin( 'ApplicationStorage' )
getPlugin( 'CookieStorage' )
etc...

You will instead call

getInstance( 'sessionStorage@cbstorages' )
getInstance( 'applicationStorage@cbstorages' )
getInstance( 'cookieStorage@cbstorages' )
etc...

Note : The API for the actual storage CFCs is the same.

MessageBox

box install cbmessagebox

This module replaces the MessageBox plugin and registers the following mapping in WireBox: messagebox@cbmessagebox.

AntiSamy

box install cbantisamy

This module replaces the AntiSamy plugin and registers the following mapping in WireBox: antisamy@cbantisamy.

MailServies

box install cbmailservices

This module replaces the MailService plugin and registers the following mapping in WireBox: mailService@cbmailservices.

Validation

box install cbvalidation

This module replaces the previously-inbuilt validation functionality of ColdBox and the validator Plugin. The ValidationManager is still available under this WireBox mapping: ValidationManager@cbvalidation. It also gives you the following methods in every handler, view, layout, etc:

validateModel()
getValidationManager()

ColdBox Debugger

If you want to use the ColdBox debugger, you'll need to install the cbdebugger module. Another benifit of this is you can omit this module in production so there's no security concerns with it getting turned on. To install as a development dependency in CommandBox, use the --saveDev flag.

box install cbdebugger --saveDev

Debugger settings can still be set in the main ColdBox.cfc config in a debugger struct. The DebuggerService and Timer are still available via the following WireBox mappings and can be retrieved via getInstance() or property injections.

debuggerService@cbdebugger
timer@cbdebugger

JavaLoader

box install cbjavaloader

This module replaces the JavaLoader plugin and registers the following mapping in WireBox: loader@cbjavaloader.

i18n

box install cbi18n

This module us a combination of both the ResourceBundle plugin and the i18n plugin rolled together now and represented by the following two WireBox mappings:

i18n@cbi18n
resourceService@cbi18n

This module also adds the following methods into your handlers, views, layouts, etc:

getFWLocale()
setFWLocale()
getResource()

ORM

box install cborm

This module brings you all the ORM virtual services that are in ColdBox 3.x and replaces the ORMService Plugin, but note that the component paths have been updated. Instead of starting with coldbox.system they start with cborm.

Unfortunately, due to the way that ORM is loaded by ColdFusion, if you are using the ORM EventHandler or ActiveEntity or any ColdBox Proxies that require ORM, you must create an Application Mapping in the Application.cfc like this:

this.mappings[ "/cborm" ] = COLDBOX_APP_ROOT_PATH & "modules/cborm";

This module also comes with two new WireBox DSL namespaces for injecting entity services:

// Inject a global ORM service
property name="genericEntityservice" inject="entityservice";

// Inject a Virtual entity service according to entityName
property name="foobarService" inject="entityservice:foobar";

Commons

box install cbcommons

cbcommons has a collection of various utilities for you to use which is made up of what used to be the following plugins:

JVMUtils Plugin
Zip Plugin
DateUtils Plugin
QueryHelper Plugin
FileUtils Plugin
Utilities Plugin

This module makes the same functionality available via these registered WireBox mappings:

JVMUtils@cbcommons
Zip@cbcommons
DateUtils@cbcommons
QueryHelper@cbcommons
FileUtils@cbcommons

ioc

box install cbioc

The module replaces the ioc plugin and registers the following mapping in WireBox: factory@cbioc which abstracts any IoC engine with typical methods like getBean() and containsBean()

Feeds

box install cbfeeds

The cbfeeds module replaces the old FeedGenerator Plugin and FeedReader Plugin by registering the following WireBox mappings for you to use:

FeedReader@cbfeeds
feedGenerator@cbfeeds

Soap

box install cbsoap

This module replaces the Webservices plugin and registers the following mapping in WireBox: webservices@cbsoap.

Security

box install cbsecurity

This module replaces the Security interceptor. The interceptor still exists, but it is wrapped inside this module as cbsecurity.interceptors.Security and it is registered with the parent application as soon as the module is loaded so you don't need to register the interceptor manually anymore.

WireBox DSL Namespaces

Some of these were covered above, but for completeness, here is a comprehensive list of the WireBox DSL Namespaces that are removed.

Model Convention

The model convention has been renamed to models to be consistent with pluralization. So you must either rename your folder or use Custom Conventions in your Configuration CFC.

ColdBox OCM Dropped

The ColdBox OCM (Object Cache Manager) has been a thin facade to CacheBox ever since ColdBox 3.0 came out. We are now removing this terminology completely in favor of direct interaction with CacheBox. References to the getColdboxOCM() method have been removed. Instead, call getCache().

JSON Plugin Dropped

The JSON plugin is no longer used in ColdBox in favor of native CFML serialization. The old plugin is in ForgeBox and can easily be converted to a model or module for use in ColdBox 4 if you need it.

BeanFactory Plugin Dropped

This plugin has been a thin facade to WireBox ever since ColdBox 3.0 came out. We are now removing the plugin and you can inject WireBox directly to get object instances. Or better yet, use our injection DSLs to inject the object instance you want directly.

Autowire Interceptor Dropped

This interceptor hasn't actually done anything in a while since WireBox now autowires new objects automatically. Remove any references to coldbox.system.interceptors.Autowire from your config. There is no need to replace it with anything.

Logger Plugin Dropped

This plugin has been a this facade to LogBox ever since ColdBox 3.0 came out. We are now removing the plugin and you can inject LogBox or a specific Logger directly for your logging needs.

Renderer Plugin Dropped

The renderer still exists, but not in plugin form. It has become a core part of the framework. If you need access to the renderer, use the getRenderer() method in the controller or the coldbox:renderer WireBox DSL.

var renderer = controller.getRenderer();

property name="renderer" inject="coldbox:renderer";

HTMLHelper Plugin Dropped

The functionality provided by the HTMLHelper plugin is still available in the core of ColdBox but now as a model. Access it by using the new WireBox mapping: HTMLHelper@coldbox. Views and layouts still have access to the HTMLHelper via the variable html like always. This has not changed.

XMLConverter Plugin Dropped

The functionality provided by the XMLConverter plugin is still available in the core of ColdBox but now as a model. Access it by using the new WireBox mapping: xmlConverter@coldbox.

Validator Plugin Dropped

Removed from core

Datasource Bean Dropped

The datasource bean has been droped in favor of flat structures. So instead of getting a bean representing a datasource structure, you just get the structure. So some old code like this:

<!--- Dependencies --->
<cfproperty name="dsn" inject="coldbox:datasource:mydsn">

<!--- list --->
<cffunction name="list" output="false" access="public" returntype="query" hint="Return the contacts">
    <cfset var q = "">

    <cfquery name="q" datasource="#dsn.getName()#">
    SELECT *
        FROM contacts
    ORDER BY name asc
    </cfquery>

    <cfreturn q>

</cffunction>

Would become this:

<!--- Dependencies --->
<cfproperty name="dsn" inject="coldbox:datasource:mydsn">

<!--- list --->
<cffunction name="list" output="false" access="public" returntype="query" hint="Return the contacts">
    <cfset var q = "">

    <cfquery name="q" datasource="#dsn.name#">
    SELECT *
        FROM contacts
    ORDER BY name asc
    </cfquery>

    <cfreturn q>

</cffunction>

Exception Bean moved to prc in the exceptionHandler

If you have configured a global exceptionHandler it used to receive the exception as rc.exceptionBean. Now it will be accessible via prc.exception.

afterAspectsLoad interception point removed

Most everything that was considered an "aspect" is now no longer part of the core. The afterAspectsLoad interception point has been removed. You can still use the afterConfigurationLoad interception point that will fire once the framework has loaded. If you need to work with models or settings that are registered via modules, this interception point is for you.

About This Book

The source code for this book is hosted in GitHub: https://github.com/ortus-docs/coldbox-docs. You can freely contribute to it and submit pull requests. The contents of this book is copyright by Ortus Solutions, Corp and cannot be altered or reproduced without author's consent. All content is provided "As-Is" and can be freely distributed.

The majority of code examples in this book are done in cfscript.
The majority of code generation and running of examples are done via CommandBox: The ColdFusion (CFML) CLI, Package Manager, REPL - http://www.ortussolutions.com/products/commandbox
All ColdFusion examples designed to run on the open soure Lucee Platform or Adobe ColdFusion 11+

External Trademarks & Copyrights

Flash, Flex, ColdFusion, and Adobe are registered trademarks and copyrights of Adobe Systems, Inc.

Notice of Liability

The information in this book is distributed “as is”, without warranty. The author and Ortus Solutions, Corp shall not have any liability to any person or entity with respect to loss or damage caused or alleged to be caused directly or indirectly by the content of this training book, software and resources described in it.

Contributing

We highly encourage contribution to this book and our open source software. The source code for this book can be found in our GitHub repository where you can submit pull requests.

Charitable Proceeds

10% of the proceeds of this book will go to charity to support orphaned kids in El Salvador - https://www.harvesting.org/. So please donate and purchase the printed version of this book, every book sold can help a child for almost 2 months.

Shalom Children's Home

Shalom Children’s Home (https://www.harvesting.org/) is one of the ministries that is dear to our hearts located in El Salvador. During the 12 year civil war that ended in 1990, many children were left orphaned or abandoned by parents who fled El Salvador. The Benners saw the need to help these children and received 13 children in 1982. Little by little, more children came on their own, churches and the government brought children to them for care, and the Shalom Children’s Home was founded.

Shalom now cares for over 80 children in El Salvador, from newborns to 18 years old. They receive shelter, clothing, food, medical care, education and life skills training in a Christian environment. The home is supported by a child sponsorship program.

We have personally supported Shalom for over 6 years now; it is a place of blessing for many children in El Salvador that either have no families or have been abandoned. This is good earth to seed and plant.

Author

Luis Fernando Majano Lainez

Luis Majano is a Computer Engineer with over 15 years of software development and systems architecture experience. He was born in San Salvador, El Salvador in the late 70’s, during a period of economical instability and civil war. He lived in El Salvador until 1995 and then moved to Miami, Florida where he completed his Bachelors of Science in Computer Engineering at Florida International University. Luis resides in Rancho Cucamonga, California with his beautiful wife Veronica, baby girl Alexia and baby boy Lucas!

He is the CEO of Ortus Solutions, a consulting firm specializing in web development, ColdFusion (CFML), Java development and all open source professional services under the ColdBox and ContentBox stack. He is the creator of ColdBox, ContentBox, WireBox, MockBox, LogBox and anything “BOX”, and contributes to many open source ColdFusion projects. He is also the Adobe ColdFusion user group manager for the Inland Empire. You can read his blog at www.luismajano.com

Luis has a passion for Jesus, tennis, golf, volleyball and anything electronic. Random Author Facts:

He played volleyball in the Salvadorean National Team at the tender age of 17
The Lord of the Rings and The Hobbit is something he reads every 5 years. (Geek!)
His first ever computer was a Texas Instrument TI-86 that his parents gave him in 1986. After some time digesting his very first BASIC book, he had written his own tic-tac-toe game at the age of 9. (Extra geek!)
He has a geek love for circuits, microcontrollers and overall embedded systems.
He has of late (during old age) become a fan of running and bike riding with his family.

Keep Jesus number one in your life and in your heart. I did and it changed my life from desolation, defeat and failure to an abundant life full of love, thankfulness, joy and overwhelming peace. As this world breathes failure and fear upon any life, Jesus brings power, love and a sound mind to everybody!
“Trust in the LORD with all your heart, and do not lean on your own understanding.” – Proverbs 3:5

Contributors

Jorge Emilio Reyes Bendeck

Jorge is an Industrial and Systems Engineer born in El Salvador. After finishing his Bachelor studies at the Monterrey Institute of Technology and Higher Education ITESM, Mexico, he went back to his home country where he worked as the COO of Industrias Bendek S.A.. In 2012 he left El Salvador and moved to Switzerland in persuit of the love of his life. He married her and today he resides in Basel with his lovely wife Marta and their daughter Sofía.

Jorge started working as project manager and business developer at Ortus Solutions, Corp. in 2013, . At Ortus he fell in love with software development and now enjoys taking part on software development projects and software documentation! He is a fellow Cristian who loves to play the guitar, worship and rejoice in the Lord!

Therefore, if anyone is in Christ, the new creation has come: The old has gone, the new is here! 2 Corinthians 5:17

Brad Wood

Brad grew up in southern Missouri where he systematically disassembled every toy he ever owned which occasionally led to unintentional shock therapy (TVs hold charge long after they've been unplugged, you know) After high school he majored in Computer Science with a music minor at MidAmerica Nazarene University (Olathe, KS). Today he lives in Kansas City with his wife and three girls where he still disassembles most of his belongings (including automobiles) just with a slightly higher success rate of putting them back together again.) Brad enjoys church, all sorts of international food, and the great outdoors.

Brad has been programming CFML for 12+ years and has used every version of CF since 4.5. He first fell in love with ColdFusion as a way to easily connect a database to his website for dynamic pages. Brad blogs at (http://www.codersrevolution.com) and likes to work on solder-at-home digitial and analog circuits with his daughter as well as building projects with Arduino-based microcontrollers.

Brad's CommandBox Snake high score is 141.

For Newbies

60 Minute Quick Start

This guide has been designed to get you started with ColdBox in fewer than 60 minutes. We will take you by the hand and help you build a RESTFul application in 60 minutes or fewer. After you complete this guide, we encourage you to move on to the Getting Started Guide and then to the other guides in this book.

Requirements

Please make sure you download and install the latest CommandBox CLI. We will show you how in the Installing ColdBox section.
Grab a cup of coffee
Get comfortable

Installing ColdBox

Welcome to the world of ColdBox!

We are excited you are taking this development journey with us. Before we get started with ColdBox let's install CommandBox CLI, which will allow you to install/uninstall dependencies, start servers, have a REPL tool and much more.

IDE Tools

ColdBox has the following supported IDE Tools:

CommandBox CLI

The first step in our journey is to install CommandBox. CommandBox is a ColdFusion (CFML) Command Line Interface (CLI), REPL, Package Manager and Embedded Server. We will be using CommandBox for almost every excercise in this book and it will also allow you to get up and running with ColdFusion and ColdBox in a much speedier manner.

Note : However, you can use your own ColdFusion server setup as you see fit. We use CommandBox as everything is scriptable and fast!

Download CommandBox

You can download CommandBox from the official site: https://www.ortussolutions.com/products/commandbox#download and install in your preferred Operating System (Windows, Mac, *unix). CommandBox comes in two flavors:

No Java Runtime (30mb)
Embedded Runtime (80mb)

So make sure you choose your desired installation path and follow the instructions here: https://commandbox.ortusbooks.com/content/setup/installation.html

Starting CommandBox

Once you download and expand CommandBox you will have the box.exe or box binary, which you can place in your Windows Path or *Unix /usr/bin folder to have it available system wide. Then just open the binary and CommandBox will unpack itself your user's directory: {User}/.CommandBox. This happens only once and the next thing you know, you are in the CommandBox interactive shell!

We will be able to execute a-la-carte commands from our command line or go into the interactive shell for multiple commands. We recommend the interactive shell as it is faster and can remain open in your project root.

All examples in this book are based on the fact of having an interactive shell open.

Installing ColdBox

To get started open the CommandBox binary or enter the shell by typing box in your terminal or console. Then let's create a new folder and install ColdBox into a directory.

mkdir myapp --cd
install coldbox

CommandBox will resolve coldbox from ForgeBox (www.forgebox.io), use the latest version available, download and install it in this folder alongside a box.json file which represents your application package.

Dir 0 Apr 25,2018 11:04:05 coldbox
File 112 Apr 25,2018 11:04:05 box.json

You can also install the latest bleeding edge version by using the coldbox@be slug instead, or any previous version.

That's it. CommandBox can now track this version of ColdBox for you in this directory. In the next section we will scaffold a ColdBox application using an application template.

You can find many scaffolding templates for ColdBox in our Github organization: github.com/coldbox-templates

Uninstalling ColdBox

To uninstall ColdBox from this application folder just type uninstall coldbox.

Updating ColdBox

To update ColdBox from a previous version, just type update coldbox.

My First ColdBox Application

CommandBox comes with a coldbox create app command that can enable you to create application skeletons using one of our official skeletons or your own:

Advanced : A tag based advanced template
AdvancedScript (default): A script based advanced template
elixir : A ColdBox Elixir based template
ElixirBower : A ColdBox Elixir + Bower based template
ElixirVueJS : A ColdBox Elixir + Vue.js based template
rest: A RESTFul services template
rest-hmvc: A RESTFul service built with modules
Simple : A traditional simple template
SuperSimple : The bare-bones template

You can find all our template skeletons here: github.com/coldbox-templates

Scaffolding Our Application

So let's create our first app using the default template skeleton AdvancedScript:

coldbox create app MyApp

This will scaffold the application and also install ColdBox for you. The following folders/files are generated for you:

+coldbox // The ColdBox framework library (CommandBox Tracked)
+config // Configuration files
+handlers // Your handlers/controllers
+includes // static assets
+interceptors // global interceptors
+layouts // Your layouts
+models // Your Models
+modules // CommandBox Tracked Modules
+modules_app // Custom modules
+tests // Test harness
+views // Your Views
+Application.cfc // Bootstrap
+box.json // CommandBox package descriptor
+index.cfm // Front controller

Now let's start a server so we can see our application running:

server start --rewritesEnable

This will start up a Lucee 5 open source CFML engine (If you are in CommandBox 4). If you would like an Adobe ColdFusion server then just add to the command: cfengine=adobe@{version} where {version} can be: 2016,11,10,9.

If you are using CommandBox 3 and below, you will be using a Lucee 4.5 Server.

This command will start a server with URL rewrites enabled, open a web browser for you and execute the index.cfmwhich in turn executes the default event by convention in a ColdBox application: main.index.

Tip: ColdBox Events map to handlers (cfc) and appropriate actions (functions)

That's it, you have just created your first application. Hooray, onward!

Tip: Type coldbox create app help to get help on all the options for creating ColdBox applications.

File/Folder Conventions

ColdBox is a conventions based framework. The location of files and functions matter. Since we scaffolded our first application, let's write down in a table below with the different conventions that exist in ColdBox.

What is the common denominator in all the conventions? That they are all optional.

Re-initializing The Application

There will be times when you make configuration or code changes that are not reflected immediately in the application due to caching. You can tell the framework to _reinit _or restart the application for you via the URL by leveraging the special URL variable fwreinit.

http://localhost:{port}/?fwreinit=1

You can also use CommandBox to reinit the application:

coldbox reinit

Tip: You can add a password to the reinit procedures for further security, please see the configuration section.

My First Handler & View

Now let's create our first controller, which in ColdBox is called Event Handler. Let's go to CommandBox again:

This will generate the following files:

A new handler called hello.cfc inside of the handlers folder
A view called index.cfm in the views/hello folder
An integration test at tests/specs/integration/helloTest.cfc.

Now go to your browser and the following URL to execute the generated event:

You will now see a big hello.index outputted to the screen. You have now created your first handler and view combination.

Handler Code

Let's check out the handler code:

As you can see, a handler is a simple CFC with functions on them. Each function maps to an action that is executed via the URL. The default action in ColdBox is index()which receives three arguments:

event - An object that models and is used to work with the current request
rc - A struct that contains both URL/FORM variables (unsafe data)
prc - A secondary struct that is private only settable from within your application (safe data)

The event object is used for many things, in the case of this function we are calling a setView() method which tells the framework what view to render to the user once execution of the action terminates.

Tip: The view is not rendered in line 7, but rendered after the execution of the action by the framework.

Executing Events

Did you detect a convention here?

The sections in the URL are the same as the name of the event handler CFC (hello.cfc) and method that was generated index(). By convention, this is how you execute events in ColdBox by leveraging the following URL pattern that matches the name of a handler and action function.

You can also nest handlers into folders and you can also pass the name of the folder(s) as well.

If no action is defined in the URL then the default action of index will be used.

All of this URL magic happens thanks to the URL mappings capabilities in ColdBox. By convention, you can write beautiful URLs that are RESTFul and by convention. You can also extend them and create more expressive URL Mappings by leveraging the config/Router.cfc which is your application router.

My First Virtual Event

Now let's create a virtual event, which is basically just a view we want to execute with no event handler controller needed. This is a great way to incorporate non-mvc files into ColdBox, baby steps!

Open the view now (/views/virtual/hello.cfm) and add the following:

Then go execute the virtual event:

You will get the Hello From ColdBox Land! displayed! This is a great way to create tests or even bring in legacy/procedural templates into an MVC framework.

Linking Events Together

ColdBox provides you with a nice method for generating links between events by leveraging an object called event that is accessible in all of your layouts/views and event handlers. This event object is called behind the scenes the request context object, which models the incoming request and even contains all of your incoming FORM and URL variables in a structure called rc.

Tip: You will use the event object to set views, set layouts, set HTTP headers, read HTTP headers, convert data to other types (json,xml,pdf), and much more.

Building Links

The method in the request context that builds links is called: buildLink(). Here are some of the arguments you can use:

Edit Your View

Edit the views/virtual/hello.cfm page and wrap the content in a cfoutput and create a link to the main ColdBox event, which by convention is main.index.

This code will generate a link to the main.index event in a search engine safe manner and in SSL detection mode. Go execute the event: http://localhost:{port}/virtual/hello and click on the generated URL, you will now be navigating to the default event /main/index. This technique will also apply to FORM submissions:

For extra credit try to use more of the buildLink arguments.

URL Structure & Mappings

ColdBox allows you to manipulate the incoming URL so you can create robust URL strategies especially for RESTFul services. This is all done by convention and you can configure it via the application router: config/Router.cfc for more granular control.

Out of the box we provide you with convention based routing that maps the URL to modules/folders/handlers and actions.

route( "/:handler/:action" ).end()

We have now seen how to execute events via nice URLs. Behind the scenes, ColdBox translates the URL into an executable event string just like if you were using a normal URL string:

/main/index -> ?event=main.index
/virtual/hello -> ?event=virtual.hello
/admin/users/list -> ?event=admin.users.list
/handler/action/name/value -> ?event=handler.action&name=value
/handler/action/name -> ?event=handler.action&name=

By convention, any name-value pairs detected after an event variable will be treated as an incoming URL variables. If there is no pair, then the value will be an empty string.

Tip: By default the ColdBox application templates are using full URL rewrites. If your web server does not support them, then open the config/Router.cfc and change the full rewrites method to false: setFullRewrites( false ).

Working With Event Handlers

Event handlers are the controller layer in ColdBox and is what you will be executing via the URLor a FORMpost. All event handlers are singletons, which means they are cached for the duration of the application, so always remember to var scope your variables in your functions.

Tip: For development we highly encourage you to turn handler caching off or you will have to reinit the application in every request, which is annoying. Open the config/ColdBox.cfc and look for the coldbox.handlerCaching setting.

Once you started the server in the previous section and opened the browser, the default event got executed which maps to an event handler CFC (controller) handlers/main.cfc and the method/action in that CFC called index(). Go open the handlers/main.cfc and let's explore the code.

Handler Code

Every action in ColdBox receives three arguments:

event - An object that models and is used to work with the current request
rc - A struct that contains both URL/FORM variables (unsafe data)
prc - A secondary struct that is private only settable from within your application (safe data)

This line event.setView( "main/index" ) told ColdBox to render a view back to the user found in views/main/index.cfm using a default layout, which by convention is called Main.cfm which can be found in the layouts folder.

Executing Events

We have now seen how to add handlers via CommandBox using the coldbox create handler command and also execute them by convention by leveraging the following URL pattern:

Also remember, that if no action is defined in the incoming URL then the default action of index will be used.

Remember that the URL mappings support in ColdBox is what allows you to execute events in such a way from the URL. These are controlled by your application router: config/Router.cfc

Working With Incoming Data

Now, let's open the handler we created before called handlers/hello.cfc and add some public and private variables to it so our views can render the variables.

Let's open the view now: views/hello/index.cfm and change it to this:

If you execute the event now: http://localhost:{port}/hello/index you will see a message of Hello nobody.

Now change the incoming URL to this: http://localhost:{port}/hello/index?name=ColdBox and you will see a message of Hello ColdBox.

Adding A Layout

Every time the framework renders a view, it will try to leverage the default layout which is located in layouts/Main.cfm by convention. This is an HTML file that gives format to your output and contains the location of where the view you want should be rendered.

Layout Code

This location is identified by the following code:

The call to the renderView() method with no arguments tells the framework to render the view that was set using event.setView(). This is called a rendering region. You can use as many rendering regions within layouts or even within views themselves.

Named Regions: The setView() method even allows you to name these regions and then render them in any layout or other views using their name.

Creating A Layout

Let's create a new simple layout with two rendering regions. Open up CommandBox and issue the following commands:

Open the layouts/Funky.cfm layout and let's modify it a bit by adding the footer view as a rendering region.

Using The Layout

Now, let's open the handler we created before called handlers/hello.cfc and add some code to use our new layout explicitly via adding a layout argument to our setView() call.

Go execute the event now: http://localhost:{port}/hello/index and you will see the view rendered with the words funky layout and footer view at the bottom. Eureka, you have now created a layout.

You can also leverage the function event.setLayout( "Funky" ) to change layouts and even concatenate the calls:

event.setView( "hello/index" ) .setLayout( "Funky" );

Adding A Model

Let's complete our saga into MVC by developing the M, which stands for . This layer is all your business logic, queries, external dependencies, etc. of your application, which represents the problem to solve or the domain to solve.

WireBox

Creating A Service Model

Let's create a simple contact listing, so open up CommandBox and issue the following command:

This will create a models/ContactService.cfc with a getAll() method and a companion unit test at tests/specs/unit/ContactServiceTest.cfc. Let's open the model object:

Notice the singleton annotation on the component tag. This tells WireBox that this service should be cached for the entire application life-span. If you remove the annotation, then the service will become a transient object, which means that it will be re-created every time it is requested.

Add Some Data

Let's mock an array of contacts so we can display them later. We can move this to a SQL call later.

You can then leverage it to mock your contacts or any simple/complex data requirement.

Wiring Up The Model To a Handler

We have now created our model so let's tell our event handler about it. Let's create a new handler using CommandBox:

This will create the handler/contacts.cfc handler with an index() action, the views/contacts/index.cfm view and the accompanying integration test tests/specs/integration/contactsTest.cfc.

Let's open the handler and add a new ColdFusion property that will have a reference to our model object.

Please note that inject annotation on the property definition. This tells WireBox what model to inject into the handler's variablesscope.

By convention it looks in the models folder for the value, which in our case is ContactService. Now let's call it and place some data in the private request collection prc so our views can use it.

Presenting The Data

Now that we have put the array of contacts into the prc struct as aContacts, let's display it to the screen using ColdBox's HTML Helper.

The ColdBox HTML Helper is a companion class that exists in all layouts and views that allows you to generate semantic HTML5 without the needed verbosity of nesting, or binding to ORM/Business objects.

Open the contacts/index.cfm and add the following to the view:

That's it! Execute the event: http://localhost:{port}/contacts/index and view the nice table of contacts being presented to you.

Congratulations, you have made a complete MVC circle!

RESTFul Data

Out of the box, ColdBox gives you all the RESTFul capabilities you will need to create robust and scalable RESTFul services. Let's add some RESTFul capabilities to our contact listing we created in the previous section.

Tip: You can find much more information about building ColdBox RESTFul services in our

Producing JSON

If you know beforehand what type of format you will be responding with, you can leverage ColdBox 5's auto-marshalling in your handlers. By default, ColdBox detects any return value from handlers and if they are complex it will convert them to JSON automatically for you:

That's it! ColdBox detects the array and automatically serializes it to JSON. Easy Peasy!

renderData()

The request context object has a special function called renderData() that can take any type of data and marshall it for you to other formats like xml, json, wddx, pdf, text, html or your own type.

Tip: You can find more information at the API Docs for renderData() here )

So let's open the handlers/contacts.cfc and add to our current code:

We have added the following line:

This tells ColdBox to render the contacts data in 4 formats: xml, json, pdf and html. WOW! So how would you trigger each format? Via the URL of course.

Format Detection

ColdBox has the ability to detect formats via URL extensions or an incoming Accepts header. If no extension is sent, then ColdBox attempts to determine the format by inspecting the Accepts header. If we still can't figure out what format to choose, the default of html is selected for you.

Tip: You can also avoid the extension and pass a URL argument called format with the correct format type: ?format=json.

Routing

Let's add a new route to our system that is more RESTFul than /contacts/index.json. You will do so by leveraging the application's router found at config/Router.cfc. Find the configure() method and let's add a new route:

The route() method allows you to register new URL patterns in your application and immediately route them to a target event. You can even give it a human readable name that can be later referenced in the buildLink() method.

We have now created a new URL route called /api/contacts that if detected will execute the contacts.index event. Now reinit the application, why, well we changed the application router and we need the changes to take effect.

Tip: Every time you add new routes make sure you reinit the application: http://localhost:{port}/?fwreinit.

You can now visit the new URL pattern and you have successfully built a RESTFul API for your contacts.