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

ColdBox Manual - v5.x

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

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

Versioning

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

<major>.<minor>.<patch>

And constructed with the following guidelines:

• Breaking backward compatibility bumps the major (and resets the minor and patch)

• New additions without breaking backward compatibility bumps the minor (and resets the patch)

• Bug fixes and misc changes bumps the patch

License

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

• Copyright by Ortus Solutions, Corp

• ColdBox is a registered trademark by Ortus Solutions, Corp

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

Discussion & Help

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

Reporting a Bug

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

• By Email: [email protected]

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

Professional Open Source

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

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

• Security Hardening

• Code Reviews

• Much More

Resources

• Official Site: https://www.coldbox.org

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

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

• Twitter: @coldbox

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

• Google+: https://www.google.com/+ColdboxOrg

• Vimeo Channel: https://vimeo.com/channels/coldbox

HONOR GOES TO GOD ABOVE ALL

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

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

ColdBox Manual - v5.0.0

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

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

Versioning

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

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 License. If you use ColdBox, please try to make mention of it in your code or web site or add a Powered By Coldbox icon.

• Copyright by Ortus Solutions, Corp

• ColdBox is a registered trademark by Ortus Solutions, Corp

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

Discussion & Help

The ColdBox help and discussion group can be found here:

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:

• By Email:

• By Jira:

Professional Open Source

ColdBox is a professional open source software backed by offering services like:

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

• Security Hardening

• Code Reviews

Resources

• Official Site:

• Source Code:

• Bug Tracker:

• Twitter:

• Facebook:

• Google+:

• Vimeo Channel:

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

Short and sweet release!

Bug

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

This is a patch release for ColdBox

Bugs

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

Improvements

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

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

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

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

Directory/File Conventions

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

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

• handlers - This holds the app's controllers

• layouts - Your HTML layouts

• models - This holds your app's CFCs

• modules - This holds the CommandBox tracked modules

• modules_app - This holds your app's modules

• views - Your HTML views will go here

Execution Conventions

This element defines custom conventions for your application. By default, the framework has a default set of conventions that you need to adhere too. However, if you would like to implement your own conventions for a specific application, you can use this setting, otherwise do not declare it:

//Conventions
conventions = {
    handlersLocation = "controllers",
    viewsLocation      = "views",
    layoutsLocation  = "views",
    modelsLocation      = "model",
    modulesLocation  = "modules",
    eventAction      = "index"
};

The layouts array element is used to define implicit associations between layouts and views/folders, this does not mean that you need to register ALL your layouts. This is a convenience for pairing them, we are in a conventions framework remember.

Before any renderings occur or lookups, the framework will check this array of associations to try and match in what layout a view should be rendered in. It is also used to create aliases for layouts so you can use aliases in your code instead of the real file name and locations.

//Register Layouts
layouts = [
    { 
        // The alias of a layout
        name="",
        // The layout file
        file="",
        // A list of view names to render within this layout
        views="",
        // A list of regex names to match a view
        folders=""
    }

    // Examples
    { name="tester",file="Layout.tester.cfm",views="vwLogin,test",folders="tags,pdf/single"    },
    { name="login",file="Login.cfm",folders="^admin/security"}
];

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

Requirements

• Please make sure you download and install the latest CommandBox CLI. We will show you how in the Installing ColdBox section.

• Grab a cup of coffee

• Get comfortable

The modules structure is used to configure the behavior of the ColdBox Modules.

modules = {
    // Will auto reload the modules in each request. Great for development but can cause some loading/re-loading issues
    autoReload = true,
    // An array of modules to load ONLY
    include = [],
    // An array of modules to EXCLUDE for operation
    exclude = [ "paidModule1", "paidModule2" ]
};

Danger Please be very careful when using the autoReload flag as module routing can be impaired and thread consistency will also suffer. This is PURELY a development flag that you can use at your own risk.

This structure is used to house module configurations. Please refer to each module's documentation on how to create the configuration structures. Usually the keys will match the name of the module to be configured.

component {

     function configure() {

         moduleSettings = {
             myModule = {
                someSetting = "overridden"
             }
        };
    }
}

This structure allows you to define a system-wide default layout and view.

//Layout Settings
layoutSettings = {
    // The default layout to use if NOT defined in a request
    defaultLayout = "Main.cfm",
    // The default view to use to render if NOT defined in a request
    defaultView   = "youForgot.cfm"
};

Hint Please remember that the default layout is Main.cfm

The base tag in HTML allows you to tell the browser what is the base URL for assets in your application. This is something that is always missed when using frameworks that enable routing.

We definitely recommend using this HTML tag reference as it will simplify your asset retrievals.

<base href="#event.getHTMLBaseURL()#">

ColdBox Core MVC does not have validation built-in but it is implemented via the offical core cbValidation module. You can easily install the module in your application via:

box install cbvalidation

You can find much more information about this module in the following resources:

• Source: https://github.com/coldbox/cbox-validation

• Documentation: https://github.com/coldbox-modules/cbox-validation/wiki

• ForgeBox : http://forgebox.io/view/cbvalidation

So what if I want to render a view outside of my application without using the setting explained above? Well, you use the renderExternalView() method.

<cfoutput>#renderExternalView(view='/myViewsMapping/tags/footer')#</cfoutput>

These are custom application settings that you can leverage in your application.

// Custom Settings
settings = {
    useSkins = true,
    myCoolArray = [1,2,3,4],
    skinsPath = "views/skins",
    myUtil = createObject("component","#appmapping#.model.util.MyUtility")
};

You can read our Using Settings section to discover how to use all the settings in your application.

This is a patch release for ColdBox.

Bug

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

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

Improvement

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

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

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

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

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

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

External Trademarks & Copyrights

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

Notice of Liability

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

Contributing

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

Charitable Proceeds

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

Shalom Children's Home

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

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

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

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

Layout Code

This location is identified by the following code:

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

Creating A Layout

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

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

Using The Layout

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

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

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

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

Getting Help

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

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

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

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

Reinitializing An Application

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

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

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

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

ConfigFile

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

ScopeRegistration

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

DefaultCache

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

Caches

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

This configuration structure is used to configure the dependency injection framework embedded in ColdBox.

binder

The location of the WireBox configuration binder to use for the application. If empty, we will use the binder in the config folder called by conventions: WireBox.cfc

singletonReload

A great flag for development. If enabled, WireBox will flush its singleton objects on every request so you can develop without any headaches of reloading.

Warning : This operation can cause some thread issues and it is only meant for development. Use at your own risk.

This directive is how you will configure the for operation. Below are the configuration keys and their defaults:

This is an array of interceptor definitions that you will use to register in your application. The key about this array is that ORDER matters. The interceptors will fire in the order that you register them whenever their interception points are announced, so please watch out for this caveat. Each array element is a structure that describes what interceptor to register.

Warning : Important: Order of declaration matters! Also, when declaring multiple instances of the same CFC (interceptor), make sure you use the name attribute in order to distinguish them. If not, only one will be registered (the last one declared).

Routing is enabled by default in the ColdBox application templates in order to work with URL's like this:

http://localhost/index.cfm/home/about

As you can see they still contain the index.cfm in the URL. In order to enable full URL rewrites that eliminates that index.cfm you must have a rewrite enabled webserver like Apache, nginx or IIS or a Java rewrite filter which ships with CommandBox by default.

http://localhost/home/about

CommandBox has built in rewrites powered by Tuckey and you can enable a server with rewrites by running:

Some Resources

• via .htaccess or configuration files (Free)

• ISAPI rewrite filter for IIS (Paid)

• native rewrite filter (Free)

• native web server (free)

• J2EE rewrite filter (free)

There will be a time where your routes will become very verbose and you would like to group them into logical declarations. These groupings can also help you prefixes repetitive patterns in many routes with a single declarative construct. These needs are met with the group() method in the router.

The best way to see how it works is by example:

As you can see from the routes above, we have lots of repetitive code that we can clean out. So let's look at the same routes but using some nice grouping action.

The options struct can contain any values that you can use within the closure. Grouping can also be very nice when creating , which is our next section.

With this interceptor you can intercept local event actions and execute things after the requested action executes. You can do it globally by using the postHandler() method or targeted to a specific action post{actionName}().

The arguments received by these interceptors are:

• event : The request context reference

• action : The action name that was intercepted

• eventArguments : The struct of extra arguments sent to an action if executed via runEvent()

• rc : The RC reference

• prc : The PRC Reference

Exceptions & Only Lists

You can fine tune these interception methods by leveraging two public properties in the handler:

• this.posthandler_only : A list of actions that the postHandler() action will fire ONLY!

• this.posthandler_except : A list of actions that the postHandler() action will NOT fire on

This is a nifty little feature that enables you to create nice helper templates on a per-view, per-folder and per-application basis. If the framework detects the helper, it will inject it into the rendering view so you can use methods, properties or whatever. All you need to do is follow a set of conventions. Let's say we have a view in the following location:

Then we can create the following templates

• homeHelper.cfm : Helper for the home.cfm view.

• generalHelper.cfm : Helper for any view in the general folder.

homeHelper.cfm

That's it. Just append Helper to the view or folder name and there you go, the framework will use it as a helper for that view specifically. What can you put in these helper templates:

• NO BUSINESS CODE

• UI logic functions or properties

• Helper functions or properties

• Dynamic JavaScript or CSS

Hint External views can also use our helper conventions

Application wide helpers

You can also use the coldbox.viewsHelper directive to tell the framework what helper file to use for ALL views and layouts rendered:

With this interceptor you can intercept local event actions and execute things before the requested action executes. You can do it globally by using the preHandler() method or targeted to a specific action pre{actionName}().

The arguments received by these interceptors are:

• event : The request context reference

• action : The action name that was intercepted

• eventArguments : The struct of extra arguments sent to an action if executed via runEvent()

• rc : The RC reference

• prc : The PRC Reference

Here are a few options for altering the default event execution:

• Use event.overrideEvent('myHandler.myAction') to execute a different event than the default.

• Use event.noExecution() to halt execution of the current event

See the documentation for more details.

Exceptions & Only Lists

You can fine tune these interception methods by leveraging two public properties in the handler:

• this.prehandler_only : A list of actions that preHandler() will ONLY fire on

• this.prehandler_except : A list of actions that preHandler() will NOT fire on

This is a patch release for ColdBox

Bugs/Regressions

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

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

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

Improvements

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

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

Automatic JSON Payload Setting

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

coldbox = {
    jsonPayloadToRC = true
}

HTML Helper Changes

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

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

Injection Shortcut

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

The logBox structure is based on the LogBox declaration DSL, see the LogBox Documentation for much more information.

//LogBox DSL
logBox = {
    // The configuration file without fileextension to use for operation, instead of using this structure
    configFile = "config/LogBox", 
    // Appenders
    appenders = {
        appenderName = {
            class="class.to.appender", 
            layout="class.to.layout",
            levelMin=0,
            levelMax=4,
            properties={
                name  = value,
                prop2 = value 2
            }
    },
    // Root Logger
    root = {levelMin="FATAL", levelMax="DEBUG", appenders="*"},
    // Granualr Categories
    categories = {
        "coldbox.system" = { levelMin="FATAL", levelMax="INFO", appenders="*"},
        "model.security" = { levelMax="DEBUG", appenders="console"}
    }
    // Implicit categories
    debug  = ["coldbox.system.interceptors"],
    info   = ["model.class", "model2.class2"],
    warn   = ["model.class", "model2.class2"],
    error  = ["model.class", "model2.class2"],
    fatal  = ["model.class", "model2.class2"],
    off    = ["model.class", "model2.class2"]
};

Info : If you do not define a logBox DSL structure, the framework will look for the default configuration file config/LogBox.cfc. If it does not find it, then it will use the framework's default logging settings.

ConfigFile

You can use a configuration CFC instead of inline configuration by using this setting. The default value is config/LogBox.cfc, so by convention you can just use that location. If no values are defined or no config file exists, the default configuration file is coldbox/system/web/config/LogBox.cfc.

In your views, layouts and handlers you can use the buildLink method provided by the request context object (event) to build routable links in your application.

buildLink(
    // Where to link to
    any to, 
    // Translate periods to slashes
    [boolean translate='true'], 
    // Force or un-force SSL, by default we keep the same protocol of the request
    [boolean ssl], 
    // Update the baseURL, usually used for testing
    [any baseURL=''], 
    // Append a query string to the URL, as convention name value-pairs
    [any queryString='']
)

Just pass in the routed URL or event and it will create the appropriate routed URL for you:

<a href="#event.buildLink( 'home.about' )#">About</a>
<a href="#event.buildLink( 'user.edit.id.#user.getID()#' )#">Edit User</a>

Inspecting The Current Route

The request context object (event) also has some handy methods to tell you the name or even the current route that was selected for execution:

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

• getCurrentRoute() - Gives you the currently executed route

• getCurrentRoutedURL() - Gives you the complete routed URL pattern that matched the route

• getCurrentRoutedNamespace() - Gives you the current routed namespace, if any

This structure configures the interceptor service in your application.

//Interceptor Settings
interceptorSettings = {
    throwOnInvalidStates = false,
    customInterceptionPoints = "onLogin,onWikiTranslation,onAppClose"
};

throwOnInvalidStates

This tells the interceptor service to throw an exception if the state announced for interception is not valid or does not exist. Defaults to false.

customInterceptionPoints

This key is a comma delimited list or an array of custom interception points you will be registering for custom announcements in your application. This is the way to provide an observer-observable pattern to your applications.

Info Please see the Interceptors section for more information.

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

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

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

You can manually add these _method fields yourselves, or you can take advantage of ColdBox's HTML Helper startForm() method. Just pass the method you like, we will take care of the rest:

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

ColdBox supports a Routing Service that will provide you with robust URL mappings for building expressive applications and RESTFul services. By convention URL routing will allow you to create URL's without using verbose parameter delimiters like ?event=this.that&m1=val and execute ColdBox events.

// Old Style
http://localhost/index.cfm?event=home.about&page=2
http://localhost/index.cfm?city=24&page=3&county=234324324

// New Routing Style
http://localhost/home/about/page/2
http://localhost/dade/miami/page/3

What is a route?

A route is a declared URL pattern that if matched it will translate the URL into one of the following:

• A ColdBox event to execute

• A View/Layout to render

• A Reponse function to execute

• A Redirection to occur

It will also inspect the URL for placeholders and translate them into the incoming Request Collection variables (RC).

Examples

function configure(){

    // Routing with placeholders to an event with placeholders
    route( "/blog/:year-numeric{4}/:month?/:day?" )
        .to( "blog.list" );

    // Redirects
    route( "/old/book" )
        .redirect( "/mybook" );

    // Responses
    route( "/echo" ).toResponse( (event,rc,prc) => {
        return "hello luis";
    } );

    // Shortcut to above
    route( "/echo", (event,rc,prc) => {
        return "hello luis";
    } );

    // Show view
    route( "/contact-us" )
        .toView( "main/contact" );

    // Direct to handler with action from URL
    route( "/users/:action" )
        .toHandler( "users" );

    // Inline pattern + target and name
    route( pattern="/wiki/:page", target="wiki.show", name="wikipage" );

}

Routing Benefits

There are several benefits that you will get by using our routing system:

• Complete control of how URL's are built and managed

• Ability to create or build URLs' dynamically

• Technology hiding

• Greater application portability

• URL's are more descriptive and easier to remember

Route Visualizer

As you create route-heavy applications visualizing the routes will be challenging especially for HMVC apps with lots of modules. Just install our ColdBox Route Visualizer and you will be able to visually see, test and debug all your routing needs.

box install route-visualizer

You can create a-la-carte namespaces for URL routes. Namespaces are cool groupings of routes according to a specific URL entry point. So you can say that all URLs that start with /testing will be found in the testing namespace and it will iterate through the namespace routes until it matches one of them.

Much how modules work, where you have a module entry point, you can create virtual entry point to ANY route by namespacing it. This route can be a module a non-module, package, or whatever you like. You start off by registering the namespace using the addNamespace( pattern, namespace ) method or the fluent route().toNamespaceRouting() method.

addNamespace( pattern="/testing", namespace="test" );
route( "/testing" ).toNamespaceRouting( "test" );

addNamespace( pattern="/news", namespace="blog" );
route( "/news" ).toNamespaceRouting( "blog" );

Once you declare the namespace you can use the grouping functionality to declare all the namespace routes or you can use a route().withNamespace() combination.

// Via Grouping
route( "/news" ).toNamespaceRouting( "blog" )
	.group( { namespace = "blog" }, function(){
		route( "/", "blog.index" )
  		.route( "/:year-numeric?/:month-numeric?/:day-numeric?", "blog.archives" );
	} );
  

// Via Routing DSL
addNamespace( "/news", "blog" );
  
route( "/" )
  .withNameSpace( "blog" )
  .to( "blog.index" );

route( "/:year-numeric?/:month-numeric?/:day-numeric?" )
  .withNameSpace( "blog" )
  .to( "blog.archives" );

You can pass localized arguments to the renderView() and renderLayout() methods in order to encapsulate the rendering via the args struct argument. Much like how you make method calls with arguments. Inside of your layouts and views you will receive the same args struct reference as well.

This gives you great DRYness (yes that is a word) when building new and edit forms or views as you can pass distinct arguments to distinguish them and keep structure intact.

Universal Form

<h1>#args.type# User</h1>
<form method="post" action="#args.action#">
...
</form>

New Form

#renderView(view='forms/universal',args={type='new',action='user.create'})#

Edit Form

#renderView(view='forms/universal',args={type='edit',action='user.update'})#

The ColdBox Controller (stored in ColdFusion application scope) stores all your application settings and also your system settings:

• ColdboxSettings : Framework specific system settings

• ConfigSettings : Your application settings

You can use the following methods to retrieve/set/validate settings in your handlers/layouts/views and interceptors:

/**
 * Get a setting from the system
 * @name The key of the setting
 * @fwSetting Retrieve from the config or fw settings, defaults to config
 * @defaultValue If not found in config, default return value
 */
function getSetting( required name, boolean fwSetting=false, defaultValue )

/**
 * Verify a setting from the system
 * @name The key of the setting
 * @fwSetting Retrieve from the config or fw settings, defaults to config
 */
boolean function settingExists( required name, boolean fwSetting=false )

/**
 * Set a new setting in the system
 * @name The key of the setting
 * @value The value of the setting
 *
 * @return FrameworkSuperType
 */
any function setSetting( required name, required value )

You can also get access to these methods via the ColdBox Controller component:

controller.getSetting()
controller.setSetting()
controller.settingExists()
controller.getConfigSettings()
controller.getColdBoxSettings()

Injecting Settings

You can use the WireBox injection DSL to inject settings in your models or non-coldbox objects. Below are the available DSL notations:

• coldbox:setting:{key} : Inject a specified config setting key

• coldbox:fwsetting:{key} : Inject a specified system setting key

• coldbox:configSettings : Inject a reference to the application settings structure

• coldbox:fwSettings : Inject a reference to the ColdBox System settings structure

component{

    property name="mysetting" inject="coldbox:setting:mysetting";
    property name="path" inject="coldbox:fwSetting:path";
    property name="config" inject="coldbox:configSettings";
    property name="settings" inject="coldbox:fwSettings";

}

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

You can leverage the resources() method in your router to register resourceful routes.

// Creates all resources that point to a photos event handler by convention
resources( "photos" );

// Register multiple resources either as strings or arrays
resources( "photos,users,contacts" )
resources( [ "photos" , "users", "contacts" ] );

// Register multiple fluently
resources( "photos" )
    .resources( "users" )
    .resources( "contacts" );

// Creates all resources to the event handler of choice instead of convention
resources( route="photos", handler="MyPhotoHandler" );

// All resources in a module
resources( route="photos", handler="photos", module="api" );

// Resources in a ModuleConfig.cfc
router.resources( "photos" )
  .resources( resource="users", handler="user" )

This single resource declaration will create all the necessary variations of URL patterns and HTTP Verbs to actions to handle the resource. Please see the table below with all the permutations it will create for you.

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

/**
* Create all RESTful routes for a resource. It will provide automagic mappings between HTTP verbs and URLs to event handlers and actions.
* By convention, the name of the resource maps to the name of the event handler.
* Example: `resource = photos` Then we will create the following routes:
* - `/photos` : `GET` -> `photos.index` Display a list of photos
* - `/photos/new` : `GET` -> `photos.new` Returns an HTML form for creating a new photo
* - `/photos` : `POST` -> `photos.create` Create a new photo
* - `/photos/:id` : `GET` -> `photos.show` Display a specific photo
* - `/photos/:id/edit` : `GET` -> `photos.edit` Return an HTML form for editing a photo
* - `/photos/:id` : `PUT/PATCH` -> `photos.update` Update a specific photo
* - `/photos/:id` : `DELETE` -> `photos.delete` Delete a specific photo
* 
* @resource         The name of a single resource or a list of resources or an array of resources
* @handler          The handler for the route. Defaults to the resource name.
* @parameterName    The name of the id/parameter for the resource. Defaults to `id`.
* @only             Limit routes created with only this list or array of actions, e.g. "index,show"
* @except           Exclude routes with an except list or array of actions, e.g. "show"
* @module           If passed, the module these resources will be attached to.
* @namespace        If passed, the namespace these resources will be attached to.
*/
function resources(
  required resource,
  handler=arguments.resource,
  parameterName="id",
  only=[],
  except=[],
  string module="",
  string namespace=""
)

Scaffolding Resources

We have created a scaffolding command in CommandBox to help you register and generate resourceful routes. Just run the following command in CommandBox to get all the help you will need in generating resources:

coldbox create resource help

Events are determined via a special variable that can be sent in via the FORM, URL, or REMOTELY called event. If no event is detected as an incoming variable, the framework will look in the configuration directives for the DefaultEvent and use that instead. If you did not set a DefaultEvent setting then the framework will use the following convention for you: main.index

Please note that ColdBox supports both normal variable routing and URL mapping routing, usually referred to as pretty URLs.

Event Syntax

In order to call them you will use the following event syntax notation format:

event={module:}{package.}{handler}{.action}

• no event : Default event by convention is main.index

• event={handler} : Default action method by convention is index()

• event={handler}.{action} : Explicit handler + action method

• event={package}.{handler}.{action} : Packaged notation

• event={module}:{package}.{handler}.{action} : Module Notation (See ColdBox Modules)

This looks very similar to a Java or CFC method call, example: String.getLength(), but without the parentheses. Once the event variable is set and detected by the framework, the framework will tokenize the event string to retrieve the CFC and action call to validate it against the internal registry of registered events. It then continues to instantiate the event handler CFC or retrieve it from cache, finally executing the event handler's action method.

Examples

// Call the users.cfc index() method
index.cfm?event=users.index
// Call the users.cfc index() method implicitly
index.cfm?event=users
// Call the users.cfc index() method via URL mappings
index.cfm/users/index
// Call the users.cfc index() method implicitly via URL mappings
index.cfm/users

There are several simple implicit AOP (Aspect Oriented Programming) interceptor methods, usually referred to as advices, that can be declared in your event handler that the framework will use in order to execute them before/after and around an event as its fired from the current handler.

This is great for intercepting calls, pre/post processing, localized security, logging, RESTful conventions, and much more. Yes, you got that right, Aspect Oriented Programming just for you and without all the complicated setup involved! If you declared them, the framework will execute them.

Luis Fernando Majano Lainez

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

He is the CEO of , a consulting firm specializing in web development, ColdFusion (CFML), Java development and all open source professional services under the ColdBox and ContentBox stack. He is the creator of ColdBox, ContentBox, WireBox, MockBox, LogBox and anything “BOX”, and contributes to many open source ColdFusion projects. He is also the Adobe ColdFusion user group manager for the . You can read his blog 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, microcontrollers and overall embedded systems.

• He has of late (during old age) become a fan of running and bike riding with his family.

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

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

Contributors

Jorge Emilio Reyes Bendeck

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

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

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

Brad Wood

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

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

Brad's CommandBox Snake high score is 141.

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

This will generate the following files:

• A new handler called hello.cfc inside of the handlers folder

• A view called index.cfm in the views/hello folder

• An integration test at tests/specs/integration/helloTest.cfc.

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

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

Handler Code

Let's check out the handler code:

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

• event - An object that models and is used to work with the current request

• rc - A struct that contains both URL/FORM variables (unsafe data)

• prc - A secondary struct that is private only settable from within your application (safe data)

Executing Events

Did you detect a convention here?

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

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

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

My First Virtual Event

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

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

Then go execute the virtual event:

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

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

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

Handler Code

Every action in ColdBox receives three arguments:

• event - An object that models and is used to work with the current request

• rc - A struct that contains both URL/FORM variables (unsafe data)

• prc - A secondary struct that is private only settable from within your application (safe data)

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

Executing Events

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

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

Working With Incoming Data

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

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

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

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

ColdBox makes it easy to access the configuration stored in your Java system properties and your server's environment variables, even if you don't know which one it is in! Three methods are provided for your convenience:

Accessing System Settings in config/ColdBox.cfc or a ModuleConfig.cfc

If you are inside config/ColdBox.cfc or a ModuleConfig.cfc or a config/WireBox.cfc you can use the three system settings functions directly! No additional work required.

Accessing System Settings in Application.cfc

If you would like to access these methods in your Application.cfc, create an instance of coldbox.system.core.util.Util and access them off of that component. This is required when adding a datasource from environment variables.

Example:

Accessing System Settings in other files

If you need to access these configuration values in other components, consider adding the values to your and injecting the values into your other components

By default, the URL mapping processor will detect routes by looking at the CGI.PATH_INFO variable, but you can override this and provide your own function. This feature can be useful to set flags for each request based on a URL and then clean or parse the URL to a more generic form to allow for simple route declarations. Uses may include internationalization (i18n) and supporting multiple experiences based on devices such as Desktop, Tablet, Mobile and TV.

To modify the URI used by the Routing Services before route detection occurs simply follow the convention of adding a function called pathInfoProvider() to your application Router (config/Router.cfc).

The pathInfoProvider() function is responsible for returning the string used to match a route.

Usage

ColdBox allows you to detect incoming extensions from incoming paths automatically for you. This is great for building multi-type responses or to just create virtual extensions for events.

If an extension is detected in the incoming URL, ColdBox will grab it and store it in the request collection (RC) as the variable format. If there is no extension, then rc.format will not be stored and thus will not exist.

Configuration

You can configure the extension detection using the following configuration methods:

The framework provides you with the relocate() method that you can use to relocate to other events thanks to the framework super type object, the grand daddy of all things ColdBox.

So always remember that you relocate via relocate() and if I asked you: "Where in the world does event handlers get this method from?", you need to answer: "From the super typed inheritance".

Every router has a default route already defined for you in the application templates, which we refer to as routing by convention:

The URL pattern in the default route includes two special position placeholders, meaning that the handler and the action will come from the URL. Also note that the :action has a question mark (?), which makes the placeholder optional, meaning it can exist or not from the incoming URL.

• :handler - The handler to execute (It can include a Package and/or Module reference)

• :action - The action to relocate to (See the ?, this means that the action is optional)

This route can handle pretty much all your needs by convention:

Convention Name-Value Pairs

Any extra name-value pairs in the remaining URL of a discovered URL pattern will be translated to variables in the request collection (rc) for you automagically.

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

ColdBox

Bugs

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

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

• [] - base url not eliminating double slashes

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

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

New Features

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

Improvements

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

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

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

• [] - Performance improvements for interception registrations and discovery

LogBox

Improvements

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

WireBox

Improvements

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

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

• [] - Performance improvements for the construction of transients

We all need values in our applications. That is why we interact with the in order to place data from our model layer into it so our views can display it, or to retrieve data from a user's request. You will either interact with the event object to get/set values or put/read values directly via the received rc and prc references.

Every event handler controller has some implicit methods that if you create them, they come alive. Just like the implicit methods in Application.cfc

onMissingAction()

With this convention you can create virtual events that do not even need to be created or exist in a handler. Every time an event requests an action from an event handler and that action does not exist in the handler, the framework will check if an onMissingAction() method has been declared. If it has, it will execute it. This is very similar to ColdFusion's onMissingMethod() but on an event-driven framework.

This event has an extra argument: missingAction which is the missing action that was requested. You can then do any kind of logic against this missing action and decide to do internal processing, error handling or anything you like. The power of this convention method is extraordinary, you have tons of possibilities as you can create virtual events on specific event handlers.

onError()

This is a localized error handler for your event handler. If any type of runtime error occurs in an event handler and this method exists, then the framework will call your method so you can process the error first. If the method does not exist, then normal error procedures ensue.

onInvalidHTTPMethod()

This method will be called for you if a request is trying to execute an action in your handler without the proper approved HTTP Verb. It will then be your job to determine what to do next:

A part from using runEvent() to execute events, you can also abstract it by using the runRoute() method. This method is fairly similar but with the added benefit of executing a NAMED route instead of the direct event it represents. This gives you the added flexibility of abstracting the direct event and leveraging the named route.

All the same feature of runEvent() apply to runRoute()

RunRoute()

Just like you can create links based on named routes and params, you can execute named routes and params as well internally via runRoute()

Parameters

The params argument you pass to the runRoute() method will be translated into event arguments. Therefore they will be passed as arguments to the event the route represents:

In the example above, the userData named route points to the user.data event.

Module Routes

If you want to execute module routes, no problem! Just use our @ or : notation to tell the controller from which module's router we should pick the route from.

You have a few arguments in the renderView() method that deal with collection rendering. Meaning you can pass any array or query and the Renderer will iterate over that collection and render out the view as many times as the records in the colleciton.

• collection : A data collection that can be a query or an array of objects, structs or whatever

• collectionAs : The name of the variable in the variables scope that will hold the collection pivot.

• collectionStartRow : Defaults to 1 or your offset row for the collection rendering

• collectionMaxRows : Defaults to show all rows or you can cap the rendering display

• collectionDelim : An optional delimiter to use to separate the collection renderings. By default it is empty.

Once you call renderView() with a collection, the renderer will render the view once for each member in the collection. The views have access to the collection via arguments.collection or the member currently iterating. The name of the member being iterated as is by convention the same name as the view. So if we do this in any layout or simple view:

Then the tags/comment will be rendered as many times as the collection rc.comments has members on it and by convention the name of the variable is comment the same as the view name.

If you don't like that, then use the collectionAs argument:

So let's see the collection view now:

You can see that I just call methods on the member as if I was looping (which we are for you). But you will also see two little variables here:

• _counter : A variable created for you that tells you in which record we are currently looping on

• _items : A variable created for you that tells you how many records exist in the collection

This will then render that specific dynamic HTML view as many times as their are records in the rc.comments array and concatenate them all for you. In my case, I separate each iteration with a simple but you can get fancy and creative.

All rendered views have associated events that are announced whenever the view is rendered via ColdBox Interceptors. These are great ways for you to be able to intercept when views are rendered and transform them, append to them, or even remove content from them in a completely decoupled approach. The way to listen for events in ColdBox is to write Interceptors, which are essential simple CFC's that by convention have a method that is the same name as the event they would like to listen to. Each event has the capability to receive a structure of information wich you can alter, append or remove from. Once you write these Interceptors you can either register them in your Configuration File or programmatically.

Caution You can disable the view events on a per-rendering basis by passing the prePostExempt argument as true when calling renderView() methods.

Sample Interceptor

Here is a sample interceptor that trims any content before it is renderer:

Of course, I am pretty sure you will be more creative than that!

We have now seen how to set views to be rendered from our handlers. However, we can use some cool methods to render views and layouts on-demand. These methods exist in the Renderer and several facade methods exist in the super type so you can call it from any handler, interceptor, view or layout.

1. renderView()

2. renderExternalView()

3. renderLayout()

Check out the latest for the latest arguments:

Model Rendering

If you need rendering capabilities in your model layer, we suggest using the following injection DSL:

This will inject a of a Renderer into your model objects. Remember that renderers are transient objects so you cannot treat them as singletons. The provider is a proxy to the transient object, but you can use it just like the normal object:

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

• update coldbox

• update logbox

• update wirebox

• update cachebox

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

Compatibility Notes

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

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

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

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

Major Updates

Performance

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

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

More Environment Detection

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

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

Custom Resource Patterns

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

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

ColdBox Release Notes

Bugs

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

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

New Features

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

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

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

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

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

Improvements

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

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

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

WireBox Release Notes

New Features

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

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

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

Improvement

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

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

ColdBox

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

Bugs

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

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

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

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

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

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

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

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

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

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

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

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

New Features

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

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

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

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

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

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

Improvements

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

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

LogBox

Bugs

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

New Features

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

Improvements

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

WireBox

Bugs

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

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

Improvements

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

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

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

ColdBox 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
* @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
* @queryString The query string to append
*/
string function buildLink(
    to,
    boolean translate=true,
    boolean ssl,
    baseURL="",
    queryString="");

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.

<cfoutput>
<h1>Hello from ColdBox Land!</h1>
<p><a href="#event.buildLink( "main.index" )#">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.

The ColdBox Routing DSL will be used to register routes for your application, which exists in your application or module router object. Routing takes place using several methods inside the router, which are divided into the following 3 categories:

1. Initiators - Starts a URL pattern registration, but does not fully register the route until a terminator is called (target).

2. Modifiers - Modifies the pattern with extra metdata to listen to from the incoming request.

3. Terminators - Finalizes the registration process usually by telling the router what happens when the route pattern is detected. This is refered to as the target.

Initiators

The following methods are used to initiate a route registration process.

• route( pattern, [target], [name] ) - Register a new route with optional target terminators and a name

• get( pattern, [target], [name] ) - Register a new route with optional target terminators, a name and a GET http verb restriction

• post( pattern, [target], [name] ) - Register a new route with optional target terminators, a name and a POST http verb restriction

• put( pattern, [target], [name] ) - Register a new route with optional target terminators, a name and a PUT http verb restriction

• patch( pattern, [target], [name] ) - Register a new route with optional target terminators, a name and a PATCH http verb restriction

• options( pattern, [target], [name] ) - Register a new route with optional target terminators, a name and a OPTIONS http verb restriction

• group( struct options, body ) - Group routes together with options that will be applied to all routes declared in the body closure/lambda.

Modifiers

Modifiers will tell the routing service about certain restrictions, conditions or locations for the routing process. It will not register the route just yet.

• header( name, value, overwrite=true ) - attach a response header if the route matches

• headers( map, overwrite=true ) - attach multiple response headers if the route matches

• as( name ) - Register the route as a named route

• rc( name, value, overwrite=true ) - Add an RC value if the route matched

• rcAppend map, overwrite=true ) - Add multiple values to the RC collection if the route matched

• prc( name, value, overwrite=true ) - Add an PRC value if the route matched

• prcAppend map, overwrite=true ) - Add multiple values to the PRC collection if the route matched

• withHandler( handler ) - Map the route to execute a handler

• withAction( action ) - Map the route to execute a single action or a struct that represents verbs and actions

• withModule( module ) - Map the route to a module

• withNamespace( namespace ) - Map the route to a namespace

• withSSL() - Force SSL

• withCondition( condition ) - Apply a runtime closure/lambda enclosure

• withDomain( domain ) - Map the route to a domain or subdomain

• withVerbs( verbs ) - Restrict the route to listen to only these HTTP Verbs

• packageResolver( toggle ) - Turn on/off convention for packages

• valuePairTranslator( toggle ) - Turn on/off automatic name value pair translations

Terminators

Terminators finalize the routing process by registering the route in the Router.

• end() - Register the route as it exists

• toAction( action ) - Send the route to a specific action or RESTFul action struct

• toView( view, layout, noLayout=false, viewModule, layoutModule ) - Send the route to a view/layout

• toRedirect( target, statusCode=301 ) - Relocate the route to another event

• to( event ) - Execute the event if the route matches

• toHandler( handler ) - Execute the handler if the route matches

• toResponse( body, statusCode=200, statusText="ok" ) - Inline response action

• toModuleRouting( module ) - Send to the module router for evaluation

• toNamespaceRouting( namespace ) - Send to the namespace router for evaluation

Alphanumeric Placeholders

In your URL pattern you can also use the : syntax to denote a variable placeholder. These position holders are alphanumeric by default:

route( "blog/:year/:month?/:day?", "blog.index" );

Once a URL is matched to the route above, the placeholders (:year/:month?/:day?) will become request collection (RC) variables:

http://localhost/blog/2012/12/22 -> rc.year=2012, rc.month=12, rc.day=22
http://localhost/blog/2012/12-> rc.year=2012, rc.month=12
http://localhost/blog/2012-> rc.year=2012

Optional Placeholders

Sometimes we will want to declare routes that are very similar in nature and since order matters, they need to be delcared in the right order. Like this one:

route( "/blog/:year-numeric/:month-numeric/:day-numeric" );
route( "/blog/:year-numeric/:month-numeric" );
route( "/blog/:year-numeric/" );
route( "/blog/" );

However, we just wrote 4 routes for this approach when we can just use optional variables by using the ? symbol at the end of the placeholder. This tells the processor to create the routes for you in the most detailed manner first instead of you doing it manually.

route( "/blog/:year-numeric?/:month-numeric?/:day-numeric?" );

Numeric Placeholders

ColdBox gives you also the ability to declare numerical only routes by appending -numeric to the variable placeholder so the route will only match if the placeholder is numeric. Let's modify the route from above.

route( "blog/:year-numeric/:month-numeric?/:day-numeric?", "blog.index" );

This route will only accept years, months and days as numbers.

Alpha Placeholders

ColdBox gives you also the ability to declare alpha only routes by appending -alpha to the variable placeholder so the route will only match if the placeholder is alpha only.

route( "wiki/:page-alpha", "wiki.show" );

This route will only accept page names that are alpha only.

There are two ways to place a regex constraint on a placeholder, using the -regex: placeholder or adding a constraints structure to the route declaration.

Regular Expression Placeholders

You can also have the ability to declare a placeholder that must match a regular expression by using the -regex( {regex_here} ) placeholder.

// route with regex placeholders
route(
    pattern="/api/:format-regex:(xml|json)/",
    target="api.execute"
);

The rc variable format must match the regex supplied: (xml|json)

Regular Expression Constraints

You can also apply a structure of regular expressions to a route instead of inlining the regular expressions in the placeholder location. You will do this using the constraints() method of the router.

The key in the structure must match the name of the placeholder and the value is a regex expression that must be enclosed by parenthesis ().

// route with custom constraints
route(
    pattern = "/api/:format/:entryID",
    target  = "api.execute"
).constraints( {
    format  = "(xml|json)",
    entryID = "([0-9]{4})" 
} );

You can register routes in ColdBox with a human friendly name so you can reference them later for link generation and more.

Registering Named Routes

You will do this in two forms:

1. Using the route() method and the name argument

2. Using the as() method

// Using the name argument
route( 
    pattern = "/users/list", 
    target = "users.index", 
    name = "usermanager" 
);

route( 
    pattern = "/user/:id/profile", 
    target = "users.show", 
    name = "userprofile"
);

// Using the as() method
route( "/users/:id/profile" )
  .as( "usersprofile" )
  .to( "users.show" )

Generating URLs to Named Routes

You will generate URLs to named routes by leveraging the route() method in the request context object (event).

route(
    // The name of the route
    required name,
    // The params to pass, can be a struct or array
    struct params={},
    // Force or un-force SSL, by default we keep the same protocol of the request
    boolean ssl
);

Let's say you register the following named routes:

route( 
    pattern = "/users/list", 
    target = "users.index", 
    name = "usermanager" 
);

route( 
    pattern = "/user/:id/profile", 
    target = "users.show", 
    name = "userprofile"
);

Then we can create routing URLs to them easily with the event.route() method:

<!-- Named Route with no params -->
<a href="#event.route( 'usermanager' )#">Manage Users</a>

<!-- Named Route with struct params -->
<a href="#event.route( 'userprofile', { id = 3 } )#">View User</a>

<!-- Named Route with array params -->
<a href="#event.route( 'userprofile', [ 3 ] )#">View User</a>

Inspecting The Current Route

The request context object (event) also has some handy methods to tell you the name or even the current route that was selected for execution:

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

• getCurrentRoute() - Gives you the currently executed route

• getCurrentRoutedURL() - Gives you the complete routed URL pattern that matched the route

• getCurrentRoutedNamespace() - Gives you the current routed namespace, if any

More often you will find that certain web operations need to be restricted in terms of what HTTP verb is used to access a resource. For example, you do not want form submissions to be done via GET but via POST or PUT operations. HTTP Verb recognition is also essential when building strong RESTFul APIs when security is needed as well.

Manual Solution

You can do this manually, but why do the extra coding :)

function delete(event,rc,prc){
    // determine incoming http method
    if( event.getHTTPMethod() == "GET" ){
        flash.put("notice","invalid action");
        setNextEvent("users.list");
    }
    else{
        // do delete here.
    }
}

This solution is great and works, but it is not THAT great. We can do better.

Allowed Methods Property

Another feature property on an event handler is called this.allowedMethods. It is a declarative structure that you can use to determine what the allowed HTTP methods are for any action on the event handler.

this.allowedMethods = {
    actionName : "List of approved HTTP Verbs"
};

If the request action HTTP method is not found in the approved list, it will look for a onInvalidHTTPMethod() on the handler and call it if found. Otherwise ColdBox throws a 405 exception that is uniform across requests.

component{

    this.allowedMethods = {
        delete : "POST,DELETE",
        list   : "GET"
    };

    function list(event,rc,prc){
        // list only
    }

    function delete(event,rc,prc){
        // do delete here.
    }
}

Allowed Methods Annotation

You can tag your event actions with a allowedMethods annotation and add a list of the allowed HTTP verbs as well. This gives you a nice directed ability right at the function level instead of a property. It is also useful when leveraging DocBox documentation as it will show up in the API Docs that are generated.

function index( event, rc, prc) allowedMethods="GET,POST"{
    // my code here
}

The framework also offers you the capability to bind incoming FORM/URL/REMOTE/XML/JSON/Structure data into your model objects by convention. This is done via WireBox's object population capabilities. The easiest approach is to use our populateModel() function which will populate the object from many incoming sources:

• request collection RC

• Structure

• json

• xml

• query

This will try to match incoming variable names to setters or properties in your domain objects and then populate them for you. It can even do ORM entities with ALL of their respective relationships. Here is a snapshot of the method:

/**
* Populate a model object from the request Collection or a passed in memento structure
* @model The name of the model to get and populate or the acutal model object. If you already have an instance of a model, then use the populateBean() method
* @scope Use scope injection instead of setters population. Ex: scope=variables.instance.
* @trustedSetter If set to true, the setter method will be called even if it does not exist in the object
* @include A list of keys to include in the population
* @exclude A list of keys to exclude in the population
* @ignoreEmpty Ignore empty values on populations, great for ORM population
* @nullEmptyInclude A list of keys to NULL when empty
* @nullEmptyExclude A list of keys to NOT NULL when empty
* @composeRelationships Automatically attempt to compose relationships from memento
* @memento A structure to populate the model, if not passed it defaults to the request collection
* @jsonstring If you pass a json string, we will populate your model with it
* @xml If you pass an xml string, we will populate your model with it
* @qry If you pass a query, we will populate your model with it
* @rowNumber The row of the qry parameter to populate your model with
*/
function populateModel(
	required model,
	scope="",
	boolean trustedSetter=false,
	include="",
	exclude="",
	boolean ignoreEmpty=false,
	nullEmptyInclude="",
	nullEmptyExclude="",
	boolean composeRelationships=false,
	struct memento=getRequestCollection(),
	string jsonstring,
	string xml,
	query qry
){

Let's do a quick example:

Person.cfc

component accessors="true"{

    property name="name";
    property name="email";

    function init(){
        setName('');
        setEmail('');
    }
}

editor.cfm

<cfoutput>
<h1>Funky Person Form</h1>
#html.startForm(action='person.save')#

    #html.textfield(label="Your Name:",name="name",wrapper="div")#
    #html.textfield(label="Your Email:",name="email",wrapper="div")#

    #html.submitButton(value="Save")#

#html.endForm()#
</cfoutput>

Event Handler -> person.cfc

component{

    function editor(event,rc,prc){
        event.setView("person/editor");        
    }

    function save(event,rc,prc){

        var person = populateModel( "Person" );

        writeDump( person );abort;
    }

}

In the dump you will see that the name and email properties have been bound.

Views (Default Layout)

The event object is the object that will let you set the views that you want to render, so please explore its API in the CFC Docs. To quickly set a view to render, do the following:

event.setView( 'view' );

The view name is the name of the template in the views directory without appending the .cfm. If the view is inside another directory, you would do this:

event.setView( 'mydirectory/myView' );

The views you set will use the default layout defined in your configuration file which by default is the layouts/Main.cfm

View With Custom Layouts

You can also use the setView(), setLayout() methods to tell the framework which view and layout combination to use:

function index( event, rc, prc ){
    // Inline
    event.setView( view="main/index", layout="2columns" );
    
    // Concatenated
    event.setView( "main/index" )
        .setLayout( "2columns" );
}

Views With No Layout

You can also tell the framework to set a view for rendering by itself with no layout using the noLayout argument

function index( event, rc, prc ){
    // Inline
    event.setView( view="widgets/users", nolayout=true );   
}

setView() Arguments

Here are the arguments for the setView() method:

* @view The name of the view to set. If a layout has been defined it will assign it, else if will assign the default layout. No extension please
* @args An optional set of arguments that will be available when the view is rendered
* @layout You can override the rendering layout of this setView() call if you want to. Else it defaults to implicit resolution or another override.
* @module The explicit module view
* @noLayout Boolean flag, wether the view sent in will be using a layout or not. Default is false. Uses a pre set layout or the default layout.
* @cache True if you want to cache the rendered view.
* @cacheTimeout The cache timeout in minutes
* @cacheLastAccessTimeout The last access timeout in minutes
* @cacheSuffix Add a cache suffix to the view cache entry. Great for multi-domain caching or i18n caching.
* @cacheProvider The cache provider you want to use for storing the rendered view. By default we use the 'template' cache provider
* @name This triggers a rendering region.  This will be the unique name in the request for specifying a rendering region, you can then render it by passing the unique name to renderView();

Cached Views

You can leverage the caching arguments in the setView() method in order to render and cache the output of the views once the framework renders it. These cached views will be stored in the template cache region, which you can retrieve or purge by talking to it: getCache( 'template' ).

// Cache in the template cache for the default amount of time
event.setView( view='myView', cache=true );
// Cache in the template cache for up to 60 minutes, or 20 minutes after the last time it's been used
event.setView( view='myView', cache=true, cacheTimeout=60, cacheLastAccessTimeout=20 );
// Cache a different version of the view for each language the site has
event.setView( view='myView', cache=true, cacheSuffix=prc.language );

View Arguments

Data can be passed from your handler to the view via rc or prc. If you want to pass data to a view without polluting rc and prc, you can pass it directly via the args parameter, much like a method call.

var viewData = {
  data1 = service.getData1(),
  data2 = service.getData2()
};

event.setView( view='myView', args=viewData );

Access the data in the view like so:

<cfoutput>
  Data 1: #args.data1#<br>
  Data 2: #args.data2#
</cfoutput>

No Rendering

If you don't want to, you don't have to. The framework gives you a method in the event object that you can use if this specific request should just terminate gracefully and not render anything at all. All you need to do is use the event object to call on the noRender() method and it will present to the user a lovely white page of death.

event.noRender();

We all need to deliver files to users at one point in time. ColdBox makes it easy to deliver any type of file even binary files via the Request Context's (event) sendFile() method.

function report( event, rc, prc ){
    var prc.reportFile = reportService.createReport();
    
    event
        .sendFile(
            file = prc.reportFile,
            name = "UserReport.xls",
            deleteFile = true
        )
        .noRender();
}

Method Signature

The API Docs can help you see the entire format of the method: https://apidocs.ortussolutions.com/coldbox/5.1.4/coldbox/system/web/context/RequestContext.html#sendFile()

The method signature is as follows:

/**
 * This method will send a file to the browser or requested HTTP protocol according to arguments.
 * CF11+ Compatibility
 *
 * @file The absolute path to the file or a binary file to send
 * @name The name to send to the browser via content disposition header.  If not provided then the name of the file or a UUID for a binary file will be used
 * @mimeType A valid mime type to use.  If not passed, then we will try to use one according to file type
 * @disposition The browser content disposition (attachment/inline) header
 * @abortAtEnd If true, then this method will do a hard abort, we do not recommend this, prefer the event.noRender() for a graceful abort.
 * @extension Only used for binary files which types are not determined.
 * @deleteFile Delete the file after it has been streamed to the user. Only used if file is not binary.
 */
function sendFile(
    file="",
    name="",
    mimeType="",
    disposition="attachment",
    boolean abortAtEnd="false",
    extension="",
    boolean deleteFile=false
)

Welcome to the world of ColdBox!

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

IDE Tools

ColdBox has the following supported IDE Tools:

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

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

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

CommandBox CLI

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

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

Download CommandBox

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

1. No Java Runtime (30mb)

2. Embedded Runtime (80mb)

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

Starting CommandBox

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

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

Installing ColdBox

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

mkdir myapp --cd
install coldbox

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

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

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

Scaffolding ColdBox Applications

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

• Advanced : A tag based advanced template

• AdvancedScript (default): A script based advanced template

• elixir : A ColdBox Elixir based template

• ElixirBower : A ColdBox Elixir + Bower based template

• ElixirVueJS : A ColdBox Elixir + Vue.js based template

• rest: A RESTFul services template

• rest-hmvc: A RESTFul service built with modules

• Simple : A traditional simple template

• SuperSimple : The bare-bones template

Uninstalling ColdBox

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

Updating ColdBox

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

Welcome to the world of ColdBox!

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

IDE Tools

ColdBox has the following supported IDE Tools:

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

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

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

CommandBox CLI

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

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

Download CommandBox

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

1. No Java Runtime (30mb)

2. Embedded Runtime (80mb)

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

Starting CommandBox

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

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

Installing ColdBox

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

mkdir myapp --cd
install coldbox

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

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

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

Uninstalling ColdBox

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

Updating ColdBox

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

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

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

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

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

• LogBoxConfig : A reference to a LogBox configuration object

Configuration Storage

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

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

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

Configuration Interceptor

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

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

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

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

• update coldbox

• update logbox

• update wirebox

• update cachebox

Major Updates

Performance

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

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

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

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

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

Better Bug Reports

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

• Show SQL error details on Adobe CF

• Current route, params and debug info

• Contributing module for the current routed URL

Merging of HTTP Verbs

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

ColdBox Core Release Notes

Bugs

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

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

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

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

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

New Features

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

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

Improvements

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

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

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

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

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

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