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

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

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

This 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 structure configures the interceptor service in your application.

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

throwOnInvalidStates

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

customInterceptionPoints

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

Info Please see the section for more information.

ColdBox is a conventions-based MVC framework for ColdFusion (CFML). It is fast, scalable, and runs on CFML engines such as Adobe ColdFusion and the open source CFML engine , for a completely free and open source development stack. ColdBox itself is Professional Open Source Software, backed by which provides support, training, architecture, consulting and commercial additions.

ColdBox was the first ColdFusion (CFML) framework to embrace Conventions Over Configuration and comes with a modular architecture to enhance developer and team productivity. It integrates seamlessly with CLI to provide you with REPL interfaces, package management, console development, testing, and automation.

Here’s a look at some of the core components of the ColdBox platform. Each of these come bundled with the framework, but are also available as separate stand-alone libraries that can be used in ANY ColdFusion application or framework:

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 less. After you complete this guide, we encourage you to move on to the and then to the other guides in this book.

You can find the source code of this quickstart here:

Requirements

Versioning Schema

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

And constructed with the following guidelines:

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

Hola amigo! I'm excited that you are interested in contributing to ColdBox, CacheBox, LogBox, and/or WireBox. Before submitting your contribution, please make sure to take a moment and read through the following guidelines:

Code Of Conduct

This project is open source, and as such, the maintainers give their free time to build and maintain the source code held within. They make the code freely available in the hope that it will be of use to other developers and/or businesses. Please be considerate towards maintainers when raising issues or presenting pull requests. We all follow the Golden Rule: Do to others as you want them to do to you.

The source code for this book is hosted on GitHub: . You can freely contribute to it and submit pull requests. The contents of this book are copyrighted by and cannot be altered or reproduced without the 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 -

In this area we will learn how to configure ColdBox programmatically via the config/ColdBox.cfc file. Most of the configurations in ColdBox are pre-set thanks to it's conventions over configuration approach. So the majority of settings are for fine-grained control, third-party modules and more.

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

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

binder

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

singletonReload

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

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

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

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

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.

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 impaired and thread consistency will also suffer. This is PURELY a development flag that you can use at your own risk.

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

Hint Please remember that the default layout is Main.cfm

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

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

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

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

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

ColdBox HMVC v8.x

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

• Much More

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

What is BoxLang?

BoxLang is a modern dynamic JVM language developed by the ColdBox team that can be deployed on multiple runtimes: operating system (Windows/Mac/*nix/Embedded), web server, lambda, iOS, android, web assembly, and more. BoxLang combines many features from different programming languages, including Java, CFML, Python, Ruby, Go, and PHP, to provide developers with a modern, functional and expressive syntax.

ColdBox has been designed to work in both BoxLang and CFML language engines. However, it is extremely optimized for BoxLang, since it is the same team that develops the language and the framework.

Read more about BoxLang here:

License

The ColdBox Platform is open source and licensed under the License.

• Copyright by Ortus Solutions, Corp

• ColdBox, CacheBox, WireBox, and LogBox are registered trademarks of Ortus Solutions, Corp.

Discussion & Help

The Ortus Community is how to get help for our entire platform and modules: .

You can also join our Slack Box Team at:

Reporting a Bug

We all make mistakes from time to time :) So why not let us know about it and help us out? We also love 😍 pull requests, so please star us and fork us at:

Jira Issue Tracking

Professional Open Source

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

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

Resources

• Official Site:

• Community:

• Video Training:

HONOR GOES TO GOD ABOVE ALL

Because of His grace, this project exists. If you don't like this, 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

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

• via .htaccess or configuration files (Free)

• ISAPI rewrite filter for IIS (Paid)

• native rewrite filter (Free)

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:

/views
  /general
    +home.cfm

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 pass localized arguments to the view() and layout() methods in order to encapsulate the rendering via the args struct argument. Much like how you make method calls with arguments. Inside of your layouts and views you will receive the same args struct reference as well.

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

Universal Form

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

New Form

Edit Form

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.

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:

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:

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.

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

QueryString Struct

The queryString argument can be a simple query string or a struct that represents the query variables to append.

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

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

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

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

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

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

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

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

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

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

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.

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.

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.

event.setLayout( name );
event.setView( view="", layout=name );

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

function home(event,rc,prc){

    if( event.valueExists('print') ){
        event.setLayout('layout.PDF');
    }

    // logic here

    // set view
    event.setView('general/home');

}

If you need the set layout to be rendered from a specific module then use the module argument from the setLayout() or renderLayout() methods:

component name="general"{

    function index(event,rc,prc){

        // call some model for data and put into the request collection
        prc.myQuery = getInstance('MyService').getData();
        // set the view for rendering
        event.setLayout( name="admin", module="contentbox" );

    }

}

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

You can easily build links with ColdBox by using two methods:

1. event.buildLink() - Build links to events or URL routes

2. event.route() - Build links to specifically

Here are the signatures

Edit Your View

Edit the views/virtual/hello.cfm page and wrap the content in a cfoutput and create a link to the main ColdBox event, which by convention, is main.index. You can use main.index or just main (Remember that index is the default action)

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:

Routing

We have been using routing by convention, but let's do named routes now to control the URL. Let's create a /home route that will execute the main.index event and update our view to change the building of the URL via route(). Let's open the config/Router.cfc

We use the route() method to register URL patterns and then tell the router what to execute if matched. This can be an event, but it can also be a view, an inline action, a relocation, and much more. Since we registered new URLs you need to reinit the app (?fwreinit=1). Now let's update the link in the hello view:

Try it out now!

The best way to get started with ColdBox is with our application templates that you can find here: coldbox-templates. We have a curated collection of starter templates to get you kicking the tires quickly. You will do so via the coldbox create app command in the CLI:

Here is a listing of the latest supported templates:

CommandBox Integration

The coldbox create app command has integration to our application templates via the skeleton argument. This can be the name of each of the templates in our repositories or you can use the following alternatives:

• A name of a ForgeBox entry: cbtemplate-advanced-script,cbtemplate-simple

• A Github shortcut: github-username/repo

• An HTTP/S URL to a zip file containing a template:

Option 1: Coldbox Config

This structure within config/Coldbox.cfc 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.

Option 2: Config Object Override

Starting in ColdBox 7, you can store module configurations as their own configuration file within the application’s config folder outside of the config/Coldbox.cfc. The naming convention is config/modules/{moduleName}.cfc

The configuration CFC will have one configure() method that is expected to return a struct of configuration settings as you did before in the moduleSettings

The following example overrides the original module configuration entirely:

For large module configs where only a few keys need to be changed, you can update the config by modifying the struct passed in as an argument and then returning the updated version.

Injections

Just like a ModuleConfig this configuration override also gets many injections:

• controller

• coldboxVersion

• appMapping

• moduleMapping

Env Support

This module configuration object will also inherit the ModuleConfig.cfc behavior that if you create methods with the same name as the environment you are on, it will execute it for you as well.

Then you can change the original struct as you see fit for that environment.

Alphanumeric Placeholders

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

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

Optional Placeholders

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

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.

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.

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.

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

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

Regular Expression Placeholders

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

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

Luis Fernando Majano Lainez

Luis Majano is a Computer Engineer, and published author that has been creating software since the year 2000. He was born in San Salvador, El Salvador in the late 70s, during a period of economical instability and civil war. He lived in El Salvador until 1995 and then moved to Miami, Florida where he studied and completed his Bachelor of Science in Computer Engineering at Florida International University.

He is the founder and CEO of Ortus Solutions, a consulting firm specializing in web development, ColdFusion (CFML), Java development, and all open-source professional services under the ColdBox, CommandBox, and ContentBox stack. He is the creator of ColdBox, ContentBox, WireBox, TestBox, LogBox, and anything “BOX”, and contributes to over 250 open-source projects. He has a passion for learning and mentoring developers so they can succeed with sustainable software practices and the usage and development of open-source software. You can read his blog at

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

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

• The Lord of the Rings and The Hobbit are his favorite books (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!)

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

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

Contributors

Jorge Emilio Reyes Bendeck

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

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

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

Brad Wood

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

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

Brad's CommandBox Snake high score is 141.

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.delegates.Env and access them off of that component. This is required when adding a datasource from environment variables.

Example:

Accessing System Settings in other files

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

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.

http://localhost/users
http://localhost/users.json
http://localhost/users.xml
http://localhost/users.pdf
http://localhost/users.html    

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:

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

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

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.

After calling relocate, further code will still be processed until you return from handler.

/**
* 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 Whether 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".

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.

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 Coldbox.cfc.

//Layout Settings
layoutSettings = {
    defaultLayout = "basic.cfm"
}

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.

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

The arguments received by these interceptors are:

• event : The request context reference

• action : The action name that was intercepted by postHandler()

• 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

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 which you can alter, append or remove from. Once you write these Interceptors you can either register them in your Configuration File or programmatically.

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

Sample Interceptor

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

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

Intro to MVC

"A developer often wishes to separate data (model) and user interface (view) concerns, so that changes to the user interface will not affect data handling, and that the data can be reorganized without changing the user interface. The model-view-controller solves this problem by decoupling data access and business logic from data presentation and user interaction, by introducing an intermediate component: the controller." ​

MVC is a popular design pattern called which seeks to promote good maintainable software design by separating your code into 3 main tiers:

Handler Scaffolding

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

This will generate the following files:

• A new handler called

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

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. Please remember to us in Github.

IDE Tools

ColdBox has the following supported IDE Tools:

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

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

• ColdboxSettings : Framework specific system settings

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 - Where configuration files are stored

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

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.

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. Here is a table of the automatic injection this object has:

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

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

RunRoute()

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.

You have a few arguments in the view() 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.

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

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.

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

There are several simple implicit (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, just for you and without all the complicated setup involved! If you declared them, the framework will execute them.

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.

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:

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

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

• Source:

• Documentation:

You can also wrap layouts within other layouts and get incredible reusability. This is accomplished by using the layout() 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 layout() method is extremely powerful as it can allow you to not only nest layouts but actually render a-la-carte layout/view combinations also.

You can also pass in the caching arguments below and your view will be rendered once and then cached for further renderings. Every ColdBox application has two active cache regions: default and template. All view and event caching renderings go into the template cache.

Purging Views

So now that our views are cached, how do I purge them programmatically? Well, you need to talk to the template cache provider and use the clearing methods:

Then we can perform several operations on views:

• clearView(string viewSnippet): Used to clear a view from the cache by using a snippet matched according to name + cache suffix.

• clearMultiView(any viewSnippets): Clear using a list or array of view snippets.

• clearAllViews([boolean async=true]) : Can clear ALL cached views in one shot and can be run asynchronously.