1 of 53

v4.x

Introduction

CBWIRE is a ColdBox module that uses Livewire and Alpine.js to help you build modern, reactive CFML applications in record time without building backend APIs.

Your First Component

mkdir cbwire-playground --cd
coldbox create app
install cbwire@4
server start

Let's insert a counter element into our Main layout using wire( "Counter" ).

<!--- ./layouts/Main.cfm --->
<cfoutput>
<!doctype html>
<html>
    <body>
        <!--- Insert a counter here --->
        #wire( "Counter" )#
    </body>
</html>
</cfoutput>

// ./wires/Counter.cfc
component extends="cbwire.models.Component" {
    // Data properties
    data = {
        "counter": 0 // default value
    };

    // Action
    function increment() {
        data.counter++;
    }
}

<!--- ./wires/counter.cfm --->
<cfoutput>
    <div>
        <div>Count: #counter#</div>
        <button wire:click="increment">+</button>
    </div>
</cfoutput>

You now have a reactive counter that increments when you click the plus button without any page refreshing or writing JavaScript! 🤯

What!? How?

CBWIRE renders the component with default values (starting at 0).
A button click triggers Livewire.js to send a request to the server.
CBWIRE processes the request, runs increment(), and updates the data.
The updated HTML is sent back in the response.
Livewire.js refreshes the display using DOM comparison.

Awesome, right?

We developed a responsive counter.
We avoided writing any JavaScript code.
We didn't need to create an API.
There was no need for page refreshes.
We skipped using webpack or dealing with JavaScript compilation.

Better With Alpine

The example shows how easily components interact with your CFML back-end. But for quick UI updates, JavaScript can handle changes without unnecessary server requests. While we don’t need a request to increment the counter, we might if we want to save it. This is where CBWIRE and Alpine work perfectly together.

Below, let's change our component to use Alpine.js and add a method to save the counter.

// ./wires/Counter.cfc
component extends="cbwire.models.Component" {   
    data = {
        "counter": 0
    };

    function onMount() {
        // Load the counter from the session
        data.counter = session.counter ?: 0;
    }
    
    function save( counter ) {
        // Save the counter to the session
        session.counter = arguments.counter;
    }
}

<!--- ./wires/counter.cfm --->
<cfoutput>
    <div
        x-data="{
            counter: $wire.counter,
            increment() {
                this.counter++   
            },
            async save() {
                // Call the save method on our component
                await $wire.save( this.counter );
            }
        }"
        wire:ignore.self>
        <div>Count: <span x-text="counter"></span></div>
        <button @click="increment">+</button>
        <button @click="save">Save</button>
    </div>
</cfoutput>

The counter updates instantly on the client side, sending a server request only when clicking "Save" to store the value in the session. On page load, onMount() sets the counter from the session. Using $wire, Alpine communicates with the component, giving full control over server requests. CBWIRE is redefining CFML development—we think you'll love it!

Credits

Project Support

How It Works

Overview

The user requests a page from the server that includes our Counter component.
ColdBox receives the request.
CBWIRE parses our component and initially renders it with its default values.
The rendered component is sent to the browser. It's important to understand that nothing extraordinary has happened at this point. We've returned HTML to the browser from an incoming request. Next is when things get interesting.
The user clicks the button.
CBWIRE uses Livewire.js to intercept the user's click on the client side and send an XHR request to the server.
CBWIRE runs the increment() method, updating the data properties.
CBWIRE re-renders the template.
CBWIRE returns the re-rendered template to the browser.
CBWIRE uses Livewire.js DOM diffing technology to update the component on the page.

Getting Started

Overview

You can get started with CBWIRE with a few initial steps.

Requirements

Adobe ColdFusion 2021+ or Lucee 5+
ColdBox 6+

Installation

Within the root of your project, run:

box install cbwire@4

If you want the latest bleeding edge, run:

box install cbwire@be

Livewire Assets

For CBWIRE to work, your layout must include Livewire's CSS and JavaScript assets. CBWIRE 4 automatically adds these assets to your layout.

<!doctype html>
<html>
<head>
	<!-- Livewire Styles -->
	<style >[wire\:loading][wire\:loading], [wire\:loading\.delay][wire\:loading\.delay], [wire\:loading\.inline-block][wire\:loading\.inline-block], [wire\:loading\.inline][wire\:loading\.inline], [wire\:loading\.block][wire\:loading\.block], [wire\:loading\.flex][wire\:loading\.flex], [wire\:loading\.table][wire\:loading\.table], [wire\:loading\.grid][wire\:loading\.grid], [wire\:loading\.inline-flex][wire\:loading\.inline-flex] {display: none;}[wire\:loading\.delay\.none][wire\:loading\.delay\.none], [wire\:loading\.delay\.shortest][wire\:loading\.delay\.shortest], [wire\:loading\.delay\.shorter][wire\:loading\.delay\.shorter], [wire\:loading\.delay\.short][wire\:loading\.delay\.short], [wire\:loading\.delay\.default][wire\:loading\.delay\.default], [wire\:loading\.delay\.long][wire\:loading\.delay\.long], [wire\:loading\.delay\.longer][wire\:loading\.delay\.longer], [wire\:loading\.delay\.longest][wire\:loading\.delay\.longest] {display: none;}[wire\:offline][wire\:offline] {display: none;}[wire\:dirty]:not(textarea):not(input):not(select) {display: none;}:root {--livewire-progress-bar-color: #2299dd;}[x-cloak] {display: none !important;}</style>
</head>
<body>
	<!-- Livewire SCRIPTS -->
	<script src="/modules/cbwire/includes/js/livewire.js?id=239a5c52" data-csrf="IwMh5yVu4bmvvh3krQjW50jdNHLPBQ6Ln7QLWEyc" data-update-uri="/cbwire/update" data-navigate-once="true"></script>
</body>
</html>

Previous versions of CBWIRE required you to do this manually.

If you want to disable this functionality and manually include the CSS and JavaScript yourself, you can set the autoInjectAssets setting to false in your ColdBox.cfc.

// config/ColdBox.cfc
moduleSettings = {
    "cbwire" : {
        "autoInjectAssets": false
    }
};

Then, you can manually add the CSS and JavaScript using the wireStyles() and wireScripts() methods in your layout file.

<!--- ./layouts/Main.cfm --->
<cfoutput>
<!DOCTYPE html>
<html>
    <head>
        <!--- CBWIRE CSS --->
        #wireStyles()#
    </head>
    <body>
        <!--- CBWIRE JS --->
        #wireScripts()#
    </body>
</html>
</cfoutput>

Your template must include Livewire's CSS and JavaScript; otherwise, CBWIRE will not work. If you are trying to use CBWIRE and it's not working as expected, this is the first place to check.

Configuration

Overview

You can alter CBWIRE and Livewire's default behavior by overriding settings in your config/ColdBox.cfc file.

// ./config/ColdBox.cfc
component{
    function configure() {
        moduleSettings = {
            "cbwire" = {
                "autoInjectAssets": false,
                "maxUploadSeconds": 5 * 60, // 5 minutes
                "throwOnMissingSetterMethod" : false,
                "trimStringValues": false,
                "wiresLocation": "wires",
                "updateEndpoint": "/cbwire/updates",
                "showProgressBar": true,
                "progressBarColor": "##2299dd",
                "csrfEnabled": false,
                "csrfStorage": "SessionStorage@cbstorages",
                "moduleRootURL": "/modules/cbwire"
            }
        };
     }
}

Overriding the module settings is optional.

autoInjectAssets

Automatically include Livewire's CSS and JavaScript assets. This removes the need to manually add references to wireStyles() in your <head> and wireScripts() at the end of </body> in your ColdBox layout file. Defaults to true.

maxUploadSeconds

The maximum amount of time allowed for uploads to complete.

trimStringValues

component extends="cbwire.models.Component" {
    trimStringValues = true;
    data = {
        "name": ""  
    };
}

wiresLocation

updateEndpoint

Sets the URI endpoint where CBWIRE posts its updates to the server. You might need to change this if you do not have URL rewriting enabled.

{
    "updateEndpoint": "/index.cfm/cbwire/update"
}

showProgressBar

progressBarColor

csrfEnabled

Determines if CSRF token protection is enabled or not. Defaults to false. This will be changed to 'true' in CBWIRE 5.

csrfStorage

CBWIRE uses CSRF tokens to protect incoming requests from bad actors. You can set the wirebox mapping to determine what storage provider is used when storing the CSRF tokens. Defaults to SessionStorage@cbstorages.

moduleRootURL

Override to change the URL root path to CBWIRE.

Release History

In this section, you will find the release notes for each version we release under this major version. If you are looking for the release notes of previous major versions use the version switcher at the top left of this documentation book.

What's New With 4.0

05/16/2024

New Features

Upgraded Livewire.js to version 3
Alpine.js automatically included with CBWIRE
Lazy loading components
Execute JS from actions using js() method
Single-page applications now with wire:navigate
Stream content using wire:stream
Transitions using wire:transition
Request bundling to cut down on server requests
Complete rewrite of CBWIRE engine

Enhancements

Removed 'enableTurbo' global setting
Removed 'throwOnMissingSetter' global setting

Bugs

None

What's New With 3.2

12/20/2023

New Features

Automatically populate data properties with passed parameters when onMount() isn't defined Contributed by Michael Rigsby
Add support for calling wire( "MyComponent@module" ). Contributed by Michael Rigsby
Add ability to dispatch browser events
Add ability to call event.method() calls from CBWIRE templates

Bugs

None

What's New With 3.1

09/25/2023

New Features

Add configuration property to include CBWIRE styling and JavaScript assets automatically. Remove the need to add wireScripts() and wireStyles() to templateBugs
Add onUpdate() and onUpdateProperty() lifecycle hooks
Add the ability to refresh all child components from the parent component when an action is called
Add the ability to call CBWIRE UDFs from the cbwire template as computed properties are too limiting.
Single file component file names are not unique and could create conflicts in high-traffic applications
Clear any compiled single file components on ColdBox fwreinit
Add params arguments as a substitute for parameters argument when calling onMount
Add 'cacheSingleFileComponents' setting to control if single file components are cached
Cleanup unnecessary variables available to templates to avoid potential collisions
Add the ability to call application helpers defined in ColdBox.cfc or any installed modules from CBWIRE templates.
Add resetExcept()

Bugs

Fix child components not re-rendering properly on subsequent requests
HTML comments in component templates cause re-renders not to work.

What's New With 3.0

05/18/2023

New Features

Add Inline Components ( NEW SYNTAX )
Make components module-aware and allow components to be created within modules

Enhancements

Remove cbValidation as a dependency of CBWIRE
Increase component rendering performance by bypassing unnecessary ColdBox view caching and lookups
Refactor core engine for better performance and easier maintenance
Remove computedPropertiesProxy as it's no longer needed
Replace calling computed properties in templates using #args.computed.[property]()# with #property()# instead.
Replace calling data properties in templates using #args.[property]()# with #property# instead.
Using new component format, validation references this.constraints. Change to just 'constraints'.
Change incorrect emitTo( event, component ) signature to instead by emitTo( component, event )

Bugs

Empty string and null values are not being correctly passed to Livewire
Fix the ability to locate Wires using full paths such as appMapping.wires.SomeComponent
Component actions that update data properties don't always update the DOM
Calling .see() and .dontSee() in component tests doesn't return the test object for additional method chaining
Overriding computed properties not working when writing component tests

What's New With 2.2

01/09/2022

New Features

Implement lifecycle hook onHydrate().
Implement lifecycle hook onHydrate[Property]().
Implement an automatic trim() for all data properties.
Implement the ability to interact with CBWIRE component from JavaScript using cbwire.find( '#args._id#' ).
Add configuration setting 'enableTurbo' to automatically include everything needed to work with Turbo for single-page applications.
Add the ability to call reset() without passing a key to reset all data properties to their original values.

Enhancements

Implement onMount() method instead of mount().

Bugs

DocBox-generated docs are failing because of file structure.
Listeners are fired immediately when calling emit() when the listener is defined on the same component, which they shouldn't.
onHydrate() is firing after actions are performed.
Computed properties are not being rendered before actions are called.

What's New With 2.1

11/26/2022

New Features

Ability to output component template directly from onRender() method instead of defining a .cfm template in wire/views.

Bugs

Computed properties that do not return a value result in the error 'variable [VALUE] doesn't exist
Nested components are causing the template rendering only to render the last nested template
Struct values are not being passed to the template and are instead being replaced with an empty string
CBWIRE doesn't work when the ColdBox app is in a subdirectory
Getting errors when rendering component templates in the latest version of ColdBox
Nested components are not rendering

What's New With 2.0

08/30/2022

New Features

File Uploads
Ability to write unit tests for components
Ability to override the default 'wires' folder location
noRender() method to prevent template rendering during actions
Implement dirty property tracking
Invoke computed properties during template rendering and only execute once per request
Ability to specify a 'moduleRootURI' setting to change the URI path for cbwire
Upgrade Livewire JS to v2.10.6
Disable browser caching on XHR responses
Reduce payload bloat by removing unnecessary data in XHR requests and responses
Move internal methods to a separate Engine object to avoid collisions with user-defined methods
Reject incoming XHR request if 'X-Livewire' HTTP Header is not present
Dependency injection capabilities to cbwire components
Update to match Livewire's current incoming and outgoing HTTP responses
Ability to use Turbo to create Single-page Applications ( SPAs )

Enhancements

Option to specify the component's template path using this.template instead of defining renderIt() method.

Specify null values for data properties

Bugs

Calling reset( "someProperty" ) throws error
Browser back history doesn't work
On subsequent renderings of components, it's changing the unique id and causing DOM diff issues
Livewire expects params to be an array
Not passing parameters when calling update methods

Resources

Current

Examples

General

Older

The resources below are dated, and CBWIRE has dramatically changed since its release.

Upgrading from CBWIRE 3.x

Coming soon

Upgrading from CBWIRE 2.x

CBWIRE has dramatically improved since its v2.x days. Here, we will outline the core differences between CBWIRE 2 and CBWIRE 4 to assist you with upgrading.

Overview

Here's a quick list of features in 4.x you'll get when upgrading:

Easier access to data properties, component methods, and computed properties from your templates.
Single-file components
- Define your component in a single .CFM file
Upgraded DOM diffing engine via Livewire.js
Ability to pass keys with your wires to control when CBWIRE renders your components.
- #wire( name="MyForm", key="my-form" )#
New HTML Directives
- $wire object allows you to access and interact with your wire from JavaScript directly

Layout

In 2.x, you had to place wireStyles() and wireScripts() in your layout like this to include CBWIRE's JavaScript and CSS assets.

<!--- ./layouts/Main.cfm --->
<html>
    <head>
        #wireStyles()#
    </head>
    <body>
        <h1>CBWIRE Rocks</h1>
        #wireScripts()#
    </body>
</html>

This is now automatically handled for you by default.

// ./config/ColdBox.cfc
component{
    function configure() {
        moduleSettings = {
            "cbwire" = {
                "autoInjectAssets": false
            }
        };
     }
}

Alpine.js

In 2.x, you had to include Alpine.js into your project via CDN or Webpak manually.

<!--- ./layouts/Main.cfm --->
<html>
    <head>
        <script src="//unpkg.com/alpinejs" defer></script>
    </head>
    <body>
        ...
    </body>
</html>

Alpine.js is now automatically included with CBWIRE 4.

CBWIRE and Alpine.js have such a deep integration together that automatically including the two makes sense, and this follows the direction that Livewire 3 took. There is no longer a need to pull Alpine.js into your project.

Removing any previous installations or references to Alpine.js is important since it is now included with CBWIRE. Otherwise, you will run into various rendering errors, and your Alpine components will likely run twice.

$wire

In 4.x, you can fully interact with your components using Alpine and the magical $wire object.

<!--- Include our form in a view or layout --->
#wire( "Form" )#

// ./wires/Form.cfc
component extends="cbwire.models.Component" {
    function submitForm() {
        // Do something important here
        sleep( 2000 );
    }
}

<!--- ./wires/form.cfm --->
<div 
    x-data="{
        loading: false,
        async submitForm() {
            this.loading = true // show loader
            console.log( 'Submitting form...' )
            await $wire.submitForm() // Run our submitForm
            this.loading = false // hide loader
        }
    }">
    <h1>My Form</h1>
    
    <form @submit.prevent="submitForm">
        <button type="submit">Submit Form</button>
    </form>

    <template x-if="loading">
        <div>Show an awesome spinner here</div>
    </template>
</div>
```

Single-file components

In 2.x, you defined your components with a .CFC file and .cfm template.

You can still use separate files in 4.x, but you can also place everything in a single .cfm file. Use whichever pattern you prefer.

<!--- ./wires/DayChecker.cfm --->
<cfoutput>
    <div>
        <cfif isMonday()>
            Bummer.
        </cfif>
    </div>
</cfoutput>

<cfscript>
    // @startWire
    function isMonday() computed {
        return false; // Let's skip Mondays    
    }
    // @endWire
</cfscript>

Rendering Components

You still render your components using the wire() method, but the signature has changed.

In 2.x, the signature was:

wire( required string componentName, struct parameters = {} )

In 4.x, the signature is:

wire(
    required string name,
    struct params = {},
    string key = "",
    lazy = false,
    lazyIsolated = true 
)

Key differences:

The arguments componaneName and parameters were given shorter names.

Data Properties

In 2.x, data properties were referenced in your templates using #args.prop#.

// ./wires/SomeWire.cfc
component extends="cbwire.models.Component" {
    data = {
        "goodDay": true
    };
}

<!--- ./views/wires/somewire.cfm --->
<cfoutput>
    <div>
        <cfif args.goodDay>
            Enjoy your day!
        <cfelse>
            Hey, it probably will get worse.
        </cfif>
    </div>
</cfoutput>

In 4.x, you can access the data property without args.

<!--- ./views/wires/somewire.cfm --->
<cfoutput>
    <div>
        <cfif goodDay>
            Enjoy your day!
        <cfelse>
            Hey, it probably will get worse.
        </cfif>
    </div>
</cfoutput>

You can still reference your props using args for backward compatibility, but it's optional.

Component Methods

Any methods you define in your component you can access from the template.

// ./wires/SomeWire.cfc
component extends="cbwire.models.Component" {
    data = {};
    
    // Returns the current date
    function getTomorrow() {
        return now().add( "d", 1 );
    }
}

<!--- ./wires/somewire.cfm --->
<cfoutput>
    <div>
        Tomorrow: #dateFormat( getTomorrow(), "mm/dd/yyyy" )#
    </div>
</cfoutput>

Computed Properties

In 2.x, computed properties were defined with a computed struct in your component.

component extends="cbwire.models.Component" {

    computed = {
        "isMonday" : function() {
            return false; // Let's skip Mondays
        }
    }

}

And you would access them in your templates like this:

<cfoutput>
    <div>
        <cfif args.computed.isMonday()>
            Bummer.
        </cfif>
    </div>
</cfoutput>

In 4.x, we define computed properties like this:

component extends="cbwire.models.Component" {
    function isMonday() computed {
        return false; // Let's skip Mondays    
    }
}

And we access them in our templates like this:

<cfoutput>
    <div>
        <cfif isMonday()>
            Bummer.
        </cfif>
    </div>
</cfoutput>

Events

In 2.x, you could communicate with your components using emit().

component extends="cbwire.models.Component" {
    function sendEmail() {
        emit( "email-sent" );
    }
}

In 4.x, this has been replaced with dispatch().

component extends="cbwire.models.Component" {
    function sendEmail() {
        dispatch( "email-sent" );
    }
}

You can also dispatch from JavaScript using $wire.$dispatch and cbwire.dispatch().

Adobe CF 2018

Official support for Adobe CF 2018 was dropped.

Validation

In 2.x, you defined your validation constraints using this.constraints.

component extends="cbwire.models.Component" {
    this.constraints = {
        "email": { required: true }
    };
}

In 4.x, you use constraints or variables.constraints.

component extends="cbwire.models.Component" {
    constraints = {
        "email": { required: true }
    };
}

Relocating

In 2.x, relocating was done with the relocate() method. It's been replaced with redirect();

TurboLinks

<a href="/some/link" wire:navigate>Click here</a>

We no longer recommend using the Turbolinks library for SPA-style applications.

The Essentials

Components

Overview

Components are sections of your application that you want to be reactive to user input.

Components can be as big or small as you like. For example, you may have a Signup form component that covers multiple steps or a simple button component that you reuse throughout your application.

Rendering Components

You can render a component using the wire() method.

You can call wire() from within your ColdBox layouts, ColdBox views, and also from your component templates ( See Nesting Components ).

External Components

You can render wires from folders and subfolders outside of the default ./wires folder.

You can also reference components within another ColdBox module by using the @module syntax.

Passing Parameters

You can pass data into a component as an additional argument using wire().

By passing in parameters, you can create reusable UI components that are unique but similar in functionality. For example, you could make a button component that you reuse throughout your app.

Using Parameters

CBWIRE only executes onMount() once when the component is initially rendered. It is not executed for subsequent update requests of the component.

Auto Populating Data Properties

Passed-in properties must have a data type of string, boolean, numeric, date, array, or struct.

Nesting Components

CBWIREController

There may be areas of your application where you need to use wire() but don't have access to it. You can use the CBWIREController object to insert wires anywhere you need.

Templates

Overview

<cfoutput>
    <!--- HTML template goes here --->
    <div>
        <button wire:click="doSomething">Click here</button>
        <!-- Any valid CFML here -->
        <cfif datePart( 'h', now() ) lt 12>
            <p>Good morning!</p>
        <cfelse>
            <p>Good afternoon!</p>
        </cfif>
    </div>
</cfoutput>

Your templates must have a single outer element for CBWIRE to bind to your component and update the DOM properly. This can be any valid HTML element. Below, we are using a div element.

Below is a template with one outer element ( good ) and another with two outer elements ( bad ).

<cfoutput>
    <!--- GOOD: single outer element --->
    <div>
        <p>My awesome component</p>
    </div>
</cfoutput>

<cfoutput>
    <!--- BAD: 2 outer elements --->
    <div>
        My awesome component    
    </div>
    <div>
        <p>This won't work.</p>
    </div>
</cfoutput>

Implicit Rendering

By default, CBWIRE will look in the ./wires folder for a .cfm file with the same name as your component.

./wires/Counter.cfc <--- CFC file
./wires/Counter.cfm <--- Template file based on CFC name

Explicit Rendering

To override the default implicit rendering, we can tell CBWIRE where our component template is by defining a onRender() method on our component and using the template() method.

// ./wires/MyTemplate.cfc
component extends="cbwire.models.Component" {
    function onRender() {
        return template( "someFolder.MyTemplate" ); // renders ./somefolder/MyTemplate.cfm    
    }
}

We can pass parameters when calling template().

// ./wires/MyTemplate.cfc
component extends="cbwire.models.Component" {
    function onRender() {
        return template( "someFolder.MyTemplate", { "someVar": "value" } );
    }
}

In this case, someVar becomes available to our template.

<!--- ./someFolder/MyTemplate.cfm --->
<cfoutput>
    <div>
        Somevar: #someVar#
    </div>
</cfoutput>

You can also return your template inline like so:

// ./wires/MyTemplate.cfc
component extends="cbwire.models.Component" {
    function onRender() {
        return "<div>My component</div>";
    }
}

Using Data Properties

// ./wires/Greeter.cfc
component extends="cbwire.models.Component" {
    data = {
        "greeting": "Hello from CBWIRE"
    };
}

<!--- ./wires/greeter.cfm --->
<cfoutput>
    <div>
        Greeting: #greeting#
    </div>
</cfoutput>

Using Computed Properties

function greeting() computed {}

// ./wires/Greeter.cfc
component extends="cbwire.models.Component" {
    function greeting() computed {
        return "Hello from CBWIRE";
    }
}

You access computed properties in your template by invoking the method.

<!--- ./wires/greeter.cfm --->
<cfoutput>
    <div>
        Greeting: #greeting()#
    </div>
</cfoutput>

Using Helper Methods

You can access any global helper methods defined in your ColdBox application and any modules you have installed.

For example, suppose you've installed the cbi8n module ( an internalization module for ColdBox ). You can access its global helper methods in your template, such as the $r() method for displaying text in various languages.

<cfoutput>
    <div>
        #$r( "greeting" )#
    </div>
</cfoutput>

Data Properties

Overview

//./wires/SomeComponent.cfc
component extends="cbwire.models.Component" {
    data = {
        "propertyName": "defaultValue"
    };
}

JavaScript parses your data properties. Your data properties can only store JavaScript-friendly values: strings, numerics, arrays, structs, or booleans.

Single or double quotes must surround property names.

JavaScript is a case-sensitive language, and CFML isn't. To preserve the casing of your property names, you must surround them with quotes.

Don't do this.

data = {
    propertyName: "defaultValue"
};

Data properties are visible to JavaScript. You SHOULD NOT store sensitive data in them.

Accessing From Actions

// ./wires/Date.cfc
component extends="cbwire.models.Component" {
    // Data properties
    data = {
        "time": now()
    };    
    // Action
    function updateTime(){
        data.time = now();
    }
}

Accessing From Templates

<cfoutput>
    <div>
        <h1>Current time</h1>
        <div>#time#</div>
        <button wire:click="updateTime">Update</button>
    </div>
</cfoutput>

Resetting Properties

component extends="cbwire.models.Component" {
    data = {
        "time": now()
    };
    function resetTime(){
        reset();
    }
}

You can reset individual, some, or all data properties.

function resetForm() {
    reset( "message" ); // resets 'message' data property
    reset( [ "message", "anotherprop" ] ); // reset multiple properties at once
    reset(); // resets all properties
}

You also can reset all properties EXCEPT the properties you pass.

function resetForm() {
    resetExecept( "email" );
    resetExcept( [ "email", "phoneNumber" ] );
}

Computed Properties

Computed Properties are dynamic properties that are cached per component rendering.

Differences

They are declared as functions within your component with a computed attribute added.
They are cached.

Defining Computed Properties

You can define Computed Properties on your components as functions with the computed attribute added.

component extends="cbwire.models.Component" {   

    // Computed property
    function isEven() computed {
        return data.counter % 2 == 0;
    }

}

Templates

You can access Computed Properties in your component template using propertyName().

<cfoutput>
    <div>
        Is Even: #isEven()#
    </div>
</cfoutput>

Actions

component extends="cbwire.models.Component" {   

    // Computed property
    function isEven() computed {
        return data.counter % 2 == 0;
    }
    
    // Action
    function increment() {
        if ( isEven() ) {
            data.counter += 2;
        } else {
            data.counter += 1;
        }
    }

}

Caching

Computed Properties cache their results for the lifetime of the request. It will only execute once if you reference your Computed Property three times in your component template or from within a component action.

// wires/UUID.cfc
component extends="cbwire.models.Component" {   

    // Computed properties
    function getUUID() computed {
        return createUUID();
    }

}

<!--- wires/uuid.cfm -->
<cfoutput>
    <div>
        <p>#getUUID()#</p>
        <p>#getUUID()#</p> <!-- Outputs the same ID because of caching -->
    </div>
</cfoutput>

You can prevent caching on a computed property by passing a false argument when invoking it.

<!--- wires/uuid.cfm -->
<cfoutput>
    <div>
        <p>#getUUID()#</p>
        <p>#getUUID( false )#</p> <!-- Does not have the same ID because caching disabled -->
    </div>
</cfoutput>

Data Binding

Overview

// wires/MyComponent.cfc
component extends="cbwire.models.Component" {
    // Data properties
    data = {
        "name" : ""
    };
}

<!--- ./wires/mycomponent.cfm --->
<cfoutput>
    <div>
        <form>
            <input wire:model.live="name" type="text">
            Name updated at #now()#
        </form>
    </div>
</cfoutput>

Resources

Actions

Overview

Here is a basic example of how to use it:

// wires/Time.cfc
component extends="cbwire.models.Component" {
    data = {
        "currentTime" : now()
    };
    function updateTime() {
        data.currentTime = now();
    }
}

<!--- wires/time.cfm --->
<cfoutput>
    <div>
        <p>Current time: #currentTime#</p>
        <button wire:click="updateTime">Update</button>
    </div>
</cfoutput>

Actions do not need to return any value. Return values are ignored.

Executing Actions

Some examples of events you can listen for include:

Event

Directive

click

wire:click

keydown

wire:keydown

submit

wire:submit

<button wire:click="doSomething">Do Something</button>

<input wire:keydown.enter="doSomething">

<form wire:submit="save">
    <button type="submit">Save</button>
</form>

You can listen for any browser events on elements using the wire:[event] directive, where [event] is the event's name. For example, to listen for a "foo" event on a button element, you would use the following code:

<button wire:foo="someAction">

On some elements, such as forms or links, you need to add a .prevent modifier to prevent the browser's default behavior. Otherwise, the browser will cause the page to reload and you will get unintended results.

<a href="##" wire:click.prevent="doSomething">Do Something</a>

Passing Parameters

You can pass parameters to actions such as actionName( arg1, arg2, arg3 ).

<cfoutput>
    <div>
        <button wire:click="addTask('Some Task')">Add Task</button>
    </div>
</cfoutput>

The parameter is then passed through to your actions via function arguments.

component extends="cbwire.models.Component" {
    function addTask( taskName ){
        queryExecute( "
            insert into tasks (
                name
            ) values (
                :name
            )
        ", { name = arguments.taskName } ); // Adds 'Some Task'
    }
}

Magic Actions

Action

Description

$refresh

Will re-render the component without firing any action

$set( 'dataproperty', value )

Shortcut to update the value of a property

$toggle( 'dataproperty' )

Shortcut to toggle boolean properties off and on

Consider the example below.

// wires/SayHello.cfc
component extends="cbwire.models.Component" {
    data = {
        "message": ""
    };
    function setMessageToHello() {
        data.message = "Hello";
    }
}

<!--- wires/sayhello.cfm --->
<div>
    #message#
    <button wire:click="$set( 'message', 'Hello' )">Say Hi</button>
</div>

Events

Overview

Events and listeners provide an elegant means for your components to communicate. You can dispatch events from one component, listen for them on another, execute actions, and re-render the listener.

Dispatching Events

// ./wires/Posts.cfc
component extends="cbwire.models.Component" {
    function addPost() {
        dispatch( "post-added" );
    }
}

<!--- ./wires/posts.cfm --->
<cfoutput>
    <div>
        <button wire:click="$dispatch( 'post-added' )">Add Post</button>
    </div>
</cfoutput>

<!--- ./wires/posts.cfm --->
<script>
    Livewire.dispatch( 'post-added' );
</script>

Passing Parameters

You can send parameters as your dispatching an event.


// ./wires/Posts.cfc
component extends="cbwire.models.Component" {
    function addPost() {
        dispatch( "post-added", { "id": post.getId() } );
    }
}

<!--- ./wires/posts.cfm --->
<button wire:click="$dispatch( 'post-added', { id: post.getId() } )">Add Post</button>

<!--- ./wires/posts.cfm --->
<script>
    Livewire.dispatch( 'post-added', { id: '#post.getID()#' } );
</script>

dispatchTo

You can dispatch events to components of a specific component using dispatchTo().

// ./wires/Posts.cfc
component extends="cbwire.models.Component" {
    function addPost() {
        dispatchTo( "TopBar", "post-added", {} );
    }
}

<!--- ./wires/posts.cfm --->
<button wire:click="$dispatchTo( 'TopBar', 'post-added', {} )">Add Post</button>

<!--- ./wires/posts.cfm --->
<script>
    Livewire.dispatchTo( 'TopBar', 'post-added', { id: '#post.getID()#' } );
</script>

dispatchSelf

You can dispatch events to the component that fired the event using dispatchSelf().

// ./wires/Posts.cfc
component extends="cbwire.models.Component" {
    function addPost() {
        dispatchSelf( "post-added", { "id": post.getId() } );
    }
}

<!--- ./wires/posts.cfm --->
<button wire:click="$dispatchSelf( 'post-added', { id: post.getId() } )">Add Post</button>

Listeners

You register event listeners by adding a listeners struct to your component.

Listeners are a key/value pair where the key is the event to listen for, and the value is the action to invoke on the component.

// ./wires/Posts.cfc
component extends="cbwire.models.Component" {
    listeners = {
        "post-added": "incrementPostCount" 
    };   
    function incrementPostCount() {
        // Increment the post count
    }
}

JavaScript keys are case-sensitive. To preserve the key casing in CFML, surround your listener names in quotations.

Dispatching Browser Events

You can also dispatch browser events using the dispatch() method.

// wires/Form.cfc
component extends="cbwire.models.Component" {
    function submitForm(){
        // Dispatch a 'form-submitted' browser event. Pass parameters
        dispatch( "form-submitted", { "submittedBy": "Grant" } );
    }

}

<!--- wires/form.cfm --->
<cfoutput>
    <div>
        <form wire:submit.prevent="submitForm">
            <button type="submit">Dispatch event</button>
        </form>
    </div>
</cfoutput>

You can listen for the event using vanilla JavaScript:

<script>
    window.addEventListener('form-submitted', event => {
        alert( 'Form submitted by: ' + event.detail.submittedBy );
    } );
</script>

<div x-data="{ show: false }" @form-submitted.window="show = true">
    <div x-show="true">
        Form was submitted.
    </div>
</div>

Nesting Components

// wires/ContactUs.cfc
component extends="cbwire.models.Component" {
    data = {
        "showForm": false
    };  
}

<!--- wires/contactus.cfm --->
<cfoutput>
    <div>
        <cfif showForm>
            <!--- Nested component --->
            #wire( name="ContactForm" )#
        </cfif>    
        <button wire:click="$toggle( 'showForm' )">Toggle form</button>
    </div>
</cfoutput>

You can also pass parameters.

// wires/ContactUs.cfc
component extends="cbwire.models.Component" {
    data = {
        "showForm": false,
        "sendEmail": false,
        "validateForm": true
    };  
    
    function onMount( params ) {
        data.sendEmail = params.sendEmail;
        data.validateForm = params.validateForm;
    }
}

<!--- wires/contactus.cfm --->
<cfoutput>
    <div>
        <cfif showForm>
            #wire(
                name="ContactForm"
                params={
                    sendEmail: true,
                    validateForm: true
                }
            )#
        </cfif>
        <button wire:click="$toggle( 'showForm' )">Toggle form</button>    
    </div>
</cfoutput>

Lifecycle Methods

Overview

Order Of Operations

The lifecycle methods are executed in the following order when a component is initially loaded:

onMount()
onRender()

Lifecycle methods are executed in this order for subsequent AJAX requests.

onHydrate[DataProperty]()
onHydrate()
onUpdate[DataProperty]()
onUpdate()
Fire actions
onRender()

Methods

onMount

It runs only once when a component is initially wired. This can inject data values into your component via params you pass in when calling wire(), or pulling in values from the RC or PRC scopes.

component extends="cbwire.models.Component" {
    data = {
        "someValue: ""
    };
    function onMount( event, rc, prc, params ){
        data.someValue = params.someValue;
    }
}

onMount() only fires when the component is initially rendered and does not fire on subsequent requests when your component re-renders. This can cause issues referencing things such as the RC or PRC scope. If you pass in values with the RC or PRC scope, you must store them as data properties to ensure they are available to your component in subsequent requests.

onRender

It runs on all requests before rendering your component. This gives you more control if needed when rendering. There is also a renderIt() alias, which does the same.

component extends="cbwire.models.Component" {
    function onRender() {
        return "<div>direct html</div>;
        // return template( _getViewPath() ); // CBWIRE's default method
        // return template( "some.custom.path" );
    }
}

onHydrate

component extends="cbwire.models.Component" {
    function onHydrate( data ) {
        // Note that computed properties have not yet rendered
        data.hydrated = true;
    }
}

onHydrate[ Property ]

Runs on subsequent requests after a specific data property is hydrated but before computed properties are rendered, before an action is performed, or before the component is rendered.

component extends="cbwire.models.Component" {
    data = {
        "count": 1
    };
    function onHydrateCount( data ) {
        // Note that computed properties have not yet rendered
        data.count += 1;
    }  
}

onUpdate

component extends="cbwire.models.Component" {
    function onUpdate( newValues, oldValues ) {
        // ....
    }
}

onUpdate() will only fire if the incoming request updates a single data property, such as when using wire:model.

onUpdate[ Property ]

component extends="cbwire.models.Component" {
    data = {
        "count": 1
    };
    function onUpdateCount( newValue, oldValue ) {
        if ( newValue >= 100 ) {
            // Reset back to 1
            data.count = 1;
        }

    }
}

JavaScript

Overview

CBWIRE includes Alpine.js, and uses Livewire.js for all client-side functionality and DOM diffing. These tools give you complete control over client-side functionality while providing ways to interact with your component server-side.

Alpine.js

Alpine.js is included with CBWIRE and was designed to work beautifully with your CBWIRE components.

// ./wires/Counter.cfc
component extends="cbwire.models.Component" {   
    // Actions
    function save( counter ) {
        // Code to save to database
    }
}

<!--- ./wires/counter.cfm --->
<cfoutput>
    <div
        x-data="{
            counter: 0,
            increment() {
                this.counter++   
            },
            async save() {
                // Call the save method on our component
                await $wire.save( this.counter );
            }
        }"
        wire:ignore.self>
        <div>Count: <span x-text="counter"></span></div>
        <button @click="increment">+</button>
        <button @click="save">Save to database</button>
    </div>
</cfoutput>

$wire object

The $wire object is one of the most powerful features in Livewire.

With $wire, you get a JavaScript representation of your server-side CBWIRE component that you can interact with. You can change data properties, call actions, access parent components, fire events, and much more.

Below are the properties and methods of the $wire object:

let $wire = {
    // All component public properties are directly accessible on $wire...
    counter: 0,
 
    // All public methods are exposed and callable on $wire...
    increment() { ... },
 
    // Access the `$wire` object of the parent component if one exists...
    $parent,
 
    // Access the root DOM element of the CBWIRE component...
    $el,
 
    // Access the ID of the current CBWIRE component...
    $id,
 
    // Get the value of a property by name...
    // Usage: $wire.$get('count')
    $get(name) { ... },
 
    // Set a property on the component by name...
    // Usage: $wire.$set('count', 5)
    $set(name, value, live = true) { ... },
 
    // Toggle the value of a boolean property...
    $toggle(name, live = true) { ... },
 
    // Call the method
    // Usage: $wire.$call('increment')
    $call(method, ...params) { ... },
 
    // Entangle the value of a CBWIRE property with a different,
    // arbitrary, Alpine property...
    // Usage: <div x-data="{ count: $wire.$entangle('count') }">
    $entangle(name, live = false) { ... },
 
    // Watch the value of a property for changes...
    // Usage: Alpine.$watch('counter', (value, old) => { ... })
    $watch(name, callback) { ... },
 
    // Refresh a component by sending a commit to the server
    // to re-render the HTML and swap it into the page...
    $refresh() { ... },
 
    // Identical to the above `$refresh`. Just a more technical name...
    $commit() { ... },
 
    // Listen for a an event dispatched from this component or its children...
    // Usage: $wire.$on('post-created', () => { ... })
    $on(event, callback) { ... },
 
    // Dispatch an event from this component...
    // Usage: $wire.$dispatch('post-created', { postId: 2 })
    $dispatch(event, params = {}) { ... },
 
    // Dispatch an event onto another component...
    // Usage: $wire.$dispatchTo('dashboard', 'post-created', { postId: 2 })
    $dispatchTo(otherComponentName, event, params = {}) { ... },
 
    // Dispatch an event onto this component and no others...
    $dispatchSelf(event, params = {}) { ... },
 
    // A JS API to upload a file directly to component
    // rather than through `wire:model`...
    $upload(
        name, // The property name
        file, // The File JavaScript object
        finish = () => { ... }, // Runs when the upload is finished...
        error = () => { ... }, // Runs if an error is triggered mid-upload...
        progress = (event) => { // Runs as the upload progresses...
            event.detail.progress // An integer from 1-100...
        },
    ) { ... },
 
    // API to upload multiple files at the same time...
    $uploadMultiple(name, files, finish, error, progress) { },
 
    // Remove an upload after it's been temporarily uploaded but not saved...
    $removeUpload(name, tmpFilename, finish, error) { ... },
 
    // Retrieve the underlying "component" object...
    __instance() { ... },
}

Executing Scripts

You can execute bespoke JavaScript in your CBWIRE component using <cbwire:script>.

<!--- ./wires/mycomponent.cfm --->
<cfoutput>
    <div>...</div>
</cfoutput>

<cbwire:script>
    <script>
        // This Javascript will get executed every time this component is loaded onto the page...
    </script>
</cbwire:script>

Here's a complete example:

<!--- ./wires/counter.cfm --->
<cfoutput>
    <div>
        Counter component in Alpine:
     
        <div x-data="counter">
            <h1 x-text="count"></h1>
            <button x-on:click="increment">+</button>
        </div>
    </div>
</cfoutput>
 
<cbwire:script>
    <script>
        Alpine.data('counter', () => {
            return {
                count: 0,
                increment() {
                    this.count++
                },
            }
        })
    </script>
</cbwire:script>

Scripts are executed after the page has loaded BUT before your CBWIRE component has rendered.

Unlike assets, which are loaded only once per page, scripts are evaluated for every component instance.

Loading Assets

You can load style assets on the page with your component using <cbwire:assets>.

<!--- ./wires/date.cfm --->
<cfoutput>
    <div>
        <input type="text" data-picker>
    </div>
</cfoutput>
 
<cbwire:assets>
    <script src="https://cdn.jsdelivr.net/npm/pikaday/pikaday.js" defer></script>
    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/pikaday/css/pikaday.css">
</cbwire:assets>
 
<cbwire:script>
    <script>
        new Pikaday({ field: $wire.$el.querySelector('[data-picker]') });
    </script>
</cbwire:script>

Livewire will ensure any assets are loaded on the page before evaluating scripts. It will also ensure that assets are only loaded once per page, even if you have multiple instances of the component.

Using $wire From Scripts

You can access your component's $wire object within your scripts block.

<cbwire:script>
    <script>
        setInterval( () => {
            $wire.$refresh()
        }, 3000 );
    </script>
</cbwire:script>

Livewire Events

You can access the livewire:init and livewire:initialized events as Livewire is loading.

<script>
    document.addEventListener('livewire:init', () => {
        // Runs after Livewire is loaded but before it's initialized
        // on the page...
    } );
 
    document.addEventListener('livewire:initialized', () => {
        // Runs immediately after Livewire has finished initializing
        // on the page...
    } );
</script>

Livewire object

You can interact with Livewire from external scripts using the Livewire global object.

// Retrieve the $wire object for the first component on the page...
let component = Livewire.first()
 
// Retrieve a given component's `$wire` object by its ID...
let component = Livewire.find(id);
 
// Retrieve an array of component `$wire` objects by name...
let components = Livewire.getByName(name);
 
// Retrieve $wire objects for every component on the page...
let components = Livewire.all();

// Dispatch an event to any CBWIRE components listening...
Livewire.dispatch( 'post-created', { postId: 2 } );
 
// Dispatch an event to a given CBWIRE component by name...
Livewire.dispatchTo( 'dashboard', 'post-created', { postId: 2 } );
 
// Listen for events dispatched from CBWIRE components...
Livewire.on('post-created', ( { postId } ) => {
    // ...
} );

// Register a callback to execute on a given internal Livewire hook...
Livewire.hook( 'component.init', ( { component, cleanup } ) => {
    // ...
})

Custom Directives

Livewire allows you to register custom directives using Livewire.directive().

<button wire:confirm="Are you sure?" wire:click="delete">Delete post</button>

Livewire.directive( 'confirm', ( { el, directive, component, cleanup } ) => {
    let content =  directive.expression;
 
    // The "directive" object gives you access to the parsed directive.
    // For example, here are its values for: wire:click.prevent="deletePost(1)"
    //
    // directive.raw = wire:click.prevent;
    // directive.value = "click";
    // directive.modifiers = ['prevent'];
    // directive.expression = "deletePost(1)";
 
    let onClick = e => {
        if (! confirm( content ) ) {
            e.preventDefault()
            e.stopImmediatePropagation()
        }
    }
 
    el.addEventListener( 'click', onClick, { capture: true } );
 
    // Register any cleanup code inside `cleanup()` in the case
    // where a Livewire component is removed from the DOM while
    // the page is still active.
    cleanup( () => {
        el.removeEventListener( 'click', onClick );
    } );
})

JavaScript Hooks

Livewire.hook('component.init', ({ component, cleanup }) => {
    // Fires every time a new component is discovered by Livewire
    // Both on page load and later on
})

Livewire.hook('element.init', ({ component, el }) => {
    // Fires for each DOM element within a given CBWIRE component
})

Livewire.hook('morph.updating',  ({ el, component, toEl, skip, childrenOnly }) => {
    // DOM morphing hook
})
 
Livewire.hook('morph.updated', ({ el, component }) => {
    // DOM morphing hook
})
 
Livewire.hook('morph.removing', ({ el, component, skip }) => {
    // DOM morphing hook
})
 
Livewire.hook('morph.removed', ({ el, component }) => {
    // DOM morphing hook
})
 
Livewire.hook('morph.adding',  ({ el, component }) => {
    // DOM morphing hook
})
 
Livewire.hook('morph.added',  ({ el }) => {
    // DOM morphing hook
})

Intercepting Commits

A commit is made every time a CBWIRE component is sent to the server. You can hook into an individual commit like this:

Livewire.hook('commit.prepare', ({ component, commit }) => {
    // Runs before commit payloads are collected and sent to the server...
})

Livewire.hook('commit', ({ component, commit, respond, succeed, fail }) => {
    // Runs immediately before a commit's payload is sent to the server...
 
    respond(() => {
        // Runs after a response is received but before it's processed...
    })
 
    succeed(({ snapshot, effect }) => {
        // Runs after a successful response is received and processed
        // with a new snapshot and list of effects...
    })
 
    fail(() => {
        // Runs if some part of the request failed...
    })
})

Request Hooks

Using the request hook, you can hook into the entire HTTP request, which may contain multiple commits.

Livewire.hook('request', ({ uri, options, payload, respond, succeed, fail }) => {
    // Runs after commit payloads are compiled, but before a network request is sent...
 
    respond(({ status, response }) => {
        // Runs when the response is received...
        // "response" is the raw HTTP response object
        // before await response.text() is run...
    })
 
    succeed(({ status, json }) => {
        // Runs when the response is received...
        // "json" is the JSON response object...
    })
 
    fail(({ status, content, preventDefault }) => {
        // Runs when the response has an error status code...
        // "preventDefault" allows you to disable Livewire's
        // default error handling...
        // "content" is the raw response content...
    })
})

Customizing Page Expiration

If the default page expiration dialog isn't suitable for your application, you can use the request hook to implement a custom solution.

<script>
    document.addEventListener('livewire:init', () => {
        Livewire.hook('request', ({ fail }) => {
            fail(({ status, preventDefault }) => {
                if (status === 419) {
                    confirm('Your custom page expiration behavior...')
                    preventDefault()
                }
            })
        })
    })
</script>

Testing

Test your components using TestBox.

CBWIRE includes a beautiful test API to test your front-end components quickly.

Test Example

To start, make sure you extend BaseWireTest in your test spec.

You can invoke your component by calling wire() and then chain additional state changes and assertions.

Test Methods

data

Set a data property to the specified value.

computed

Set a computed property to the specified closure.

toggle

Toggles a data property between true and false.

call

Calls an action. An optional array of parameters can be provided.

emit

Emits an event and fires any listeners that are defined on the component. An optional array of parameters can be provided, which will be passed on to listeners.

see

Verifies a value can be found in the current component rendering. Otherwise, the test fails.

dontSee

Verifies a value is not found in the current component rendering. Otherwise, the test fails.

seeData

Verifies a data property matches a specified value. Otherwise, the test fails.

dontSeeData

Verifies a data property does not match a specified value. Otherwise, test fails.

Features

Single-file Components

Overview

Single File Format

Let's combine these into a single file.

There are only a few differences with the single-file format.

The contents of your .cfc file are instead placed inside a <cfscript> block
The // @startWire and // @endWire comment markers have been added so that CBWIRE can parse the file.

You must add the //@startWire and //@endWire markers when using single-file format.

You can place your <cfscript> block above or below your template. CBWIRE parses this out before processing.

Performance

There is a slight performance hit when using the single file format because CBWIRE has to parse out the sections of your file. However, this hit is minimal because of the internal caching CBWIRE uses.

Cached files can be found under ./modules/cbwire/models/tmp. This directory gets cleared anytime you reinit your application using ColdBox's fwreinit.

http://myapp/?fwreinit=true

Alpine.js

Coming soon.

Lazy Loading

Overview

A slow component can slow down the loading of an entire page. CBWIRE's lazy loading feature allows you to delay loading your components until the page is fully rendered.

Let's create a slow component that users will hate.

<!--- ./views/someview.cfm --->
#wire( "SlowComponent" )#

// ./wires/SlowComponent.cfc
component extends="cbwire.model.Component" {
    function onMount() {
        sleep( 2000 ); // Make this component slow
    }
}

<!--- ./wires/slowcomponent.cfm --->
<cfoutput>
    <div>
        <h1>Slow Component</h1>
    </div>
</cfoutput>

Changing this to a lazy-loaded component is as simple as using wire( lazy=true ).

#wire( name="SlowComponent", lazy=true )#

This will cause Livewire to skip this component on the initial page load. Once visible in the viewport, Livewire will request a network to load the component fully.

Lazy loading also delays the execution of the onMount() lifecycle method.

Placeholder

As your components load, you often want to display some indicator, such as a spinner, to your users. You can do this easily using the placeholder() method.

// ./wires/SlowComponent.cfc
component extends="cbwire.model.Component" {
    function onMount() {
        sleep( 2000 ); // Make this component slow
    }
    function placeholder() {
        return "<div>Loading...</div>";
    }
}

By default, CBWIRE inserts an empty <div></div> for your component before it loads.

The placeholder and the main component must use the same root element type, such as a div. You will get rendering errors if you don't use the same root element.

Placeholder using ColdBox view

You can render a ColdBox view for a placeholder using the view() method.

// ./wires/SlowComponent.cfc
component extends="cbwire.model.Component" {
    function onMount() {
        sleep( 2000 ); // Make this component slow
    }
    function placeholder() {
        return view( "spinner" ); // renders ./views/spinner.cfm
    }
}

Form Validation

Overview

Installation

box install cbvalidation

Previous versions of CBWIRE included cbValidation automatically. However, this introduced issues if you wanted to use a version different from CBWIRE's.

Defining Constraints

// ./wires/Form.cfc
component extends="cbwire.models.Component" {
    // Data properties
    data = {
        "task": ""
    };
    // Validation constraints
    constraints = {
        "task": {
            "required": true,
            "requiredMessage": "Task is required"
        }
    };
}

Available Constraints

Below are the currently available constraints.

propertyName = {
        // The field under validation must be yes, on, 1, or true. This is useful for validating "Terms of Service" acceptance.
        accepted : any value
        
        // The field under validation must be a date after the set targetDate
        after : targetDate
        
        // The field under validation must be a date after or equal the set targetDate
        afterOrEqual : targetDate

        // The field must be alpha ONLY
        alpha : any value
        
        // The field under validation is an array and all items must pass this validation as well
        arrayItem : {
            // All the constraints to validate the items with
        }
        
        // The field under validation must be a date before the set targetDate
        before : targetDate
        
        // The field under validation must be a date before or equal the set targetDate
        beforeOrEqual : targetDate
        
        // The field under validation is a struct and all nested validation rules must pass
        constraints: {
           // All the constraints for the nested struct
        }
        
        // The field under validation must be a date that is equal the set targetDate
        dateEquals : targetDate
        
        // discrete math modifiers
        discrete : (gt,gte,lt,lte,eq,neq):value
        
        // the field must or must not be an empty value
        // needed because `required` counts empty strings as valid
        // and `type` ignores empty strings as "not required"
        empty : boolean [false]

        // value in list
        inList : list
        
        // Verify the instance of the target
        InstanceOf : "instance.path"
        
        // An alias for arrayItem
        items : {
            // All the constraints to validate the items with
        }

        // max value
        max : value

        // Validation method to use in the target object must return boolean accept the incoming value and target object 
        method : methodName

        // min value
        min : value
        
        // An alias for constraints
        nestedConstraints: {
           // All the constraints for the nested struct
        }
        
        // not same as but with no case
        notSameAsNoCase : propertyName

        // not same as another property
        notSameAs : propertyName

        // range is a range of values the property value should exist in
        range : eg: 1..10 or 5..-5

        // regex validation
        regex : valid no case regex

        // required field or not, includes null values
        required : boolean [false]

        // The field under validation must be present and not empty if the `anotherfield` field is equal to the passed `value`.
        requiredIf : {
            anotherfield:value, anotherfield:value
        }

        // The field under validation must be present and not empty unless the `anotherfield` field is equal to the passed 
        requiredUnless : {
            anotherfield:value, anotherfield:value
        }

        // same as but with no case
        sameAsNoCase : propertyName

        // same as another property
        sameAs : propertyName

        // size or length of the value which can be a (struct,string,array,query)
        size  : numeric or range, eg: 10 or 6..8

        // specific type constraint, one in the list.
        type  : (alpha,array,binary,boolean,component,creditcard,date,email,eurodate,float,GUID,integer,ipaddress,json,numeric,query,ssn,string,struct,telephone,url,usdate,UUID,xml,zipcode),

        // UDF to use for validation, must return boolean accept the incoming value and target object, validate(value,target,metadata):boolean
        udf = variables.UDF or this.UDF or a closure.

        // Check if a column is unique in the database
        unique = {
            table : The table name,
            column : The column to check, defaults to the property field in check
        }

        // Custom validator, must implement coldbox.system.validation.validators.IValidator
        validator : path or wirebox id, example: 'mypath.MyValidator' or 'id:MyValidator'
}

Manual Validation

validate

validate() returns a ValidateResult object

component extends="cbwire.models.Component" {
    // Data properties
    data = {
        "task": ""
    };
   
    // Validation constraints
    constraints = {
        "task": { "required": true, "requiredMessage": "Task is required" }
    };
    // Action
    function addTask() {
        var result = validate(); // ValidateResult object
        if ( !result.hasErrors() ) {
            // Do something
        }
    }
}

validateOrFail

component extends="cbwire.models.Component" {
    // Data properties
    data = {
        "task": ""
    };
    // Validation constraints
    constraints = {
        "task": { "required": true, "requiredMessage": "Task is required" }
    };
    // Action
    function addTask() {
        validateOrFail(); // fail silently if validation doesn't pass.
        // Otherwise, continue
    }
}

With validateOrFail(), the error is gracefully caught and further processing of the action is prevented.

If you need more granular control over the response, use validate() instead.

Explicit Constraints

You can also run validations against any constraints you provide by passing them to the validate() method, which returns a ValidateResult object.

<cfscript>
    // Action
    function addTask() {
        var result = validate(
            target=data,
            constraints={
                "task": { required: true }
            }
        );
        if ( !result.hasErrors() ) {
            // Do something
        }
    }
</cfscript>

<cfoutput>
    <div>
        <!--- HTML goes here --->
    </div>
</cfoutput>

Displaying Errors

You can use hasErrors() and getErrors() to check for validation errors that have occurred and to display all errors.

<div>
    Add Task
    <cfif hasErrors()>
        <div class="alert alert-danger">
            <ul>
                <cfloop array="#getErrors()#" index="error">
                    <li>#error#</li>
                </cfloop>
            </ul>
        </div>
    </cfif>
</div>

To check for errors on a specific data property, you can use hasError( field) and getError( field )

<div>
    <input type="text" wire:model.blur="name">
    <cfif hasError( "name" )>
        <span class="text-danger">#getError( "name" )</span>
    </cfif>
</div>

Query String

Set your data properties with incoming query string values.

It can sometimes be helpful to update the browser's query string when your component's state changes.

Let's say we are building a component to search articles.

<!--- ./wires/SearchArticles.cfm --->
<cfscript>
    data = {
        "search": ""
    };
</cfscript>

<cfoutput>
    <div>
        <input wire:model="search" type="search" placeholder="Search articles...">
    </div>
</cfoutput>

We can automatically populate the search property above from the URL query string by adding a queryString array to our component.

queryString = [ "search" ];

<!-- ./wires/SearchArticles.cfm -->
<cfscript>
    queryString = [ "search" ];

    data = {
        "search": ""
    };
</cfscript>

<cfoutput>
    <div>
        <input wire:model="search" type="search" placeholder="Search articles...">
    </div>
</cfoutput>

Now when we access the page with 'search' included in the query string (/search-articles?search=some+string), the search property will have a default value of "some string".

In addition to this, when the user starts typing into our search field, the URL displayed in the browser will be instantly updated.

WireBox

Overview

This is a great way to keep your business logic out of your components.

You can achieve this by defining a CFC property in your component and using inject.

property name="postService" inject="PostService";

// ./models/PostService.cfc
component singleton {
    function getAll() {
        return queryExecute( "select * from posts" );
    }
}

// ./wires/Posts.cfc
component extends="cbwire.models.Component" {
    property name="postService" inject="PostService";
    function allPosts() {
        return postService.getAll();
    }
}

<!--- ./wires/posts.cfm --->
<cfoutput>
    <div>
        <h1>Posts</h1>
        <cfloop array="#allPosts()#" index="post">
            <div wire:key="post-#post.id#">
                <h2>#post.title#</h2>
            </div>
        </cfloop>
    </div>
</cfoutput>

CBWIRE uses WireBox internally to load your components. Any lifecycle methods fired by WireBox are available to you.

Getting Instances

You can use getInstance() to access a dependency from within your actions.

// ./wires/Posts.cfc
component extends="cbwire.models.Component" {
    function allPosts() {
        var postService = getInstance( "PostService" );
        return postService.getAll();
    }
}

Here is the method signature for getInstance():

/**
 * Get a instance object from WireBox
 *
 * @name The mapping name or CFC path or DSL to retrieve
 * @initArguments The constructor structure of arguments to passthrough when initializing the instance
 * @dsl The DSL string to use to retrieve an instance
 *
 * @return The requested instance
 */
function getInstance( name, initArguments={}, dsl )

Documentation

Template Directives

wire:click

Overview

Add wire:click on any HTML elements, not just buttons and links.

Using on links

When adding wire:click to links, you need to include the .prevent modifier to stop the default handling of a link in the browser. Otherwise, the browser will load the link and update the page's URL.