7.3.1 - March 2, 2025

Bug

COLDBOX-1293 DBAppender with SQL Server Not Compatible with Adobe 2023

7.3.0 - May 13, 2024

New Feature

COLDBOX-1270 Abililty to restart schedulers with a restart() method

Improvement

COLDBOX-1268 WireBox Singleton auto reload now only affects app singletons and not core singletons

COLDBOX-1269 Do not add double headers if `event.setHTTPHeader()` is called more than once

COLDBOX-1273 Removal of deprecated CFML functions in core

COLDBOX-1275 Improved engine detection by the CFMLEngine feature class

COLDBOX-1278 Remove unsafe evaluate function usage

Bug

COLDBOX-1266 Logger for MS SQL using date not datetime.

COLDBOX-1267 Lucee only isEmpty function call

COLDBOX-1279 Render encapsulator bleed of this scope by engines

ColdBox HMVC Platform- v7.x

ColdBox Hierarchical MVC is the de-facto enterprise-level HMVC framework for ColdFusion (CFML) developers. 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 ColdFusion (CFML) development with features such as:

• Conventions instead of configuration

• Modern routing engine

• RESTFul API ready

• A hierarchical approach to MVC using ColdBox Modules

• Event-driven programming

• Async and Parallel programming constructs

• Integration & Unit Testing

• Included dependency injection

• Caching engine and API

• Logging engine

• An extensive ecosystem

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

License

The ColdBox Platform is open source and licensed under the Apache 2 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: https://community.ortussolutions.com.

You can also join our Slack Box Team at: https://boxteam.ortussolutions.com

Reporting a Bug

Jira Issue Tracking

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

• https://ortussolutions.atlassian.net/browse/WIREBOX

• https://ortussolutions.atlassian.net/browse/LOGBOX

• https://ortussolutions.atlassian.net/browse/CACHEBOX

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

• CFCasts Video Training: http://www.cfcasts.com

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

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

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

• Slack: https://boxteam.ortussolutions.com

• Twitter: @coldbox @ortussolutions

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

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.

• As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.

• Participants will be tolerant of opposing views.

• Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.

• Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions not aligned with this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.

• When interpreting the words and actions of others, participants should always assume good intentions. Emotions cannot be derived from textual representations.

• Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.

Bug Reporting

Each of the main standalone frameworks in ColdBox has separate locations for submitting bug reports. Please also ensure that if you submit a pull request, you link it to the appropriate issue.

• ColdBox Core: https://ortussolutions.atlassian.net/browse/COLDBOX

• CacheBox : https://ortussolutions.atlassian.net/browse/CACHEBOX

• LogBox : https://ortussolutions.atlassian.net/browse/LOGBOX

• WireBox: https://ortussolutions.atlassian.net/browse/WIREBOX

If you file a bug report, your issue should contain a title, a clear description of the issue, a way to replicate the issue, and any support files we might need to replicate your issue. The goal of a bug report is to make it easy for yourself - and others - to replicate the bug and develop a fix for it. All issues that do not contain a way to replicate will not be addressed.

Support Questions

If you have questions about usage, professional support, or just ideas to bounce off the maintainers, please do not create an issue. Leverage our support channels first.

• Ortus Community Discourse: https://community.ortussolutions.com/c/communities/coldbox/13

• Box Slack Team: http://boxteam.ortussolutions.com/

• Professional Support: https://www.ortussolutions.com/services/support

Pull Request Guidelines

• The master branch is just a snapshot of the latest stable release. All development should be done in dedicated branches. Do not submit PRs against the master branch. They will be closed.

• All pull requests should be sent against the development branch or the LTS version branch releases/v{version}

• It's OK to have multiple small commits as you work on the PR - GitHub will automatically squash it before merging.

• Make sure all local tests pass before submitting the merge.

• Please make sure all your pull requests have companion tests.

• Please link the Jira issue in your PR title when sending the final PR

Security Vulnerabilities

If you discover a security vulnerability, please email the development team at security@ortussolutions.com and make sure you report it to the #security channel in our Box Team Slack Channel. All security vulnerabilities will be promptly addressed.

Development Setup

We have added all the necessary information to develop on ColdBox in our readme collaboration area and our tests readme so you can set up the database to test against.

Language Compatibility

Please make sure your code runs on the following Supported CFML Engines:

• Lucee 5+

• Adobe ColdFusion 2018+

Coding Styles & Formatting

We are big on coding styles and have included a .cfformat.json in the root of the project so that you can run the formatting tools and CommandBox scripts:

# Format everything
box run-script format

# Start a watcher, type away, save and auto-format for you
box run-script format:watch

We recommend that anytime you hack on the core, you start the format watcher (box run-script format:watch). This will monitor your changes and auto-format your code for you.

You can also see the Ortus Coding Standards you must follow here: https://github.com/Ortus-Solutions/coding-standards.

CFC Docs With DocBox

All CFCs are self-documenting, and we leverage DocBox to document the entire software. All functions must be properly documented using the DocBox syntax: https://docbox.ortusbooks.com/getting-started/annotating-your-code

Financial Contributions

You can support ColdBox and all of our Open Source initiatives at Ortus Solutions by becoming a Patreon. You can also get lots of goodies and services depending on the level of contributions.

• Become a backer or sponsor on Patreon

• One-time donations via PayPal

Contributors

Thank you to all the people who have already contributed to ColdBox! We: heart: : heart: : heart: love you!

Made with contributors-img

This is a minor release with tons of updates and bug fixes.

Scheduled Tasks Debugging

You can now add a debug argument to your task definitions, and your console will add tons of debugging for your tasks:

toRedirectTo() Matcher

You can now use this matcher to test relocations in a nice fluent expectation:

REST on{errorType}Exception() Convention

Thanks to our very own Gavin Pickin you can now create exception handlers in your REST Handlers that follow the on{type}Exception() convention and you can listen to specific error type exceptions:

Release Notes

The full release notes per library can be found below. Just click on the library tab and explore their release notes:

Versioning Schema

And constructed with the following guidelines:

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

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

• Bug fixes and misc changes bump the patch

LTS - Support Policy

For all ColdBox releases, updates are provided for 12 months, and security fixes are provided for 2 years after the next major release.

Releases

In this section, you will find the release notes and links for each version's documentation. If you are looking for the release notes of previous major versions, use the version switcher at the top left of this documentation book.

• Version 3.0 - March 2011

• Version 2.0 - April 2007

• Version 1.0 - June 2006

The full release notes per library can be found below. Just click on the library tab and explore their release notes:

Welcome to ColdBox 7.2.0, which packs a big punch on stability and tons of new features.

ColdBox Updates

SchemaInfo Helper

A new helper has been born that assists you with dealing with Database Schema-related methods that are very common and core to ColdBox and supporting modules. This will grow as needed and be decoupled to its own module later.

• hasTable()

• hasColumn()

• getDatabaseInfo()

• getTextColumnType()

• getDateTimeColumnType()

• getQueryParamDateTimeType()

Async allApply() error handlers

The allApply() is great when dealing with async operations on arrays or collections of objects. However, if something blows up, it would blow up with no way for you to log in or know what happened. However, now you can pass an errorHandler argument which is a UDF/closure that will be attached to the onException() method of the future object. This way, you can react, log, or recover.

Scheduled Task Groups

All scheduled tasks now have a group property so you can group your tasks. This is now available when creating tasks or setting them manually.

You can then get the group using the getGroup() method or it will be added to all task metadata and stats.

New everySecond() period

A new period method shortcut: everySecond(). Very useful so you can fill up your logs with data.

Task Results Are Optionals

All task results, if any, are now stored in a ColdBox Optional. Which is a class that can deal with nulls gracefully and it's very fluent:

Task Get Last Result

New method to get the last result, if any, from a task via the getLastResult() method.

DateTimeHelper Updates

Lot's of great new methods and goodies so you can deal with date and times and timezones Oh My!

• now( [timezone] )

• getSystemTimezoneAsString()

• getLastBusinessDayOfTheMonth()

• getFirstBusinessDayOfTheMonth()

• dateTimeAdd()

• timeUnitToSeconds()

• validateTime()

• getIsoTime()

• toInstant()

• toLocalDateTime()

• parse()

• toLocalDate()

• getTimezone()

• getSystemTimezone()

• toJavaDate()

• duration()

• period()

WireBox Updates

AOP Auto Mixer

If in your binder you declare aspects or AOP bindings. Then WireBox will automatically detect it and load the AOP Mixer listener for you. You no longer have to declare it manually.

CacheBox Updates

New Struct Literal Config

LogBox Updates

New Struct Literal Config

Category Appender Excludes

When you declare categories in LogBox you usually choose the appenders to send messages to, but you could never exclude certain ones. Now you can use the exclude property:

New Event Listeners

You now have two new event listeners that all LogBox appenders can listen to:

• preProcessQueue( queue, context ) : Fires before a log queue is processed element by element.

• postProcessQueue( queue, context ) : After the log queue has been processed and after the listener has slept.

processQueueElement receives the queue

The processQueueElement( data, context, queue ) now receives the entire queue as well as the queue third argument.

New Archive Layouts

If you use the RollingFileAppender the default layout format of the archive package was static and you could not change it. The default is:

Now you have the power. You can set a property for the appender called archiveLayout which maps to a closure/UDF that will build out the layout of the file name.

Release Notes

The full release notes per library can be found below. Just click on the library tab and explore their release notes:

The source code for this book is hosted on GitHub: https://github.com/ortus-docs/coldbox-docs. You can freely contribute to it and submit pull requests. The contents of this book are copyrighted by Ortus Solutions, Corp 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 - http://www.ortussolutions.com/products/commandbox

External Trademarks & Copyrights

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

ColdBox, CommandBox, FORGEBOX, TestBox, ContentBox, and Ortus Solutions are all trademarks and copyrights of Ortus Solutions, Corp.

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 concerning 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 contributions to this book and our open-source software. The source code for this book can be found in our GitHub repository where you can submit pull requests.

Charitable Proceeds

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

Shalom Children's Home

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

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

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

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

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

• He has of late (during old age) become a fan of organic gardening.

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 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 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 digital and analog circuits with his daughter as well as building projects with Arduino-based microcontrollers.

Brad's CommandBox Snake high score is 141.

ColdFusion 2016 Support Dropped

ColdFusion 2016 support has been dropped. Adobe doesn't support them anymore, so neither do we.

HTML Helper addAsset() Changes

The addAsset() now leverages the following settings for determining the convention locations for JavaScript and CSS assets:

So if you want to change the location of your JavaScript and CSS, you can create these settings in your ColdBox.cfc

Integration Testing Defaults

In ColdBox 7, the this.unloadColdBox setting is false by default. In ColdBox 6 this was true by default. So make sure you update this setting if you want ColdBox to be unloaded on each Test Bundle iteration.

Hierarchical Injectors

All modules have their own injector now if you use the this.moduleInjector = true setting. Meaning the concept of a global injector no longer exists. Therefore, there are some edge cases where certain types of code will not work in ColdBox 7.

Testing Injector Creations

If you are creating your own WireBox injector in your tests and using integration testing, you will have Injector collisions.

This actually affects EVERY version of ColdBox because the default behavior of instantiating an Injector like the code above is to put the Injector in application scope: application.wirebox. This means that the REAL injector in an integration test lives in application.wirebox will be overridden. To avoid this collision, disable scope registration:

Custom Wirebox DSLs

For those of you with custom wirebox DSLs, you'll need to update your DSL to match the new process() method signature:

Removals

AnnounceInterception

routes.cfm

setUniqueURLs()

This setting was in charge of converting NON-SES Urls into SES URLs. However, it was extremely error-prone and sometimes produced invalid URLs. This is now completely removed and if the user wants to do this feature, they can use CommandBox or Nginx, or Apache rewrites.

jsonQueryFormat Removed

The jsonQueryFormat argument for rendering data is now removed. We default to an array of structs format for queries as it is the only format that makes sense.

Deprecations

renderView(), renderLayout(), renderExternalView()

These methods have been deprecated since version 6. Please use the shorthand versions

• view()

• layout()

• externalView()

Utility Environment Methods

The core utility methods on env and Java variables have been deprecated from the utility object and moved to the Env delegate. Here are the methods deprecated:

• getSystemSetting()

• getSystemProperty()

• getEnv()

So if you had code like this:

That will work, but it is deprecated now. You will have to move it to the delegate:

If you were using them in your integration or unit tests, then you can use our shorthand methods:

BeanPopulator Deprecated

The object BeanPopulator has been deprecated in favor of ObjectPopulator.

Welcome to the world of ColdBox!

IDE Tools

ColdBox has the following supported IDE Tools:

CommandBox CLI

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 open the binary, and CommandBox will unpack to your user's directory: {User}/.CommandBox. This happens only once, and the next thing you know, you are in the CommandBox interactive shell!

We can 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 CLI

We can now use CommandBox to install the ColdBox CLI to assist us in all aspects of ColdBox Development:

You will now have a coldbox command namespace. You can do coldbox help and get all the help you need with the commands.

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. Try it out!

Updating ColdBox

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

Intro to MVC

• Model - Business Logic, Data, Queries, Etc

• View - Representation of your models, queries, data.

• Controller - Orchestrator of client request to the appropriate models and views

Let's go a little deeper.

Model

Views

The Views are what the users see and interact with. They are the templates used to render your application out for the web browser. Typically this means cfm/HTML, but it can also be JSON, XML, data views, etc.

In modern times, your views can even be pure HTML with a combination of a JavaScript MVC framework. The major players in the MVC front-end world that we would recommend in order of personal preference:

Controllers

Controllers are the traffic cops of your application. They direct flow control, and interface directly without incoming parameters from FORM and URL scopes. It is the controller’s job to communicate with the appropriate models for processing, and set up either a view to display results or return serialized data like JSON, XML, PDF, etc.

Benefits of MVC

Separation of Concerns

The model and the view layers have different concerns about their implementations. A view layer is concerned with how to render the data, the type of browser, or remote rendering, etc. While the model is more concerned with the business rules of the application, how to store data and even database operations. You use different development approaches to each layer.

Multiple GUI’s

Due to this separation, you can easily create multiple views for the same model data without affecting how the model works or is coded. The view layers can adapt to the model by coding their own implementations. This makes it really easy to create multiple GUI’s for applications.

Unit and Behavioral Testing

Non-visual objects are easier to test than visual objects, in theory. With the introduction of Selenium, integration and visual UI testing has become rather simple. However, the key benefit here is that testing can be done separately. Frameworks like ColdBox even give you the ability to do UI and integration testing within its domain.

Dependency

The most important benefit that we can arise out of the MVC pattern, is the direction of the dependencies. A view depends on its model data and controller, but the model itself does not depend on the view or controllers. This is how you want to build your business logic, encapsulated and providing a good API.

Evolution of MVC Architecture

Spaghetti Hell

As you can see from the spaghetti hell diagram above, everything is linear and can become extremely convoluted. Tracking bugs are difficult, maintenance suffers and reusability is not efficient. Everything is in the same bowl of soup.

MVC

With the introduction of MVC we can hack away our spaghetti hell and at least have three distinct and separate layers of logic. Ahh much better. However, we can get even more complex.

MVC Plus

MVC Plus shows us how you can further partition your model layer into more layers. We can identify now a layer of service CFCs and data access object CFCs. The main transportation of data between these layers by default is implied to be ColdFusion Query objects.

MVC Plus Objects

In this architecture approach, we have replaced (mostly) queries as our data structure of preference and converted to the usage of business objects. We are approaching a more object oriented architectural style. Remember that data is just data, objects are data plus behavior. We can encapsulate more features and abstract more behavior into actual objects now, which we could not do with queries.

MVC Plus ORM

In this architecture approach we have replaced business objects for ORM entities and replaced our data access layer to be controlled now by the ORM. This takes us very deep into object oriented land where the majority of our model is now modeled vi relational objects.

More Resources

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

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 (convert) 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 lets create a new action called data

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:

We have registered the API route and also defaulted the format to JSON. Try it out.

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

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

Here are the signatures

/**
 * Builds links to events or URL Routes
 *
 * @to          The event or route path you want to create the link to
 * @queryString The query string to append which can be a regular query string string, or a struct of name-value pairs
 * @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
 */
string function buildLink(
	to,
	queryString       = "",
	boolean translate = true,
	boolean ssl,
	baseURL = ""
)


/**
 * Builds links to named routes with or without parameters. If the named route is not found, this method will throw an `InvalidArgumentException`.
 * If you need a route from a module then append the module address: `@moduleName` or prefix it like in run event calls `moduleName:routeName` in order to find the right route.
 *
 * @name   The name of the route
 * @params The parameters of the route to replace
 * @ssl    Turn SSL on/off or detect it by default
 *
 * @throws InvalidArgumentException - If thre requested route name is not registered
 */
string function route( required name, struct params = {}, boolean ssl )

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)

<cfoutput>
    <h1>Hello from ColdBox Land!</h1>
    <p><a href="#event.buildLink( "main" )#">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>

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

// @app_routes@

route( "/home" ).as( "home" ).to( "main.index" );

// Conventions-Based Routing
route( ":handler/:action?" ).end();

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:

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

Try it out now!

Handler Scaffolding

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

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

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.

Default URL Routing

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

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

You will now see a big hello.index outputted to the screen. You have now created your first handler and view combination. However, how did this work? It works by convention.

Your application router is located at : config/Router.cfc. It will include a few default routes for you and the following default URL route:

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

This route tells ColdBox to look for the names of handlers (including directory names) and names of the handler actions (functions). The ? on the :action portion denotes that the action might or might not exist in the URL. If it doesn't exist, then another convention is in play, the default action, which is index.

So /main will execute main.index and /main/index will execute main.index

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 represents the request and can modify the response. We call this object the request context.

• 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, 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. Migrating from a traditional application?

coldbox create view name="virtual/hello" --open

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 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 Lucee, for a completely free and open source development stack. ColdBox itself is Professional Open Source Software, backed by Ortus Solutions 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 CommandBox 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:

WireBox

Managing your domain objects has never been easier with this Dependency Injection and Inversion of Control (IOC) framework. WireBox supports all forms of injection as well as maintaining persistence for your domain objects. WireBox can also interface and provide Java classes, web services, and aspects of the ColdBox framework itself. WireBox also has built-in Aspect Oriented Programming (AOP) support; you’ll never need another Dependency Injection engine again.

LogBox

This is a highly-configurable logging library which can be set up to relay messages of different types from any portion of your application to any number of predefined logging appenders.

CacheBox

A highly-versatile caching aggregator and enterprise cache that allows for multiple named caching stores as well as granular control over cache behaviors and eviction policies. CacheBox can interface out of the box with Ehcache, Adobe ColdFusion cache, and any Lucee cache.

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 Getting Started Guide and then to the other guides in this book.

You can find the source code of this quickstart here: https://github.com/coldbox-samples/60-minute-quickstart

Requirements

• Please make sure you download and install the latest CommandBox CLI. We will show you how in the Installing ColdBox section.

• Grab a cup of coffee or tea

• Get comfortable

Need Help?

The Ortus Community is the way to get any help for our entire platform and modules: https://community.ortussolutions.com

ColdBox 7.0.0 is a major release for the ColdBox HMVC platform. It has some dramatic new features as we keep pushing for more modern and sustainable approaches to web development and tons of bug fixes and improvements.

We break down the major areas of development below, and you can also find the full release notes per library at the end.

Engine Support

This release drops support for Adobe 2016 and adds support for Adobe 2023 and Lucee 6 (Beta). Please note that there are still issues with Adobe 2023 as it is still in Beta.

ColdBox CLI

 ██████╗ ██████╗ ██╗     ██████╗ ██████╗  ██████╗ ██╗  ██╗      ██████╗██╗     ██╗
██╔════╝██╔═══██╗██║     ██╔══██╗██╔══██╗██╔═══██╗╚██╗██╔╝     ██╔════╝██║     ██║
██║     ██║   ██║██║     ██║  ██║██████╔╝██║   ██║ ╚███╔╝█████╗██║     ██║     ██║
██║     ██║   ██║██║     ██║  ██║██╔══██╗██║   ██║ ██╔██╗╚════╝██║     ██║     ██║
╚██████╗╚██████╔╝███████╗██████╔╝██████╔╝╚██████╔╝██╔╝ ██╗     ╚██████╗███████╗██║
 ╚═════╝ ╚═════╝ ╚══════╝╚═════╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═╝      ╚═════╝╚══════╝╚═╝
                                                                                  

We now have an official CLI for ColdBox, which lives outside CommandBox. It will always be included with CommandBox, but it now has its own life cycles, and it will support each major version of ColdBox as well.

install coldbox-cli
coldbox --help

The new CLI has all the previous goodness but now also v7 support and many other great features like migration creation, API testing, and more. You can find the source for the CLI here: https://github.com/coldbox/coldbox-cli

VSCode ColdBox Extension

We have updated our VSCode ColdBox extension now to support the latest version of snippets and skeletons for code generation.

Application Templates

All the application templates have been updated in our ColdBox Templates Org: https://github.com/coldbox-templates. They have been updated to support our LTS strategy, so now we can have templates based on each major iteration of ColdBox.

Here is a listing of the latest supported templates:

WireBox Updates

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

WireBox has gotten tons of love in this release, with several additions, bug fixes, and improvements.

Transient Request Cache

This feature is one of the most impactful for applications that leverage DI on transient objects, especially ORM-related applications. WireBox will now, by default, cache the signatures of the injections and delegations for you, so they are only done once per instance type. This addition has brought speed improvements of over 585% in Lucee and Adobe ColdFusion. You read that right, 585% performance increases. This is really a game changer for ORM-heavy applications that use DI and delegations. Go try it; you don't have to do a thing. Install and run it!

If this is not for you or there are issues in your system because of it, we have a setting for it to turn it off. Open the WireBox.cfc binder and add it as a config item.

// Config DSL
wirebox : {
    transientInjectionCache : false
}

// Binder Call
binder.transientInjectionCache( false )

You can also disable the cache on a per-CFC basis by using the transientCache=false annotation in your component declaration:

component transientCache=false{

}

Known Issues

Even though the transient cache can help tremendously with performance, there is a price to pay. All the injections and delegations will be cached on a per-cfc definition basis. Thus, if you are injecting transients, those transients will become singletons. Therefore you have two options to alleviate this side effect:

1. Disable the cache entirely (The heavy-handed approach)

2. Disable the cache on that specific entity via the transientCache annotation (The surgical approach)

3. Add the transient injection as a provider injection (The ninja approach)

4. Add the property as a lazy property and add a builder that will construct it when called (The Jedi approach)

component name="Transient" transientCache="false"{
    
   // This will become a singleton
   property name="transient2" inject="t2";
   // Provider injection
   property name="transient2" inject="provider:t2";
   // Lazy property
   property name="transient2" lazy;
   
   function buildTransient2(){
    return variables.wirebox.getInstance( "t2" );
   }
}

WireBox Delegators

WireBox supports the concept of object delegation in a simple, expressive DSL. You can now add a delegate annotation to injections or use the delegates annotations to components to inject and absorb the object's methods into yourself.

// Inject and use as a delegate
property name="memory" inject delegate

// Delegate Component
component name="computer" delegates="Memory"{
}

In object-oriented programming, an object delegator is a programming technique where an object delegates some of its responsibilities to another object. The delegating object passes the responsibility for handling a particular task to the delegate object. This allows the delegating object to focus on its core responsibilities while the delegate object handles the delegated task.

Basically, a way to inject/proxy calls from one object to the other and avoid the overuse of inheritance, and avoid runtime mixins. WireBox provides a set of rules for method lookup and dispatching that will allow you to provide delegation easily in your CFML applications. This feature is similar to traits in PHP or object delegators in Kotlin.

You can use it to encapsulate behavior on small, focused, and testable classes that can be brought in as traits into ANY component without abusing inheritance. In contrast, object delegation is a more flexible approach that allows objects to delegate tasks to any other object, regardless of its class hierarchy. Finally, object delegation can help to improve code performance by allowing objects to use specialized delegate objects for specific tasks.

Let's look at an example of how we would use delegation without this feature:

  component name="Memory"{
  
  function init(){
    return reset()
  }
  
  function reset(){
    variables.data = []
    return this;
  }
  
  function read( index ){
    return variables.data[ arguments.index ]
  }
  
  function write( data ){
    variables.data.append( arguments.data )
  }
  
}
  

Now let's look at the computer

component name="computer"{

    // Inject a memory object via WireBox
    property name="memory" inject;
    
    // read delegator proxy method
    function read( index ){
        return variables.memory.read( argumentCollection = arguments )
    }
    
    // write delegator proxy method
    function write( data ){
        return variables.memory.read( argumentCollection = arguments )
    }

}

As you can see, in the traditional approach we must type and inject and know every detail of the delegated methods. Now let's delegalize it via WireBox:

component name="computer"{
  // Inject and use as a delegate
  property name="memory" inject delegate

}

computer = getInstance( "Computer" )
computer.read( index )
computer.write( data )

Or use the shorthand notation via the delegates annotation of components:

component name="computer" delegates="Memory"{

   // code

}

computer = getInstance( "Computer" )
computer.read( index )
computer.write( data )

You can also do prefixes, suffixes, method includes, excludes, and even add as many delegates as you want:

component name="computer"
	delegates=">Memory, <Disk=read,sleep"
}

component name="computer"{

   property name="authorizable." 
	inject="provider:Authorizable@cbsecurity"
	delegate;

}

Read more about delegates here: https://wirebox.ortusbooks.com/usage/wirebox-delegators

Core Delegates

Now that we have seen what delegators are, WireBox offers core delegators to your application via the @coreDelegates namespace

• Async - This delegate is useful to interact with the AsyncManager and the most used functionality for asynchronous programming

• DateTime - Leverage the date time helper

• Env - Talk to environment variables

• Flow - Several fluent flow methods

• JsonUtil - JSON utilities

• StringUtil - String utilities

• Population - Population utilities

So let's say you have a service that needs to populate objects and work with the system environment:

component 
    delegates="population@coreDelegates, Env@coreDelegates"{
}

WireBox Property Observers

WireBox supports the concepts of component property observers. Meaning that you can define a function that will be called for you when the setter for that property has been called and thus observe the property changes.

You will accomplish this by tagging a property with an annotation called observed then by convention, it will look for a function called: {propertyName}Observer by convention. This function will receive three arguments:

• newValue : The value is set into the property

• oldValue : The old value of the property, including null

• property : The name of the property

component{

  property name="data" observed;
  
  /**
   * Observer for data changes.  Anytime data is set, it will be called
     	 *
   * @new The new value
   * @old The old value
   * @property The name of the property observed
   */
  function dataObserver( newValue, oldValue, property ){
  	// Execute after data is set
  }

}

Read more here: https://wirebox.ortusbooks.com/advanced-topics/property-observers

WireBox Lazy Properties

WireBox supports the concept of marking properties in your components as lazy. This will allow the property to be constructed ONCE when requested ONLY (lazy loaded). This way, you can take advantage of the construction of the property being lazy-loaded.

Internally, we will generate a getter method for you that will make sure to construct your property via a builder function you will provide, lock the request (by default), store it in the variables scope, and return it to you.

Note: With lazy properties, you must use the getter only to retrieve the property

component{
	
  // Lazy property: Constructed by convention via the buildUtil() method
  property name="util" lazy;
  
  /**
   * Build a util object lazyily.
   * The first time you call it, it will lock, build it, and store it by convention as 'variables.util'
   */
  function buildUtil(){
   return new coldbox.system.core.util.Util();
  }

}

Read more about Lazy Properties here: https://wirebox.ortusbooks.com/advanced-topics/lazy-properties

onInjectorMissingDependency event

A new event called onInjectorMissingDependency is now registered in Wirebox. It will be called whenever a dependency cannot be located. The data sent into the event will contain:

• name - The name of the requested dependency

• initArguments - The init arguments, if passed

• targetObject - The target object that requested the dependency

• injector - The injector in use building the dependency

If you return in the data struct an element called, instance we will return that as the dependency, else the normal exception will be thrown.

// Simple listener example
listen( "onInjectorMissingDependency", (data,event,rc,prc)=>{
    if( data.name == "OldLegacyOne" ){
        data.instance = myNewObject();
    }
});

Population Enhancements

• The object populator now caches ORM entity maps, so they are only loaded once, and the population with ORM objects accelerates tremendously.

• The object populator caches relational metadata for a faster population of the same type of objects

Mass Population Config: this.population

This new convention allows for objects to encapsulate the way the mass population of data is treated. This way, you don’t have to scrub or pass include excludes lists via population arguments; it can all be nicely encapsulated in the targeted objects:

this.population = {
    include : [ "firstName", "lastName", "username", "role" ],
    exclude : [ "id", "password", "lastLogin" ]
};

The populator will look for a this.population struct with the following keys:

• include : an array of property names to allow population ONLY

• exclude : an array of property names to NEVER allow population

The population methods also get a new argument called: ignoreTargetLists which defaults to false, meaning it inspects the objects for these population markers. If you pass it as true then the markers will be ignored. This is great for the population of objects from queries or an array of structs or mementos that YOU have control of.

populateFromStruct(
    target : userService.newUser(),
    memento : record,
    ignoreTargetLists : true
}

Inline Configuration

You can now instantiate an Injector with the binder argument being the config structure instead of creating a binder. This will allow you to create injectors and pass the configuration structure as well:

injector  = new coldbox.system.ioc.Injector({
	"scopeRegistration" : {
		"enabled" : false
	},
	"transientInjectionCache" : true
});

Injector Names

Each injector can now have a human-friendly name via the name property

injector.getName()
injector.setName( "AwesomeInjector" )

Clear Objects From Scopes

You can also now use a clear( key ) method in ALL scopes so you can remove a-la-carte objects from any supported scope.

Root Injector

In a ColdBox or WireBox context, there will always be a root injector in a hierarchy. This root injector can have children, and all of these children can have a direct link to its root via a hasRoot() and getRoot() methods.

Methods

• hasRoot()

• getRoot()

• setRoot()

Injection DSL

There are also injection DSLs for retrieving the root injector:

property name="root" inject="wirebox:root"
property name="root" inject="coldbox:rootWireBox"

Schedule Tasks Revamped

Thanks to Giancarlo Gomez, scheduled tasks get a big revamp in ColdBox 7. Here are the updates:

New Properties

• annually You can now task on an annual basis

• delayTimeUnit used to work with delays regardless of the setting in the chain

• debug used for debug output during task executions

• firstBusinessDay boolean to flag the task as on the first business day schedule

• lastBusinessDay boolean to flag the task as on the last business day schedule

• taskTime log of time of day for first business day and last business day tasks

• startTime limits tasks to run on or after a specific time of day

• endTime limits tasks to run on or before a specific time of day

• meta The user can use this struct to store any data for the task ( helpful for building UIs and not having to manage outside of the task )

• stats.nextRun ColdBox now determines the next run for the task in its scheduler interval

Updated Functions

• run( boolean force = false ) Added the force argument, to allow running the task on demand, even if it is paused.

• validateTime() Sets minutes if missing from time entry and returns time value if successful - removes a lot of repetitive code

New Functions

• debug() Used for setting debug setting ( can also be done in task init )

• startOnTime() used to set variables.startTime

• endOnTime() used to set variables.endTime

• between() used to set variables.startTime and variables.endTime in one call

• setMeta() used to set variables.meta

• setMetaKey() used to add / save a key to variables.meta

• deleteMetaKey() used to delete a key from variables.meta

New Private Functions

• getLastBusinessDayOfTheMonth()

• getFirstBusinessDayOfTheMonth()

• setInitialNextRunTime()

• setInitialDelayPeriodAndTimeUnit()

• setNextRunTime()

• debugLog()

Module Updates

Config Object Override

In ColdBox 7, you can now store the module configurations outside of the config/Coldbox.cfc. Especially in an application with many modules and many configs, the modulesettings would get really unruly and long. Now you can bring separation. This new convention will allow module override configurations to exist as their own configuration file within the application’s config folder.

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

component{

    function configure(){
        return {
            key : value
        };
    }

}

Injections

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

* controller
* coldboxVersion
* appMapping
* moduleMapping
* modulePath
* logBox
* log
* wirebox
* binder
* cachebox
* getJavaSystem
* getSystemSetting
* getSystemProperty
* getEnv
* appRouter
* router

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.

function development( original ){
   // add overides to the original struct
}

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

Module Injectors

We have an experimental feature in ColdBox 7 to enable per-module injectors. This will create a hierarchy of injections and dependency lookups for modules. This is in preparation for future capabilities to allow for multi-named modules in an application. In order to activate this feature you need to use the this.moduleInjector = true in your ModuleConfig.cfc

this.moduleInjector = true

Once enabled, please note that your module injector will have a unique name, and a link to the parent and root injectors and will ONLY know about itself and its children. Everything will be encapsulated under itself. No more global dependencies, we are now in module-only dependencies. This means each module must declare its dependencies beforehand.

ModuleConfig Injections

If the module injector is enabled, you will also get different injections in your ModuleConfig

Root Helpers

The supertype also has methods to interact with the root and module injector getRootWireBox() and getWireBox() for the module injector.

getRootWireBox().getInstance( "GlobalModel" )

Injection Awareness

Every module also can inject/use its models without the need to namespace them.

// Before, using the @contacts address
property name="contactService" inject="contactService@contacts";

// If using module injectors
property name="contactService" inject="contactService";

Config/Settings Awareness

You can now use the {this} placeholder in injections for module configurations-settings, and ColdBox will automatically replace it with the current module it's being injected in:

property name="mySettings" inject="coldbox:moduleSettings:{this}"
property name="myConfig" inject="coldbox:moduleConfig:{this}"

This is a great way to keep your injections clean without adhering to the module name.

Interceptor listen() Order

You can now use listen( closure, point ) or listen( point, closure) when registering closure interception points.

listen( ()=> log.info( "executed" ), "preProcess" )
// or
listen( "preProcess", ()=> log.info( "executed" ) )

ColdBox Delegates

Since WireBox introduced delegates, we have taken advantage of this great reusable feature throughout ColdBox. We have also created several delegates for your convenience that can be used via its name and the @cbDelegates namespace:

Let's say you have a security service that needs to get settings, announce events and render views:

component name="SecurityService"
    delegates="settings@cbDelegates, rendering@cbDelegates, interceptor@cbDelegates"{
    
    function login(){
        if( getSetting( "logEnabled" ) ){
            ... 
            
            var viewInfo = view( "security/logdata" );
            
        }
        
        ...
        
        announce( "onLogin" );
    }

}

Here you can find more information about the CBDelegates: https://s3.amazonaws.com/apidocs.ortussolutions.com/coldbox/7.0.0/coldbox/system/web/delegates/package-summary.html

User Identifier Providers

In previous versions of ColdBox, it would auto-detect unique request identifiers for usage in Flash Ram, storages, etc., following this schema:

1. If we have session enabled, use the jessionId or session URL Token

2. If we have cookies enabled, use the cfid/cftoken

3. If we have in the URL the cfid/cftoken

4. Create a unique request-based tracking identifier: cbUserTrackingId

However, you can now decide what will be the unique identifier for requests, flash RAM, etc by providing it via a coldbox.identifierProvider as a closure/lambda in your config/Coldbox.cfc

coldbox : {
    ...
    
    identifierProvider : () => {
        // My own logic to provide a unique tracking id
        return myTrackingID
    }
    
    ...

}

If this closure exists, ColdBox will use the return value as the unique identifier. A new method has also been added to the ColdBox Controller so you can retrieve this value:

controller.getUserSessionIdentifier()

The supertype as well so all handlers/layouts/views/interceptors can get the user identifier:

function getUserSessionIdentifier()

App Mode Helpers

ColdBox 7 introduces opinionated helpers to the FrameworkSuperType so you can determine if you are in three modes: production, development, and testing by looking at the environment setting:

function isProduction()
function isDevelopment()
function isTesting()

These super-type methods delegate to the ColdBox Controller. So that means that if you needed to change their behavior, you could do so via a Controller Decorator.

You can also use them via our new AppModes@cbDelegates delegate in any model:

component delegate="AppModes@cbDelegates"{}

Resource Route Names

When you register resourceful routes now, they will get assigned a name so you can use it for validation via routeIs() or for route link creation via route()

Baby got back()!

The framework super type now sports a back() function so you can use it to redirect back to the referer in a request.

function save( event, rc, prc ){
    ... save your work
    
    // Go back to where you came from
    back();
}

Here is the method signature:

/**
 * Redirect back to the previous URL via the referrer header, else use the fallback
 *
 * @fallback      The fallback event or uri if the referrer is empty, defaults to `/`
 * @persist       What request collection keys to persist in flash ram
 * @persistStruct A structure key-value pairs to persist in flash ram
 */
function back( fallback = "/", persist, struct persistStruct )

RequestContext Routing/Pathing Enhancements

The RequestContext has a few new methods to assist you when working with routes, paths, and URLs.

Native DateHelper

The FrameworkSuperType now has a getDateTimeHelper(), getIsoTime() methods to get access to the ColdBox coldbox.system.async.time.DateTimeHelper to assist you with all your date/time/timezone needs and generate an iso8601 formatted string from the incoming date/time.

getDateTimeHelper().toLocalDateTime( now(), "Americas/Central" )
getDateTimeHelper().getSystemTimezone()
getDateTimeHelper().parse( "2018-05-11T13:35:11Z" )
getIsoTime()

You can also use the new date time helper as a delegate in your models:

component delegate="DateTime@coreDelegates"{

}

View variables Scope Variables

You can now influence any view by injecting your own variables into a view's variables scope using our new argument: viewVariables. This is great for module developers that want native objects or data to exist in a view's varaibles scope.

view( view : "widget/messagebox", viewVariables : { wire : cbwire } 

view( view : "widget/client", viewVariables : { client : thisClient } )

Then you can use the wire and client objects in your views natively:

<cfif client.isLoaded()>
    <h1>#client.getFullName()#</h1>
</cfif>

Whoops! Upgrades

Whoops got even more love:

• SQL Syntax Highlighting

• JSON Pretty Printing

• JSON highlighting

• Debug Mode to show source code

• Production detection to avoid showing source code

• Rendering performance improvements

RESTFul Exception Responses

The RESTFul handlers have been updated to present more useful debugging when exceptions are detected in any call to any resource. You will now get the following new items in the response:

• environment

  • A snapshot of the current routes, URLs and event

• exception

  • A stack frame, detail, and type

{
  "data": {
    "environment": {
      "currentRoutedUrl": "restfulHandler/anError/",
      "timestamp": "2023-04-26T20:21:05Z",
      "currentRoute": ":handler/:action/",
      "currentEvent": "restfulHandler.anError"
    },
    "exception": {
      "stack": [
        "/Users/lmajano/Sites/projects/coldbox-platform/system/web/context/RequestContext.cfc:1625",
        "/Users/lmajano/Sites/projects/coldbox-platform/test-harness/handlers/restfulHandler.cfc:42",
        "/Users/lmajano/Sites/projects/coldbox-platform/system/RestHandler.cfc:58",
        "/Users/lmajano/Sites/projects/coldbox-platform/system/web/Controller.cfc:998",
        "/Users/lmajano/Sites/projects/coldbox-platform/system/web/Controller.cfc:713",
        "/Users/lmajano/Sites/projects/coldbox-platform/test-harness/models/ControllerDecorator.cfc:71",
        "/Users/lmajano/Sites/projects/coldbox-platform/system/Bootstrap.cfc:290",
        "/Users/lmajano/Sites/projects/coldbox-platform/system/Bootstrap.cfc:506",
        "/Users/lmajano/Sites/projects/coldbox-platform/test-harness/Application.cfc:90"
      ],
      "detail": "The type you sent dddd is not a valid rendering type. Valid types are JSON,JSONP,JSONT,XML,WDDX,TEXT,PLAIN,PDF",
      "type": "RequestContext.InvalidRenderTypeException",
      "extendedInfo": ""
    }
  },
  "error": true,
  "pagination": {
    "totalPages": 1,
    "maxRows": 0,
    "offset": 0,
    "page": 1,
    "totalRecords": 0
  },
  "messages": [
    "An exception ocurred: Invalid rendering type"
  ]
}

ColdBox DebugMode

ColdBox now has a global debugMode setting, which is used internally for presenting sources in Whoops and extra debugging parameters in our RESTFul handler. However, it can also be used by module developers or developers to dictate if your application is in debug mode or not. This is just a fancy way to say we trust the user doing the requests.

coldbox : {
    ...
    
    debugMode : true
    
    ...

}

You also have a inDebugMode() method in the main ColdBox Controller and the FrameworkSuperType that will let you know if you are in that mode or not.

boolean function inDebugMode()

// Debug mode report
if( inDebugMode() ){
    include "BugReport.cfm";
}

You can also use the AppModes@cbDelegates delegate to get access to the inDebugMode and other methods in your models:

component delegates="AppModes@cbDelegates"{

    ...
    if( inDebugMode() ){
    
    }
    ...

}

Testing Enhancements

Unload ColdBox is now false

All integration tests now won't unload ColdBox after execution. Basically, the this.unloadColdBox = false is now the default. This is to increase performance where each request run tries only to load the ColdBox virtual app once.

Environment Detection Method

All test bundles now get a getEnv() method to retrieve our environment delegate so you can get env settings and properties:

getEnv().getSystemSetting()
getEnv().getSystemProperty()
getEnv().getEnv()

LogBox Updates

$$\                          $$$$$$$\                      
$$ |                         $$  __$$\                     
$$ |      $$$$$$\   $$$$$$\  $$ |  $$ | $$$$$$\  $$\   $$\ 
$$ |     $$  __$$\ $$  __$$\ $$$$$$$\ |$$  __$$\ \$$\ $$  |
$$ |     $$ /  $$ |$$ /  $$ |$$  __$$\ $$ /  $$ | \$$$$  / 
$$ |     $$ |  $$ |$$ |  $$ |$$ |  $$ |$$ |  $$ | $$  $$<  
$$$$$$$$\\$$$$$$  |\$$$$$$$ |$$$$$$$  |\$$$$$$  |$$  /\$$\ 
\________|\______/  \____$$ |\_______/  \______/ \__/  \__|
                   $$\   $$ |                              
                   \$$$$$$  |                              
                    \______/                               

JSON Pretty Output

All logging messages in LogBox are now inspected for simplicity or complexity. If any extra argument is a complex variable, then LogBox will now serialize the output to JSON, and it will prettify it. This will allow for your log messages in your console to now look pretty!

[INFO ] 2023-04-26 15:48:47 coldbox.system.EventHandler Executing index action | ExtraInfo: {
	"ARCS":[
		1,
		2,
		3,
		4
	],
	"TEST":"Message goes here",
	"NAME":"Test",
	"WHEN":"April,
	26 2023 15:48:47 +0000"
}

Exception Improvements

If exception objects are being sent to any logger, LogBox will detect it and pretty print it back to the console instead of dumping a massive exception object.

[ERROR] 2023-04-26 16:10:25 coldbox.system.EventHandler Raw Exception ==> component [cbtestharness.models.myRequestContextDecorator] has no  function with name [getValuesss] | ExtraInfo:
ErrorType = expression
Message = component [cbtestharness.models.myRequestContextDecorator] has no  function with name [getValuesss]
StackTrace = lucee.runtime.exp.ExpressionException: component [cbtestharness.models.myRequestContextDecorator] has no  function with name [getValuesss]
TagContext =  ID: ??; LINE: 23; TEMPLATE: /Users/lmajano/Sites/projects/coldbox-platform/test-harness/handlers/testerror.cfc
 ID: ??; LINE: 1257; TEMPLATE: /Users/lmajano/Sites/projects/coldbox-platform/system/web/Controller.cfc
 ID: ??; LINE: 1006; TEMPLATE: /Users/lmajano/Sites/projects/coldbox-platform/system/web/Controller.cfc
 ID: ??; LINE: 713; TEMPLATE: /Users/lmajano/Sites/projects/coldbox-platform/system/web/Controller.cfc
 ID: ??; LINE: 71; TEMPLATE: /Users/lmajano/Sites/projects/coldbox-platform/test-harness/models/ControllerDecorator.cfc
 ID: ??; LINE: 290; TEMPLATE: /Users/lmajano/Sites/projects/coldbox-platform/system/Bootstrap.cfc
 ID: ??; LINE: 506; TEMPLATE: /Users/lmajano/Sites/projects/coldbox-platform/system/Bootstrap.cfc
 ID: ??; LINE: 90; TEMPLATE: /Users/lmajano/Sites/projects/coldbox-platform/test-harness/Application.cfc

ExtraInfo = ""

Closure Logging

In previous versions, you had to use the canxxxx method to determine if you can log at a certain level:

if( log.canInfo() ){
    log.info( "This is a log message", data );
}

if( log.canDebug() ){
    log.debug( "This is a debug message", data );
}

In ColdBox 7, you can use a one-liner by leveraging a lambda function:

log.info( () => "This is a log message", data )
log.debug( () => "This is a debug message", data )

Integration Testing Request Timeout

The RequestContext now has a setRequestTimeout() function that can provide timeouts in your application, and when in testing mode, it will mock the request timeout. This is essential to encapsulate this setting as if you have requested timeout settings in your app; they will override the ones in testing.

event.setRequestTimeout( 5 ) // 5 seconds

Release Notes

You can find the release notes on the page below:

Let's complete our saga into MVC by developing the M, which stands for model. 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

This layer is controlled by WireBox, the dependency injection framework within ColdBox, which will give you the flexibility of wiring your objects and persisting them for you.

Creating A Service Model

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

coldbox create service name="ContactService" methods="getAll" --open

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:

/**
 * I am a new Model Object
 */
component singleton accessors="true"{

	// Properties
	

	/**
	 * Constructor
	 */
	ContactService function init(){

		return this;
	}

	/**
	 * getAll
	 */
	function getAll(){

	}


}

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.

/**
 * I am a new Model Object
 */
component singleton accessors="true"{

	// Properties
	property name="data" type="array";

	/**
	 * Constructor
	 */
	ContactService function init(){
	  variables.data = [
            { "id"=1, "name"="coldbox" },
            { "id"=2, "name"="superman" },
            { "id"=3, "name"="batman" }
          ];
		return this;
	}

	/**
	 * Get all the contacts
	 */
	function getAll(){
	  return variables.data;
	}


}

Wiring Up The Model To a Handler

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

coldbox create handler name="contacts" actions="index" --open

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.

component{ 

    property name="contactService" inject="ContactService";

    any function index( event, rc, prc ){ 
        event.setView( "contacts/index" ); 
    }
}

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.

any function index( event, rc, prc ){
    prc.aContacts = contactService.getAll();
    event.setView( "contacts/index" );
}

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 in all layouts and views that allows you to generate semantic HTML without the needed verbosity of nesting or binding to ORM/Business objects.

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

<cfoutput>
<h1>My Contacts</h1>

#html.table( data=prc.aContacts, class="table table-striped" )#
</cfoutput>

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!

Tip You can find much more information about models and dependency injection in our full docs

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:

Getting Help

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

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.

Requirements

• Lucee 5+

• Adobe 2018+

IDE Tools

ColdBox has the following supported IDE Tools:

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

2. Embedded Runtime (120mb)

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

The ColdBox CLI is your best friend when developing with ColdBox and it's based on CommadBox. Just fire up that terminal and install it

Updating ColdBox

To update ColdBox from a previous version, just type update coldbox. You can also run the command outdated periodically to verify the packages in your application.

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

Handler Code

Go open the handlers/main.cfc and let's explore the code.

Let's recap: Every action in ColdBox receives three arguments:

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

Setting Views - Default Layout

This line event.setView( "main/index" ) in the index action told ColdBox to render a view back to the user found in views/main/index.cfm.

ColdBox also has the concept of layouts, which are essentially reusable views that can wrap up other views or layouts. They allow you to reuse content to render views/layouts inside a specific location in the CFML content. By convention, ColdBox looks for a layout called layouts/Main.cfm. This is yet another convention, the default layout. Your application can have many layouts or non-layouts at all.

Working With Incoming Data

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

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

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

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

Routing Params

Now let's expect the name as part of the URL pattern; open the config/Router.cfc and let's add another route:

We use the : colon to denote incoming URL/FORM placeholder params that, if found are translated to the request collection (rc). So let's try it out: http://localhost:{port}/hello/coldbox

You can use the route() to generate the URL with params in a nice struct way:

Need Help

IDE Tools

ColdBox has the following supported IDE Tools:

Install CommandBox and ColdBox CLI

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

Now let's install the ColdBox CLI

Now you will have the coldbox namespace of commands. Run coldbox help and discover it.

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 where 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 (Even though they might be more generated files/folders)

• 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

• tests - Your test harness for unit and integration testing

• views - Your HTML views will go here

Start It Up

Now that our shiny new MVC app is ready 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, and 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 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.

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 of your application. They can be services, entities, 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 #view()#. Add this line right before it to render out the message box that we set in our handler.

Here we leverage the cbMessagebox() helper function which the MessageBox module collaborates to all layouts, views, handlers and interceptors.

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.

• Default: The default app template

• 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

Scaffolding Our Application

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

File/Folder Conventions

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

Here are the major files you should know about:

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

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!