All the new ColdBox, CacheBox, WireBox, TestBox and LogBox docs can be found here:

help  namespaces  categories  help  rss feeds


<< Back to Dashboard


Exploring the MessageBox Plugin

The new docs for the MessageBox are here:


The MessageBox plugin is a very small but super useful UI plugin that allows you to create informative HTML messageboxes by leveraging ColdBox's FlashRAM to save messages across relocations.

Some convenience methods are:

  • info() : To render info message directly
  • warning() : To render a warning message
  • error() : To render an error message
  • setMessage(type, message, messageArray) : Set a message according to passed type

All convenience methods take in the following arguments:

Key Type Required Default Description
message string No A simple message string to show
messageArray Array No --- An array of messages to render separated by a
by default
getPlugin("MessageBox").info( "Hello" );
getPlugin("MessageBox").error( messageArray=[ "Hello", "You Welcome!" ] );
getPlugin("MessageBox").warning( messageArray=[ "Hello", "You Welcome!" ] );

getPlugin("MessageBox").setMessage( "info", "This is an info message" );

Rendering Messages

Once you have set you need to render messages. You have two choices for this:

  • renderIt([clearMessage=true], [template]) : To render the message
  • renderMessage(type, message, [template]) : A-la-carte rendering

The renderIt() method is the most typical and even if there are no messages to render the MessageBox is smart enough to not emit anything, so you can safely do this in your code:


#getPlugin("MessageBox").renderMessage( "info", "This is an info from message land!" )#

Important: Please note that the MessageBox plugin leverages the FlashRAM and all messages are cleared for you automatically after rendering. You can delay that if you use the clearMessage=false argument.

MessageBox Custom Templates

The MessageBox plugin will render out the MessageBox HTML according to our standards. However, we all know the developers are picky beings and very individualistic. Therefore, we allow the usage of your own templates for rendering out the MessageBox. You can do this by adding a custom setting: messagebox_template to your ConfigurationCFC for global usage of the template.

settings.messagebox_template = "include path";

The template can then be written:

	switch( msgStruct.type ){
		case "info" : {
			local.cssType = " alert-info";
			local.iconType = "icon-info-sign";
		case "error" : {
			local.cssType = " alert-error";
			local.iconType = "icon-minus-sign";
		default : {
			local.cssType = "";
			local.iconType = "icon-warning-sign";
<div class="alert#local.cssType#" style="min-height: 38px">
	<button type="button" class="close" data-dismiss="alert">×</button>
	<i class="#local.iconType# icon-large icon-2x pull-left"></i> #msgStruct.message#

You can also ignore the global setting and use the template argument via the renderIt() and renderMessage() methods:

#getPlugin("MessageBox").renderMessage(type="info", message="Hello", template=path)#

Appending/PrePending Messages

You can also append messages to the MessageBox FlashRAM entry by leveraging the, drum roll please......, append() or appendArray() methods:

getPlugin("MessageBox").append( "Hello" );
getPlugin("MessageBox").appendArray( [ "Hello", "You Welcome!" ] );
getPlugin("MessageBox").prependArray( [ "Hello", "You Welcome!" ] );

Utility Methods

The plugin also sports some convenience methods:

  • getMessage() : Retrieve the raw message structure
  • clearMessage() : Clear the Flash RAM
  • isEmptyMessage() : Verify if we have messages to show

Custom Metadata

You can also store custom metadata alongside your custom messages. This is great for storing any type of information you might need again back when rendering the messages. For this we have the following methods:

  • putData(array data) : Add an array of data that can be used for arbitrary stuff
  • addData(key, value) : Store key-value pairs of metadata alongside the message
  • getData([clearData=true]) : Get your array of data back
  • getDataJSON([clearData=true]) : Get your array of data back as JSON

Custom CSS

If you want to style your own MessageBox you will need to create a setting called: messagebox_style_override in your settings structure in your ConfigurationCFC and set it to true. Then make sure the CSS for the MessageBox exists in the request, usually in your main CSS file or layout:

settings = {
	messagebox_style_override = true

Custom Messages

You can also render messages a-la-carte or on-demand by using the renderMessage method:

#getPlugin("MessageBox").renderMessage("info", "Info Message")#

#getPlugin("MessageBox").renderMessage("warning", flash.get('notice'))#

Download in other Formats:
markup Markup | html HTML | word Word

comments Comments (0)

ColdBox Books