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

Release Notes

Bugs

• [COLDBOX-429] - Bundling Modules w/ module excludes does not respect excludes

• [COLDBOX-453] - API docs have broken links

• [COLDBOX-462] - adobe CF incompatibillty on restful template response object

• [COLDBOX-463] - addAsset does not recognize urls that ends with say "app.js?123" as js, not css.

• [COLDBOX-467] - fix for tomcat 8 not removing repeating slashes on path info

• [COLDBOX-471] - HTML Helper's startForm() doesn't pick up if current request is HTTPS

• [COLDBOX-474] - doctype default switch case was on the wrong type, thanks to Hector Cruz

• [COLDBOX-475] - _counter does not increment in rendering query-based view collections

• [COLDBOX-485] - Bean Populator not working correctly when ORM entity inherits from other

• [COLDBOX-487] - Bean populator errors on null values in JSON string

• [COLDBOX-490] - syntax and wrong argument type matching on exception bean object

• [COLDBOX-497] - double forward slash generated in buildLink

• [COLDBOX-509] - SES interceptor has poor query string parsing, updated to new algorithm

New Features

• [COLDBOX-477] - Update testing docs for collaboration and update core for CommandBox development

• [COLDBOX-483] - Add a test browser by default to the test harness

• [COLDBOX-492] - Integration testing execute method has two new arguments: route,querystring to alow you to do SES route testing

• [COLDBOX-493] - Added a memento argument to the populateModel method to allow for overriding of what struct to populate with instead of the request collection

• [COLDBOX-494] - Added json,xml,query additions to the populateModel() method to allow for more populations from different types of data structures

• [COLDBOX-498] - Update build process for DocBox and travis integrations

• [COLDBOX-499] - Update and Cleanup of app templates

• [COLDBOX-500] - Allow for applications with no ColdBox.cfc config, full convention mode

• [COLDBOX-501] - new convenience method on testing request context to retrieve rendered content: getRenderedContent()

• [COLDBOX-506] - Refactor app templates to their own repositories

• [COLDBOX-507] - New context method: getHTMLBaseURL() to get a http protocol sensitive request context base url

Improvements

• [COLDBOX-191] - New setting directive viewCaching to turn view caching on/off

• [COLDBOX-246] - Autowire remote proxies, changed to manual instead of automatic due to ORM issues

• [COLDBOX-348] - Remove requirement to have at least one handler in your application for ColdBox to work.

• [COLDBOX-472] - Update the documentation URL in box.json

• [COLDBOX-486] - Support for german characters for slugify for HTML helper

• [COLDBOX-495] - Load internal system modules first rather than last in module hierarchy discovery

• [COLDBOX-496] - Error detail, message empty on CF10 CF11

• [COLDBOX-503] - Replace StringBuffer with StringBuilder for performance improvements on later JDKs

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

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: bugs@coldbox.org

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

Professional Open Source

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

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

• Security Hardening

• Code Reviews

• Much More

Resources

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

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

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

• Twitter: @coldbox

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

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

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

HONOR GOES TO GOD ABOVE ALL

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

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

ColdBox Manual - v5.0.0

Versioning

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

• 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

Reporting a Bug

Professional Open Source

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

• Security Hardening

• Code Reviews

Resources

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

The major compatibility issues will be covered as well as how to smoothly upgrade to this release from previous ColdBox versions. You can also check out the guide to give you a full overview of the changes.

ColdBox 3.x Compatibility Module

If you want to convert a larger ColdBox 3.x site over piece by piece, we have created a ColdBox Compat module you can install that will give you much of the 3.x functionality back including plugins, ColdBox OCM, UDFLibraryFile setting, and WireBox DSL namespaces. You quickly install this module using CommandBox with the following command:

For more information and a full list of features, visit the

ColdFusion 8 Support Dropped

ColdFusion 8 support has been dropped.

Application.cfc Bootstrap changed

The bootstrap CFC used by Application.cfc has been updated from coldbox.system.Coldbox to coldbox.system.Bootstrap. This is basically just a rename-- all other functionality is the same so a simple find/replace in your Application.cfc should fix it up. This is the first change you'll need to make and is mandatory.

Sample Application.cfc using inheritance

Async Loggers Dropped

The Asynchronous loggers in LogBox have been removed in preference to the new async property that can be used in any logger. The affected loggers are:

• AsyncDBAppender -> DBAppender

• AsyncFileAppender -> FileAppender

• AsyncRollingFileAppender -> RollingFileAppender

You can just declare each appender but add an async=true property to each when declaring:

Plugins Removed

ColdBox Plugins have graduated to become just models. The plugins convention has been removed and all references to plugin injection or DSL's are gone. You must now place all your plugins in your models directory and request them via getInstance() or getModel() calls.

Plugins are an old ColdBox convention but their baggage doesn't really serve a purpose now that we have modules for easy packaging of libraries and WireBox for easy creation of CFCs. Neither of those existed back when Plugins were birthed. It's time to say goodbye to the concept of plugins, but all their functionality will still be here, just with a slightly different (and more standardized) way of creating them.

Plugin Base Class

With the removal of plugins, coldbox.system.Plugin no longer exists. If you have custom-written plugins that used some of the convenience variables such as controller, logbox, or wirebox that came from this base class, you'll need to inject them using the appropriate injection DSL. If you were using any of the convenience methods such as getRequestContext() or getRequestCollection() should be delegated to the appropriate service or the ColdBox controller.

Any variables or methods related to instance.pluginName, instance.pluginVersion, etc serve no purpose now and can be removed from the code.

New Core Modules

Storages

• Session Storage Plugin

• Application Storage Plugin

• Client Storage Plugin

• Cluster Storage Plugin

• Cookie Storage Plugin

All of these plugins have been refactored into the cbstorages module.

Instead of using:

You will instead call

Note : The API for the actual storage CFCs is the same.

MessageBox

This module replaces the MessageBox plugin and registers the following mapping in WireBox: messagebox@cbmessagebox.

AntiSamy

This module replaces the AntiSamy plugin and registers the following mapping in WireBox: antisamy@cbantisamy.

MailServies

This module replaces the MailService plugin and registers the following mapping in WireBox: mailService@cbmailservices.

Validation

This module replaces the previously-inbuilt validation functionality of ColdBox and the validator Plugin. The ValidationManager is still available under this WireBox mapping: ValidationManager@cbvalidation. It also gives you the following methods in every handler, view, layout, etc:

• validateModel()

• getValidationManager()

ColdBox Debugger

If you want to use the ColdBox debugger, you'll need to install the cbdebugger module. Another benifit of this is you can omit this module in production so there's no security concerns with it getting turned on. To install as a development dependency in CommandBox, use the --saveDev flag.

Debugger settings can still be set in the main ColdBox.cfc config in a debugger struct. The DebuggerService and Timer are still available via the following WireBox mappings and can be retrieved via getInstance() or property injections.

• debuggerService@cbdebugger

• timer@cbdebugger

JavaLoader

This module replaces the JavaLoader plugin and registers the following mapping in WireBox: loader@cbjavaloader.

i18n

This module us a combination of both the ResourceBundle plugin and the i18n plugin rolled together now and represented by the following two WireBox mappings:

• i18n@cbi18n

• resourceService@cbi18n

This module also adds the following methods into your handlers, views, layouts, etc:

• getFWLocale()

• setFWLocale()

• getResource()

ORM

This module brings you all the ORM virtual services that are in ColdBox 3.x and replaces the ORMService Plugin, but note that the component paths have been updated. Instead of starting with coldbox.system they start with cborm.

Unfortunately, due to the way that ORM is loaded by ColdFusion, if you are using the ORM EventHandler or ActiveEntity or any ColdBox Proxies that require ORM, you must create an Application Mapping in the Application.cfc like this:

This module also comes with two new WireBox DSL namespaces for injecting entity services:

Commons

cbcommons has a collection of various utilities for you to use which is made up of what used to be the following plugins:

• JVMUtils Plugin

• Zip Plugin

• DateUtils Plugin

• QueryHelper Plugin

• FileUtils Plugin

• Utilities Plugin

This module makes the same functionality available via these registered WireBox mappings:

• JVMUtils@cbcommons

• Zip@cbcommons

• DateUtils@cbcommons

• QueryHelper@cbcommons

• FileUtils@cbcommons

ioc

The module replaces the ioc plugin and registers the following mapping in WireBox: factory@cbioc which abstracts any IoC engine with typical methods like getBean() and containsBean()

Feeds

The cbfeeds module replaces the old FeedGenerator Plugin and FeedReader Plugin by registering the following WireBox mappings for you to use:

• FeedReader@cbfeeds

• feedGenerator@cbfeeds

Soap

This module replaces the Webservices plugin and registers the following mapping in WireBox: webservices@cbsoap.

Security

This module replaces the Security interceptor. The interceptor still exists, but it is wrapped inside this module as cbsecurity.interceptors.Security and it is registered with the parent application as soon as the module is loaded so you don't need to register the interceptor manually anymore.

WireBox DSL Namespaces

Some of these were covered above, but for completeness, here is a comprehensive list of the WireBox DSL Namespaces that are removed.

Model Convention

The model convention has been renamed to models to be consistent with pluralization. So you must either rename your folder or use Custom Conventions in your Configuration CFC.

ColdBox OCM Dropped

The ColdBox OCM (Object Cache Manager) has been a thin facade to CacheBox ever since ColdBox 3.0 came out. We are now removing this terminology completely in favor of direct interaction with CacheBox. References to the getColdboxOCM() method have been removed. Instead, call getCache().

JSON Plugin Dropped

The JSON plugin is no longer used in ColdBox in favor of native CFML serialization. The old plugin is in ForgeBox and can easily be converted to a model or module for use in ColdBox 4 if you need it.

BeanFactory Plugin Dropped

This plugin has been a thin facade to WireBox ever since ColdBox 3.0 came out. We are now removing the plugin and you can inject WireBox directly to get object instances. Or better yet, use our injection DSLs to inject the object instance you want directly.

Autowire Interceptor Dropped

This interceptor hasn't actually done anything in a while since WireBox now autowires new objects automatically. Remove any references to coldbox.system.interceptors.Autowire from your config. There is no need to replace it with anything.

Logger Plugin Dropped

This plugin has been a this facade to LogBox ever since ColdBox 3.0 came out. We are now removing the plugin and you can inject LogBox or a specific Logger directly for your logging needs.

Renderer Plugin Dropped

The renderer still exists, but not in plugin form. It has become a core part of the framework. If you need access to the renderer, use the getRenderer() method in the controller or the coldbox:renderer WireBox DSL.

HTMLHelper Plugin Dropped

The functionality provided by the HTMLHelper plugin is still available in the core of ColdBox but now as a model. Access it by using the new WireBox mapping: HTMLHelper@coldbox. Views and layouts still have access to the HTMLHelper via the variable html like always. This has not changed.

XMLConverter Plugin Dropped

The functionality provided by the XMLConverter plugin is still available in the core of ColdBox but now as a model. Access it by using the new WireBox mapping: xmlConverter@coldbox.

Validator Plugin Dropped

Removed from core

Datasource Bean Dropped

The datasource bean has been droped in favor of flat structures. So instead of getting a bean representing a datasource structure, you just get the structure. So some old code like this:

Would become this:

Exception Bean moved to prc in the exceptionHandler

If you have configured a global exceptionHandler it used to receive the exception as rc.exceptionBean. Now it will be accessible via prc.exception.

afterAspectsLoad interception point removed

Most everything that was considered an "aspect" is now no longer part of the core. The afterAspectsLoad interception point has been removed. You can still use the afterConfigurationLoad interception point that will fire once the framework has loaded. If you need to work with models or settings that are registered via modules, this interception point is for you.

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:

Bugs

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

Improvements

• [] -binder.mapDirectory now skips hidden dirs

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

New Features

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

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

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

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

Major Enhancements

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.

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.

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:

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.

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

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

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

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

External Trademarks & Copyrights

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

Notice of Liability

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

Contributing

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

Charitable Proceeds

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

Shalom Children's Home

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

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

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

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

1. No Java Runtime (30mb)

2. Embedded Runtime (80mb)

Starting CommandBox

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

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

Installing ColdBox

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

Uninstalling ColdBox

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

Updating ColdBox

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

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

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.

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

Building Links

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

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

Edit Your View

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

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

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

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

URL Structure & Mappings

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

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

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

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

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

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

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

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

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

• Advanced : A tag based advanced template

• AdvancedScript (default): A script based advanced template

• elixir : A ColdBox Elixir based template

• ElixirBower : A ColdBox Elixir + Bower based template

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

• rest: A RESTFul services template

• rest-hmvc: A RESTFul service built with modules

• Simple : A traditional simple template

• SuperSimple : The bare-bones template

Scaffolding Our Application

So let's create our first app using the default template skeleton AdvancedScript:

coldbox create app MyApp

This will scaffold the application and also install ColdBox for you. The following folders/files are generated for you:

+coldbox // The ColdBox framework library (CommandBox Tracked)
+config // Configuration files
+handlers // Your handlers/controllers
+includes // static assets
+interceptors // global interceptors
+layouts // Your layouts
+models // Your Models
+modules // CommandBox Tracked Modules
+modules_app // Custom modules
+tests // Test harness
+views // Your Views
+Application.cfc // Bootstrap
+box.json // CommandBox package descriptor
+index.cfm // Front controller

Now let's start a server so we can see our application running:

server start --rewritesEnable

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

That's it, you have just created your first application. Hooray, onward!

File/Folder Conventions

ColdBox is a conventions based framework. The location of files and functions matter. Since we scaffolded our first application, let's write down in a table below with the different conventions that exist in ColdBox.

Re-initializing The Application

There will be times when you make configuration or code changes that are not reflected immediately in the application due to caching. You can tell the framework to _reinit _or restart the application for you via the URL by leveraging the special URL variable fwreinit.

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

You can also use CommandBox to reinit the application:

coldbox reinit

Luis Fernando Majano Lainez

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

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

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

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

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

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

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

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

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

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

Contributors

Jorge Emilio Reyes Bendeck

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

Introduction

ColdBox 4 is a major release in our ColdBox Platform series and includes a new revamped MVC core and all extra functionality has been refactored into modules. We have pushed the modular architecture to a 1st class citizen even in the core itself. There are several compatibility updates that you must do in order to upgrade your ColdBox 3.X applications to ColdBox 4 standards. You will notice that the source and download of ColdBox 4 has been reduced by almost 75% in size. This is now due to our modular approach where functionality can just be brought in dynamically. How you might say?

CommandBox

CommandBox, our new ColdFusion (CFML) command line interface, package manager and REPL. You can now use CommandBox to install dependencies, modules and even ColdBox itself, all from our centralized code repository: ForgeBox. To install ColdBox 4 Bleeding Edge you can just type:

box install coldbox-be

You can even use CommandBox to generate ColdBox applications, modules, handlers, etc. It has a plethora of commands to get you started on a fantastic ColdBox Adventure:

// Get help on all the ColdBox commands
coldbox help

// create a ColdBox app with TestBox support
coldbox create app MyFirstApp --installTestBox

Internal Library Updates

ColdBox is composed of three internal libraries: WireBox (DI & AOP), CacheBox (Caching) and LogBox (Logging). Below you can find what's new with this release for each library:

• WireBox 2.0.0

• CacheBox 2.0.0

• LogBox 2.0.0

Major Updates

Performance Updates

The core has been completely revamped by removing ColdFusion 7/8 code, decoupled from many features that are now available as modules and rewrites to pure cfscript syntax. The end result is the fastest ColdBox release since our 1.0.0 days. In our initial vanilla load tests, normal requests take around 4-6ms to execute.

RunEvent Caching

The runEvent method has been extended to include caching capabilities very similar to what has previously been available to the renderView methods. This will allow folks to execute internal or widget-like events and be able to use the built-in caching capabilities of ColdBox to cache the results according to the arguments used. Below is the new signature of the method:

/**
* Executes events with full life-cycle methods and returns the event results if any were returned.
* @event The event string to execute, if nothing is passed we will execute the application's default event.
* @prePostExempt If true, pre/post handlers will not be fired. Defaults to false
* @private Execute a private event if set, else defaults to public events
* @defaultEvent The flag that let's this service know if it is the default event running or not. USED BY THE FRAMEWORK ONLY
* @eventArguments A collection of arguments to passthrough to the calling event handler method
* @cache.hint Cached the output of the runnable execution, defaults to false. A unique key will be created according to event string + arguments.
* @cacheTimeout.hint The time in minutes to cache the results
* @cacheLastAccessTimeout.hint The time in minutes the results will be removed from cache if idle or requested
* @cacheSuffix.hint The suffix to add into the cache entry for this event rendering
* @cacheProvider.hint The provider to cache this event rendering in, defaults to 'template'
*/
function runEvent(
    event="",
    boolean prePostExempt=false,
    boolean private=false,
    boolean defaultEvent=false,
    struct eventArguments={},
    boolean cache=false,
    cacheTimeout="",
    cacheLastAccessTimeout="",
    cacheSuffix="",
    cacheProvider="template"
){

Please note that the default cache provider used for event caching is the template cache, so it must be a valid ColdBox Enabled Cache Provider. So if we execute our sample widget below, we will be able to leverage its caching arguments:

<!--- Render with default cache timeouts --->
#runEvent( event="widgets.users", cache=true )#

<!--- Render with specific cache args --->
#runEvent( event="widgets.users", cache=true, cacheTimeout=60 )#

<!--- Render with specific event args --->
#runEvent( event="widgets.users", eventArguments={ filter:true }, cache=true, cacheTimeout=60 )#

Info : Internally ColdBox creates an internal hash of the passed in event and eventArguments arguments for the cache key. It also leverages the template cache for event caching.

Model called Models

The convention has been updated so it matches the other conventions. You now must create a models folder instead of a model folder.

onInvalidHTTPMethod Handler Convention

We have created a new action convention in all your handlers called onInvalidHTTPMethod which will be called for you if a request is trying to execute an action in your handler without the right HTTP Verb. It will then be your job to determine what to do next:

function onInvalidHTTPMethod( faultAction, event, rc, prc ){
    return "Yep, onInvalidHTTPMethod works!";
}

HTTP Content Auto Marshalling

The getHTTPContent method on the Request Context now takes in two boolean arguments:

1. json

2. xml

If set, ColdBox will auto-marshall the HTTP Body content from JSON or XML to native ColdFusion data types.

myStruct  = event.getHTTPContent( json=true );
xmlObject = event.getHTTPContent( xml=true );

SES regex route placeholders

You can now define a-la-carte regex matching on route placeholders. If the route matches with that regex in the placeholder the value will now be stored in the RC as well:

addRoute( pattern = 'format/:extension-regex:(xml|json)' );

New Global View Helper

You now have a new ColdBox core setting viewsHelper which is a template that will be injected and binded to any layout/view that is rendered. This means that finally you have a template that can be globally available to any view/layout in your system.

coldbox = {
    viewsHelper = "includes/helpers/ViewHelper.cfm"
};

Application Template Java Support

All the new ColdBox application templates have been updated to include a folder called lib which is automatically wired for you to class load Java classes and jars. All you have to do is drop any jar or class file into this folder and it will be available via createobject(“java”) anywhere in your app.

New Core Modules

All internal plugins, and lots of functionality, have been refactored out of the ColdBox Core and into standalone Modules. All of them are in ForgeBox and have their own Git repositories. Also, all of them are installable via CommandBox; Our ColdFusion (CFML) CLI and Package Manager. This has reduced the ColdBox Core by over 75% in source size and complexity. Not only that, but it allows us to be able to release patches and updates for feature functionality without releasing an entire framework release, but just 1 or more modules.

• ColdBox Debugger

box install cbdebugger

• Storages

box install cbstorages

• Feeds

box install cbfeeds

• Commons

box install cbcommons

• i18n

box install cbi18n

• ORM

box install cborm

• ioc

box install cbioc

• JavaLoader

box install cbjavaloader

• AntiSamy

box install cbantisamy

• MailServies

box install cbmailservices

• MessageBox

box install cbmessagebox

• Soap

box install cbsoap

• Security

box install cbsecurity

• Validation

box install cbvalidation

New Anti-Forgery Module

We have created a nice anti-forgery module called csrf which can be found in ForgeBox and in GitHub: https://github.com/ColdBox/cbox-csrf. This module will enhance your ColdBox applications with Anti-Cross Site Request Forgery capabilities. You can also install it via CommandBox

box install csrf

ORM Module Updates

As you know by now, all the ColdBox ORM features are available as a module that can be installed in your application via CommandBox or downloaded separately. We have done several updates to the ORM extensions like:

• Lucee multi-datasource support

• Expanded createAlias() method to allow for a criteria argument

  which leverages hibernate's ability to do a where statement on a

  join

• Script updates

New System Renderer

The ColdBox Renderer plugin has been removed and it is now part of the core as the system renderer (coldbox.system.web.Renderer).

• It has been migrated to full script and optimized for ColdFusion 9+

  syntax

• We have also created a new DSL to inject it via WireBox: coldbox:renderer

• You can also add mixins or alter its behavior by talking to its

  WireBox mapping (Renderer@coldbox)

• All handlers/interceptors/views/layouts have access to the renderer

  by calling the getRenderer() method in the super type

• The main ColdBox controller has a new method called getRenderer() to retrieve the system renderer

New Error Template

By default, we are now not showing any exceptions in the ColdBox default error template for security and encapsulation. You now have to specify the full exception bug template if you would like to see the exceptions via the CustomErrorTemplate setting:

coldbox = {
    customErrorTemplate = "/coldbox/system/includes/BugReport.cfm"
};

This is to be secure by default. The default template used is /coldbox/system/includes/BugReport-Public.cfm

Remote Proxies Autowired

You've always been able to get models in a remote proxy (web-accessible CFC that extends coldbox.system.remote.ColdBoxProxy) using the getModel() method. Now you can also autowire your remote proxies using cfproperties just like you do in handlers and WireBox-managed models.

/remote/myProxy.cfc

component extends="coldbox.system.remote.ColdBoxProxy" {
    property name='myService' inject='myService';

    remote function doRemote() {
        variables.myService.doSomething();
    }
}

Note The autowiring only works for web-accessible remote proxies being directly invoked. You can extend the ColdBoxProxy by another manually-created CFC (such as an ORM eventHandler) but it won't be autowired.

Handlers Are Now Singletons

In pre-4.0.0 applications, all event handlers were cached in CacheBox with specific timeouts. We have found that this just created extra noise and complexity for handler CFCs. So now all event handlers will be cached as singletons by default (unless specified in the ColdBox.cfc).

Bootstrap Enhancement

The ColdBox application bootstrapper, the one used in Application.cfc has been completely updated and renamed to Bootstrap instead of Coldbox. This brings in lots of performance enhancements and faster startup times to your applications. Just use the included application templates or just update the Coldbox reference to Bootstrap.

// Inheritance
component extends="coldbox.system.Bootstrap"{

}

// Non-Inheritance
component{
    public boolean function onApplicationStart(){
        application.cbBootstrap = new coldbox.system.Bootstrap( COLDBOX_CONFIG_FILE, COLDBOX_APP_ROOT_PATH, COLDBOX_APP_KEY, COLDBOX_APP_MAPPING );
        application.cbBootstrap.loadColdbox();
        return true;
    }
}

Module Enhancements

There has been tremendous focus on modules in this release as we have moved completely to a modular architecture in the core as well. First of all, we have moved almost 75% of the source into modules so they can be installed a-la-carte by developers. Here are some major updates:

• New getModuleSettings() & getModuleConfig() super type methods.

  This allows you to get access to any module setting or configuration

  property rather easily and directly.

• All module properties are NOT required anymore except the name.

• Modules no longer register their models folder as scan locations

  to increase performance.

• try/catch around module unloads, so if a module throws an exception

  during unload it will be intercepted, unloaded and then throw an

  exception. This way it will allow developers to fix the unloading

  issues instead of basically restarting the entire CFML engine to

  make it work.

Module Inception

We have altered the module services to now allow you to nest modules within modules up to the Nth degree. Our final move to hierarchical MVC is complete. Now you can package a module with other modules that can even contain other modules within. It really opens a great opportunity for better packaging, delivery and a further break from monolithic applications. To use, just create a modules folder in your module and drop the modules there as well.

Module Config New Properties

The ''ModuleConfig.cfc'' has been updated with several new properties:

this.autoMapModels = true;
this.modelNamespace = "store";
this.aliases = [ "store", "ecommerce", "shop" ];
this.cfmapping = "cbstore";
this.dependencies = [ "JavaLoader", "CFCouchbase" ];

Module Dependencies

Modules can now declare other module dependencies. This means that before the declared module is activated, the dependencies will be registered and activated FIRST and then the declared module will load.

Module Aliases

In pre-4.0.0 ColdBox applications, the way that you executed module handlers was via its registered module name, which had to be the name of the module folder on disk. This was ok to a certain point, but it would cause issues as it was very restrictive to the name on disk. On ColdBox 4 you can now give the module different execution aliases so you can execute the handler events via the aliases and the module folder name as well.

Module CF Mappings

Every module can now tell ColdBox what ColdFusion mapping to register for it that points to the module root location on disk when deployed. This is a huge feature for portability and the ability to influence the ColdFusion mappings for you via ColdBox.

Module Models Auto Mapped

The entire models folder will now be automatically mapped for you in WireBox via the mapDirectory call with a namespace attached to the objects (the name of the module). This way, all models are automatically mapped for you so you can just use them. Let's say you have a module called store:

property name="orderService" inject="OrderService@store";

As you can see it adds a @moduleName to discover models that come from a module directly.

Hint You can alter this behavior by setting the this.autoMapModels configuration setting to false. You can also alter the namespace used via the this.modelNamespace configuration property.

Module Bundles

You can now bundle your modules into an organizational folder that has the convention name of {name}-bundle. This is mostly for organizational purposes.

coldbox-bundle
  * cbstorages
  * cborm
  * cbsecurity

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.

Let's complete our saga into MVC by developing the M, which stands for . This layer is all your business logic, queries, external dependencies, etc. of your application, which represents the problem to solve or the domain to solve.

WireBox

Creating A Service Model

Let's create a simple contact listing, so open up CommandBox and issue the following command:

This will create a models/ContactService.cfc with a getAll() method and a companion unit test at tests/specs/unit/ContactServiceTest.cfc. Let's open the model object:

Add Some Data

Let's mock an array of contacts so we can display them later. We can move this to a SQL call later.

Wiring Up The Model To a Handler

We have now created our model so let's tell our event handler about it. Let's create a new handler using CommandBox:

This will create the handler/contacts.cfc handler with an index() action, the views/contacts/index.cfm view and the accompanying integration test tests/specs/integration/contactsTest.cfc.

Let's open the handler and add a new ColdFusion property that will have a reference to our model object.

Please note that inject annotation on the property definition. This tells WireBox what model to inject into the handler's variablesscope.

By convention it looks in the models folder for the value, which in our case is ContactService. Now let's call it and place some data in the private request collection prc so our views can use it.

Presenting The Data

Now that we have put the array of contacts into the prc struct as aContacts, let's display it to the screen using ColdBox's HTML Helper.

The ColdBox HTML Helper is a companion class that exists in all layouts and views that allows you to generate semantic HTML5 without the needed verbosity of nesting, or binding to ORM/Business objects.

Open the contacts/index.cfm and add the following to the view:

That's it! Execute the event: http://localhost:{port}/contacts/index and view the nice table of contacts being presented to you.

Congratulations, you have made a complete MVC circle!

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

Directory/File Conventions

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

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

• handlers - This holds the app's controllers

• layouts - Your HTML layouts

• models - This holds your app's CFCs

• modules - This holds the CommandBox tracked modules

• modules_app - This holds your app's modules

• views - Your HTML views will go here

Execution Conventions

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

Layout Code

This location is identified by the following code:

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

Creating A Layout

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

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

Using The Layout

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

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

The ColdBox HMVC Platform is the de-facto enterprise-level HMVC framework for CFML developers. It's professionally backed, highly extensible, and productive. Getting started with ColdBox is quick and painless. The only thing you need to begin is , a command line tool for CFML developers.

This is a one-page introductory guide to ColdBox. If you are new to MVC or ColdBox, you can also leverage our as well.

IDE Tools

ColdBox has the following supported IDE Tools:

• Sublime -

• VSCode -

• CFBuilder -

Install CommandBox

You can read through our one-page . Or simply grab the CommandBox executable from the and double click it to run.

You should now be seeing a prompt that looks like this:

Create A New Site

Now we're cooking with gas! Let's create a new ColdBox application. CommandBox comes with built-in commands for scaffolding out new sites as well as installing ColdBox and other libraries. We'll start by changing into an empty directory were we want our new app to live. If necessary, you can create a new folder.

Now let's ask CommandBox to create a new ColdBox app for us.

File/Folder Conventions

This command will place several new folders and files in your working directory. Let's run the ls command to view them.

Here's a rundown of the important bits.

• coldbox - This is the ColdBox framework managed by CommandBox

• config/Coldbox.cfc - Your application configuration object

• config/Router.cfc - Your application URL Router

• handlers - Your controller layer, which in ColdBox they are called event handlers

• layouts - Your HTML layouts

• models - This holds your model CFCs

• modules - This holds the CommandBox tracked modules

• modules_app - This holds your app's modules

• views - Your HTML views will go here

Start It Up

Now that our shiny new MVC app is ready to go, let's fire it up using the embedded server built into CommandBox. You don't need any other software installed on your PC for this to work. CommandBox has it all!

In a few seconds, a browser window will appear with your running application. This is a full server with access to the web administrator where you can add data sources, mappings, or adjust the server settings. Notice the handy icon added to your system tray as well. The --rewritesEnable flag will turn on some basic URL rewriting so we have nice, pretty URLs.

Take A Look Around

ColdBox uses easy conventions to define the controllers and views in your app. Let's open up our main app controller in your default editor to have a looksie.

At the top, you'll see a function named "index". This represents the default action that runs for this controller, which in ColdBox land they are referred to as event handlers.

Now let's take a look in the main/index view. It's located int he views folder.

This line of code near the top of the view is what outputs the prc.welcomeMessage variable we set in the controller.

Try changing the value being set in the handler and refresh your browser to see the change.

Building On

Let's define a new event handler now. Your controllers act as event handlers to respond to requests, REST API, or remote proxies.

Pull up CommandBox again and run this command.

That's it! You don't need to add any special configuration to declare your handler. Now we have a new handler called helloWorld with actions index, add, edit, and list. The command also created a test case for our handler as well as stubbed-out views for each of the actions.

Now, let's re-initialize the framework to pick up our new handler by typing ?fwreinit=1 at the end of the URL.

Let's hit this new controller we created with a URL like so. Your port number will probably be different.

127.0.0.1:43272/helloWorld

Install Packages

Here's some useful examples:

• BCrypt -- Industry-standard password hashing

• cbdebugger -- For debugging Coldbox apps

• cbjavaloader - For interacting with Java classes and libraries

• cbMarkdown - For writing in markdown

• cbMessagebox -- Display nice error/success messages

• cborm -- Awesome ORM Services

• cb18n -- For multilingual sites

• cbt - ColdBox templating language

• cbValidation - Back-end validation framework

• qb - Fluent query builder and schema builder

• route-visualizer - For visualizing your application routes

Install cbmessagebox from the CommandBox prompt like this:

We can see the full list of packages by using the list command.

Right now we can see that our app depends on coldbox and cbmessagebox to run. We'll use our new cbmessagebox module in a few minutes. But first, we'll create a simple Model CFC to round out our MVC app.

Creating A Model

Models encapsulate the business logic your application. They can be services, beans, or DAOs. We'll use CommandBox to create a GreeterService in our new app with a sayHello method.

Let's finish implementing the sayHello() method by adding this return statement and save the file.

We can also add the word singleton to the component declaration. This will tell WireBox to only create one instance of our service.

Tie It All Together

Ok, let's open up that helloWorld handler we created a while back. Remember, you can hit tab while typing to auto-complete your file names.

We'll inject our greeterService and the cbmessagebox service into the handler by adding these properties to the top of /handlers/helloWorld.cfc.

This will put the instance of our services in the variables scope where we can access it in our action methods.

And now in our index method, we'll set the output of our service into an info message.

One final piece. Open up the default layout located in layouts/Main.cfm and find the #renderView()#. Add this line right before it to render out the message box that we set in our handler.

Now hit your helloWorld handler one final time with ?fwreinit=1 in the URL to see it all in action! (Again, your port number will most likely be different.

127.0.0.1:43272/helloWorld?fwreinit=1

What's Next?

Congratulations! In a matter of minutes, you have created a full MVC application. You installed a community module from ForgeBox, created a new handler/view and tied in business logic from a service model.

As easy as that was, you're just scratching the surface of what ColdBox can do for you. Continue reading this book to learn more about:

• Environment-specific configuration

• Easy SES URL routing

• Tons of 3rd party modules

• Drop-in security system

• Sweet REST web service support

Getting Help

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

The basic configuration object has 1 method for application configuration called configure() where you will place all your configuration directives and settings:

Directives

Inside of this configuration method you will place several core and third-party configuration structures that can alter your application settings and behavior. Below are the core directives you can define:

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

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

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

Reinitializing An Application

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

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

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

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

1. No Java Runtime (30mb)

2. Embedded Runtime (80mb)

Starting CommandBox

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

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

Installing ColdBox

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

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

Scaffolding ColdBox Applications

• Advanced : A tag based advanced template

• AdvancedScript (default): A script based advanced template

• elixir : A ColdBox Elixir based template

• ElixirBower : A ColdBox Elixir + Bower based template

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

• rest: A RESTFul services template

• rest-hmvc: A RESTFul service built with modules

• Simple : A traditional simple template

• SuperSimple : The bare-bones template

Uninstalling ColdBox

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

Updating ColdBox

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

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

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

ConfigFile

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

ScopeRegistration

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

DefaultCache

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

Caches

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

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.

environments = {
    // The key is the name of the environment
    // The value is a list of regex to match against cgi.http_host
    development = "^cf2016.,^lucee.,localhost",
    staging = "^stg"
};

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.

/**
* Executed whenever the development environment is detected
*/
function development(){
    // Override coldbox directives
    coldbox.handlerCaching = false;
    coldbox.eventCaching = false;
    coldbox.debugPassword = "";
    coldbox.reinitPassword = "";

    // Add dev only interceptors
    arrayAppend( interceptors, {class="#appMapping#.interceptors.CustomLogger} );
}

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:

string public detectEnvironment(){
}

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.

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

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

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

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

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