ColdBox 5.2.0 is a minor version update with lots of fixes, improvements and some new features not only to the ColdBox core but to LogBox and WireBox alike. Below are the major areas of improvement and the full release notes. To update your ColdBox installation just leverage CommandBox: update coldbox

ColdBox

The major areas of improvement for the ColdBox core where on tons of fixes, however there are some nice new features discussed below.

Bugs

• [COLDBOX-597] - Function addAsset generate wrong link if asset path contains ".js"

• [COLDBOX-668] - Make implicit views case sensitive by default for linux systems

• [COLDBOX-677] - HTML HELPER - Fix a requirement for columnName if column is defined

• [COLDBOX-696] - Passing headers to `request` breaks RoutingService when in test mode

• [COLDBOX-724] - Add ENV overload in detectEnvironment() via ENVIRONMENT system setting/property

• [COLDBOX-726] - setNextEvent does not exist in coldbox.system.web.Controller

• [COLDBOX-727] - fail fast strong typed to boolean, update to allow closures

• [COLDBOX-729] - getRenderData() in base test case was not looking at the right request collection

• [COLDBOX-732] - Fail fast can't be turned off for original behavior

• [COLDBOX-736] - Module mappings disappear when not unloading ColdBox in base test case

• [COLDBOX-738] - Clear not working on string builders: Use setLength(0) since clear is not a method on StringBuilder

• [COLDBOX-740] - When using group() operations with a handler and no explicit handler routing call added, route never registered the handler

New Features

• [COLDBOX-722] - New global directive: autoMapModels which if true, it will map all root models just like modules do.

This will allow root models to behave like modules where all models are registered automatically for you but with no namespace.

• [COLDBOX-737] - toAction() terminator is missing from the new router DSL

This terminator was missing from the new Routing DSL. This will allow you to build up routes that terminate at an action.

• [COLDBOX-720] - Register config/Router.cfc as an interceptor

The main application router and ALL module routers are now also interceptors.

Improvements

• [COLDBOX-730] - Implicitly pass args from renderLayout() into the rendered views

• [COLDBOX-739] - List modules which have already been processed when a module cannot be activated to help with debugging

LogBox

Bugs

• [LOGBOX-29] - when using async option on FileAppender, nothing logs, well now it does!

New Features

• [LOGBOX-31] - Add defaultValue arguments to getProperty() methods on abstract appenders

Improvements

• [LOGBOX-30] - Leave off text "ExtraInfo: " from console appender if empty string

WireBox

Bugs

• [WIREBOX-76] - Virtual inheritance not injecting generic getters and setters correctly on target objects

• [WIREBOX-77] - Virtual inheritance not inheriting init from super class

Improvements

• [WIREBOX-51] - Add method to binder to override alias of current mapping, by passing the current mapping to the influencer closure

• [WIREBOX-75] - Don't exclude path in parent mapping destinations

• [WIREBOX-78] - Simplify error message for missing dependency to be human readable

ColdBox 5.6.0 is a minor version update with lots of fixes, improvements, performance enhancements and some nice new features. Below are the major areas of improvement and the full release notes. To update ColdBox or any of the standalone libraries just leverage CommandBox:

• update coldbox

• update logbox

• update wirebox

• update cachebox

Major Updates

Performance

We had two specific tickets that have resulted in extreme performance improvements for ALL ColdBox requests. You will feel and see the difference:

• [] - Event Handler Bean: Single instance per handler action for major performance improvements

This ticket was contributed by Dom Watson () one of the lead engineers of the amazing PresideCMS project built on top of ColdBox. We worked together to avoid the creation of handler beans on each runnable event. We now cache each event handler bean representation which results in an extreme boost in performance. Thanks Dom!

• [] - Remove afterInstanceAutowire interceptor in handlerService as afterHandlerCreation is now officially removed.

Thanks to our local mad scientist Brad Wood, he reported that the handler services still listened to ALL CFC creations in an application in order to relay an afterHandlerCreation interception point from the good 'ol 2.6 days. This has been finally removed and boom, another big boost in performance!

Better Bug Reports

We have enhanced the bug reporting templates to include much more information when dealing with exceptions:

• Show SQL error details on Adobe CF

• Current route, params and debug info

• Contributing module for the current routed URL

Merging of HTTP Verbs

Thanks to our very own Eric Peterson, you can now merge HTTP verbs on the same route pattern, which you could not do before:

ColdBox Core Release Notes

Bugs

New Features

Improvements

CacheBox Release Notes

Bugs

Short and sweet release!

Bug

• [] - Left one encodeforhtml in textarea that was missing.

This is a patch release for ColdBox

Bugs

• [COLDBOX-715] - Elvis operator inconsistencies on Adobe Engines, please Adobe, patch the engines and fix your compiler!

Improvements

• [COLDBOX-237] - Some HTMLHelper method still need escaping as certain values should never be HTML

• [COLDBOX-716] - determine session/client state via CF getApplicationMetadata() instead of isDefined() to avoid load issues for flash ram

• [COLDBOX-717] - RemotingUtil converted to cfscript #367

ColdBox 5.3.0 is a minor version update with lots of fixes, improvements, performance enhancements and some nice new features. Below are the major areas of improvement and the full release notes. To update your ColdBox installation just leverage CommandBox: update coldbox

ColdBox

Bugs

• [COLDBOX-741] - Defining UDF as COLDBOX_FAIL_FAST no longer returns false

• [COLDBOX-750] - Fixed typo(s) in call of function prePend() on routing

• [COLDBOX-752] - base url not eliminating double slashes

• [COLDBOX-756] - Setter for valid extensions is setting the wrong variable

• [COLDBOX-759] - Cleanup the with closure on group routing to avoid leakage

New Features

• [COLDBOX-753] - Add new flag to router: multiDomainDiscovery that can be turned on/off

Improvements

• [COLDBOX-742] - Add trimming to asset loader to avoid spaces on links

• [COLDBOX-744] - InterceptorState + EventPool uses syncrhonizedMap that has locking issues: refactor to avoid these issues

• [COLDBOX-754] - set initiated bit for ColdBox after modules are activated

• [COLDBOX-760] - Performance improvements for interception registrations and discovery

LogBox

Improvements

• [LOGBOX-32] - Add test and fix for adding a LogBox category after the fact

WireBox

Improvements

• [WIREBOX-79] - Account for leading slashes in mapDirectory()

• [WIREBOX-80] - Throw a nicer DSL error if ColdBox is not linked

• [WIREBOX-81] - Performance improvements for the construction of transients

ColdBox 5.5.0 is a minor version update with lots of fixes, improvements, performance enhancements and some nice new features. Below are the major areas of improvement and the full release notes. To update your ColdBox installation just leverage CommandBox:

• update coldbox

• update logbox

• update wirebox

• update cachebox

The major libraries updated in this release are ColdBox MVC and WireBox.

Compatibility Notes

If you are using annotations for component aliases you will have to tell WireBox explicitly to process those mappings. As by default, we no longer process mappings on startup.

// Process a single mapping immediately
map( name ).process();

// Process all mappings in the mapDiretory() call
mapDirectory( packagePath="my.path", process=true )
mapDirectory( "my.path" ).process();

// Map all models in a module via the this.autoProcessModels in the ModuleConfig.cfc
this.autoProcessModels = true

Major Updates

Performance

This release is a big performance boost for two areas of operation: modules, and models. The Module Service has been completely revised to make it as fast as possible when registering and activating modules. If you have an extensive usage of modules, you will feel the difference when booting up or re-initing the framework.

The other area is the inspection of models that has been lazy evaluated. This allows for faster bootups and reinits as models are only inspected on demand or when explicitly marked.

More Environment Detection

Our environment functions have now been added to the Framework SuperType and thus all objects in the ColdBox eco-system receive it:

• getEnv(), getSystemSetting() and getSystemProperty()

Custom Resource Patterns

As resources have become more mainstream in ColdBox, we now give you the ability to choose the URL pattern you want to attach to the resource. This allows you to create a-la-carte resource patterns and also allow you to nest resources via patterns.

resources(
  pattern="/site/:siteId/agents",
  resource="agents"
);

ColdBox Release Notes

Bugs

• [COLDBOX-786] - HTMLHelper typo on getSetting call via elixirpath()

• [COLDBOX-788] - Private method in handler is accessible from public ( direct link )

New Features

• [COLDBOX-783] - New module directive: autoProcessModels which defaults to false to defer to lazy processing of models

• [COLDBOX-789] - Added getEnv(), getSystemSetting() and getSystemProperty() to super type for easier environment setting retrievals

• [COLDBOX-790] - Added much more logging and info when booting up the Module Service

• [COLDBOX-791] - buildLink(), relocate() now will translate raw : to / in URL with appropriate module entry points thanks to richard herbert

• [COLDBOX-792] - Allow nested resources and the ability for custom URL patterns for resources

Improvements

• [COLDBOX-782] - Add TestBox 3 and code coverage to the core

• [COLDBOX-785] - Module service performance optimizations for module activations.

• [COLDBOX-787] - Update RequestContext.cfc getFullUrl() to include port number

WireBox Release Notes

New Features

• [WIREBOX-84] - Remove auto processing of all mappings defer to lazy loading

• [WIREBOX-85] - MapDirectory new boolean argument process which defers to false, if true, the mappings will be auto processed

• [WIREBOX-86] - New binder method: process() if chained from a mapping, it will process the mapping's metadata automatically.

Improvement

• [WIREBOX-87] - AOP debug logging as serialized CFCs which clogs log files

ColdBox 5.4.0 is a minor version update with lots of fixes, improvements, performance enhancements and some nice new features. Below are the major areas of improvement and the full release notes. To update your ColdBox installation just leverage CommandBox:

• update coldbox

• update logbox

• update wirebox

• update cachebox

Box Namespace

In our initiative to make all Modules sharable between ColdBox, CommandBox and whatever other boxes we make in the future. We created the box alias for injections. In our case any injection with the prefix coldbox can be used as box

RunRoute()

We have created a new internal runner called runRoute() which is similar to runEvent() but it allows you to abstract your events by leveraging named routes. So just like you can create links based on named routes and params, you can execute named routes and params as well internally via runRoute()

/**
 * Executes internal named routes with or without parameters. If the named route is not found or the route has no event to execute then this method will throw an `InvalidArgumentException`.
 * If you need a route from a module then append the module address: `@moduleName` or prefix it like in run event calls `moduleName:routeName` in order to find the right route.
 * The route params will be passed to events as action arguments much how eventArguments work.
 *
 * @name The name of the route
 * @params The parameters of the route to replace
 * @cache Cached the output of the runnable execution, defaults to false. A unique key will be created according to event string + arguments.
 * @cacheTimeout The time in minutes to cache the results
 * @cacheLastAccessTimeout The time in minutes the results will be removed from cache if idle or requested
 * @cacheSuffix The suffix to add into the cache entry for this event rendering
 * @cacheProvider The provider to cache this event rendering in, defaults to 'template'
 * @prePostExempt If true, pre/post handlers will not be fired. Defaults to false
 *
 * @throws InvalidArgumentException
 */
any function runRoute(
	required name,
	struct params={},
	boolean cache=false,
	cacheTimeout="",
	cacheLastAccessTimeout="",
	cacheSuffix="",
	cacheProvider="template",
	boolean prePostExempt=false
)

CacheBox Rewritten

This should have been a major release on its own. The entire CacheBox framework was re-written in script and modernized from top to bottom. We removed all implicit variable access which gave us huge performance boosts and we streamlined all operations with modern techniques. The results are great and our maintenance will be much less in the future. A part from those optimizations we managed to add a few nice items:

• Adobe 2018 certified

• New setting resetTimeoutOnAccess which allows you to simulate session scopes on any CacheBox cache. Every time a get() operation is done, that item's timeout will be reset.

• All cache providers get some multi function goodness: setMulti(), getMulti(), lookupMulti(), clearMulti(),getCachedObjectMetadataMulti()

LogBox Improvements

There are two major improvements we did with LogBox in this release:

1) The file locking operations on file appenders have been streamlined to avoid high i/o operations.

2) The console appender uses an asynchronous streaming technique which makes it extremely efficient and fast.

ColdBox Release Notes

Bugs

• [COLDBOX-556] - prePostExempt doesn't skip around advices

• [COLDBOX-755] - Core interceptors in coldbox.cfc do not listen or register custom interception points that are contributed by modules

• [COLDBOX-761] - invalidEventHandler gets in to an infinite loop when the invalidEventHandler isn't a full event

• [COLDBOX-766] - ColdBox shutdown errors onApplicationEnd due to lack of application scope

• [COLDBOX-770] - Use of event.sendFile delivers a file with single quotes in the name

• [COLDBOX-773] - Remove default defaultValue as it never will throw an exception if missing on requestcontext on getHTTPHeader()

New Features

• [COLDBOX-765] - Update all elixir methods to match new version

• [COLDBOX-771] - Add Elixir version 3 path methods

• [COLDBOX-775] - Added `:` as a delimiter for the route() method when using modules to be consistent with run event

• [COLDBOX-776] - new runner: runRoute() that allows you to run routes internally with param passing

Improvements

• [COLDBOX-767] - Change "module already registered" from warn to debug

• [COLDBOX-774] - Introduce generic "box" namespace for Wirebox injections

CacheBox Release Notes

Bugs

• [CACHEBOX-46] - CacheboxProvider metadata and stores: use CFML functions on java hash maps breaks concurrency

• [CACHEBOX-50] - getOrSet() provider method doesn't work with full null support

• [CACHEBOX-52] - getQuiet(), clearQuiet(), getSize(), clearAll(), expireAll() broken in acf providers

New Features

• [CACHEBOX-48] - New setting: `resetTimeoutOnAccess` to allow the ability to reset timeout access for entries

• [CACHEBOX-49] - Global script conversion and code optimizations

• [CACHEBOX-53] - lookup operations on ACF providers updated to leverage cacheIdExists() improves operation by over 50x

• [CACHEBOX-54] - setMulti(), getMulti(), lookupMulti(), clearMulti(),getCachedObjectMetadataMulti() is now available on all cache providers

Improvements

• [CACHEBOX-47] - Increased timeout on `getOrSet` lock

• [CACHEBOX-51] - Consolidated usages of the abstract cache provider to all providers to avoid redundancy

WireBox Release Notes

Bugs

• [WIREBOX-82] - builder.toVirtualInheritance(): scoping issues

• [WIREBOX-83] - When using sandbox security, and using a provider DSL the file existence checks blow up

LogBox Release Notes

New Features

• [LOGBOX-34] - Console appender completely rewritten to support asynchronous streaming

Improvements

• [LOGBOX-33] - Improve file exists usage on file appenders to avoid i/o operations

ColdBox 5.0.0 is a major release for the ColdBox MVC platform. It has been long standing as we have been learning so much especially around containerization and portability. This release has over 70 key issues addressed from new features, improvements and bug fixes. So let's begin our ColdBox 5 adventure.

Global Versioning

All internal libraries now have a standard version according to the major ColdBox release of 5.0.0. Further releases of WireBox, CacheBox and LogBox will adhere to the unified version.

Engine Deprecation

It is also yet another source code reduction due to the dropping of support for the following CFML Engines:

• Adobe ColdFusion 9

• Adobe ColdFusion 10

That's right, you will need Adobe ColdFusion 11+ or Lucee 4.5+ in order to work with ColdBox 5.

Automation

We have fully automated all build processes with ColdBox 5 to include CommandBox and TestBox testing, Travis integration and a fully automated test suite that executes against ALL supported CFML engines. Our code coverage has increased dramatically due to this work. We discovered engine bugs that must have plagued our users for years. YAY for testing!

Performance Improvements & Optimizations

As we update core files we keep optimizing the source code and migrating to full cfscript. This migration has allowed us to optimize very old code into modern times with significant performance gains. We have also moved from internal Java reflection to get file information to native CFML functions since now all engines support it. Just this alone has improved vanilla requests tremendously.

WireBox object creation and manipulation has also increased due to new locking strategies in our Mixer Util. You will especially see the difference when creating many transient objects.

Lucee Full Null Support

Thanks to the community we have now full null support for the Lucee CFML engine and up-coming Adobe 2018.

Core Framework Exception Handling

The core framework has been revised with a fine tooth comb to provide better exception messages, better helpful messages and also the ability to intercept exceptions at the framework level via normal exception handlers. You will also see that ColdBox can detect response headers now and make sure it can avoid caching exceptions when event caching is turned on. The appropriate status code will now be reported.

You will also find in the log files attempts to reinit the framework with invalid or missing passwords.

Containers + Environments Support

ColdBox introduces two new methods that are available for your ColdBox.cfc and your ModuleConfig.cfc objects:

• getSystemProperty( name, defaultValue ) - Retrieve a Java System property

• getSystemSetting( name, defaultValue ) - Discover an environment variable either by searching system properties first and then system environment variables second.

Hint These methods are also found in the ColdBox core utility object: coldbox.system.core.util.Util which can be injected anywhere it is needed.

These methods will allow you to interact with docker environment variables and override settings, add new settings, and much more.

Modules, Modules and more Modules

We continue to innovate in the Hierarchical MVC (HMVC) design of ColdBox by fine-tuning the modular services and interactions. Here are the major updates to modules in ColdBox 5.

• All module interceptors are now namespaced to avoid name conflicts with other modules.

• New modules injected variable: coldboxVersion to be able to quickly detect what version of ColdBox they are running under. This will allow you to create modules that can respond to multiple ColdBox versions.

Inherited Entry Point

All modules have had a URL entry point since the beginning: this.entryPoint = "/route". This entry point is registered in the URL mappings to allow for a unique URL pattern to exist for specific modules. That is great! However, in modern times and with the amount of API centric applications that we are building, we wanted to introduce an easier way to build resource centric APIs.

What if our resource URLs could match by convention our module inceptions? Well, with the new inherited entry points, you can do just that. By leveraging HMVC and module inception you can now create automatic URL nesting schemas.

You can turn this on just by adding the following flag in your ModuleConfig.cfc:

When the module is registered it will recurse its parent tree and discover all parent entry points and assemble the entry point accordingly. Let's see an example. We are working on an API and we want to create the following URL resource: /api/v1/users. We can leverage HVMC and create the following modular structure:

This models our URL resource modularly. We can now go into each of the module's ModuleConfig and add only the appropriate URL pattern and turn on inherit entry point.

This feature will not only help you identify API routing, but help you build with modularity in mind. You will also find a new method in the request context called getModuleEntryPoint() to retrieve a modules inherited entry point, which is great for URL building.

New Module Events

You can now listen to more events of the module life-cycle:

• preModuleRegistration - before each module is registered

• postModuleRegistration - after each module is registered

• afterModuleRegistrations - This will fire when all modules have been registered. This is great if you want modules to dynamically depend on each other.

• afterModuleActivations - This will fire when all modules have been succesfully activated. Great for caching updates, announcements, etc.

Modules_app convention for inception

We have now added the modules_app convention for all module inceptions.

Default Model Export Convention

If you create a module where there is a model with the same name, then we will automatically map it in Wirebox as @modulename.

This is great for 1 model modules.

Routing Enhancements

We continue to push forward in making ColdBox the best RESTFul framework for ColdFusion (CFML). In ColdBox 5 we have great new additions for both routing and rendering.

Simplified URL Rewrites

The SES interceptor now has a boolean flag to denote if rewrites are turned on/off and you will no longer set a base URL. We will automatically detect the base URLs according to multi-domain hosting. Meaning you can out of the box create multi-tenant applications with ease. We will also be adding subdomain routing in our final release.

Named Routes

This has been a long-time coming to ColdBox and I can't believe we had never added this before. Well, named routes are here, finally!

If you have used other frameworks in other languages, they allow you to name your routes so you can build links to them in an easier manner. We have done just the same. The addRoute() method accepts the name parameter and we have extended the request context with some new methods:

• getCurrentRouteName() - Gives you the name of the current route, if any

• route() - Allows you to build URLs according to named routes

Define the Route

Build Links

The route method signature can be seen below:

Resourceful Routes

In ColdBox 5, you can register resourceful routes to provide automatic mappings between HTTP verbs and URLs to event handlers and actions by convention. By convention, all resources map to a handler with the same name or they can be customized if needed. This allows for a standardized convention when building routed applications.

You will now have a new resources() method in the SES interceptor or a resources struct in your modules. Yes, all modules can have their own resourceful routes as well.

This single resource declaration will create all the necessary variations of URL patterns and HTTP Verbs to actions to handle the resource. It will even create named routes for you.

For in-depth usage of the resources() method, let's investigate the API Signature:

Event Execution

We have also done several updates for event executions, event caching and overall MVC operations:

• You can now return the event object from event handlers and the framework will not fail. It will be ignored.

• setNextEvent() is now deprecated in favor of a relocate() method.

• Request context has a getOnly( keys, private=false ) method to allow for retrieval of certain keys only from the public or private request contexts. Great for functional programming.

Event Caching Enhancements

Dynamic Cache Suffix

You can now leverage the cache suffix property in handlers to be declared as a closure so it can be evaluated at runtime instead of a static prefix.

With this ability you can enable dynamic cache suffixes according to runtime environments on a per user basis.

Cache Provider Annotations

You can now add a cacheProvider annotation to your cache enabled functions and decide to which CacheBox provider the output will be cached too instead of the default provider of template:

Rendering Enhancements

We have also done tremendous updates to the rendering engines in ColdBox 5, especially for RESTFul responses and content negotiation.

• ColdBox now detects the rc.format not only to incoming URL extensions, but also via the Accept Header as content-negotiation.

• New interception point afterRenderInit which will allow you to add your own injections to the main ColdBox renderer and modify the renderer at runtime.

• The request context can now deliver files to users via our sendFile() method.

Native JSON Responses + Handler Auto-Marshalling

JSON is the native response now for event handlers that return complex variables.

That's it! If you return a complex variable from an event handler, ColdBox will convert it to JSON for you automatically. We will even inspect the return object and if it has a $renderdata() method, we will call it for you and return your very own marshalled data! But there's more. You can add a renderData annotation to your action and add any valid renderdata() type and it will return it accordingly.

You can even add a default response type by adding the renderdata annotation to the component construct:

Named Regions

We have introduced the concept of named rendering regions with ColdBox 5. As we increase the reuse of views and create many self-sufficient views or widgets, we end up with setView() or renderView() method calls that expose too much logic, location, parameters, etc. With named regions, we can actually abstract or describe how a region should be rendered and then render it when we need it via a name.

Definition

Rendering

Testing Enhancements

Here are some of the major updates for integration testing with ColdBox and TestBox:

• Reset the response when calling setup() in integration testing to avoid duplicate headers within same request executions.

• Base test case doesn't allow for inherited annotations. It now does since we moved the testing life-cycle methods to be annotation based instead of by name.

• Added dynamic methods getRenderData() and getStatusCode() helpers to the request context upon execute() execution. This will allow you a shorthand approach to getting response status codes and response rendering data struct.

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

ColdBox Manual - v5.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

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

ColdBox Manual - v5.0.0

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

The source code for this book is hosted in GitHub: . You can freely contribute to it and submit pull requests. The contents of this book is copyright by 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 -

• 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 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 - . 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 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.

ColdBox 5.1.0 is a minor version update with lots of fixes, improvements and some new features. Below are the major areas of improvement and the full release notes. To update your ColdBox installation just leverage CommandBox: update coldbox

Event Caching Improvements

The event caching cleanup and clearing methods did not work when using granular query strings. This has now been resolved and optimized.

New Auto-Deserialization of JSON Payloads

If you are working with any modern JavaScript framework, this feature is for you. ColdBox on any incoming request will inspect the HTTP Body content and if the payload is JSON, it will deserialize it for you and if it is a structure/JS object, it will append itself to the request collection for you. So if we have the following incoming payload:

The request collection will have 3 keys for name, type and data according to their native CFML type.

Flash Scope getAll()

The flash scope needed a way to get all of its name-value pair elements in one shot, you can now with the getAll() method.

Complete Rewrite of the HTML Helper

The HTML helper has been completely rewritten in 5.1 into script notation, optimized for performance and security. All HTML output is now XSS encoded for attributes and tag content.

View and Directory Helper Combo

You can now declare a view and directory helper and ColdBox will use them both instead of always picking the view helper only. The order of inclusion is:

• directory helper

• view helper

• view

ColdBox Fail Fast

This is a nice feature that will give your applications stability when doing deployments or production reinits. We have added a new application variable flag: application.fwReinit which is set to true when the framework is reinitializing and false when it completes. We have also added a new directive called COLDBOX_FAIL_FAST which defaults to true.

If fail fast is activated, the framework will present a nice message to users that the application is not yet available instead of holding them in a queue waiting for the reinit or application load to finish. This fail fast will release your traffic queue and produce less timeouts and failures.

The fail fast directive can also be a closure. Then we will execute your closure and you can do whatever you like within it to advice your users' about the reinit. Below you can see what happens with the fail fast code.

Release Notes

Bugs

New Features

Improvements

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 guide to give you a full overview of the changes.

event.getCurrentHandler() returns different results

In ColdBox 4, calling getCurrentHandler() would return the module if it existed:

In ColdBox 5, we correctly remove the module name so it can be retrieved via getCurrentModule() instead.

setNextEvent() deprecated in favor of relocate()

The setNextEvent() method has been renamed to relocate() to better adjust to modern times. This deprecation will be removed in future versions of ColdBox.

Modules AutoReload deprecated

The modules autoReload flag has been deprecated. This causes more headaches than anything. If you want changes reflected, reinit the framework.

onInvalidEvent renamed to invalidEventHandler

The ColdBox construct setting onInvalidEvent has been renamed now to invalidEventHandler. This will be removed in future versions of ColdBox.

setAutoReload() Removed

The setAutoReload() flag in the SES interceptor has been removed. It is evil I tell you. If you want your routing to be re-read, then reinit the framework.

BuildLink LinkTo Argument Deprecated

The buildLink() method had the argument linkTo to denote the event or route to link to. This was verbose, so we shortened it to to:

Railo Support Dropped

Railo support dropped. Any classes that started with the word Railo need to be changed to Lucee especially on the CacheBox providers.

ColdFusion 9-10 Support Dropped

ColdFusion 9-10 support has been dropped. Adobe doesn't support them anymore, so neither do we.

Datasources Configuration Dropped

The datasources configuration setting directive has been dropped in favor of just leveraging the settings directive. Just move your datasource metadata into the settings struct and reference it using the settings DSL.

Previous

New

DSL Builder Interface Update

The WireBox interface: coldbox.system.ioc.dsl.IDSLBuilder has changed in ColdBox 5, so if you are implementing your own DSLs, then you must update it like so:

In ColdBox 5 we removed the output attribute:

Interceptor Update

appendToBuffer() Dropped

The string buffer has been updated in order to become thread safe and there are several methods that have been deprecated. Instead of using appendToBuffer() you need to use the buffer argument.

Previous

New

This is a patch release for ColdBox.

Bug

• [] - regression onmissingmethod on html helper method was public and changed to private

• [] - viewModule logic was not working at all yet again.

Improvement

• [] - Remove setting throwOnInvalidInterceptionStates, makes no sense anymore

• [] - Moved order of event manager states the injector provides to a ColdBox app so the binder can listen on itself

This is a patch release for ColdBox

Bugs/Regressions

• [] - HTML helper cannot add fontawesome icons in button due to XSS enabled by default

• [] - ColdBox shutdown code that uses CF mappings for modules fails on fwreinit

• [] - addAsset throw error when called from handlers

Improvements

• [] - Too many issues when encoding by default for HTML Helper, revert to non-encoded and provide ways to encode globally and a-la-carte

• [] - Framework setting for the automatic deserialization of JSON payloads to the RC: jsonPayloadToRC

Automatic JSON Payload Setting

The automatic JSON to request collection feature defaults now to false to avoid backwards compatibility. You can easily turn it on via the setting: coldbox.jsonPayloadToRC

HTML Helper Changes

The HTML Helper has been migrated to an internal module in this release. It allows you to configure it via the following configuration settings in your ColdBox.cfc.

Injection Shortcut

You can also now inject the HTML helper anywhere using it's injection DSL Shortcut of @HTMLHelper

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.

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:

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.

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.

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 and then to the other guides in this book.

Requirements

• Please make sure you download and install the latest . We will show you how in the .

• Grab a cup of coffee

• Get comfortable

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:

• Sublime -

• VSCode -

• CFBuilder -

CommandBox CLI

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

1. No Java Runtime (30mb)

2. Embedded Runtime (80mb)

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.

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.

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.

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 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 . Luis resides in Rancho Cucamonga, California with his beautiful wife Veronica, baby girl Alexia and baby boy Lucas!

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 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 Christian 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's CommandBox Snake high score is 141.

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

• 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

Scaffolding Our Application

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

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

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

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.

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

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.

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.

You can also use CommandBox to reinit the application:

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)

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.

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.

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.

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:

any function index( event, rc, prc ){
    return contactService.getAll();    
}

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

If you want your incoming JSON requestbody to be handled the same as FORM and URL variables you can enable coldbox.jsonPayloadToRC = true in your coldbox config. See releasenotes 5.1.0 and 5.1.2 for details.

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.

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

any function index( event, rc, prc ){
    prc.aContacts = contactService.getAll();    
    event.renderData( data=prc.aContacts, formats="xml,json,pdf,html" );
}

We have added the following line:

event.renderData( data=prc.aContacts, formats="xml,json,pdf,html" );

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.

# Default: The view is presented using no extension or html,cfm
http://localhost:{port}/contacts/index
http://localhost:{port}/contacts/index.html
http://localhost:{port}/contacts/index.cfm

# JSON output
http://localhost:{port}/contacts/index.json
# OR Accepts: application/json

# XML output 
http://localhost:{port}/contacts/index.xml
# OR Accepts: application/xml

# PDF output
http://localhost:{port}/contacts/index.pdf
# OR Accepts: application/pdf

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:

// Restuful Route
route( 
    pattern="/api/contacts",
    target="contacts.index",
    name="api.contacts"
);

// Default Route
route( ":handler/:action?" ).end();

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.

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

http://localhost:{port}/api/contacts.json

Congratulations! Did you finish this guide in less than 60 minutes? If you did please leave us some great feedback below. If you didn't, then please do tell us why, we would love to improve our guides.

You can now move on to the next level in becoming a ColdBox Guru! Choose your path below:

• Learn about HMVC via ColdBox Modules

• Learn about Dependency Injection

• Learn about Caching

• Learn about Logging

• Learn about Testing

Getting Help

If you run into issues or just have questions, please jump on our ColdBox Google Group and our Slack team and ask away.

ColdBox is Professional Open Source under the Apache 2.0 license. We'd love to have your help with the product.

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:

<div id="maincontent">
#renderView()#
</div>

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.

Creating A Layout

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

# Create a Funky layout
coldbox create layout name="Funky"

# Create a footer
coldbox create view name="main/footer"

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

<h1>funky Layout</h1>
<cfoutput>#renderView()#</cfoutput>

<hr>
<cfoutput>#renderView( "main/footer" )#</cfoutput>

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.

function index( event, rc, prc ){
    // param an incoming variable.
    event.paramValue( "name", "nobody" );
    // set a private variable
    prc.when = dateFormat( now(), "full" );

    // set the view to render with our new layout
    event.setView( view="hello/index", layout="Funky" );
}

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.

In order to create a ColdBox application you must adhere to some naming conventions and a pre-set directory structure. This is needed in order for ColdBox to find what it needs and to help you find modules more easily instead of configuring every single area of your application.

You can also configure many aspects of ColdBox, third-party modules and application settings in our programmtic configuration object: ColdBox.cfc.

Reinitializing An Application

Please note that anytime you make any configuration changes or there are things in memory you wish to clear out, you will be using a URL action that will tell the ColdBox Bootstrapper to reinitialize the application. This special URL variable is called fwreinit and can be any value or a specific password you setup in the ColdBox configuration directive.

// reinit with no password
index.cfm?fwreinit=1

// reinit with password
index.cfm?fwreinit=mypass

You can also use CommandBox to reinit your application if you are using its embedded server:

CommandBox>coldbox reinit

The CacheBox structure is based on the CacheBox declaration DSL, and it allows you to customize the caches in your application. Below are the main keys you can fill out, but we recommend you review the CacheBox documentation for further detail.

//cachebox configuration
cachebox = {
    // Location of the configuration CFC for CacheBox
    configFile = "config/CacheBox.cfc",
    // Scope registration for CacheBox
    scopeRegistration = {enabled=true,scope=application,key=cacheBox},
    // Default Cache Configuration
    defaultCache  = "views",
    // Caches Configuration
    caches      = {}
};

Info : We would recommend you create a config/CacheBox.cfc and put all your caching configuration there instead of in the main ColdBox configuration file. This will give you further portability and decoupling.

ConfigFile

An absolute or relative path to the CacheBox configuration CFC or XML file to use instead of declaring the rest of the keys in this structure. So if you do not define a cacheBox structure, the framework will look for the default value: config/CacheBox.cfc and it will load it if found. If not found, it will use the default CacheBox configuration found in /coldbox/system/web/config/CacheBox.cfc

ScopeRegistration

A structure that enables scope registration of the CacheBox factory in either server, cluster, application or session scope.

DefaultCache

The configuration of the default cache which will have an implicit name of default which is a reserved cache name. It also has a default provider of CacheBox which cannot be changed.

Caches

A structure where you can create more named caches for usage in your CacheBox factory.

The core conventions delineate the contract between ColdBox and you for file/directory locations and more. Below is a table of the core conventions:

Directory/File Conventions

• config/Coldbox.cfc - Your application configuration object (optional)

• config/Router.cfc - Your application URL Router (optional)

• handlers - This holds the app's controllers

• layouts - Your HTML layouts

• models - This holds your app's CFCs

• modules - This holds the CommandBox tracked modules

• modules_app - This holds your app's modules

• views - Your HTML views will go here

Execution Conventions

The basic configuration object has 1 method for application configuration called configure() where you will place all your configuration directives and settings:

/**
* A simple CFC that configures a ColdBox application.  You can even extend, compose, strategize and do your OO goodness.
*/
component{

    // Mandatory configuration method
    function configure(){
        coldbox = {
          
        };
    }
    
}

Directives

Inside of this configuration method you will place several core and third-party configuration structures that can alter your application settings and behavior. Below are the core directives you can define:

Let's complete our saga into MVC by developing the M, which stands for model. 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

This layer is controlled by WireBox, the dependency injection framework within ColdBox, which will give you the flexibility of wiring your objects and persisting them for you.

Creating A Service Model

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

coldbox create model name="ContactService" methods="getAll" persistence="singleton"

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:

component singleton accessors="true"{      

    ContactService function init(){         
        return this;     
    }

    function getAll(){      

    }

}

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.

component singleton accessors="true"{

    ContactService function init(){
        variables.data = [
            { id=1, name="coldbox" },
            { id=2, name="superman" },
            { id=3, name="batman" }
        ];    
        return this;

    }

    function getAll(){
        return variables.data;
    }

}

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:

coldbox create handler name="contacts" actions="index"

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.

component{ 

    property name="contactService" inject="ContactService";

    any function index( event, rc, prc ){ 
        event.setView( "contacts/index" ); 
    }
}

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.

any function index( event, rc, prc ){
    prc.aContacts = contactService.getAll();
    event.setView( "contacts/index" );
}

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:

<cfoutput>
<h1>My Contacts</h1>

#html.table( data=prc.aContacts, class="table table-striped" )#
</cfoutput>

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!

Tip You can find much more information about models and dependency injection in our full docs

The ColdBox HMVC Platform is the de-facto enterprise-level HMVC framework for CFML developers. It's professionally backed, highly extensible, and productive. Getting started with ColdBox is quick and painless. The only thing you need to begin is CommandBox, a command line tool for CFML developers.

This is a one-page introductory guide to ColdBox. If you are new to MVC or ColdBox, you can also leverage our 60 minute quick start guide as well.

IDE Tools

ColdBox has the following supported IDE Tools:

• Sublime - https://packagecontrol.io/packages/ColdBox Platform

• VSCode - https://marketplace.visualstudio.com/items?itemName=ortus-solutions.vscode-coldbox

• CFBuilder - https://www.forgebox.io/view/ColdBox-Platform-Utilities

Install CommandBox

You can read through our one-page CommandBox Getting Started Guide. Or simply grab the CommandBox executable from the download page and double click it to run.

http://www.ortussolutions.com/products/commandbox

You should now be seeing a prompt that looks like this:

Create A New Site

Now we're cooking with gas! Let's create a new ColdBox application. CommandBox comes with built-in commands for scaffolding out new sites as well as installing ColdBox and other libraries. We'll start by changing into an empty directory were we want our new app to live. If necessary, you can create a new folder.

CommandBox> mkdir playground --cd

Now let's ask CommandBox to create a new ColdBox app for us.

CommandBox> coldbox create app MyPlayground

File/Folder Conventions

This command will place several new folders and files in your working directory. Let's run the ls command to view them.

CommandBox> ls

Here's a rundown of the important bits.

• coldbox - This is the ColdBox framework managed by CommandBox

• config/Coldbox.cfc - Your application configuration object

• config/Router.cfc - Your application URL Router

• handlers - Your controller layer, which in ColdBox they are called event handlers

• layouts - Your HTML layouts

• models - This holds your model CFCs

• modules - This holds the CommandBox tracked modules

• modules_app - This holds your app's modules

• views - Your HTML views will go here

Start It Up

Now that our shiny new MVC app is ready to go, let's fire it up using the embedded server built into CommandBox. You don't need any other software installed on your PC for this to work. CommandBox has it all!

CommandBox> start --rewritesEnable

In a few seconds, a browser window will appear with your running application. This is a full server with access to the web administrator where you can add data sources, mappings, or adjust the server settings. Notice the handy icon added to your system tray as well. The --rewritesEnable flag will turn on some basic URL rewriting so we have nice, pretty URLs.

Take A Look Around

ColdBox uses easy conventions to define the controllers and views in your app. Let's open up our main app controller in your default editor to have a looksie.

CommandBox> edit handlers/main.cfc

At the top, you'll see a function named "index". This represents the default action that runs for this controller, which in ColdBox land they are referred to as event handlers.

// Default Action
function index(event,rc,prc){
    prc.welcomeMessage = "Welcome to ColdBox!";
    event.setView("main/index");
}

Now let's take a look in the main/index view. It's located int he views folder.

CommandBox> edit views/main/index.cfm

This line of code near the top of the view is what outputs the prc.welcomeMessage variable we set in the controller.

<h1>#prc.welcomeMessage#</h1>

Try changing the value being set in the handler and refresh your browser to see the change.

prc.welcomeMessage = "This is my new welcome message";

Building On

Let's define a new event handler now. Your controllers act as event handlers to respond to requests, REST API, or remote proxies.

Pull up CommandBox again and run this command.

CommandBox> coldbox create handler helloWorld index,add,edit,list

That's it! You don't need to add any special configuration to declare your handler. Now we have a new handler called helloWorld with actions index, add, edit, and list. The command also created a test case for our handler as well as stubbed-out views for each of the actions.

Now, let's re-initialize the framework to pick up our new handler by typing ?fwreinit=1 at the end of the URL.

Let's hit this new controller we created with a URL like so. Your port number will probably be different.

127.0.0.1:43272/helloWorld

Install Packages

ColdBox's MVC is simple, but it's true power comes from the wide selection of modules you can install into your app to get additional functionality. You can checkout the full list of modules available on the Forgebox directory: www.forgebox.io.

forgebox.io/type/modules

Here's some useful examples:

• BCrypt -- Industry-standard password hashing

• cbdebugger -- For debugging Coldbox apps

• cbjavaloader - For interacting with Java classes and libraries

• cbMarkdown - For writing in markdown

• cbMessagebox -- Display nice error/success messages

• cborm -- Awesome ORM Services

• cb18n -- For multilingual sites

• cbt - ColdBox templating language

• cbValidation - Back-end validation framework

• qb - Fluent query builder and schema builder

• route-visualizer - For visualizing your application routes

Install cbmessagebox from the CommandBox prompt like this:

CommandBox> install cbmessagebox

We can see the full list of packages by using the list command.

CommandBox> list
Dependency Hierarchy for myApp (0.0.0)
+-- cbmessagebox (1.0.0)
+-- coldbox (4.0.0)

Right now we can see that our app depends on coldbox and cbmessagebox to run. We'll use our new cbmessagebox module in a few minutes. But first, we'll create a simple Model CFC to round out our MVC app.

Creating A Model

Models encapsulate the business logic your application. They can be services, beans, or DAOs. We'll use CommandBox to create a GreeterService in our new app with a sayHello method.

CommandBox> coldbox create model GreeterService sayHello --open

Let's finish implementing the sayHello() method by adding this return statement and save the file.

We can also add the word singleton to the component declaration. This will tell WireBox to only create one instance of our service.

component singleton {

    function sayHello(){
        return 'Hey, you sexy thing!';
    }

}

Tie It All Together

Ok, let's open up that helloWorld handler we created a while back. Remember, you can hit tab while typing to auto-complete your file names.

CommandBox> edit handlers/helloWorld.cfc

We'll inject our greeterService and the cbmessagebox service into the handler by adding these properties to the top of /handlers/helloWorld.cfc.

This will put the instance of our services in the variables scope where we can access it in our action methods.

component {

    property name='greeterService' inject='greeterService';
    property name='messageBox' inject='@cbmessagebox';

    ...
}

And now in our index method, we'll set the output of our service into an info message.

function index( event, rc, prc ){
    messageBox.info( greeterService.sayHello() );
    event.setView( "helloWorld/index" );
}

One final piece. Open up the default layout located in layouts/Main.cfm and find the #renderView()#. Add this line right before it to render out the message box that we set in our handler.

#getInstance( 'messagebox@cbmessageBox').renderIt()#
<div class="container">#renderView()#</div>

Now hit your helloWorld handler one final time with ?fwreinit=1 in the URL to see it all in action! (Again, your port number will most likely be different.

127.0.0.1:43272/helloWorld?fwreinit=1

What's Next?

Congratulations! In a matter of minutes, you have created a full MVC application. You installed a community module from ForgeBox, created a new handler/view and tied in business logic from a service model.

As easy as that was, you're just scratching the surface of what ColdBox can do for you. Continue reading this book to learn more about:

• Environment-specific configuration

• Easy SES URL routing

• Tons of 3rd party modules

• Drop-in security system

• Sweet REST web service support

Getting Help

If you run into issues or just have questions, please jump on our ColdBox Google Group and our Slack team and ask away.

ColdBox is Professional Open Source under the Apache 2.0 license. We'd love to have your help with the product.

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.

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

// Default Action
function index( event, rc, prc ){
    prc.welcomeMessage = "Welcome to ColdBox!";
    event.setView( "main/index" );
}

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:

http://localhost:{port}/folder/handler/action
http://localhost:{port}/handler/action
http://localhost:{port}/handler

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

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.

function index( event, rc, prc ){
    // param an incoming variable.
    event.paramValue( "name", "nobody" );
    // set a private variable
    prc.when = dateFormat( now(), "full" );
    // set the view to render
    event.setView( "hello/index" );
}

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

<cfoutput>
<p>Hello #encodeForHTML( rc.name )#, today is #prc.when#</p>
</cfoutput>

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.

The ColdBox configuration CFC is the heart of your ColdBox application. It contains the initialization variables for your application and extra information used by third-party modules and ultimately how your application boots up. In itself, it is also an event listener or ColdBox Interceptor, so it can listen to life-cycle events of your application.

This CFC is instantiated by ColdBox and decorated at runtime so you can take advantage of some dependencies.

• Controller : Reference to the main ColdBox Controller object (coldbox.system.web.Controller)

• AppMapping : The location of the application on the web server

• LogBoxConfig : A reference to a LogBox configuration object