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

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

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()

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

New Features

Improvements

CacheBox Release Notes

Bugs

New Features

Improvements

WireBox Release Notes

Bugs

LogBox Release Notes

New Features

Improvements

This is a patch release for ColdBox

Bugs/Regressions

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

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

• [COLDBOX-713] - addAsset throw error when called from handlers

Improvements

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

• [COLDBOX-702] - 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

coldbox = {
    jsonPayloadToRC = true
}

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.

moduleSettings = {
    htmlHelper = {
        // Base path for loading JavaScript files
        js_path = "",
        // Base path for loading CSS files
        css_path = "",
        // Auto-XSS encode values when using the HTML Helper output methods
        encodeValues = false
    }
}

Injection Shortcut

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

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:

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

This ticket was contributed by Dom Watson (https://twitter.com/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!

• [COLDBOX-810] - 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:

router
    .post( "photos/", "photos.create" )
    .get( "photos/", "photos.index" )
    .delete( "photos/", "photos.remove" );

ColdBox Core Release Notes

Bugs

• [COLDBOX-778] - ModuleService to add default route doesn't work correctly

• [COLDBOX-794] - Fix default bug report to show SQL error detail for adobe SQL exceptions

• [COLDBOX-796] - When doing package resolving if you are in a module it still tries to resolve a module

• [COLDBOX-806] - Error in HTML helper WRAPPERATTRS doesn't exist in argument scope

• [COLDBOX-811] - Include the colon for non 80 or 443 port numbers #419 in github

New Features

• [COLDBOX-812] - Allow merging of HTTP verbs when doing separate verbs for the same route

• [COLDBOX-813] - Update cfconfig to use env variables instead of inline mixins, modernizeOrDie

Improvements

• [COLDBOX-795] - Add more current route information to the BugReport.cfm template

• [COLDBOX-797] - Ability for bug reports and app to know which module contributed the incoming URL route.

• [COLDBOX-798] - Use of .keyExists() can needlessly use memory in requests, suggest StructKeyExists() instead

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

• [COLDBOX-800] - HandlerService.cfc$newHandler(): declares variables that are never used

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

CacheBox Release Notes

Bugs

• [CACHEBOX-56] - AbstractCacheProvider.getOrSet(): local var unscoped when checking if null

Short and sweet release!

Bug

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

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

This is a patch release for ColdBox

Bugs

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

Improvements

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

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

• [] - RemotingUtil converted to cfscript #367

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.

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.

ColdBox Release Notes

Bugs

New Features

Improvements

WireBox Release Notes

New Features

Improvement

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

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

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

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

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:

# With rewrites enabled
http://localhost:{port}/hello/index

# With no rewrites enabled
http://localhost:{port}/index.cfm/hello/index

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:

component{

    /**
     * Default Action
     */
     function index( event, rc, prc ){
        event.setView( "hello/index" );
     }


}

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.

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

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!

coldbox create view name="virtual/hello"

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

<h1>Hello from ColdBox Land!</h1>

Then go execute the virtual event:

http://localhost:{port}/virtual/hello

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.

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.

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

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

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

You can also use CommandBox to reinit the application:

coldbox reinit

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

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

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:

1. No Java Runtime (30mb)

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

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

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.

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.

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.

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.

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:

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.

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!

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:

Getting Help

If you run into issues or just have questions, please jump on our and our and ask away.

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

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:

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 and 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:

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.

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.

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

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.

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

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.

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.

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

Configuration Storage

Once the application starts up, a reference to the instantiated configuration CFC will be stored in the configuration settings with the key coldboxConfig. You can then retrieve it later in your handlers, interceptors, modules, etc.

// retrieve it
config = getSetting( 'coldboxConfig' );

// inject it
property name="config" inject="coldbox:setting:coldboxConfig";

Configuration Interceptor

Another cool concept for the Configuration CFC is that it is also registered as a ColdBox Interceptor once the application starts up automatically for you. Create functions that will listen to application events:

function preProcess( event, interceptData, buffer, rc, prc ){
    writeDump( 'I just hijacked your app!' );abort;
}

function preRender( event, interceptData, buffer, rc, prc ){
    controller.getWirebox().getInstance( 'loggerService' ).doSomething();
}

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

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:

1. No Java Runtime (30mb)

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

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

That's it! CommandBox can now track this version of ColdBox for you in this directory.

Scaffolding ColdBox Applications

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

• 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

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.

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!';
    }

}