Skip to content

SKILL.md

Latest commit

 

History

History
311 lines (261 loc) · 7.73 KB

SKILL.md

File metadata and controls

311 lines (261 loc) · 7.73 KB
name coldbox-layout-development
description Use this skill when creating ColdBox layouts (master page templates), building admin layouts, creating reusable view partials, implementing nested content rendering with renderView(), switching layouts dynamically per handler, or organizing HTML structure around content views.

Layout Development

When to Use This Skill

Use this skill when creating ColdBox layout templates that wrap views with a consistent HTML structure (navigation, headers, footers).

Language Mode Reference

Examples use BoxLang (.bx) syntax by default. Adapt for your target language:

Concept BoxLang (.bx) CFML (.cfc)
Class declaration class [extends="..."] { component [extends="..."] {
DI annotation @inject above property name="svc"; property name="svc" inject="svc";
View templates .bxm suffix .cfm / .cfml suffix
Tag prefix <bx:if>, <bx:output>, <bx:set> <cfif>, <cfoutput>, <cfset>

CFML Compat Mode: With BoxLang + CFML Compat module, .bx and .cfc files coexist freely. BoxLang-native classes use class {} (.bx files); CFML-compat classes use component {} (.cfc files).

Core Concepts

ColdBox layouts:

  • Live in layouts/ directory
  • Wrap rendered views with headers, footers, navigation
  • Default layout is Main.cfm
  • Views render within layouts via #renderView()#
  • Can be overridden per handler or per action
  • Support nested partials with #renderView( view = "shared/..." )#

Main Layout (BoxLang/CFML)

<!--- layouts/Main.cfm --->
<!DOCTYPE html>
<html lang="en">
<head>
    <cfoutput>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>#encodeForHTML( prc.pageTitle ?: "My Application" )#</title>
    <link rel="stylesheet" href="/includes/css/app.css">
    </cfoutput>
</head>
<body>
    <!--- Navigation partial --->
    #renderView( "shared/_nav" )#

    <!--- Flash messages --->
    #renderView( "shared/_flash" )#

    <!--- Main content view --->
    <main class="container">
        #renderView()#
    </main>

    <!--- Footer partial --->
    #renderView( "shared/_footer" )#

    <script src="/includes/js/app.js"></script>
</body>
</html>

Admin Layout

<!--- layouts/Admin.cfm --->
<!DOCTYPE html>
<html lang="en">
<head>
    <cfoutput>
    <meta charset="UTF-8">
    <title>Admin | #encodeForHTML( prc.pageTitle ?: "Administration" )#</title>
    <link rel="stylesheet" href="/includes/css/admin.css">
    </cfoutput>
</head>
<body class="admin">
    #renderView( "admin/shared/_header" )#

    <div class="admin-wrapper">
        <aside>
            #renderView( "admin/shared/_sidebar" )#
        </aside>
        <main class="admin-content">
            #renderView( "shared/_flash" )#
            #renderView()#
        </main>
    </div>

    #renderView( "admin/shared/_footer" )#
    <script src="/includes/js/admin.js"></script>
</body>
</html>

Named Layouts in ColdBox.cfc

// config/ColdBox.cfc
class ColdBox extends coldbox.system.Coldbox {
    function configure() {
        layoutSettings = {
            defaultLayout : "Main",
            defaultView   : "main/index"
        }
    }
}

CFML (.cfc):

// config/ColdBox.cfc
component extends="coldbox.system.Coldbox" {
    function configure() {
        layoutSettings = {
            defaultLayout : "Main",
            defaultView   : "main/index"
        }
    }
}

Switching Layouts per Handler

// Admin handler — use admin layout for all actions
class Admin extends coldbox.system.EventHandler {

    this.preHandler = "setAdminLayout"

    private function setAdminLayout( event, rc, prc, action ) {
        event.setLayout( "Admin" )
        prc.section = "admin"
    }

    function index( event, rc, prc ) {
        prc.pageTitle = "Dashboard"
        event.setView( "admin/dashboard" )
    }
}

// Per-action layout override
function preview( event, rc, prc ) {
    event.setView( view = "report/print", layout = "Print" )
}

function modal( event, rc, prc ) {
    event.setView( "users/modal" ).noLayout()
}

CFML (.cfc):

// Admin handler — use admin layout for all actions
component extends="coldbox.system.EventHandler" {

    this.preHandler = "setAdminLayout"

    private function setAdminLayout( event, rc, prc, action ) {
        event.setLayout( "Admin" )
        prc.section = "admin"
    }

    function index( event, rc, prc ) {
        prc.pageTitle = "Dashboard"
        event.setView( "admin/dashboard" )
    }
}

// Per-action layout override
function preview( event, rc, prc ) {
    event.setView( view = "report/print", layout = "Print" )
}

function modal( event, rc, prc ) {
    event.setView( "users/modal" ).noLayout()
}

Shared Partials

<!--- views/shared/_nav.cfm --->
<cfoutput>
<nav class="navbar">
    <a href="#buildLink( 'main.index' )#" class="brand">My App</a>
    <ul>
        <cfif auth().check()>
            <li><a href="#buildLink( 'dashboard.index' )#">Dashboard</a></li>
            <li><a href="#buildLink( 'security.logout' )#">Logout</a></li>
        <cfelse>
            <li><a href="#buildLink( 'security.login' )#">Login</a></li>
        </cfif>
    </ul>
</nav>
</cfoutput>

<!--- views/shared/_flash.cfm --->
<cfoutput>
<cfif flash.exists( "success" )>
    <div class="alert alert-success">#encodeForHTML( flash.get( "success" ) )#</div>
</cfif>
<cfif flash.exists( "error" )>
    <div class="alert alert-error">#encodeForHTML( flash.get( "error" ) )#</div>
</cfif>
<cfif flash.exists( "errors" )>
    <div class="alert alert-error">
        <ul>
        <cfloop array="#flash.get( 'errors' )#" item="e">
            <li>#encodeForHTML( e )#</li>
        </cfloop>
        </ul>
    </div>
</cfif>
</cfoutput>

Print / Email Layouts

<!--- layouts/Print.cfm — no navigation, clean for printing --->
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <style>
        body { font-family: Arial, sans-serif; margin: 40px; }
        @media print { .no-print { display: none; } }
    </style>
</head>
<body>
    #renderView()#
    <div class="no-print">
        <button onclick="window.print()">Print</button>
    </div>
</body>
</html>

<!--- layouts/Email.cfm — minimal for email rendering --->
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <style>
        body { font-family: Arial, sans-serif; color: #333; }
    </style>
</head>
<body>
    <table width="600" align="center">
        <tr><td>#renderView()#</td></tr>
    </table>
</body>
</html>

Module-Specific Layouts

<!--- modules_app/admin/layouts/Admin.cfm --->
<!DOCTYPE html>
<html>
<head>
    <title>Admin Module</title>
</head>
<body>
    #renderView( view = "shared/_nav", module = "admin" )#
    <main>#renderView()#</main>
</body>
</html>
// ModuleConfig.cfc — set module default layout
class ModuleConfig {
    function configure() {
        layoutSettings = {
            defaultLayout : "Admin"
        }
    }
}

CFML (.cfc):

// ModuleConfig.cfc — set module default layout
component {
    function configure() {
        layoutSettings = {
            defaultLayout : "Admin"
        }
    }
}

Layout Best Practices

  • Name layouts semantically (Main, Admin, Print, Email, Minimal)
  • Use #renderView()# (no args) to inject the current view content
  • Prefix shared partials with _ by convention (_nav.cfm, _flash.cfm)
  • Keep layouts free of business logic — they should only compose HTML
  • Set the default layout in layoutSettings.defaultLayout in ColdBox.cfc
  • Use .noLayout() for AJAX responses, modals, and email rendering
  • Place module-specific layouts in the module's layouts/ folder