Cbmessagebox

CBMessagebox Skill

When to Use This Skill

Load this skill when:

• Displaying success/error/warning/info notifications after form submissions or redirects
• Integrating flash-scope messaging into a ColdBox layout or view
• Checking for specific message types before rendering
• Clearing messages programmatically
• Customizing the message template to match a CSS framework

Installation

box install cbmessagebox

Core API

Injection

// cbmessagebox is available as a mixin in all ColdBox handlers and views
// Direct injection when needed in services or interceptors:
property name="messagebox" inject="messagebox@cbmessagebox";

Setting Messages (in Handlers)

// Types: info | success | warning | error
messagebox.info(    "Profile updated." )
messagebox.success( "Changes saved successfully!" )
messagebox.warning( "Please verify your email address." )
messagebox.error(   "An error occurred while processing your request." )

Append Multiple Messages

messagebox.info( "Step 1 complete." )
messagebox.info( "Step 2 complete." )

Clear Messages

messagebox.clearMessage( "info" )   // clear specific type
messagebox.clearAll()               // clear all types

Production Patterns

Handler — CRUD with Flash Messages

function save( event, rc, prc ) {
    try {
        // Validate first
        validateOrFail( target = rc, constraints = "userConstraints" )

        userService.update( rc.id, rc )

        messagebox.success( "User updated successfully." )
        relocate( "users.index" )

    } catch ( ValidationException e ) {
        messagebox.error( "Please fix the validation errors below." )
        flash.put( "validationResult", e.getValidationResult() )
        relocate( "users.edit" )

    } catch ( any e ) {
        messagebox.error( "An unexpected error occurred: #e.message#" )
        relocate( "users.edit" )
    }
}

function delete( event, rc, prc ) {
    userService.delete( rc.id )
    messagebox.success( "User deleted." )
    relocate( "users.index" )
}

Layout — Render Messages Once

<!--- In your main layout, just before or after the body --->
<cfif messagebox.hasMessage()>
    #messagebox.renderit()#
</cfif>

Render Specific Type

<!--- Render only errors at top of a form --->
<cfif messagebox.hasMessage( "error" )>
    <div class="alert-block">
        #messagebox.renderMessage( "error" )#
    </div>
</cfif>

<!--- Render all messages --->
#messagebox.renderit()#

Custom Bootstrap 5 Template

// In config or an interceptor's configure method
messagebox.setTemplate(
    "<div class='alert alert-{type} alert-dismissible fade show' role='alert'>" &
    "{message}" &
    "<button type='button' class='btn-close' data-bs-dismiss='alert'></button>" &
    "</div>"
)

Available tokens in the template: {type}, {message}.

Best Practices

• Always relocate() after setting a message — never render a page in the same request that sets a flash message (post-redirect-get pattern)
• Render messages in the layout — not in individual views — for consistent placement
• Use hasMessage() before rendering — silent when no messages exist
• Match {type} values to CSS framework class names by customizing the template
• Prefer specific types (error vs warning) so users understand severity

Documentation

• cbmessagebox: https://github.com/coldbox-modules/cbmessagebox