In this section you will find the release notes for each version we release under this major version. If you are looking for the release notes of previous major versions use the version switcher at the top left of this documentation book. Here is a breakdown of our major version releases.

• Version 6.0 - August 2020

• Version 5.0 - July 2018

• Version 4.0 - January 2015

• Version 3.0 - March 2011

• Version 2.0 - April 2007

• Version 1.0 - June 2006

Added

• Github actions for LTS Releases

• LTS Updates

Bugs

• COLDBOX-1219 CFProvider ACF versions are Hard-Coded

• WIREBOX-132 WireBox caches Singletons even if their autowired dependencies throw exceptions.

Release Notes

Added

• COLDBOX-1229 Added debug argument to ScheduleExecutor and Scheduler when creating tasks for consistency

• COLDBOX-1230 Reorganized ScheduledTasks functions within the CFC into code groups and comments

Improvements

• COLDBOX-1226 Scheduled Tasks Updates

Fixed

• COLDBOX-1145 RestHandler OnError() Exception not checking for empty `exception` blocks which would cause another exception on development ONLY

Bug

COLDBOX-1138 Event Cache Response Has Status Code of 0 (or Null)

COLDBOX-1139 make event caching cache keys lower cased to avoid case issues when clearing keys

Release notes - ColdBox Platform - 6.10.0

Bug

COLDBOX-1274 javacasting to long for new Java LocalDateTime instead of int, Adobe not doing type promotion

COLDBOX-1279 Render encapsulator bleed of this scope by engines

Improvement

COLDBOX-1273 Removal of deprecated CFML functions in core

COLDBOX-1275 Improved engine detection by the CFMLEngine feature class

COLDBOX-1278 Remove unsafe evaluate function usage

Major Updates

Here is a listing of all the major updates and improvements in this version.

Event Caching HTTP Response Codes

Event caching has been updated to allow the caching of the set http response code from your handler code via event.setHTTPHeader() or event.renderData() . This is essential from a developer's perspective as it will respect whatever response code you respond with. This is also imperative for RESTFul services.

function data( event, rc, prc ) cache=true cacheTimeout=5{
    
    event.setHTTPHeader( statusCode = 404 );

}

WireBox Performance, Performance and More Performance

This release brings in a complete re-architecture of the creation, inspection and wiring of objects in WireBox in order to increase performance. Every single line of code was optimized and analyzed in order to bring the creation, inspection and wiring of objects to its maximum speed. This will be noted more on the creation of transient (non-persisted) objects more than in singleton objects. So if you are asking WireBox for transient objects, you will see and feel the difference.

In some of our performance testing we had about 4000 object instantiations running between 500ms-1,100 ms depending on CPU load. While with simple createObject() and no wiring, they click around 400-700 ms. Previously, we had the same instantiations clocking at 900-3,500 ms. So we can definitely see a major improvement in this area.

New ColdBox Testing Virtual App

This release sports the creation of the encapsulated virtual ColdBox App: coldbox.system.testing.VirtualApp. Previously, the only way to create virtual apps was to do it manually just like the BaseTestCase object did when doing integration testing and that's about it. In this release, we provide a clean interface for starting, restarting, checking and shutting down virtual applications that can be used for testing, proxying, etc. It also allows a faster and eager approach to starting the virtual application before your runner and tests. This will allow any ORM bridges to be respected and best of all the ability to execute anything in the framework before your runners, suites or specs. Database migrations anyone?

Test Harness

All application templates have been updated to use the new Virtual App in the tests/Application.cfc. This will allow for a virtual application to be started once your runner or specs are executed and shutdown at the end of the request. Here are the two methods in charge of doing this in the Application.cfc

public boolean function onRequestStart( targetPage ){
	// Set a high timeout for long running tests
	setting requestTimeout="9999";
	// New ColdBox Virtual Application Starter
	request.coldBoxVirtualApp = new coldbox.system.testing.VirtualApp( appMapping = "/root" );

	// If hitting the runner or specs, prep our virtual app
	if ( getBaseTemplatePath().replace( expandPath( "/tests" ), "" ).reFindNoCase( "(runner|specs)" ) ) {
		request.coldBoxVirtualApp.startup();
	}

	// ORM Reload for fresh results
	if( structKeyExists( url, "fwreinit" ) ){
		if( structKeyExists( server, "lucee" ) ){
			pagePoolClear();
		}
		// ormReload();
		request.coldBoxVirtualApp.restart();
	}

	return true;
}

public void function onRequestEnd( required targetPage ) {
	request.coldBoxVirtualApp.shutdown();
}

Your integration tests and unit tests remain the same. The only difference is that internally they all use this object to create the virtual applications.

Scheduled Tasks Exception Handling

All scheduled tasks have automatic exception handling now. Before, whenever you had exceptions and you did NOT implement any of the exception handling listeners, your code would be swallowed up and never to be seen! Now, we avoid this and log them to standard error so you can debug your code.

Also, in the previous version, if you had an exception your afterAnyTask() or the after() life cycle methods would never be called. Now they are!! Hooray!!

ColdBox Schedulers Automatic Injection

All ColdBox enabled schedulers will have the following automatic injections so you can have ease of use for leveraging objects and contexts during your task declarations and executables.

All module schedulers will have the following extra automatic injections:

Scheduled Tasks Start and End Dates

All scheduled tasks now support the ability to seed in the start and end dates via our DSL:

• startOn( date, time = "00:00" )

• endOn( data, time = "00:00" )

This means that you can tell the scheduler when the task will become active on a specific data and time (using the scheduler's timezone), and when the task will become disabled.

task( "restricted-task" )
  .call( () => ... )
  .everyHour()
  .startOn( "2022-01-01", "00:00" )
  .endOn( "2022-04-01" )

xTask() - Easy Disabling of Tasks

Thanks to the inspiration of TestBox where you can mark a spec or test to be skipped from execution by prefixing it with the letter x you can now do the same for any task declaration. If they are prefixed with the letter x they will be registered but disabled automatically for you.

function configure(){

	xtask( "Disabled Task" )
		.call ( function(){
			writeDump( var="Disabled", output="console" );
		})
		.every( 1, "second" );

	task( "Scope Test" )
		.call( function(){
			writeDump( var="****************************************************************************", output="console" );
			writeDump( var="Scope Test (application) -> #getThreadName()# #application.keyList()#", output="console" );
			writeDump( var="Scope Test (server) -> #getThreadName()# #server.keyList()#", output="console" );
			writeDump( var="Scope Test (cgi) -> #getThreadName()# #cgi.keyList()#", output="console" );
			writeDump( var="Scope Test (url) -> #getThreadName()# #url.keyList()#", output="console" );
			writeDump( var="Scope Test (form) -> #getThreadName()# #form.keyList()#", output="console" );
			writeDump( var="Scope Test (request) -> #getThreadName()# #request.keyList()#", output="console" );
			writeDump( var="Scope Test (variables) -> #getThreadName()# #variables.keyList()#", output="console" );
			writeDump( var="****************************************************************************", output="console" );
		} )
		.every( 60, "seconds" )
		.onFailure( function( task, exception ){
			writeDump( var='====> Scope test failed (#getThreadName()#)!! #exception.message# #exception.stacktrace.left( 500 )#', output="console" );
		} );
		
}

Scheduled Tasks Singular Time Units

Every time unit can now be used as plural or singular, so it can allow you to create beautiful scheduled task DSLs:

// Before
task( "my-task" )
	.call( () => {} )
	.every( 1, 'hours' );

// Which sounds weird when you read it. So now you can use singular

task( "my-task" )
	.call( () => {} )
	.every( 1, 'hour' );

Available Time Units

• Nanosecond(s)

• Microsecond(s)

• Millisecond(s)

• Second(s)

• Minute(s)

• Hour(s)

• Day(s)

Safe Shutdown of Executors and Schedulers

All executors and schedulers can now be shutdown more gracefully by passing a timeout argument to the async manager and automatically by the framework. This will allow the executor to shutdown and gracefully yell at it's tasks to shutdown in a default period of 30 seconds. It will wait and then try again, if not, then well, you can't directly kill anything anymore, so you will be notified so you can do harsher punishments to these tasks.

The only exception this is NOT the case in a normal ColdBox app is when a reinit happens or when integration testing is being executed. Then we revert to the previous behavior of nuking the executors and schedulers.

AsyncManager

• shutdownAllExecutors( force, timeout )

• shutdownExecutor( name, force, timeout)

The timeout ONLY works when the force argument is false. If force is true, then it's NOT gracefully shutdown. This usually happens on ColdBox reinits or integration testing.

Schedulers

All schedulers have a shutdownTimeout property that defaults to 30 seconds. When you configure your schedulers you can change this value to whatever you see fit.

function configure(){
    
    // Set shutdown timeout to 60 seconds
    setShutdownTimeout( 60 );

}

Executors - shutdown and wait...

All executors now have a new method: shutdownAndAwaitTermination( numeric timeout = 30 ) which is used to do just that. It places the executor in shutdown mode and waits the timeout for all the tasks to complete. If they don't complete then it issues a forced shutdown.

forAttribute() - Integrate with JS Frameworks Easily

All handlers/layouts and views get a new function called forAttribute( data )which will allow you to serialize simple or complex data so it can be used within HTML attributes. This will take care of serialize the data and encoding it correctly so it can be bound to the HTML attribute so the JavaScript framework can use it as native JSON.

<div>
    <User :data="#forAttribute( prc.user.getMemento() )#">
</div>

This technique will allow you to bridge your CFML apps with your JS apps natively.

Async Interceptors Data

Finally in this version of ColdBox asynchronous interceptors will work with any complex data without any thread contingency or duplication. You can even use them for ORM events and it will work accordingly. So go for it, asynchronize your interception calls!

threadData = announce(
    state           = "onPageCreate", 
    data            = { page= local.page }, 
    asyncAll        = true,
    asyncPriority   = "high"
);

ORM Event Handling

This was a rough regression due to the way Hibernate is loaded by the CFML engines. We have moved to a lazy load first strategy on the entire architecture of the framework. So anything using the ColdBox proxy, like the ORM event handling, will now work in any loading situation.

Release Notes

ColdBox 6.3.0 is a minor release that squashes lots of bugs and does tons of improvements for performance!

ColdBox 6.1.0 is a minor release sporting fixes and a few minor updates to make your coding life easier 😂.

Release Notes

ColdBox HMVC Platform- v6.x

ColdBox Hierarchical MVC is the de-facto enterprise-level HMVC framework for ColdFusion (CFML) developers. It's professionally backed, conventions-based, modular, highly extensible, and productive. Getting started with ColdBox is quick and painless. ColdBox takes the pain out of development by giving you a standardized methodology for modern ColdFusion (CFML) development with features such as:

• Conventions instead of configuration

• Modern routing engine

• RESTFul API ready

• A hierarchical approach to MVC using ColdBox Modules

• Event-driven programming

• Async and Parallel programming constructs

• Integration & Unit Testing

• Included dependency injection

• Caching engine and API

• Logging engine

• An extensive eco-system

• Much More

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.

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.

• Copyright by Ortus Solutions, Corp

• ColdBox, CacheBox, WireBox, LogBox are registered trademarks by Ortus Solutions, Corp

Discussion & Help

The Ortus Community is the way to get any type of help for our entire platform and modules: https://community.ortussolutions.com

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 at: https://github.com/coldbox/coldbox-platform

Jira Issue Tracking

• https://ortussolutions.atlassian.net/browse/COLDBOX

• https://ortussolutions.atlassian.net/browse/WIREBOX

• https://ortussolutions.atlassian.net/browse/LOGBOX

• https://ortussolutions.atlassian.net/browse/CACHEBOX

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

• CFCasts Video Training: http://www.cfcasts.com

• Source Code: https://github.com/coldbox/coldbox-platform

• Bug Tracker: https://ortussolutions.atlassian.net/browse/COLDBOX

• Twitter: @coldbox

• Facebook: https://www.facebook.com/coldboxplatform

• 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 6.0.0 is a major release for the ColdBox HMVC platform. It has some dramatic new features as we keep pushing for more modern and sustainable approaches to web development. We break down the major areas of development below and you can also find the full release notes per library at the end.

Engine Support

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

• Adobe ColdFusion 11

• Lucee 4.5

The info-graphic above shows you the supported engines the 6.x platform will support.

Asynchronous Programming

We have done a tremendous amount of work to expose all the async and parallel programming constructs in ColdBox to the entire framework so developers can leverage them. There is just so much we have done on this release for concurrency, task scheduling, and parallel programming to include in one page. So visit our Async Programming section to start delving into what we are lovingly calling cbFutures!

ColdBox Executors & Tasks

Thanks to our new futures approach, all major internal libraries (WireBox, CacheBox, LogBox, MVC) will leverage them for different tasks that require asynchronicity and scheduling. You will see a noticeble difference especially in the following areas:

• Cache Reaping: All cache reaping is now done via a scheduled task running on specific frequencies

• File Appenders: It uses an async schedule to stream log data to files instead of blocking operations for sending logs. It will use a logging in-memory queue to stream the log data to the file. So you can potentially send 10000 log events and eventually they will be streamed to disk.

What are ColdBox Futures?

A ColdBox future is used for async/parallel programming where you can register a task or multiple tasks that will execute in a non-blocking approach and trigger dependent computations which could also be asynchronous. This Future object can then be used to monitor the execution of the task and create rich completion/combining pipelines upon the results of such tasks. You can still use a get() blocking operation, but that is an over simplistic approach to async programming because you are ultimately blocking to get the result.

ColdBox futures are backed by Java's CompletableFuture API, so the majority of things will apply as well; even Java developers will feel at home. It will allow you to create rich pipelines for creating multiple Futures, chaining, composing and combining results.

// Parallel Executions
async().all(
    () => hyper.post( "/somewhere" ),
    () => hyper.post( "/somewhereElse" ),
    () => hyper.post( "/another" )
).then( (results)=> logResults( results ) );

// Race Conditions, let the fastest dns resolve
var dnsServer = async().any( 
    () => dns1.resolve(),
    () => dns2.resolve()
).get();

// Process an incoming order
async().newFuture( () => orderService.getOrder() )
    .then( (order) => enrichOrder( order ) )
    .then( (order) => performPayment( order ) )
    .thenAsync( 
        (order) => dispatchOrder( order ), 
        async().getExecutor( "cpuIntensive" )
     )
    .then( (order) => sendConfirmation( order ) );

// Combine Futures
var bmi = async().newFuture( () => weightService.getWeight( rc.person ) )
    .thenCombine(
        async().newFuture( () => heightService.getHeight( rc.person ) ),
        ( weight, height ) => {
            var heightInMeters = arguments.height/100;
            return arguments.weight / (heightInMeters * heightInMeters );
        }
    )
    .get();

// Compose Futures with exceptions
async()
    .newFuture( () => userService.getOrFail( rc.id ) )
    .thenCompose( ( user ) => creditService.getCreditRating( user ) )
    .then( (creditRating) => event.getResponse().setData( creditRating ) )
    .onException( (ex) => event.getResponse().setError( true ).setMessages( ex.toString() ) );

This new approach to creating async pipelines and parallel processing, will further create extensibility and robustness in your ColdBox applications.

coldbox-tasks Global Executor

ColdBox apps by default register a coldbox-tasks fixed executor (20 threads - IO bound) that is used internally for cleanups, tasks, and schedules. However, any module or application can leverage it for scheduling tasks or workers.

asyncManager.getExecutor( "coldbox-tasks" )

CacheBox Executors

CacheBox has been refactored to leverage the async facilities in ColdBox to schedule cache reaps instead of a request initiating the reaps. This brings a lot more stability and consistency to the reaping of caches as they all execute within the new ColdBox coldbox-tasks schedule task executor.

If you are in CacheBox standalone mode, then the task scheduler will be called cachebox-tasks.

Logging Enhancements

LogBox has been entirely rewritten in script and a more fluent programming approach. It has also been revamped to leverage the scheduling executors and async programming aspects of our async package. All loggers now sport logging via an async queue and it is completely non-blocking. If you do heavy logging, the performance will be substantial.

The ModuleService and all internal ColdBox services have deeper logging constructs and more information logging to understand what happens inside of the core.

Whoops! Modern Exception Handling

Thanks to Eric Peterson, we have included Whoops as part of our core exception handling template. All the new application templates come pre-configured with whoops as part of the development custom error template.

function development() {
    coldbox.exceptionEditor = "vscode";
    // coldbox.customErrorTemplate = "/coldbox/system/exceptions/BugReport.cfm"; // static bug reports
    coldbox.customErrorTemplate = "/coldbox/system/exceptions/Whoops.cfm"; // interactive bug report
}

This exception template will help you visualize and navigate your exceptions so you can fix those pesky bugs 🐞. You can even configure it to open the files directly into your favorite IDE using the coldbox.exceptionEditor setting:

function development() {
    coldbox.exceptionEditor = "vscode";
}

Valid Exception Editors are:

• vscode (Default)

• vscode-insiders

• sublime

• textmate

• emacs

• macvim

• idea

• atom

• espresso

RestHandler & ColdBox Response

After many years of adding a base handler and a response object to our application templates, we finally have integrated them into the core so developers can have even more support when building RESTFul services. This new rest handler will provide you with tons of utilities and approaches to make all of your RESTFul services:

• Uniform

• Consistent

• A consistent and extensible response object

• Error handling

• Invalid Route handling

• Much more

Base Class

New base class coldbox.system.RestHandler which you can inherit from or use our new restHandler annotation. This will give you access to our enhanced API utilities and the native response object via the request context's getResponse() method.

component extends="coldbox.system.RestHandler"{

  function index( event, rc, prc ){
    event.getResponse()
      .setData( "Hello from restful Land" );
  }
}

component resthandler{

  function index( event, rc, prc ){
    event.getResponse()
      .setData( "Hello from restful Land" );
  }

}

You can now build all of your api’s using the native response object like the rest templates, but now from the core directly. This Rest Handler gives you the following actions out of the box:

AroundHandler in Detail

The aroundHandler() provided in the RestHandler will intercept all rest calls in order to provide consistency and uniformity to all your actions. It will try/catch for major known exceptions, time your requests, add extra output on development and much more. Here are a list of the features available to you:

• Exception Handling

  • Automatic trapping of the following exceptions: InvalidCredentials, ValidationException, EntityNotFound, RecordNotFound

  • Automatic trapping of other exceptions

  • Logging automatically the exception with extra restful metadata

  • If in a development environment it will respond with much more information necessary for debugging both in the response object and headers

• Development Responses

  • If you are in a development environment it will set the following headers for you:

    • x-current-route

    • x-current-routed-url

    • x-current-routed-namespace

    • x-current-event

• Global Headers

  • The following headers are sent in each request

    • x-response-time : The time the request took in CF

    • x-cached-response : If the request is cached via event caching

The aroundHandler() is also smart in detecting the following outputs from a handler:

• Handler return results

• Setting a view or layout to render

• Explicit renderData() calls

RequestContext Additions

• getResponse()

  • Will get you the current prc.response object, if the object doesn’t exist, it will create it and set it for you

  • The core response object can be found here: coldbox.system.web.context.Response

Extending The RestHandler

If you would like to extend or modify the behavior of the core RestHandler then you will have to create your own base handler that inherits from it. Then all of your concrete handlers will inherit from your very own handler.

// BaseHandler
component extends="coldbox.system.Resthandler"{

  // Modify it here

}

// Then make your own handlers extend from it
component extends="BaseHandler"{

}

Extending The Response Object

The response object can be found here: coldbox.system.web.context.Response and the rest handler constructs it by calling the request context’s getResponse() method. The method verifies if there is a prc.response object and if it exists it returns it, else it creates a new one. So if you would like to use your very own, then just make sure that before the request you place your own response object in the prc scope.

Here is a simple example using a preProcess() interceptor. Create a simple interceptor with commandbox e.g

coldbox create interceptor name=MyInterceptor points=preProcess

and add the following method:

function preProcess( event, interceptData, rc, prc ){
  prc.response = wirebox.getInstance( "MyResponseObject" );
}

Don't forget to register your interceptor in config/Coldbox.cfc:

		interceptors = [
			{
			class      : "interceptors.MyInterceptor",
				name       : "MyInterceptor",
				properties : {}
			}
		];

That’s it. Once that response object is in the prc scope, ColdBox will utilize it. Just make sure that your custom Response object satisfies the methods in the core one. If you want to modify the output of the response object a good place to do that would be in the getDataPacket() method of your own MyResponseObject. Just make sure this method will return a struct.

Functional If's using when()

Our super type now includes a new when() method that will allow you to build functional statements within your handlers. Here is the signature of this functional helper:

/**
 * Functional construct for if statements
 *
 * @target The boolean evaluator, this can be a boolean value
 * @success The closure/lambda to execute if the boolean value is true
 * @failure The closure/lambda to execute if the boolean value is false
 *
 * @return Returns the super type for chaining
 */
function when( required boolean target, required success, failure )

The target is a boolean and can be an expression that evaluates to a boolean. If the target is true, then the success closure will be executed for you, if not, the failure closure will be executed.

function save( event, rc, prc ){
    var oUser = populateModel( "User" );
    
    when( hasAccess(), () => oUser.setRole( rc.role ) );

}

ColdBox Renderer Becomes a Singleton

The entire rendering mechanisms have changed in ColdBox 6 and we now support a singleton based approach to view rendering. It still allows for variable safety, but the way renderings in ColdBox 6 are done are orders of magnitude faster than pre ColdBox 6 days. If you are using applications like ContentBox or Preside CMS or applications with tons of renderView() calls, your applications will fly now!

Custom ReinitKey

Thanks to a community pull request you now have the ability to chose the reinit key instead of the default of fwReinit. This is useful for security purposes.

coldbox.reinitKey = "cbReinit";

Then you can use it in the request: http://localhost/index.cfm?cbReinit=true

LogBox Config Path Init

If you are using LogBox in standalone mode, you can now construct it by passing the path to your LogBox configuration file or no path at all and we will construct LogBox with our new default config file to stream logs to the console.

application.logbox = new LogBox();

application.logbox = new LogBox( "config.MyLogBox" );

AnnounceInterception(), processState() Deprecated

These methods have been deprecated in favor of our new announce() method. We have also deprecated the argument interceptData in favor of just data.

// New consistent method
announce( state, data );

// Usage
announce( "myCustomEvent", { data = this } );

New listen() method to register one-off closures

Have you ever wanted to dynamically listen to events but not create CFC to enclose the method? Well, now you can use the new listen() method which accepts a closure/udf so you can listen to ColdBox interceptions. Here is the method signature:

/**
 * Register a closure listener as an interceptor on a specific point
 *
 * @target The closure/lambda to register
 * @point The interception point to register the listener to
 */
void function listen( required target, required point )

This allows you to easily register dynamic closures/udfs whenever you like so they can listen to events:

// Within a handler/interceptor/layouts/view
listen( function(){
    log.info( "executing from closure listener");
}, "preProcess" );

listen( () => log.info( "executing from closure listener"), "preProcess" );

// Within models (Injecting the interceptor service or controller)
controller
    .getInterceptorService()
    .listen( function(){
        log.info( "executing from closure listener");
    }, "preProcess" );

New Interception: onColdBoxShutdown()

We have created a new interception point that is fired before ColdBox is shutdown completely. This can come from a reinit or an application expiration. This is a great place to shutdown custom executors, or messaging queues like RabbitMQ.

function onColdBoxShutdown(){
    myRabbitMQChannel.close();
}

Routing Enhancements

We have done several enhancements to the entire routing capabilities in ColdBox apart from several bug fixes.

buildLink() Ease of Use

We have also re-arranged the arguments so you can easily build links with query strings using positional arguments instead of name-value pairs:

string function buildLink(
    to,
    queryString       = "",
    boolean translate = true,
    boolean ssl,
    baseURL     = ""
);

<a href="#event.buildLink( 'main.list', 'userid=4' )#">My Link</a>

buildLink() Named Route Support

The request context method event.buildLink() has been now added named route support. The event.route() method was introduced to do named routing with a name and params argument. Now, you can also use this approach but via the to argument in the buildLink() method by just passing a struct.

// Using the route() method
event.route( "contactUs", { id : 3 } )

// Using the buildLink() method and the to struct arg
event.buildLink( { name : "contactUs", params : { id : 3 } } )

Route Metadata

You can now add custom metadata to specific route or resourceful routes by using the meta() method or the meta argument. This is simply a struct of name value pairs you can add into the route record.

route( "/render/:format" )
	.meta( { secure : false } )
	.to( "actionRendering.index" );

// Resources
	resources(
		resource: "photos",
		meta    : { secure : true }
	);

Now, how good is adding the metadata if you can't get it. So you can get the current route's metadata via the new request context method: getCurrentRouteMeta() method:

if( event.getCurrentRouteMeta().secure ){
  // secure it.
}

Route Record

We have also added the method getCurrentRouteRecord() to the request context so you can get the struct definition of the route record of the currently routed route. Below is a sample screenshot of the record:

Dynamic Routing Redirection

The toRedirect() method has been enhanced to accept a closure as the target of relocation. This closure will received the parsed parameters, the incoming route record and the event object. You can now determine dynamically where the relocation will go.

( route, params, event ) => "/new/route" 

function( route, params, event ){ return "/new/route"; }

This is great if you need to actually parse the incoming route and do a dynamic relocation.

route( "/old/api/users/:id" )
    .toRedirect( ( route, params, event ) => { return "/api/v1/users/#params.id#" } )

Happy Redirecting!

Release Notes

The full release notes per library can be found below. Just click on the library tab and explore their release notes:

Compatibility Notes

Please note that the following ticket corrects behavior in ColdBox that MIGHT affect interceptors that have injected dependencies that have the same name as application helper methods from other modules.

Example:

The interceptor above has a dependency of auth from the cbauth module. However, the cbauth module also has an application helper called auth. So at runtime, this will throw an exception:

This is because now we can't inject the cbauth mixin because we already have a cbauth dependency injected. The resolution, is to RENAME the injection variables so they don't collide with module application helpers.

6.5.2 Release Notes - July 14, 2021

Regression

6.5.1 Release Notes - July 12th, 2021

Bug

Improvement

6.5.0 Release Notes - July 9th, 2021

Lucee 4.5 Support Dropped

Lucee 4.5 support has been dropped.

ColdFusion 11 Support Dropped

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

Setting Changes

The following settings have been changed and altering behavior:

• coldbox.autoMapModels is now defaulted to true

  • Which means that all your models will be MAPPED for you. If you have specific mappers in your config/WireBox.cfc make sure they override the mapping or turn this setting false.

• coldbox.onInvalidEvent has been REMOVED in preference to coldbox.invalidEventHandler

• coldbox.jsonPayloadToRC is now defaulted to true

BuildLink( linkto ) argument removed

The buildLink() method had an argument linkTo . It has now changed to to to provide simplification

SES Interceptor Removed

The SES interceptor has finally been removed. You can now remove it from your interceptor declarations. If you are relying on the SES interceptor for routing, then you will need to access the RoutingService via the following injection methods or retrieval methods:

Method Changes

getModel() Removed

This method was marked for deprecation in ColdBox 5 and now it is removed. You can use the getInstance() method instead.

WireBox Provider get() method to $get()

All WireBox providers now implement the new interface which has changed the method of get() to $get() to avoid proxying to methods that already implement a get() method. So if you are using the get() method just update it to the new $get() method.

getSetting()

The getSetting() method does NOT include a fwSetting boolean argument anymore. You can now use the getColdBoxSetting() method instead.

announceInterception( state, interceptData ) => announce( state, data )

This method has now been deprecated in favor of its shorthand announce(). This method will still work but it will be removed in the next major version. So just rename it now. Also note that the interceptData has now changed to just data

processState( state, interceptData ) => announce( state, data )

This method was used in the event manager and interceptor service and has been marked for deprecation. Please use the method announce() instead. Which is also a consistency in naming now.

setNextEvent() Removed

The method setNextEvent() has been removed in favor of relocate(). We had deprecated this method in ColdBox 5.

Interceptor Buffer Methods Removed

These methods have been deprecated since version 4 and they are now removed.

• getBufferObject()

• getBufferString()

• appendToBuffer()

• clearBuffer()

Every interception listener receives the buffer as an argument so there is no need to go to global functions for working with the buffer.

Interceptor Arguments: interceptData => data

All interceptors receive arguments when listening, we have renamed the interceptData to just data. The old approach still works but it is marked as deprecated. So just rename it to data

System Path Changes

• Default Bug Report Files are now located in /coldbox/system/exceptions/. Previously /coldbox/system/includes/

So make sure you update your CustomErrorTemplate path to this new path:

Rendering Changes

The entire rendering mechanisms in ColdBox 6 have changed. We have retained backwards compatibility but there might be some loopholes that worked before that won't work now. Basically, the renderer is a singleton and each view renders in isolation. Meaning if a view sets a variable in it's variables scope NO OTHER view will have access to it.

• The majority of code examples in this book are done in cfscript.

• All ColdFusion examples designed to run on the open source Lucee Platform or Adobe ColdFusion 11+

External Trademarks & Copyrights

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

ColdBox, CommandBox, FORGEBOX, TestBox, ContentBox, Ortus Solutions are all trademarks and copyrights of Ortus Solutions, Corp.

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

Charitable Proceeds

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 6.4.0 is more of a major than a minor release due to the amount of work we have done to bring you one of the most revolutionary features of this framework: Scheduled Tasks.

ColdBox Scheduled Tasks

Scheduled tasks have always been a point of soreness for many developers in ANY language. Especially choosing where to place them for execution: should it be cron? windows task scheduler? ColdFusion engine? Jenkins, Gitlab? and the list goes on and on.

The ColdBox Scheduled Tasks offers a fresh, programmatic and human approach to scheduling tasks on your server and multi-server application. It allows you to define your tasks in a portable Scheduler we lovingly call the Scheduler.cfc which not only can be used to define your tasks, but also monitor all of their life-cycles and metrics of tasks. Since ColdBox is also hierarchical, it allows for every single ColdBox Module to also define a Scheduler and register their own tasks as well. This is a revolutionary approach to scheduling tasks in an HMVC application.

You can learn all about them in our two sections:

Release Notes

ColdBox 6.2.0 is a minor release with some major improvements in many areas like:

• Async programming

• Logging

• Object creations

• WireBox Mappings and Binders

WireBox Binder & Mapping Objects Rewritten

This is a major change in the core as we have finally rewritten the WireBox Binder and object Mapping objects to script. This resulted in a 45-50% code reduction for those objects and an impressive 30% speed improvements when creating and processing mappings with the new binder processing optimizations. We analyzed every single line of code on these two objects and we are incredibly satisfied with the initial results.

That's right, we have some async goodness prepared for future versions when dealing with multiple directory mappings and much more.

Async Package Performance Upgrades

It is also available to ANY ColdFusion application that is NOT running ColdBox. This is achieved by using either of our standalone libraries: WireBox, CacheBox and LogBox.

Test Dependency Injection

This version introduces the capability for you to tag your integration tests with an autowire annotation on the component tag. By adding this annotation, your test object will be inspected and wired with dependencies just like any other WireBox object.

ColdBox Test Matchers

We have also included a new object coldbox.system.testing.CustomMatchers which will register matchers into TestBox when doing integration tests. It will give you the nice ability to expect status codes and validation exceptions on RESTFul Requests via the ColdBox Response object.

• toHaveStatus()

• toHaveInvalidData()

More Rendering Improvements

Whoops! Keeps Getting Better

We have had tons of updates and requests from our new exception handling experience in ColdBox: Whoops! In this release we tackle CFML core engine files so they can render appropriately, AJAX rendering for exceptions and best of all a huge performance and size boost when dealing with exceptions. Even when dealing with exceptions we want the best and the fastest experience possible for our developers.

The previous approach whoops took was to read and load all the source code of all the templates that caused the exception. You could then navigate them to discover your faults. However, each template could be loaded from 1 to up to 10 times if the stack trace followed it. In this new update we provide source template caching and dynamic runtime injection and highlighting of the source code. This has granted us the following improvements in small test cases (Your improvements could be higher)

Release Notes

6.2.0

6.2.1

6.2.2

Major Updates

API Resourceful Routes

We have created a shortcut approach to creating RESTFul API resources in your ColdBox Routers via the new method apiResources(). This method will create all the routes for your API service with no HTML views.

Module Enhancements

We have made several enhancements with modules:

• Performance optimizations when registering and activating modules

• Better logging of modules when they activate and register

Experimental New App Structure

We have been working on a new directory structure for ColdBox applications where the web root is not just dumped with everything on it. We have made several internal tickets to allow for this to work and we have a very early alpha available in github:

Scheduler and Task Updates

There are so many tickets that helped resolved issues with the ColdBox schedulers and scheduled tasks. We have also solidifying our Adobe scope issues and brought many new helpers for developers when building task objects.

Integration Testing of Subdomain/Domain Routing

Custom Session Identifiers

ColdBox has always had its internal way of figuring out what identifier to use for each user's request based on the way ColdFusion works. However, now you can influence and provide your own approach instead of relying on the core CFML approach. You will do this by adding a coldbox.identifierProvider closure/lambda into your config/Coldbox.cfc.

WireBox Child Injectors

Welcome to the world of hierarchical dependency injection. We had the ability before to add a parent injector to WireBox, but now you can not only add a parent, but also many children to the hierarchy.

Every injector has the capability to store an ordered collection (ordered struct) of child injectors via the childInjectors property. Child injectors are used internally in many instances to provide a hierarchical approach to DI where instances can be searched for locally, in the parent and in the children. Here are some of the new methods to assist with child injectors:

• hasChildInjector( name ) - Verify if a child injector has been registered

• registerChildInjector( name, child ) - Register a child injector by name

• removeChildInjector( name ) - Remove a child injector by name

• getChildInjector( name ) - Get a child injector by name

• getChildInjectors() - Get all the child injectors registered

• getChildInjectorNames() - Get an array of all the registered child injectors

Child Enhanced Methods

• getInstance()

  • The getInstance()method now has an injector argument so you can EXPLICITLY request an instance from a child injector by name getInstance( name : "service", injector : "childInjector" )

  • Apart from the explicit lookup it can also do implicit hierarchical lookups using the following order:

    • Locally

    • Parent

    • All Children (in order of registration)

• containsInstance( name ) - This method now also searches in the child collection for the specific name instance. The lookup searches in the following order:

  1. Locally

  2. Parent

  3. Children

• shutdown() - The shutdown method has been enhanced to issue shutdown method calls to all child injectors registered.

Getting Instances From Specific Child Injectors

The getInstance() has been modified to have an injector argument that you can use to specifically ask for an instance from that child injector. If the child injector has not been registered you will get a InvalidChildInjector Exception.

Child Injector Explicit DSL

The following is the DSL you can use to explicitly target a child injector for a dependency. You will prefix it with wirebox:child:{name} and the name of the injector:

IInjector Interface Updates

The coldbox.system.ioc.IInjector interface's getInstance() method has been modified to include support for child injector retrievals:

Release Notes

• AdvancedScript (default): A script based advanced 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:

Default Event

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

Hooray, we have scaffolded our first application, started a server and executed the default event. Explore the application template generated, as it contains many useful information about your application.

File/Folder Conventions

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:

Welcome to the world of ColdBox!

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

IDE Tools

ColdBox has the following supported IDE Tools:

CommandBox CLI

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. Try it out!

Updating ColdBox

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

Handler Scaffolding

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.

Default URL Routing

Now go to your browser and enter 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. However, how did this work? It works as ColdBox by convention creates another agreement with you on how to execute events, default URL routing.

Your application router is located at : config/Router.cfc. It will include a few default routes for you and the following default URL route:

This route tells ColdBox to look for the names of handlers (including directory names) and for names of the handler actions (functions). The ? on the :action portion denotes that the action might or might not exist in the URL. If it doesn't exist, then another convention is in play, the default action which is index.

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:

• 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. Migrating from a traditional application?

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.

Requirements

• Grab a cup of coffee or tea

• Get comfortable

Need Help?