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.

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

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

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 3.0 - March 2011

• Version 2.0 - April 2007

• Version 1.0 - June 2006

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

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.

apiResources( "users" );
apiResources( "photos" );

Module Enhancements

We have made several enhancements with modules:

• Performance optimizations when registering and activating modules

• Modules now track their own registration and activation load times (Which are now visible in cbdebugger)

• 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

If you are building multi-tenant applications with ColdBox and are leveraging domain and subdomain routing, then you can easily use the domain argument in all of our request(), execute() and HTTP Verb methods to simulate the domain in play for THAT specific spec execution.

describe( "subdomain routing", function(){
	beforeEach( function(){
		setup();
	} );
	
	it( "can match on a specific domain", function(){
		var event = execute( route: "/", domain: "subdomain-routing.dev" );
		var rc    = event.getCollection();
		expect( rc ).toHaveKey( "event" );
		expect( rc.event ).toBe( "subdomain.index" );
	} );
	
	it( "skips if the domain is not matched", function(){
		var event = execute( route: "/", domain: "not-the-correct-domain.dev" );
		var rc    = event.getCollection();
		expect( rc ).toHaveKey( "event" );
		expect( rc.event ).toBe( "main.index" );
	} );
	
	it( "can match on a domain with wildcards", function(){
		var event = execute( route: "/", domain: "luis.forgebox.dev" );
		var rc    = event.getCollection();
		expect( rc ).toHaveKey( "event" );
		expect( rc.event ).toBe( "subdomain.show" );
	} );
	
	it( "provides any matched values in the domain in the rc", function(){
		var event = execute( route: "/", domain: "luis.forgebox.dev" );
		var rc    = event.getCollection();
		expect( rc ).toHaveKey( "username" );
		expect( rc.username ).toBe( "luis" );
	} );
} );

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.

coldbox : {
    identifierProvider : function(){
        if( isNull( cookie.mytracker ) ){
            cookie.myTracker = createUUID();
        }
        return cookie.myTracker;
    }
}

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.

getInstance( name: "CategoryService", injector : "ChildInjector" )

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:

// Use the property name as the instance name
property name="categoryService" inject="wirebox:child:childInjector"
// Use a specific instance name
property name="categoryService" inject="wirebox:child:childInjector:CategoryService"
// Use any DSL
property name="categoryService" inject="wirebox:child:childInjector:{DSL}"

IInjector Interface Updates

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

/**
 * Locates, Creates, Injects and Configures an object model instance
 *
 * @name The mapping name or CFC instance path to try to build up
 * @initArguments The constructor structure of arguments to passthrough when initializing the instance
 * @dsl The dsl string to use to retrieve the instance model object, mutually exclusive with 'name'
 * @targetObject The object requesting the dependency, usually only used by DSL lookups
 * @injector The child injector name to use when retrieving the instance
 */
function getInstance(
	name,
	struct initArguments,
	dsl,
	targetObject = "",
	injector
);

Release Notes

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:

• CFML Scheduled Tasks

• ColdBox Scheduled Tasks

Release Notes

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.

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

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.

xTask() - Easy Disabling of Tasks

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:

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.

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.

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

Async Interceptors Data

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

Luis Fernando Majano Lainez

Luis Majano is a Computer Engineer with over 15 years of software development and systems architecture experience. He was born in in the late 70’s, during a period of economical instability and civil war. He lived in El Salvador until 1995 and then moved to Miami, Florida where he completed his Bachelors of Science in Computer Engineering at

Luis 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, micro-controllers and overall embedded systems.

• He has of late (during old age) become a fan of organic gardening.

Keep Jesus number one in your life and in your heart. I did and it changed my life from desolation, defeat and failure to an abundant life full of love, thankfulness, joy and overwhelming peace. As this world breathes failure and fear upon any life, Jesus brings power, love and a sound mind to everybody!

“Trust in the LORD with all your heart, and do not lean on your own understanding.” – Proverbs 3:5

Contributors

Jorge Emilio Reyes Bendeck

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

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

Brad Wood

Brad's CommandBox Snake high score is 141.

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.

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.

Release notes - ColdBox Platform - 6.10.0

Bug

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

Render encapsulator bleed of this scope by engines

Improvement

Removal of deprecated CFML functions in core

Improved engine detection by the CFMLEngine feature class

Remove unsafe evaluate function usage

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

Added

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

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

Improvements

• Scheduled Tasks Updates

Fixed

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

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

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

• The majority of code generation and running of examples are done via CommandBox: The ColdFusion (CFML) CLI, Package Manager, REPL -

• All ColdFusion examples designed to run on the open 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

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

Charitable Proceeds

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

Shalom Children's Home

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

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

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

/**
 * Builds links to events or URL Routes
 *
 * @to          The event or route path you want to create the link to
 * @queryString The query string to append which can be a regular query string string, or a struct of name-value pairs
 * @translate   Translate between . to / depending on the SES mode on to and queryString arguments. Defaults to true.
 * @ssl         Turn SSl on/off on URL creation, by default is SSL is enabled, we will use it.
 * @baseURL     If not using SES, you can use this argument to create your own base url apart from the default of index.cfm. Example: https://mysample.com/index.cfm
 */
string function buildLink(
	to,
	queryString       = "",
	boolean translate = true,
	boolean ssl,
	baseURL = ""
){

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. You can use main.index or just main (Remember that index is the default action)

<cfoutput>
    <h1>Hello from ColdBox Land!</h1>
    <p><a href="#event.buildLink( "main" )#">Go home</a></p>
</cfoutput>

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:

<form action="#event.buildLink( 'user.save' )#" method="post">
...
</form>

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.

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

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

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

Creating A Layout

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

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

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

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

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

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

If you are use to using cfinclude to reuse templates, think about it the same way. renderview() is a much more powerful cfinclude.

Using The Layout

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

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

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

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

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

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

• Learn about HMVC via ColdBox Modules

• Learn about Dependency Injection

• Learn about Caching

• Learn about Logging

• Learn about Testing

Getting Help

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

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

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 auto-marshalling in your handlers. By default, ColdBox detects any return value from handlers and if they are complex it will convert them to JSON automatically for you:

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

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

renderData()

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

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

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

We have added the following line:

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

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

Format Detection

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

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

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

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

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

Routing

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

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

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

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

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

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

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

Handler Scaffolding

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.

Default URL Routing

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

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

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:

// Conventions based routing
route( ":handler/:action?" ).end();

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:

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 represents the request and can modify the response. We call this object the request context.

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

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

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

• config/WireBox.cfc - Your application WireBox Configuration (optional )

• handlers - This holds the app's event handlers (controller layer)

• layouts - Your HTML layouts (view layer)

• models - This holds your app's CFCs (model layer)

• modules - This holds the CommandBox tracked modules

• modules_app - This holds your app's modules

• tests - Your test harness including unit and integration testing

• views - Your HTML views will go here (view layer)

Execution Conventions

ColdBox also has several execution conventions. This means that we have a convention or a default for the event, action and layout to be used if you do not tell it what to use:

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.

You can find the source code of this quickstart here: https://github.com/coldbox-samples/60-minute-quickstart

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

• Get comfortable

Need Help?

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

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 exercise in this book and it will also allow you to get up and running with ColdFusion and ColdBox in a much speedier manner.

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/setup/installation

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.