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

ColdBox Manual - v5.0.0

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

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

Versioning

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

<major>.<minor>.<patch>

And constructed with the following guidelines:

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

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

• Bug fixes and misc changes bumps the patch

License

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

• Copyright by Ortus Solutions, Corp

• ColdBox is a registered trademark by Ortus Solutions, Corp

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

Discussion & Help

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

Reporting a Bug

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

• By Email: [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 - v4.x.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

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

Requirements

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

• Grab a cup of coffee

• Get comfortable

This structure configures the interceptor service in your application.

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 section for more information.

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

Hint Please remember that the default layout is Main.cfm

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

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

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

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

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.

Introduction

CacheBox 2.0.0 is a major release, mostly aligned to support our ColdBox 4 release.

Release Notes

You can find the release version information here: https://ortussolutions.atlassian.net/browse/CACHEBOX/fixforversion/12303

Improvements

• [CACHEBOX-25] - Deprecate Cachebox xml config support

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

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

Reinitializing An Application

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

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

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

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

CommandBox>coldbox reinit

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

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

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

ConfigFile

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

ScopeRegistration

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

DefaultCache

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

Caches

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

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"
};

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

// flash scope configuration
flash = {
    // Available scopes are: session,client,cache,mock or your own class path
    scope = "session",
    // constructor properties for the flash scope implementation
    properties = {},
    // automatically inflate flash data into the RC scope at the beginning of a request
    inflateToRC = true, 
    // automatically inflate flash data into the PRC scope at the beginning of a request
    inflateToPRC = false, 
    // automatically purge flash data for you
    autoPurge = true, 
    // automatically save flash scopes at end of a request and on relocations.
    autoSave = true 
};

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.

//Register interceptors as an array, we need order
interceptors = [

    { 
        // The CFC instantiation path
        class="",
        // The alias to register in WireBox, if not defined it uses the name of the CFC
        name="",
        // A struct of data to configure the interceptor with.
        properties={}
    }

    { class="mypath.MyInterceptor",
      name="MyInterceptor",
      properties={useSetterInjection=false}
    },
    { class="coldbox.system.interceptors.SES", name="MySES" }
];

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

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"
             }
        };
    }
}

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:

server start --rewritesEnable

Some Resources

• Apache mod_rewrite via .htaccess or configuration files (Free)

• Helicon Tech ISAPI rewrite filter for IIS (Paid)

• IIS 7 native rewrite filter (Free)

• nginx native web server (free)

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

function group( struct options={}, body );

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

route( pattern="/news", target="public.news.index" );
route( pattern="/news/recent", target="public.news.recent" );
route( pattern="/news/removed", target="public.news.removed" );
route( pattern="/news/add/:title", target="public.news.add" );
route( pattern="/news/delete/:slug", target="public.news.remove" );
route( pattern="/news/v/:slug", target="public.news.view" );

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.

group( { pattern="/news", target="public.news." }, function(){
	route( "/", "index" )
	.route( "/recent", "recent" )
	.route( "/removed", "removed" )
	.route( "/add/:title", "add" )
	.route( "/delete/:slug", "remove" )
	.route( "/v/:slug", "view" );
} );

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

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

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

Introduction

LogBox 2.0.0 is a major release, mostly aligned to support our ColdBox 4 release.

Release Notes

You can find the release version information here:

Bug

• [] - Truncating of category data to avoid error on insertion on DB Appender

Improvement

• [] - deprecate logbox xml support

New Feature

• [] - Ability to asynchronize any logger via new 'async' property

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.

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

Configuration Interceptor

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

The configuration CFC has embedded environment control and detection built-in. In this structure you will set up the application environments and their associated regular expressions for its cgi host names to match for you automatically. If the framework matches the regex with the associated cgi.http_host, it will set a setting called Environment in your configuration settings and look for that environment setting name in your CFC as a method by convention. That's right, it will check if your CFC has a method with the same name as the environment and if it exists, it will call it for you. Here is where you basically override, remove, or add any settings according to your environment.

Warning : The environment detection occurs AFTER the configure() method is called. Therefore, whatever settings or configurations you have on the configure() method will be stored first, treat those as Production settings.

In the above example, I declare a development key with a value list of regular expressions. If I am in a host that starts with cf2016, this will match and set the environment setting equal to development. It will then look for a development method in this CFC and execute it.

Custom Environment Detection

If you want your own detection algorithm instead of looking at the cgi.http_host variable, then fear not. You will NOT fill out an environments structure but actually create a method with the following signature:

This method will be executed for you at startup and it must return the name of the environment the application is on. It will then store it and execute the method if it exists.

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.

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.

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:

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.

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 , usually referred to as pretty URLs.

Event Syntax

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

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

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

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.

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 (event) sendFile() method.

Method Signature

The API Docs can help you see the entire format of the method:

The method signature is as follows:

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

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 the preHandler() action will fire ONLY!

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

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

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.

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.

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.

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:

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

New Form

Edit Form

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:

You can also wrap layouts within other layouts and get incredible reusability. This is accomplished by using the renderLayout() method in the Renderer. As always, refer to the CFC API for the latest method arguments and capabilities.

So if I wanted to wrap my basic layout in a PDF wrapper layout (pdf.cfm) I could do the following:

That's it! The renderLayout() method is extremely power as it can allow you to not only nest layouts but actually render a-la-carte layout/view combinations also.

Default Layout

The default layout in a ColdBox application is layouts/main.cfm by convention. You can change this by using the layoutSettings in your Configuration.cfc.

Default View

There is no default view in ColdBox, but you can configure one by using the same layoutSettings configuration directive and the defaultView directive:

This means that if no view is set in the request context, ColdBox will fallback to this view for rendering.

Ok, now that we have started to get funky, let's keep going. How can I change the layout on the fly for a specific view? Very easily, using yet another new method from the event object, called setLayout() or the layout argument to the setView() method.

This is great, so we can change the way views are rendered on the fly programmatically. We can switch the content to a PDF in an instant. So let's do that

A layout is simply an HTML file that acts as your shell where views can be rendered in and exists in the layouts folder of your application. The layouts can be composed of multiple views and one main view. The main view is the view that gets set in the request collection during a request via event.setView() usually in your handlers or interceptors.

You can have as many layouts as you need in your application and they are super easy to override or assign to different parts of your application. Imagine switching content from a normal HTML layout to a PDF or mobile layout with one line of code. How cool would that be? Well, it's that cool with ColdBox. Another big benefit of layouts, is that you can see the whole picture of the layout, not the usual cfmodule calls where tables are broken, or divs are left open as the module wraps itself around content. The layout is a complete html document and you basically describe where views will be rendered. Much easier to build and simpler to maintain.

Info Another important aspect of layouts is that they can also consume other layouts as well. So you can create nested layouts very easily via the renderLayout() method.

ColdBox 4.1.0 is a minor release that addresses several issues and introduces some enhancements. You can see below the release notes.

Release Notes

Bugs

• [COLDBOX-434] - Controller loc.args is referenced and not existing in pre{Actions}

• [COLDBOX-435] - Module routing was not respecting package resolving within handlers

• [COLDBOX-441] - onError handler doesn't work

• [COLDBOX-454] - abstractFlashScope getKeys() doesn't work

Improvements

• [COLDBOX-425] - Modules that include applicationhelpers are incompat with modules.autoReload setting, add recognition

• [COLDBOX-440] - Add x-forwarded-proto checks on isSSL() verifications to allow for proxy configuraitons

• [COLDBOX-444] - Better locking naming technique to avoid server-wide collisions

• [COLDBOX-455] - Ability to test ORM entities with base cases if loading ColdBox or using entity injection

New Features

• [COLDBOX-430] - Update application templates to use new logo

• [COLDBOX-448] - Add session and application timeouts to testing harnesses

• [COLDBOX-449] - Create a new testing annotation to control if application should be teardown in integration tests

• [COLDBOX-457] - Create REST application template for ColdBox

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

Layout Code

This location is identified by the following code:

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

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

Creating A Layout

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

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

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

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

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

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

Using The Layout

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

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

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

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

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.

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:

component {

    variables.util = new coldbox.system.core.util.Util();

    this.datasources[ "my_datasource" ] = {
        driver = util.getSystemSetting( "DB_DRIVER" ),
        host = util.getSystemSetting( "DB_HOST" ),
        port = util.getSystemSetting( "DB_PORT" ),
        database = util.getSystemSetting( "DB_DATABASE" ),
        username = util.getSystemSetting( "DB_USERNAME" ),
        password = util.getSystemSetting( "DB_PASSWORD" )
    };

}

Accessing System Settings in other files

If you need to access these configuration values in other components, consider adding the values to your ColdBox settings and injecting the values into your other components via dependecy injection.

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

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

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:

// Basic Routing
http://localhost/general -> event=general.index
http://localhost/general/index -> event=general.index

// If 'admin' is a package/folder in the handlers directory
http://localhost/admin/general/index -> event=admin.general.index 

// If 'admin' is a module
http://localhost/admin/general/index -> event=admin:general.index

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.

http://localhost/general/show/page/2/name/luis
# translate to
event=general.show, rc.page=2, rc.name=luis

http://localhost/users/show/export/pdf/name
# translate to
event=users.show, rc.export=pdf, rc.name={empty value}

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

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

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.

/**
* Relocate user browser requests to other events, URLs, or URIs.
*
* @event The name of the event to run, if not passed, then it will use the default event found in your configuration file
* @URL The full URL you would like to relocate to instead of an event: ex: URL='http://www.google.com'
* @URI The relative URI you would like to relocate to instead of an event: ex: URI='/mypath/awesome/here'
* @queryString The query string to append, if needed. If in SES mode it will be translated to convention name value pairs
* @persist What request collection keys to persist in flash ram
* @persistStruct A structure key-value pairs to persist in flash ram
* @addToken Wether to add the tokens or not. Default is false
* @ssl Whether to relocate in SSL or not
* @baseURL Use this baseURL instead of the index.cfm that is used by default. You can use this for ssl or any full base url you would like to use. Ex: https://mysite.com/index.cfm
* @postProcessExempt Do not fire the postProcess interceptors
* @statusCode The status code to use in the relocation
*/
void function relocate(
	event,
	URL,
	URI,
	queryString,
	persist,
	struct persistStruct,
	boolean addToken,
	boolean ssl,
	baseURL,
	boolean postProcessExempt,
	numeric statusCode
)

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

relocate( "home" );
relocate( event="shop", ssl=true );
relocate( event="user.view", queryString="id=#rc.id#" );
relocate( url="http://www.google.com" );
relocate( uri="/docs/index.html" )

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 API Docs for the latest arguments:

<cfoutput>
// render inline
#renderView( 'tags/metadata' )#

// render from a module
#renderView( view="security/user", module="security" )#

// render and cache
#renderView(
    view="tags/longRendering", 
    cache=true, 
    cacheTimeout=5, 
    cacheProvider="couchbase"
)#

// render a view from the handler action
function showData(event,rc,prc){
    // data here
    return renderView( "general/showData" );    
}

// render an email body content in an email template layout
body = renderlayout( layout='email',view='templates/email_generic' );
</cfoutput>

Model Rendering

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

property name="renderer" inject="provider:coldbox:renderer";

This will inject a provider 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:

function sendEmail(){
    
    // code here.
    var body = renderer.renderView( "templates/email" );

}

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:

component{

    function postViewRender(event,interceptData){
        interceptData.renderedView = trim( interceptData.renderedView );
    }
}

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

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

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

• The majority of code generation and running of examples are done via CommandBox: The ColdFusion (CFML) CLI, Package Manager, REPL - http://www.ortussolutions.com/products/commandbox

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

External Trademarks & Copyrights

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

Notice of Liability

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

Contributing

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

Charitable Proceeds

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

Shalom Children's Home

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

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

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

Luis Fernando Majano Lainez

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

He is the CEO of Ortus Solutions, a consulting firm specializing in web development, ColdFusion (CFML), Java development and all open source professional services under the ColdBox and ContentBox stack. He is the creator of ColdBox, ContentBox, WireBox, MockBox, LogBox and anything “BOX”, and contributes to many open source ColdFusion projects. He is also the Adobe ColdFusion user group manager for the Inland Empire. You can read his blog at www.luismajano.com

Luis has a passion for Jesus, tennis, golf, volleyball and anything electronic. Random Author Facts:

• He played volleyball in the Salvadorean National Team at the tender age of 17

• The Lord of the Rings and The Hobbit is something he reads every 5 years. (Geek!)

• His first ever computer was a Texas Instrument TI-86 that his parents gave him in 1986. After some time digesting his very first BASIC book, he had written his own tic-tac-toe game at the age of 9. (Extra geek!)

• He has a geek love for circuits, microcontrollers and overall embedded systems.

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

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

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

Contributors

Jorge Emilio Reyes Bendeck

Jorge is an Industrial and Systems Engineer born in El Salvador. After finishing his Bachelor studies at the Monterrey Institute of Technology and Higher Education ITESM, Mexico, he went back to his home country where he worked as the COO of Industrias Bendek S.A.. In 2012 he left El Salvador and moved to Switzerland in persuit 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 Cristian who loves to play the guitar, worship and rejoice in the Lord!

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

Brad Wood

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

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

Brad's CommandBox Snake high score is 141.

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

}

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.

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

// executes after any action
function postHandler( event, action, eventArguments, rc, prc ){
}

// executes after the list() action ONLY
function postList( event, action, eventArguments, rc, prc ){
}

// concrete examples
function postHandler( event, action, eventArguments, rc, prc ){
    log.info("Finalized executing #action#");
}

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

// only fire for the actions: save(), delete()
this.posthandler_only = "save,delete";
// DO NOT fire for the actions: login(), doLogin(), logout()
this.posthandler_except = "login,doLogin,logout"

Welcome to the world of ColdBox!

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

IDE Tools

ColdBox has the following supported IDE Tools:

• Sublime -

• VSCode -

• CFBuilder -

CommandBox CLI

The first step in our journey is to 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: 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:

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.

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

That's it. CommandBox can now track this version of ColdBox for you in this directory. In the 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.

ColdBox provides you with a nice method for generating links between events by leveraging an object called event that is accessible in all of your layouts/views and event handlers. This event object is called behind the scenes the request context object, which models the incoming request and even contains all of your incoming FORM and URL variables in a structure called rc.

Building Links

The method in the request context that builds links is called: buildLink(). Here are some of the arguments you can use:

Edit Your View

Edit the views/virtual/hello.cfm page and wrap the content in a cfoutput and create a link to the main ColdBox event, which by convention is main.index.

This code will generate a link to the main.index event in a search engine safe manner and in SSL detection mode. Go execute the event: http://localhost:{port}/virtual/hello and click on the generated URL, you will now be navigating to the default event /main/index. This technique will also apply to FORM submissions:

URL Structure & Mappings

ColdBox allows you to manipulate the incoming URL so you can create robust URL strategies especially for RESTFul services. This is all done by convention and you can configure it via the application router: config/Router.cfc for more granular control.

We have now seen how to execute events via nice URLs. Behind the scenes, ColdBox translates the URL into an executable event string just like if you were using a normal URL string:

• /main/index -> ?event=main.index

• /virtual/hello -> ?event=virtual.hello

• /admin/users/list -> ?event=admin.users.list

• /handler/action/name/value -> ?event=handler.action&name=value

• /handler/action/name -> ?event=handler.action&name=

By convention, any name-value pairs detected after an event variable will be treated as an incoming URL variables. If there is no pair, then the value will be an empty string.

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

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

Handler Code

Every action in ColdBox receives three arguments:

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

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

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

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

Executing Events

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

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

Working With Incoming Data

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

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

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

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

Out of the box, ColdBox gives you all the RESTFul capabilities you will need to create robust and scalable RESTFul services. Let's add some RESTFul capabilities to our contact listing we created in the previous section.

Producing JSON

If you know beforehand what type of format you will be responding with, you can leverage ColdBox 5's auto-marshalling in your handlers. By default, ColdBox detects any return value from handlers and if they are complex it will convert them to JSON automatically for you:

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

renderData()

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

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

We have added the following line:

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

Format Detection

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

Routing

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

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

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

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

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

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

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 and you will be able to visually see, test and debug all your routing needs.

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

Let's do a quick example:

Person.cfc

editor.cfm

Event Handler -> person.cfc

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

Apart from executing events from the URL/FORM or Remote interfaces, you can also execute events internally, either public or private from within your event handlers or from interceptors, other handlers, layouts or views.

RunEvent()

You do this by using the runEvent() method which is inherited from our FrameworkSuperType class. Here is the method signature:

The interesting aspect of internal executions is that all the same rules apply, so your handlers can return content like widgets, views, or even data. Also, the eventArguments enables you to pass arguments to the method just like method calls:

Executions

Declaration

Caching

As you can see from the function signature you can tell ColdBox to cache the result of the event call. All of the cached content will go into the template cache by default unless you use the cacheProvider argument. The cache keys are also based on the name of the event and the signature of the eventArguments structure. Meaning, the framework can cache multiple permutations of the same event call as long as the eventArguments are different.

ColdBox provides you with a very simple but flexible and powerful layout manager and content renderer. You no longer need to create module tags or convoluted broken up HTML anymore. You can concentrate on the big picture and create as many layouts as your application needs. Then you can programmatically change rendering schemas (or skinning) and also create composite or component based views.

In this section we will explore the different rendering mechanisms that ColdBox offers and also how to utilize them. As you know, are our controller layer in ColdBox and we will explore how these objects can interact with the user in order to render content, whether HTML, JSON, XML or any type of rendering data.

Conventions

Let's do a recap of our conventions for layouts and view locations:

ColdBox Renderer

It is imperative to know who does the rendering in ColdBox and that is the Renderer class that you can see from our diagram above. As you can tell from the diagram, it includes your layouts and/or views into itself in order to render out content. So by this association and inheritance all layouts and views have some variables and methods at their disposal since they get absorbed into the object. You can visit the to learn about all the Renderer methods. All of the following property members exist in all layouts and views rendered by the Renderer:

As you can see, all views and layouts have direct reference to the request collections so it makes it incredibly easy to get and put data into it. Also, remember that the Renderer inherits from the Framework SuperType so all methods are at your disposal if needed.

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.

Introduction

WireBox 2.0.0 is a major release of our Dependency Injection and AOP library with some major fixes and some cool new updates.

Release Notes

You can find the release version information here: https://ortussolutions.atlassian.net/browse/WIREBOX/fixforversion/12300

Bugs

• [WIREBOX-31] -Builder.buildDSLDependency does not use the custom DSL correctly as the default namespace kicks in

Improvements

• [WIREBOX-32] -binder.mapDirectory now skips hidden dirs

• [WIREBOX-35] -Remove coldbox:cacheManager DSL reference, it is no longer valid

New Features

• [WIREBOX-2] -allow mapDSL to be altered at runtime by modules via new wirebox method: registerDSL()

• [WIREBOX-30] -Support wiring new injection DSL = byType, which leverages the type to match to an implementation

• [WIREBOX-33] -Add a force argument to the map functions so you can override if a mapping already exists

• [WIREBOX-36] -New coldbox dsl to get a renderer reference: coldbox:renderer

Major Enhancements

• All LogBox libraries updated

• All CacheBox libraries updated

ColdBox DSL Updates

The ColdBox injection DSL has had major updates to get to the ColdBox 4 standards.

• All ocm injections have been removed in preference to

  cachebox injection DSL

• The coldbox:cachemanager DSL has been removed in preference to

  cachebox injection DSL

• All plugin injections have been deprecated in preference to

  model/object injections

• New coldbox:renderer dsl to inject the new ColdBox system

  renderer

Forced Mappings

The map() function on the Configuration Binder now has a force argument which allows you to map no matter if the mapping exists or not already.

map( alias="MyService", force=true )
    .to( "model.MyService" );

Dynamic Custom DSL Registration

Injectors allow you to register custom DSLs at runtime by using the registerDSL() method on any injector. This feature was mostly done for modules, so they could enhance WireBox in a ColdBox context. However, this also allows you to leverage this in any non-ColdBox applications.

// Register Custom DSL
controller.getWireBox()
    .registerDSL( namespace="javaloader", path="#moduleMapping#.model.JavaLoaderDSL" );

Injection By Type: byType DSL

We have expanded our custom DSL and injectors to allow you to do injection by ColdFusion types. This feature is more in-line with features from Java or static languages were you can tell injectors to inject by argument or property type. Let's say you have a package of interfaces with subpackages of implementations:

/app/pkg/ISomeObject.cfc // <- interface
/app/pkg/adb/SomeObject.cfc // <- component implementing the above interface.
/app/pkg/odb/SomeObject.cfc // <- component implementing the above interface.

You then want to rely on the interface type field of properties in my dependent CFCs and leveraging the byType injection DSL. You would first map the right implementation using the alias as the name of the Interface.

// mappings...
map( "app.pkg.ISomeObject" ).to( "app.pkg.adb.SomeObject" );

// Injection
component {

    /**
     * @inject byType
     */
    property app.pkg.ISomeObject object;

}

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

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

This will generate the following files:

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

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

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

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

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

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

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

Handler Code

Let's check out the handler code:

component{

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


}

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

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

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

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

Executing Events

Did you detect a convention here?

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

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

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

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

My First Virtual Event

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

coldbox create view name="virtual/hello"

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

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

Then go execute the virtual event:

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

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

Here are just a few of those rewrite rules for you for major rewrite engines. You can spice them up as needed.

.htaccess

RewriteEngine on
#if this call related to adminstrators or non rewrite folders, you can add more here.
RewriteCond %{REQUEST_URI} ^/(.*(CFIDE|cfide|CFFormGateway|jrunscripts|railo-context|lucee|mapping-tag|fckeditor)).*$
RewriteRule ^(.*)$ - [NC,L]

#Images, css, javascript and docs, add your own extensions if needed.
RewriteCond %{REQUEST_URI} \.(bmp|gif|jpe?g|png|css|js|txt|xls|ico|swf)$
RewriteRule ^(.*)$ - [NC,L]

#The ColdBox index.cfm/{path_info} rules.
RewriteRule ^$ index.cfm [QSA,NS]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.cfm%{REQUEST_URI} [QSA,L,NS]

nginx

################### LOCATION: ROOT #####################
location / {
     # First attempt to serve real files or directory, else it sends it to the @rewrite location for processing
     try_files $uri $uri/ @rewrite;
}

################### @REWRITE: COLDBOX SES RULES #####################
# Rewrite for ColdBox (only needed if you want SES urls with this framework)
# If you don't use SES urls you could do something like this
# location ~ \.(cfm|cfml|cfc)(.*)$ {
location @rewrite {
  rewrite ^/(.*)? /index.cfm/$request_uri last;
  rewrite ^ /index.cfm last;
}

################### CFM/CFC LUCEE HANDLER #####################
# The above locations will just redirect or try to serve cfml files
# We need this to tell NGinx that if we receive the following requests to pass them to Lucee
location ~ \.(cfm|cfml|cfc|jsp)(.*)$ {
# Include our connector
include lucee.conf;
}

IIS7 web.config

<configuration>
    <system.webServer>
        <rewrite>
            <rules>
               <rule name="Application Adminsitration" stopProcessing="true">
                    <match url="^(.*)$" />
                    <conditions logicalGrouping="MatchAll">
                        <add input="{SCRIPT_NAME}" pattern="^/(.*(CFIDE|cfide|CFFormGateway|jrunscripts|lucee|railo-context|fckeditor)).*$" ignoreCase="false" />
                    </conditions>
                    <action type="None" />
                </rule>
                <rule name="Flash and Flex Communication" stopProcessing="true">
                    <match url="^(.*)$" ignoreCase="false" />
                    <conditions logicalGrouping="MatchAll">
                        <add input="{SCRIPT_NAME}" pattern="^/(.*(flashservices|flex2gateway|flex-remoting)).*$" ignoreCase="false" />
                    </conditions>
                    <action type="Rewrite" url="index.cfm/{PATH_INFO}" appendQueryString="true" />
                </rule>
                <rule name="Static Files" stopProcessing="true">
                    <match url="^(.*)$" />
                    <conditions logicalGrouping="MatchAll">
                        <add input="{SCRIPT_NAME}" pattern="\.(bmp|gif|jpe?g|png|css|js|txt|pdf|doc|xls)$" ignoreCase="false" />
                    </conditions>
                    <action type="None" />
                </rule>
                <rule name="Insert index.cfm" stopProcessing="true">
                    <match url="^(.*)$" ignoreCase="false" />
                    <conditions logicalGrouping="MatchAll">
                        <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
                        <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
                    </conditions>
                    <action type="Rewrite" url="index.cfm/{PATH_INFO}" appendQueryString="true" />
                </rule>
            </rules>
        </rewrite>
    </system.webServer>
</configuration>

Tuckey Rewrite

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE urlrewrite PUBLIC "-//tuckey.org//DTD UrlRewrite 3.2//EN" "http://tuckey.org/res/dtds/urlrewrite3.2.dtd">
<urlrewrite>
    <rule>
        <note>ContentBox Media URLs</note>
        <condition type="request-uri" operator="equal">^/__media/.*$</condition>
        <from>^/(.*)$</from>
        <to type="passthrough">/index.cfm/$1</to>
    </rule>
    <rule>
        <note>Generic Front-Controller URLs</note>
        <condition type="request-uri" operator="notequal">/(index.cfm|robots.txt|osd.xml|flex2gateway|cfide|cfformgateway|railo-context|lucee|admin-context|modules/contentbox-dsncreator|modules/contentbox-installer|modules/contentbox|files|images|js|javascripts|css|styles|config).*</condition>
        <condition type="request-uri" operator="notequal">\.(bmp|gif|jpe?g|png|css|js|txt|xls|ico|swf|woff|ttf|otf)$</condition>
        <!-- For some reason this is not working now.
        <condition type="request-filename" operator="notdir"/>
        <condition type="request-filename" operator="notfile"/>
        -->
        <from>^/(.+)$</from>
        <to type="passthrough">/index.cfm/$1</to>
    </rule>
</urlrewrite>

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

• 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 accep 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})" 
} );

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

Every ColdBox application has a URL router and can be located by convention at config/Router.cfc. This is called the application router and it is based on the router core class: coldbox.system.web.routing.Router. Here is where you will configure router settings and define routes using our routing DSL.

Application Router - Router.cfc

// Inherits from Router and FrameworkSuperType
component{


    function configure(){
        // Turn on Full URL Rewrites, no index.cfm in the URL
        setFullRewrites( true );
        
        // Routing by Convention
        route( "/:handler/:action?" ).end();
        
    }
    
}

The application router is a simple CFC that virtually inherits from the core ColdBox Router class and is configured via the configure() method. It will be decorated with all the capabilties to work with any request much like any event handler or interceptor. In this router you will be doing 1 of 2 things:

1. Configuring the Router

2. Adding Routes via the Routing DSL

Generated Settings

Once the routing service loads your Router it will create two application settings for you:

• SESBaseURL : The multi-domain URL base URL of your application: http://localhost

• HTMLBaseURL : The same path as SESBaseURLbut without any index.cfm in it (Just in case you are using index.cfm rewrite). This is a setting used most likely by the HTML <base> tag.

Configuration Methods

You can use the following methods to fine tune the configuration and operation of the routing services:

function configure(){

    setFullRewrites( true );
    setExtensionDetection( true );
    setValidExtensions( "json,cfm,pdf" );

}

The next sections will discus how to register routes for your application.

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