Templates

Templates define your component's HTML presentation layer using standard HTML/CFML tags. They're dynamic, reactive views that access your component's data properties and methods to create interactive user experiences.

CBWIRE automatically looks for template files with the same name as your component. Templates can use BoxLang tags like <bx:if>, <bx:loop>, and <bx:output> or CFML tags like <cfif>, <cfloop>, and <cfoutput> alongside wire directives for reactive behavior.

BoxLang

<!-- wires/greeter.bxm -->
<bx:output>
<div>
    <h1>#greeting#</h1>
    <button wire:click="updateGreeting">Update</button>
    
    <bx:if timeOfDay() EQ "morning">
        <p>Good morning!</p>
    <bx:else>
        <p>Good day!</p>
    </bx:if>
</div>
</bx:output>

CFML

File Structure

CBWIRE uses automatic file matching for components and templates:

./wires/Counter.bx     <!-- BoxLang class -->
./wires/Counter.cfc    <!-- CFML component -->
./wires/counter.bxm    <!-- BoxLang template -->
./wires/counter.cfm    <!-- CFML template -->

Template Requirements

Templates must have a single outer element for proper DOM binding:

<!-- ✅ Good: Single outer element -->
<div>
    <h1>My Component</h1>
    <p>Content here</p>
</div>

<!-- ❌ Bad: Multiple outer elements -->
<div>Component header</div>
<div>Component body</div>

Data Properties

Access component data properties directly by name:

BoxLang

// wires/UserCard.bx
class extends="cbwire.models.Component" {
    data = {
        "name": "John Doe",
        "email": "[email protected]",
        "isActive": true
    };
}

CFML

BoxLang

<!-- wires/userCard.bxm -->
<bx:output>
<div class="user-card">
    <h2>#name#</h2>
    <p>Email: #email#</p>
    <bx:if isActive>
        <span class="active">Active User</span>
    </bx:if>
</div>
</bx:output>

CFML

Computed Properties

Define computed properties with the computed annotation and call them as methods:

BoxLang

// wires/Dashboard.bx
class extends="cbwire.models.Component" {
    data = {
        "tasks": [
            {"id": 1, "completed": true},
            {"id": 2, "completed": false}
        ]
    };

    function completedCount() computed {
        return data.tasks.filter(function(task) {
            return task.completed;
        }).len();
    }
}

CFML

<!-- Template usage -->
<div>
    <h1>Task Progress</h1>
    <p>Completed: #completedCount()# of #tasks.len()#</p>
</div>

Computed properties are cached and only executed when first called or when their dependencies change. See Computed Properties for details.

Explicit Templates

Override default template location using the onRender() method:

BoxLang

// wires/CustomComponent.bx
class extends="cbwire.models.Component" {
    function onRender() {
        return template("shared.CustomLayout");
    }
    
    // With parameters
    function onRender() {
        return template("shared.UserCard", {
            "theme": "dark",
            "showAvatar": true
        });
    }
    
    // Inline template
    function onRender() {
        return "<div><h1>Simple Component</h1></div>";
    }
}

CFML

Helper Methods

Access global helper methods from installed ColdBox modules:

<!-- Using cbi18n module -->
<div>
    <h1>#$r("welcome.title")#</h1>
    <p>#$r("welcome.message")#</p>
</div>

<!-- Using cbstorages module -->
<div>
    <p>Session ID: #getSessionStorage().getId()#</p>
</div>

ColdBox Event Object

Access the ColdBox event object (request context) directly in your templates to use helpful methods like event.buildLink() for generating URLs:

BoxLang

<!-- wires/navigation.bxm -->
<bx:output>
<nav>
    <ul>
        <li><a href="#event.buildLink('dashboard')#">Dashboard</a></li>
        <li><a href="#event.buildLink('profile')#">Profile</a></li>
        <li><a href="#event.buildLink('settings')#">Settings</a></li>
    </ul>
</nav>
</bx:output>

CFML

Be cautious when using event.getCollection() (RC scope) or event.getPrivateCollection() (PRC scope) in templates. CBWIRE fires background requests to /cbwire/update on component re-renders, which may not have access to values set by interceptors or handlers that only run on your primary routes. If you need values from RC or PRC scopes, store them as data properties in your component's onMount() method to ensure they persist across re-renders.