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

Release Notes

Bugs

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

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

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

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

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

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

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

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

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

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

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

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

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

New Features

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

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

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

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

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

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

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

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

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

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

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

Improvements

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

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

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

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

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

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

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

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

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

Release Notes

Bugs

• [COLDBOX-434] - Controller loc.args is referenced and not existing in pre{Actions}

• [COLDBOX-435] - Module routing was not respecting package resolving within handlers

• [COLDBOX-441] - onError handler doesn't work

• [COLDBOX-454] - abstractFlashScope getKeys() doesn't work

Improvements

• [COLDBOX-425] - Modules that include applicationhelpers are incompat with modules.autoReload setting, add recognition

• [COLDBOX-440] - Add x-forwarded-proto checks on isSSL() verifications to allow for proxy configuraitons

• [COLDBOX-444] - Better locking naming technique to avoid server-wide collisions

• [COLDBOX-455] - Ability to test ORM entities with base cases if loading ColdBox or using entity injection

New Features

• [COLDBOX-430] - Update application templates to use new logo

• [COLDBOX-448] - Add session and application timeouts to testing harnesses

• [COLDBOX-449] - Create a new testing annotation to control if application should be teardown in integration tests

• [COLDBOX-457] - Create REST application template for ColdBox

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

Module Parent Settings

We have now introduced a standardized approach to defining/overriding module settings in your module and overrides via the parent application. You can now define a moduleSettings structure in your config/ColdBox.cfc which will hold all the override settings for any modules you have installed in your system.

Module developers can then create defaults for those settings in a modules's ModuleConfig.cfc via the settings structure.

// myModule/ModuleConfig.cfc
component {
  function configure() {
    settings = {
      someSetting = "default",
      anotherSetting = "default"
    };
  }
}

// config/ColdBox.cfc
component {
  function configure() {
    moduleSettings = {
      myModule = {
        someSetting = "overridden" 
      }
    };
  }
}

// end result
{
  someSetting = "overridden",
  anotherSetting = "default"
}

Global invalidHTTPMethodHandler

You can now define a global invalid HTTP method handler in your coldbox configuration structure:

coldbox = {
  invalidHTTPMethodHandler = "main.invalidHTTP"
}

This will provide your application with error consistency when building RESTFul services.

New allowedMethods annotation for handlers

Your event handler actions can now define their allowed HTTP methods of execution via the allowedMethods annotation:

function index( event, rc, prc) allowedMethods="GET,POST"{
...
}

New convention modules_app

With the introduction of CommandBox we can now have tracked modules and un-tracked modules in a ColdBox application. The default convention for modules called modules is now the default location of tracked CommandBox modules. The new convention modules_app is for your own custom un-tracked modules.

What is tracked? Modules that are tracked by CommandBox and usually not added to source control. CommandBox controls their installation, updating, etc.

Interceptors get rc and prc references

All interceptor methods now receive a reference to rc and prc for convenience:

function preProcess( event, rc, prc, interceptData, buffer )

String Builders

Internal concatenation tools and interceptor response buffers have been migrated to Java String Builders for a more awesome performance updates.

Binary HTTP Content

You can now receive and decode binary HTTP content when doing RESTFul services

Models in Modules accept aliases now

Models in Modules can now have name aliases via the alias annotation or binder alias definitions.

HTTP Method Spoofing

Although we have access to all these HTTP verbs, modern browsers still only support GET and POST. With ColdBox and HTTP Method Spoofing, you can take advantage of all the HTTP verbs in your web forms.

By convention, ColdBox will look for an _method field in the form scope. If one exists, the value of this field is used as the HTTP method instead of the method that was made. For instance, the following block of code would execute with the DELETE action instead of the POST action:

<cfoutput>
<form method="POST" action="#event.buildLink('posts/#prc.post.getId()#')#">
    <input type="hidden" name="_method" value="DELETE" />
    <button type="submit">Delete</button>
</form>
</cfoutput>

You can manually add these _method fields yourselves, or you can take advantage of ColdBox's HTML Helper.

<cfoutput>
#html.startForm( action = "posts.#prc.post.getId()#", method="DELETE" )#
    #html.submitButton( name = "Delete", class = "btn btn-danger" )#
#html.endForm()#
</cfoutput>

Release Notes

Bugs

• [COLDBOX-479] - onInvalidHTTPMethod not firing with SES Interceptor

• [COLDBOX-512] - ColboxProxy.cfc has reference to method tracer - which no longer exists in that component.

• [COLDBOX-515] - Exception handling broken for customErrorTemplate when application relative path used

• [COLDBOX-517] - CF mapping's for modules don't get created for proxy requests

• [COLDBOX-520] - Only remove the scriptname from the pathinfo if it is the first element in the pathinfo

• [COLDBOX-521] - afterAspectsLoad was missing from core

• [COLDBOX-527] - bug report view is not thread safe

• [COLDBOX-528] - Coldbox Event Cache discards the Content-Type when caching non renderdata results

• [COLDBOX-529] - Object in RC or PRC causes async interceptors to fail

• [COLDBOX-534] - getHTMLBaseURL returns with a double slash at the end,

• [COLDBOX-537] - ColdBox Cache Flash not discovering session/cookie as app has not loaded first

• [COLDBOX-539] - Private event actions are no longer executable (regression)

New Features

• [COLDBOX-371] - Convention to override a module's settings in an application or parent module

• [COLDBOX-505] - New coldbox directive: invalidHTTPMethodHandler that will fire globally if an action is called with an invalid HTTP Method

• [COLDBOX-511] - New action annotation "allowedMethods" so you can allow inline annoation for allowed HTTP Verbs thanks to Nic Tunney

• [COLDBOX-522] - Add rc and prc available directly to custom error templates

• [COLDBOX-525] - HTTP Method Spoofing for Forms

• [COLDBOX-530] - Add 'modules_app' as a default external location instead of manually adding it.

• [COLDBOX-540] - Interception points get reference to rc and prc now.

• [COLDBOX-541] - invokerasync was not passing the buffer

Improvements

• [COLDBOX-502] - RequestBuffers now leverage string builders.

• [COLDBOX-513] - Calling processState from within an interceptor clears buffer

• [COLDBOX-531] - execute() in BaseTestCase now uses the default event (defined in config/ColdBox.cfc) if / is passed in as the route

• [COLDBOX-532] - event.getHTTPContent() doesn't work on binary encoding

• [COLDBOX-536] - Rendered output has ALWAYS a precedent empty line, delete it!

• [COLDBOX-538] - Alises in module models aren't picked up

ColdBox Manual - v5.0.0

Versioning

And constructed with the following guidelines:

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

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

• Bug fixes and misc changes bumps the patch

License

• Copyright by Ortus Solutions, Corp

• ColdBox is a registered trademark by Ortus Solutions, Corp

Info: The ColdBox Websites, Documentation, logo and content have a separate license and they are a separate entity.

Discussion & Help

Reporting a Bug

Professional Open Source

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

• Security Hardening

• Code Reviews

Resources

HONOR GOES TO GOD ABOVE ALL

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

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

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

ColdBox 3.x Compatibility Module

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

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

ColdFusion 8 Support Dropped

ColdFusion 8 support has been dropped.

Application.cfc Bootstrap changed

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

Sample Application.cfc using inheritance

Async Loggers Dropped

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

• AsyncDBAppender -> DBAppender

• AsyncFileAppender -> FileAppender

• AsyncRollingFileAppender -> RollingFileAppender

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

Plugins Removed

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

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

Plugin Base Class

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

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

New Core Modules

Storages

• Session Storage Plugin

• Application Storage Plugin

• Client Storage Plugin

• Cluster Storage Plugin

• Cookie Storage Plugin

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

Instead of using:

You will instead call

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

MessageBox

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

AntiSamy

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

MailServies

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

Validation

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

• validateModel()

• getValidationManager()

ColdBox Debugger

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

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

• debuggerService@cbdebugger

• timer@cbdebugger

JavaLoader

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

i18n

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

• i18n@cbi18n

• resourceService@cbi18n

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

• getFWLocale()

• setFWLocale()

• getResource()

ORM

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

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

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

Commons

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

• JVMUtils Plugin

• Zip Plugin

• DateUtils Plugin

• QueryHelper Plugin

• FileUtils Plugin

• Utilities Plugin

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

• JVMUtils@cbcommons

• Zip@cbcommons

• DateUtils@cbcommons

• QueryHelper@cbcommons

• FileUtils@cbcommons

ioc

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

Feeds

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

• FeedReader@cbfeeds

• feedGenerator@cbfeeds

Soap

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

Security

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

WireBox DSL Namespaces

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

Model Convention

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

ColdBox OCM Dropped

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

JSON Plugin Dropped

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

BeanFactory Plugin Dropped

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

Autowire Interceptor Dropped

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

Logger Plugin Dropped

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

Renderer Plugin Dropped

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

HTMLHelper Plugin Dropped

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

XMLConverter Plugin Dropped

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

Validator Plugin Dropped

Removed from core

Datasource Bean Dropped

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

Would become this:

Exception Bean moved to prc in the exceptionHandler

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

afterAspectsLoad interception point removed

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

Introduction

WireBox 2.0.0 is a major release of our Dependency Injection and AOP library with some major fixes and some cool new updates.

Release Notes

You can find the release version information here:

Bugs

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

Improvements

• [] -binder.mapDirectory now skips hidden dirs

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

New Features

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

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

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

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

Major Enhancements

ColdBox DSL Updates

The ColdBox injection DSL has had major updates to get to the ColdBox 4 standards.

• All ocm injections have been removed in preference to

  cachebox injection DSL

• The coldbox:cachemanager DSL has been removed in preference to

  cachebox injection DSL

• All plugin injections have been deprecated in preference to

  model/object injections

• New coldbox:renderer dsl to inject the new ColdBox system

  renderer

Forced Mappings

The map() function on the Configuration Binder now has a force argument which allows you to map no matter if the mapping exists or not already.

Dynamic Custom DSL Registration

Injectors allow you to register custom DSLs at runtime by using the registerDSL() method on any injector. This feature was mostly done for modules, so they could enhance WireBox in a ColdBox context. However, this also allows you to leverage this in any non-ColdBox applications.

Injection By Type: byType DSL

We have expanded our custom DSL and injectors to allow you to do injection by ColdFusion types. This feature is more in-line with features from Java or static languages were you can tell injectors to inject by argument or property type. Let's say you have a package of interfaces with subpackages of implementations:

You then want to rely on the interface type field of properties in my dependent CFCs and leveraging the byType injection DSL. You would first map the right implementation using the alias as the name of the Interface.

Introduction

LogBox 2.0.0 is a major release, mostly aligned to support our ColdBox 4 release.

Release Notes

You can find the release version information here:

Bug

• [] - Truncating of category data to avoid error on insertion on DB Appender

Improvement

• [] - deprecate logbox xml support

New Feature

• [] - Ability to asynchronize any logger via new 'async' property

Introduction

CacheBox 2.0.0 is a major release, mostly aligned to support our ColdBox 4 release.

Release Notes

You can find the release version information here: https://ortussolutions.atlassian.net/browse/CACHEBOX/fixforversion/12303

Improvements

• [CACHEBOX-25] - Deprecate Cachebox xml config support

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

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

• The majority of code generation and running of examples are done via CommandBox: The ColdFusion (CFML) CLI, Package Manager, REPL - http://www.ortussolutions.com/products/commandbox

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

External Trademarks & Copyrights

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

Notice of Liability

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

Contributing

We highly encourage contribution to this book and our open source software. The source code for this book can be found in our 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 is 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 that either have no families or have been abandoned. This is good earth to seed and plant.

Luis Fernando Majano Lainez

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

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

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

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

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

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

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

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

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

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

Contributors

Jorge Emilio Reyes Bendeck

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

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

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

Brad Wood

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

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

Brad's CommandBox Snake high score is 141.

Introduction

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

CommandBox

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

box install coldbox-be

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

// Get help on all the ColdBox commands
coldbox help

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

Internal Library Updates

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

• WireBox 2.0.0

• CacheBox 2.0.0

• LogBox 2.0.0

Major Updates

Performance Updates

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

RunEvent Caching

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

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

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

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

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

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

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

Model called Models

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

onInvalidHTTPMethod Handler Convention

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

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

HTTP Content Auto Marshalling

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

1. json

2. xml

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

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

SES regex route placeholders

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

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

New Global View Helper

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

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

Application Template Java Support

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

New Core Modules

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

• ColdBox Debugger

box install cbdebugger

• Storages

box install cbstorages

• Feeds

box install cbfeeds

• Commons

box install cbcommons

• i18n

box install cbi18n

• ORM

box install cborm

• ioc

box install cbioc

• JavaLoader

box install cbjavaloader

• AntiSamy

box install cbantisamy

• MailServies

box install cbmailservices

• MessageBox

box install cbmessagebox

• Soap

box install cbsoap

• Security

box install cbsecurity

• Validation

box install cbvalidation

New Anti-Forgery Module

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

box install csrf

ORM Module Updates

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

• Lucee multi-datasource support

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

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

  join

• Script updates

New System Renderer

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

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

  syntax

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

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

  WireBox mapping (Renderer@coldbox)

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

  by calling the getRenderer() method in the super type

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

New Error Template

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

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

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

Remote Proxies Autowired

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

/remote/myProxy.cfc

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

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

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

Handlers Are Now Singletons

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

Bootstrap Enhancement

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

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

}

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

Module Enhancements

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

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

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

  property rather easily and directly.

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

• Modules no longer register their models folder as scan locations

  to increase performance.

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

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

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

  issues instead of basically restarting the entire CFML engine to

  make it work.

Module Inception

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

Module Config New Properties

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

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

Module Dependencies

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

Module Aliases

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

Module CF Mappings

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

Module Models Auto Mapped

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

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

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

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

Module Bundles

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

coldbox-bundle
  * cbstorages
  * cborm
  * cbsecurity