A collection of useful recipes for the ColdBox Framework.

We have a Github organization called coldbox-templates that has a great collection of application startup templates. You can collaborate with the existing ones or send us new ones to add.

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:

• Name of template in our organization: advanced,simple,super-simple,rest, rest-hmvc, vuejs, etc

• 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: http://myapptemplates.com/template.zip

• A folder containing a template: /opt/shared/templates/my-template

• A zip file containing the template: /opt/shared/templates/my-template.zip

We have a special module just for helping you monitor and debug ColdBox applications. To install, fire up CommandBox and install it as a dependency in your application.

CbDebugger Requirements

• Hibernate extension (on Lucee)

• ORM package (on ACF 2021)

install cbdebugger --saveDev

Remember that this module is for development so use the --saveDev flag. This will install the ColdBox Debugger module for you, which will attach a debugger to the end of the request and give you lots of flexibility. Please read the instructions here in order to spice it up as you see fit: https://github.com/coldbox-modules/cbdebugger

Introduction

If you use any of the view partial caching mechanisms in Coldbox either through setView() orrenderView() you might be asking yourself:

Is there an easy, programmatic way to remove a specific element from the view cache?

The answer is, of course! All view and event caching occurs in a cache provider called template and you can retrieve it like so from your handlers, layouts, views, plugins and interceptors:

You can also use the WireBox injection DSL

Clearing methods

There are a few methods that will help you clear views:

• clearView(viewSnippet) - Clear views with a snippet

• clearAllViews(async) - Clear all views

• clearViewMulti(viewSnippets) - Clear multiple view snippets with a list or array of snippets

Very easy! Just send in what you need and it will be purged.

ColdBox provides you with several ways to handle different types of exceptions during a typical ColdBox request execution:

• Global exception handler

• Global onException interceptor

• Global invalid event handler

• Global onInvalidEvent interceptor

• Global missing template handler

• Handler onMissingAction()

• Handler onError()

• Handler onInvalidHTTPMethod

Global Exception Handler

The global exception handler will manage any runtime exception that occurs during the flow of a typical ColdBox request execution. This could be an exception at the handler, model, or view levels. This feature is activated by configuring the coldbox.exceptionhandler setting in your configuration ColdBox.cfc. The value of the setting is the event that will act as your global exception handler.

This event can the be used for logging the exception, relocating to a fail page or aborting the request. By default once the exception handler executes, ColdBox will continue the request by presenting the user the default ColdBox error page or a customized error template of your choosing via the coldbox.customErrorTemplate setting. ColdBox will also place an object in the private request collection called exception. This object models the entire exception and request data that created the exception. You can then use it to get any information needed to handle the exception.

Caution Please note that if you set a view for rendering or renderdata in this exception handler, nothing will be rendered. The framework is in exception mode and will not allow any custom renderings or views as that could also produce exceptions as well.

Global onException Interceptor

This is a standard ColdBox interception point that can be used to intercept whenever a global exception has occurred in the system. The interceptor call is actually made before the global exception handler, any automatic logging or presentation of the error page to the user. This is the first line of defense towards exceptions. You might be asking yourself, what is the difference between writing an onException() interceptor and just a simple exception handler? Well, the difference is in the nature of the design.

Interceptors are designed to be decoupled classes that can react to announced events, thus an event-driven approach. You can have as many CFCs listening to the onException event and react accordingly without them ever knowing about each other and doing one job and one job only. This is a much more flexible and decoupled approach than calling a single event handler where you will procedurally decide what happens in an exception.

Also remember that you need to register the interceptor in your configuration file or dynamically so ColdBox knows about it:

Caution Remember that the onException() interceptors execute before the global exception handler, any automatic error logging and presentation of the core or custom error templates.

Global Invalid Event Handler

The global invalid event handler allows you to configure an event to execute whenever ColdBox detects that the requested event does not exist. This is a great way to present the user with page not found exceptions and 404 error codes. The setting is called coldbox.invalidEventHandler and can be set in your configuration ColdBox.cfc. The value of the setting is the event that will handle these missing events.

Please note the importance of setting a 404 header as this identifies to the requester that the requested event does not exist in your system. Also note that if you do not set a view for rendering or render data back, the request might most likely fail as it will try to render the implicit view according to the incoming event.

ColdBox will also place the invalid event requested in the private request collection with the value of invalidevent.

Global onInvalidEvent Interceptor

This is a standard ColdBox interception point that can be used to intercept whenever a requested event in your application was invalid. You might be asking yourself, what is the difference between writing an onInvalidEvent() interceptor and just a simple invalid event handler? Well, the difference is in the nature of the design.

Interceptors are designed to be decoupled classes that can react to announced events, thus an event-driven approach. You can have as many CFCs listening to the onInvalidEvent event and react accordingly without them ever knowing about each other and doing one job and one job only. This is a much more flexible and decoupled approach than calling a single event handler where you will procedurally decide what happens in an invalid event.

The interceptData argument receives the following variables:

• invalidEvent : The invalid event string

• ehBean : The internal ColdBox event handler bean

• override : A boolean indicator that you overwrote the event

You must tell ColdBox that you want to override the invalid event (override = true) and you must set in the ehBean to tell ColdBox what event to execute:

Also remember that you need to register the interceptor in your configuration file or dynamically so ColdBox knows about it:

Global Missing Template Handler

The global missing template handler allows you to configure an event to execute whenever ColdBox detects a request to a non-existent CFML page. This is a great way to present the user with page not found exceptions or actually use it to route the request in a dynamic matter, just like if those pages existed on disk. The setting is called coldbox.missingTemplateHandler and can be set in your configuration ColdBox.cfc. The value of the setting is the event that will handle these missing pages.

Info Note that in order for this functionality to work the method onMissingTemplate() must exist in the Application.cfc with the default ColdBox handler code.

ColdBox will place the path to the requested page as a request collection variable called missingTemplate, which you can parse and route or just use.

Handler onMissingAction()

This approach allows you to intercept at the handler level when someone requested an action (method) that does not exist in the specified handler. This is really useful when you want to respond to dynamic requests like /page/contact-us, /page/hello, where page points to a Page.cfc and the rest of the URL will try to match to an action that does not exist. You can then use that portion of the URL to lookup a dynamic record. However, you can also use it to detect when invalid actions are sent to a specific handler.

Handler onError()

This approach allows you to intercept at the handler level whenever a runtime exception has occurred. This is a great approach when creating a family of event handlers and you create a base handler with the onError() defined in it. We have found tremendous success with this approach when building ColdBox RESTFul services in order to provide uniformity for all RESTFul handlers.

*Caution Please note that this only traps runtime exceptions, compiler exceptions will bubble up to a global exception handler or interceptor.

Handler onInvalidHTTPMethod()

This approach allows you to intercept at the handler level whenever an action execution is requested with an invalid HTTP verb. This is a great approach when creating a family of event handlers and you create a base handler with the onInvalidHTTPMethod() defined in it. We have found tremendous success with this approach when building ColdBox RESTFul services in order to provide uniformity for all RESTFul handlers.

Introduction

In this recipe we will create a simple interceptor that will be in charge of challenging users with HTTP Basic Authentication. It features the usage of all the new RESTful methods in our Request Context that will make this interceptor really straightforward. We will start by knowing that this interceptor will need a security service to verify security, so we will also touch on this.

You can find the code for this recipe here:

Application Setup

Let's start building the app using CommandBox and installing all the necessary dependencies:

Security Service

Let's build a simple security service to track users. Use CommandBox to generate the service model with two functions and let's mark it as a singleton:

This will create the models/SecurityService and the companion unit tests. Let's fill them out:

Security Service Test

Security Service

Please note that we are using a hard coded username and password, but you can connect this to any provider or db.

The Interceptor

Let's generate the interceptor now and listen to preProcess

The preProcesslistener is to listen to all incoming requests are inspected for security. Please note that the unit test for this interceptor is also generated. Let's fill out the interceptor test first:

Interceptor Test

So to make sure this works, here is our Interceptor Test Case with all possibilities for our Security Interceptor.

As you can see from our A,B, anc C tests that we use MockBox to mock the security service, the request context and methods so we can build our interceptor without knowledge of other parts.

Interceptor Code

As you can see it relies on a SecurityService model object that is being wired via:

Then we check if a user is logged in or not and if not we either verify their incoming HTTP basic credentials or if none, we challenge them by setting up some cool headers and bypass event execution:

The renderData() is essential in not only setting the 401 status codes but also concatenating to a noExecution() method so it bypasses any event as we want to secure them.

Interceptor Declaration

Open your Coldbox.cfc configuration file and add it.

Now reinit your app coldbox reinit and you are simple auth secured!

Why provider

You might have noticed the injection of the security service into the interceptor used a provider: DSL prefix, why? Well, global interceptors are created first, then modules are loaded, so if we don't use a provider to delay the injection, then the storages module might not be loaded yet.

Extra Credit

Now that the hard part is done, we encourage you to try and build the integration test for the application now. Please note that most likely you would NOT do the unit test for the interceptor if you do the integration portion in BDD Style.

Overview

REST APIs are a popular and easy way to add HTTP endpoints to your web applications to act as web services for third parties or even other internal systems. REST is simpler and requires less verbosity and overhead than other protocols such as SOAP or XML-RPC.

Creating a fully-featured REST API is easy with the ColdBox Platform. Everything you need for creating routes, working with headers, basic auth, massaging data, and enforcing security comes out of the box. We even have several application templates just for REST, so you can use CommandBox to create your first RESTFul app:

You will then see the following JSON output:

Quick Reference Card

Below you can download our quick reference card on RESTFul APIs

Introduction To REST

REST stands for Representational State Transfer and builds upon the basic idea that data is represented as resources and accessed via a URI, or unique address. An HTTP client (such as a browser, or the CFHTTP tag) can send requests to a URI to interact with it. The HTTP verb (GET, POST, etc) sent in the header of the request tells the server how the client wants to interact with that resource.

As far as how your data is formatted or how you implement security is left up to you. REST is less prescriptive than other standards such as SOAP (which uses tons of heavy XML and strictly-typed parameters). This makes it more natural to understand and easier to test and debug.

Defining Resources

A REST API can define its resources on its own domain (https://api.example.com), or after a static placeholder that differentiates it from the rest of the app (https://www.example.com/api/). We'll use the latter for these examples.

Let's consider a resource we need to represent called user. Resources should usually be nouns. If you have a verb in your URL, you're probably doing it wrong.

Here are a few pointers when using the HTTP verbs:

• GET /api/user will return a representation of all the users. It is permissible to use a query string to control pagination or filtering.

• POST /api/user/ will create a new user

• GET /api/user/53 will return a representation of user 53

• PUT /api/user/53 will update user 53

• DELETE /api/user/53 will delete user 53

In ColdBox, the easiest way to represent our /api/user resource is to create a handler called user.cfc in the /handlers/api/ directory. In this instance, ColdBox will consider the api to be a handler package. You can leverage CommandBox for this:

Here in my handler, I have stubbed out actions for each of the operations I need to perform against my user resource.

/handlers/api/user.cfc

Defining URL Routes

Now that we have this skeleton in place to represent our user resource, let's move on to show how you can have full control of the URL as well as mapping HTTP verbs to specific handler actions.

Let's add our new routes BEFORE the default route. We add them BEFORE because you must declare routes from the most specific to the most generic. Remember, routes fire in declared order.

Route Placeholders

Numeric Pattern Matcher

Append -numeric to the end of the placeholder to only match numbers.

addRoute( pattern = 'user/:userID-numeric' );

This route will match user/123 but not user/bob.

Alphabetic Pattern Matcher

Append -alpha to the end of the placeholder to only match upper and lowercase letters.

addRoute( pattern = 'page/:slug-alpha' );

This route will match page/contactus but not page/contact-us3.

Regex Pattern Matcher

For full control, you can specify your own regex pattern to match parts of the route

addRoute( pattern = 'api/:resource-regex(user|person)' );

This route will match api/user and api/person, but not /api/contact

Placeholder Quantifiers

You can also add the common regex {} quantifier to restrict how many digits a placeholder should have or be between:

As you can see, you have many options to craft the URL routes your API will use. Routes can be as long as you need. You can even nest levels for URLs like /api/users/contact/address/27 which would refer to the address resource inside the contact belonging to a user.

Returning Representations (Data)

REST does not dictate the format you use to represent your data. It can be JSON, XML, WDDX, plain text, a binary file or something else of your choosing.

Handler Return Data

• String => HTML

• Complex => JSON

renderData()

• XML

• JSON/JSONP

• TEXT

• WDDX

• PDF

• Custom

Format Detection

Many APIs allow the user to choose the format they want back from the endpoint. ColdBox will inspect the Accepts header to determine the right format to use by default or the URI for an extension.

Another way to do this is by appending a file extension to the end of the URL:

ColdBox has built-in support for detecting an extension in the URL and will save it into the request collection in a variable called format. What's even better is that renderData() can find the format variable and automatically render your data in the appropriate way. All you need to do is pass in a list of valid rendering formats and renderData() will do the rest.

Status Codes

Status codes are a core concept in HTTP and REST APIs use them to send messages back to the client. Here are a few sample REST status codes and messages.

• 200 - OK - Everything is hunky-dory

• 201 - Created - The resource was created successfully

• 202 - Accepted - A 202 response is typically used for actions that take a long while to process. It indicates that the request has been accepted for processing, but the processing has not been completed

• 400 - Bad Request - The server couldn't figure out what the client was sending it

• 401 - Unauthorized - The client isn't authorized to access this resource

• 404 - Not Found - The resource was not found

• 500 - Server Error - Something bad happened on the server

You can easily set status codes as well as the status message with renderData(). HTTP status codes and messages are not part of the response body. They live in the HTTP header.

Status codes can also be set manually by using the event.setHTTPHeader()method in your handler.

Caching

One of the great benefits of building your REST API on the ColdBox platform is tapping into awesome features such as event caching. Event caching allows you to cache the entire response for a resource using the incoming FORM and URL variables as the cache key. To enable event caching, set the following flag to true in your ColdBox config: Coldbox.cfc:

Next, simply add the cache=true annotation to any action you want to be cached. That's it! You can also get fancy, and specify an optional cacheTimeout and cacheLastAccesstimeout (in minutes) to control how long to cache the data.

Auto-Deserialization of JSON Payloads

If you are working with any modern JavaScript framework, this feature is for you. ColdBox on any incoming request will inspect the HTTP Body content and if the payload is JSON, it can deserialize it for you and if it is a structure/JS object, it will append itself to the request collection for you. So if we have the following incoming payload:

The request collection will have 3 keys for name, type and data according to their native CFML type.

Security

Adding authentication to an API is a common task and while there is no standard for REST, ColdBox supports just about anything you might need.

Requiring SSL

To prevent man-in-the-middle attacks or HTTP sniffing, we recommend your API require SSL. (This assumes you have purchased an SSL Cert and installed it on your server). When you define your routes, you can add withSSL() and ColdBox will only allow those routes to be accessed securely

If your client is capable of handling cookies (like a web browser), you can use the session or client scopes to store login details. Generally speaking, your REST API should be stateless, meaning nothing is stored on the server after the request completes. In this scenario, authentication information is passed along with every request. It can be passed in HTTP headers or as part of the request body. How you do this is up to you.

Basic HTTP Auth

One of the simplest and easiest forms of authentication is Basic HTTP Auth. Note, this is not the most robust or secure method of authentication and most major APIs such as Twitter and FaceBook have all moved away from it. In Basic HTTP Auth, the client sends a header called Authorization that contains a base 64 encoded concatenation of the username and password.

You can easily get the username and password using event.getHTTPBasicCredentials().

Custom

In addition to having access to the entire request collection, the event object also has handy methods such as event.getHTTPHeader() to pull specific headers from the HTTP request.

/interceptors/APISecurity.cfc

Register the interceptor with ColdBox in your ColdBox.cfc:

Restricting HTTP Verbs

In our route configuration we mapped HTTP verbs to handlers and actions, but what if users try to access resources directly with an invalid HTTP verb? You can easily enforce valid verbs (methods) by adding this.allowedMethods at the top of your handler. In this handler the list() method can only be accessed via a GET, and the remove() method can only be accessed via POST and DELETE.

The key is the name of the action and the value is a list of allowed HTTP methods. If the action is not listed in the structure, then it means allow all. If the request action HTTP method is not found in the list then it throws a 405 exception. You can catch this scenario and still return a properly-formatted response to your clients by using the onError() or the onInvalidHTTPMethod() convention in your handler or an exception handler which applies to the entire app.

Error Handling

ColdBox REST APIs can use all the same error faculties that an ordinary ColdBox application has. We'll cover three of the most common ways here.

Handler onError()

If you create a method called onError() in a handler, ColdBox will automatically call that method for runtime errors that occur while executing any of the actions in that handler. This allows for localized error handling that is customized to that resource.

Handler onInvalidHTTPMethod()

If you create a method called onInvalidHTTPMethod() in a handler, ColdBox will automatically call that method whenever an action is trying to be executed with an invalid HTTP verb. This allows for localized error handling that is customized to that resource.

Global Exception Handler

The global exception handler will get called for any runtime errors that happen anywhere in the typical flow of your application. This is like the onError() convention but covers the entire application. First, configure the event you want called in the ColdBox.cfc config file. The event must have the handler plus action that you want called.

Then create that action and put your exception handling code inside. You can choose to do error logging, notifications, or custom output here. You can even run other events.

ColdBox Relax

ColdBox Relax is a set of ReSTful Tools For Lazy Experts. We pride ourselves in helping you (the developer) work smarter and ColdBox Relax is a tool to help you document your projects faster. ColdBox Relax provides you with the necessary tools to automagically model, document and test your ReSTful services. One can think of ColdBox Relax as a way to describe ReSTful web services, test ReSTful web services, monitor ReSTful web services and document ReSTful web services–all while you relax!

To install the examples place them into the models directory in a subdirectory called 'resources' (as per the Github repo), then add the following relax structure to your Coldbox.cfc file:

You can then visit http://[yourhost]/relax to view Relax.