My First ColdBox Application

The coldbox create app command enables you to create application skeletons using one of our official skeletons or your own. Here are the names of the common ones you can find in our Github Organization:

• Default: The default app template

• Elixir : A ColdBox Elixir based template to do asset compilation for you

• Rest: A RESTFul services template

• Rest-hmvc: A RESTFul service built with modules

• SuperSimple : The bare-bones template

• Vite: The default template using VITE for asset bundling

You can find all our template skeletons here: github.com/coldbox-templates

IntroductionColdBox Elixir

ColdBox Elixir Docs

Scaffolding Our Application

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

coldbox create app Quickstart

File/Folder Conventions

Here are some of the major files and directory conventions you should know about:

Directory	Convention	Mandatory	Description
.vscode			Mappings and build tasks for VSCode
build			Docker helpers
coldbox			The framework library
config			Configurations and module configurations
handlers			Event handler controllers
includes			i18n, JavaScript, helpers, CSS
interceptors			Event driven listeners go here
layouts			Application CFML layouts
lib			Java libraries or third party libraries
models			Model objects
modules			CommandBox driven dependencies
modules_app			Custom applicaiton modules
tests			Your application specs
views			Application CFML views

Here are the major files you should know about:

File	Convention	Mandatory	Description
.cfconfig.json			Loads the CFML Engine settings
.cfformat.json			Formatting rules
.cflintrc			Linting rules
.env			Environment variables (Never commit)
.env.example			Example env file
Application.cfc			Your application bootstrap
box.json			Your CommandBox package descriptor
index.cfm			Front placeholder file
server.json			CommandBox server control

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

server start

This will start up a Lucee 5 open-source CFML engine. If you would like an Adobe ColdFusion server then add to the command: cfengine=adobe@{version} where {version} can be: 2021,2018,2016.

Default Event

This command will start a server with URL rewrites enabled, open a web browser for you, and execute the index.cfm which in turn executes the default event by convention in a ColdBox application: main.index. This is now our first runtime convention!

Instead of executing pages like in a traditional application, we always execute the same page but distinguish the event we want via URL routing. When no mappings are present, we execute the default event by convention.

Tip: ColdBox Events map to handlers (cfc) and appropriate actions (functions)

Tip: The default event can also be changed in the configuration file: config/Coldbox.cfc

Hooray, we have scaffolded our first application, started a server, and executed the default event. Explore the application template generated, which contains useful information about your application.

Tip: Type coldbox create app help to get help on all the options for creating ColdBox applications.

Let's open the handler and see the code, so open handlers/main.cfc

component extends="coldbox.system.EventHandler" {

	/**
	 * Default Action
	 */
	function index( event, rc, prc ){
		prc.welcomeMessage = "Welcome to ColdBox!";
		event.setView( "main/index" );
	}

	/**
	 * Produce some restfulf data
	 */
	function data( event, rc, prc ){
		return [
			{ "id" : createUUID(), "name" : "Luis" },
			{ "id" : createUUID(), "name" : "Joe" },
			{ "id" : createUUID(), "name" : "Bob" },
			{ "id" : createUUID(), "name" : "Darth" }
		];
	}

	/**
	 * Relocation example
	 */
	function doSomething( event, rc, prc ){
		relocate( "main.index" );
	}

	/**
	 * --------------------------------------------------------------------------
	 * Implicit Actions
	 * --------------------------------------------------------------------------
	 * All the implicit actions below MUST be declared in the config/Coldbox.cfc in order to fire.
	 * https://coldbox.ortusbooks.com/getting-started/configuration/coldbox.cfc/configuration-directives/coldbox#implicit-event-settings
	 */

	function onAppInit( event, rc, prc ){
	}

	function onRequestStart( event, rc, prc ){
	}

	function onRequestEnd( event, rc, prc ){
	}

	function onSessionStart( event, rc, prc ){
	}

	function onSessionEnd( event, rc, prc ){
		var sessionScope     = event.getValue( "sessionReference" );
		var applicationScope = event.getValue( "applicationReference" );
	}

	function onException( event, rc, prc ){
		event.setHTTPHeader( statusCode = 500 );
		// Grab Exception From private request collection, placed by ColdBox Exception Handling
		var exception = prc.exception;
		// Place exception handler below:
	}

}

The action (function) we are interested in is the index() function.

function index( event, rc, prc ){
	prc.welcomeMessage = "Welcome to ColdBox!";
	event.setView( "main/index" );
}

It sets a message in an incoming prc argument and then calls a method in the incoming event argument to set a view for rendering. We will discover these arguments in the next section. For now, we need to understand that handler actions are in place of traditional CFML pages. Depending on the incoming URL route, we execute the appropriate handler and action function.

Re-initializing the Application

There will be times when you make configuration or metadata/singleton 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

Tip: You can add a password to the reinit procedures for further security, please see the configuration section.