Compatability Guide for ColdBox 2.5.0

This guide is a review of the major changes starting in ColdBox 2.5.0. The major compatibility issues will be covered and also how to smoothly upgrade to this release from previous ColdBox versions. You can also check out the What's New with 2.5.0 guide to give you an in-depth overview.

Application.cfc Support

You will have to upgrade and replace your current Application.cfc and index.cfm files with the ones included in the Application Template folder. 2.5.0 includes a new bootstrapper and new abilities to register your application.

IMPORTANT NOTE:So please update these important files or YOU WILL SEE WEIRD STUFF.

ColdBox Cache

• The updated ColdBox Cache is now case-sensitive for the cache keys. So please make sure you have the correct syntax when using the keys.
• The cache also includes eviction policies LFU & LRU which will expire the objects for the next reap. It will not do immediate eviction, since the object might still be in use.

Getting Settings

The get settings processor has been updated to allow retrieval without evaluations. This means, that you can no longer use structure traversals via the name of the setting. You can retrieve the structure setting and then traverse it outside of the method call. Look below for source samples, considering we have a Structure called myStructure with two keys: name & date

Deprecated Calls

<cfset name = getSetting("myStructure.name")>
<cfoutput>#getSetting("myStructure.date")#</cfoutput>

New Calls

<cfset name = getSetting("myStructure").name>
<cfoutput>#getSetting("myStructure").date#</cfoutput>

Messagebox Plugin

The messagebox plugin has been totally revamped to a css design. The MessageboxStyleClass setting has been deprecated and replaced with a new setting: MessageboxStyleOverride. This setting is a boolean setting that determines wether to override the css used when creating the messagebox; the default value is FALSE. So now you can create your own styles and use your own images for the messagebox. Below you can see the actual css of the messagebox and the output html you will be able to override.

Messagebox Setting Source

<Setting name="MessageboxStyleOverride" value="true" />

Messagebox CSS Source

<style>
.cbox_messagebox{
        font-size: 13px;
        font-weight: bold;
}
.cbox_messagebox_info{
        background: ##D1E6EF url(/coldbox/system/includes/images/cmsg.gif) no-repeat scroll .5em 50%;
        border: 1px solid ##2580B2;
        margin: 0.3em;
        padding: 0pt 1em 0pt 3.5em;
}
.cbox_messagebox_warning{
        background: ##FFF2CF url(/coldbox/system/includes/images/wmsg.gif) no-repeat scroll .5em 50%;
        border: 1px solid ##2580B2;
        margin: 0.3em;
        padding: 0pt 1em 0pt 3.5em;
}
.cbox_messagebox_error{
        background: ##FFFFE0 url(/coldbox/system/includes/images/emsg.gif) no-repeat scroll .5em 50%;
        border: 1px solid ##2580B2;
        margin: 0.3em;
        padding: 0pt 1em 0pt 3.5em;
}
</style>

Messagebox HTML Source

<div class="#msgClass#">
  <p class="cbox_messagebox">#msgStruct.message#</p>
</div>

HandlersIndexAutoReload Setting Updated

For some reason this setting was also cleaning the cache. This setting should only reindex the handler registration for development purposes. This is a quick way to reindex the handlers with no reloading of the entire app. For version 2.5.0 and above this setting will NOT reload the cache, it will just reload the handler registration index.

Controller getMyPlugin() deprecated

The controller's method getMyPlugin() has been deprecated in version 2.5.0 in order to provide a single entry point into the plugin service. The facade method in the super type that all handlers and plugins inherit will remain the same. The main change is only in the controller. So if you have the following calls, then please update your code:

Deprecated Calls

<cfset controller.getMyPlugin("myplugin")>

New Calls

<!--- call via facade --->
<cfset getMyPlugin("myplugin")>
<!--- call via facade --->
<cfset getPlugin("myplugin",true)>
<!--- Call directly --->
<cfset controller.getPlugin("myplugin",true)>

FileWriter Plugin Deprecated

The FileWriter plugin has been deprecated since it was no longer needed by the core. You can still find it as a custom plugin here: cbCustomPlugins? and use it as a custom plugin.

FileUtilities Plugin renamed to Utilities Plugin

This is a long idea in the making and I was too lazy to change it. Now it has been correctly changed. The plugin is now called Utilities and it functions as so. The 2.5 distribution will include a compatability plugin: FileUtilties for compatability. However, it will be completely removed by the 2.7 version. So please make sure you update your calls to this plugin like so:

Deprecated Calls

<cfset getPlugin("FileUtilities")>

New Calls

<cfset getPlugin("Utilities")>