1 of 38

v2.x

Introduction

CBWIRE is a ColdBox module that makes building modern, reactive CFML apps a breeze without the need for JavaScript frameworks such as Vue or React, and without the hassle of creating unnecessary APIs.

But what if you could have the best of both worlds: the power of Vue and React with the simplicity of CFML? Impossible, you say? Think again!

Introducing CBWIRE: Power up your CFML and make your app dreams a reality!

Let's create a counter...

Next, add wireStyles() and wireScripts() to our layout. This is required for CBWIRE to do it's magic.

Let's also insert a counter element into the page using wire( "Counter" ).

Refresh the page. You now have a reactive counter that increments when you click the plus button without any page refreshing!

What!? How?

CBWIRE renders our Counter Wire template. Our counter value defaults to 0.
When a user clicks the plus button, CBWIRE detects the event and makes an XHR request to the server.
CBWIRE picks up the XHR request and invokes the increment action.
The increment method updates the counter state by 1.
CBWIRE re-renders the template and returns the updated HTML in the XHR response
CBWIRE detects any state changes and uses Livewire to mutate the DOM.

Awesome, right?

We built a reactive counter with no page refreshing.
We didn't write any JavaScript.
We didn't use webpack or mess with JavaScript compilation.

CBWIRE is transforming the way we build CFML applications, and we think you're going to love it also!

Credits

Project Support

Resources

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 2.2

01/09/2022

Added

Changed

Fixed

What's New With 2.1

11/26/2022

Added

Fixed

What's New With 2.0

08/30/2022

Added

CBWIRE-24: File Uploads

CBWIRE-55: Ability to write unit tests for components

CBWIRE-59: Ability to override the default 'wires' folder location

CBWIRE-60: noRender() method to prevent template rendering during actions

CBWIRE-61: Implement dirty property tracking

CBWIRE-65: Invoke computed properties during template rendering and only execute once per request

CBWIRE-70: Ability to specify a 'moduleRootURI' setting to change the URI path for cbwire

CBWIRE-71: Upgrade Livewire JS to v2.10.6

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

CBWIRE-82: Disable browser caching on XHR responses

CBWIRE-83: Reduce payload bloat by removing unnecessary data in XHR requests and responses

CBWIRE-84: Move internal methods to a separate Engine object to avoid collisions with user-defined methods

CBWIRE-85: Reject incoming XHR request if 'X-Livewire' HTTP Header is not present

CBWIRE-86: Specify null values for data properties

CBWIRE-87: Dependency injection capabilities to cbwire components

CBWIRE-90: Update to match Livewire's current incoming and outgoing HTTP responses

CBWIRE-91: Ability to use Turbo to create Single-page Applications ( SPAs )

Fixed

CBWIRE-73: Calling reset( "someProperty" ) throws error

CBWIRE-74: Browser back history doesn't work

CBWIRE-80: On subsequent renderings of components, it's changing the unique id and causing DOM diff issues

CBWIRE-88: Livewire expects params to be an array

CBWIRE-89: Not passing parameters when calling update methods

Getting Started

With CommandBox, you can start building reactive CFML apps in seconds.

Requirements

Adobe ColdFusion 2018+ or Lucee 5+
ColdBox 6+

Installation

Within the root of your project, run:

box install cbwire

If you want the latest bleeding edge, run:

box install cbwire@be

Layout Setup

You need to add references for wireStyles() and wireScripts() to your layout file.

<!--- ./layouts/Main.cfm --->
<cfoutput>
<!DOCTYPE html>
<html lang="en">
    <head>
        <title>CBWIRE Example</title>
        #wireStyles()#
    </head>
    <body>
        
        <!--- JavasScript references below --->
        #wireScripts()#
    </body>
</html>
</cfoutput>

CBWIRE will not work if you do not add these to your layout.

Inserting Wires

<!--- ./layouts/Main.cfm --->
<body>
    <!--- Insert our task list wire here --->
    #wire( "TaskList" )#
            
    <!--- JavasScript references below --->
    #wireScripts()#
</body>

<!--- ./views/someview.cfm --->
<cfoutput>
    <div>#wire( "TaskList" )#</div>
</cfoutput>

Examples

See CBWIRE in action!

Git Repository

In addition to the examples above, we have a GitHub repo that contains more examples of CBWIRE. Each example includes both the code to generate the example and a section where you can see the results in real-time.

Essentials

Configuration

Alter CBWIRE's behavior with these nifty configuration options.

ColdBox.cfc

You can alter any default behavior by overriding settings in your config/ColdBox.cfc file.

// File: ./config/ColdBox.cfc
component{
    function configure() {
        moduleSettings = {
            cbwire = {
                "enableTurbo": false,
                "maxUploadSeconds": 5 * 60, // 5 minutes
                "throwOnMissingSetterMethod" : false,
                "trimStringValues": false,
                "wiresLocation": "myWires",
                "useComputedPropertiesProxy": false
            }
        };
     }
}

enableTurbo

maxUploadSeconds

The maximum amount of time allowed for uploads to complete.

throwOnMissingSetter

trimStringValues

When set to true, any data properties that contain strings will be automatically trimmed. Great for form inputs. Defaults to false.

wiresLocation

useComputedPropertiesProxy

Wires

Wires are reactive UI elements you create. They include a powerful feature-set provided by CBWIRE.

Wires primarily consist of the following:

Basic Example

// File: wires/TaskList.cfc
component extends="cbwire.models.Component" {

    // Data properties
    data = {
        "task": "",
        "tasks": []
    };
    
    // Computed properties
    computed = {
        "counter": function() {
            return arrayLen( data.tasks );
        }
    };
    
    // Listeners
    listeners = {
        "taskAdded": "sendEmail"
    };
    
    // Action
    function addTask(){
        data.tasks.append( data.task );
        this.emit( "taskAdded", data.task );
    }
    
}

<!--- /views/wires/tasklist.cfm --->
<cfoutput>
<div>
    <div>Number of tasks: #args.computed.counter()#</div>
    <div><input wire:model="task"></div>
    <div><button wire:click="addTask">Add Task</button></div>
</div>
</cfoutput>

Scaffolding

From our CommandBox shell, type:

install commandbox-cbwire

Let's create a Counter Wire that we will use to list our favorite movies.

cbwire create Counter
// Created /wires/Counter.cfc
// Created /views/wires/counter.cfm
// Created /tests/specs/integration/wires/CounterTest.cfc

You can provide named arguments as well.

cbwire create name=Counter views=false
// Created /wires/Counter.cfc
// Created /tests/specs/integration/wires/CounterTest.cfc

Data Properties

Define reactive properties for your UI Wires with just a few lines of code.

Defining Properties

component extends="cbwire.models.Component"{
    data = {
        "task": ""
    };
}

When data properties are mutated, the UI will update also.

Accessing Properties

Data Variable

You can reference a property using data.[propertyName].

component extends="cbwire.models.Component"{

    property name="taskService" inject="TaskService@myapp";
    
    // Data properties
    data = {
        "task": ""
    };
    
    // Action
    function addTask(){
        taskService.create( data.task );
    }
}

Getters

Getter methods are automatically available for your properties based on the property's name. You to access the property within your Wire using this.get[propertyName]().

component extends="cbwire.models.Component"{
    
    property name="taskService" inject="TaskService@myapp";

    // Data properties
    data = {
        "task": ""
    };
    
    // Action
    function addTask(){
        taskService.create( this.getTask() );
    }
}

You can use this as an alternative to using data.

Templates

You can reference data properties within your Wire's template using args.[propertyName].

<cfoutput>
<div>
    <h1>Task</h1>
    <div>#args.task#</div>
</div>
</cfoutput>

Resetting Properties

You can reset properties back to their original value using reset().

component extends="cbwire.models.Component"{

    // Data properties
    data = {
        "task": "Some task here"
    };

    // Action
    function resetForm() {
        data.task = "Another value";
        reset( "task" ); // Reverts data.task to 'Some task here'
    }

}

There are several ways to use reset.

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

Security

Your component's private variables scope will hold your data property definitions and current values, but it's necessary to be cautious about what you store.

You should NEVER store sensitive data ( such as passwords, and SSNs ) that you wouldn't want your application's users to see.

Computed Properties

Create dynamic properties for your UI Wires.

Computed Properties are dynamic properties and are helpful for deriving values from a database or another persistent store like a cache.

They are declared as inline functions using computed.
They can return any type of CFML value or object, not just values that can be serialized and parsed by JavaScript like Data Properties.

Defining Properties

component extends="cbwire.models.Component" {

    property name="taskService" inject="taskService@myapp";

    // Computed Properties
    computed = {
        "allTasks": function() {
            return taskService.getAll();
        }
    };
}

Accessing Properties

component extends="cbwire.models.Component" {

    property name="taskService" inject="taskService@myapp";

    // Computed Properties
    computed = {
        "allTasks": function() {
            return taskService.getAll();
        }
    };

    // Action
    function deleteTasks() {
        
        // Notice below we don't invoke the method using computed.allTasks().
        // We instead just use 'computed.allTasks'.
        // At this point, cbwire has rendered our computed properties
        // and overwritten the references with their result.
        if ( arrayLen( computed.allTasks ) {
            taskService.deleteAll();
        }

    }
}

Getters

Getters are automatically created based on the property's name.

In the example below, you to access the property using this.getAllTasks(). You can use this as an alternative to using computed.

component extends="cbwire.models.Component" {

    property name="taskService" inject="taskService@myapp";

    // Computed Properties
    computed = {
        "allTasks": function() {
            return taskService.getAll();
        }
    };

    // Action
    function deleteTasks() {
        if ( arrayLen( this.getAllTasks() ) {
            taskService.deleteAll();
        }
    }
}

Templates

<cfoutput>
<div>
    <ul>
        <cfloop array="#args.allTasks#" index="task">
            <li>#task#</li>    
        </cfloop>
    </ul>
</div>
</cfoutput>

Computed Properties ( Proxied )

Create dynamic properties for your UI Wires.

In CBWIRE 2.3.5, we introduced the ability to proxy Computed Properties, which offers several advantages, including:

Computed Properties are passed around as closures and are only rendered when called.
The ability to invoke Computed Properties anywhere they are needed (both Actions and Templates).
The ability to cache Computed Property results to enhance performance.

Computed Properties are dynamic properties and help derive values from a database or another persistent store like a cache.

They are declared as inline functions using computed.
They can return any CFML value or object.

Defining Properties

component extends="cbwire.models.Component" {

    property name="taskService" inject="taskService@myapp";

    // Computed Properties
    computed = {
        "allTasks": function() {
            return taskService.getAll();
        }
    };
}

Accessing From Actions

component extends="cbwire.models.Component" {

    // Computed Properties
    computed = {
        "allTasks": function() {
            // return something here
        }
    };

    // Action
    function deleteTasks() {      

        if ( arrayLen( computed.allTasks() ) {
            taskService.deleteAll();
        }

    }
}

Accessing From Templates

<cfoutput>
<div>
    <ul>
        <cfloop array="#args.computed.allTasks()#" index="task">
            <li>#task#</li>    
        </cfloop>
    </ul>
</div>
</cfoutput>

Actions

The magic sauce. Actions allow you to easily listen to page interactions and call a method on your Wires.

Here is a basic example of how to use it:

component extends="cbwire.model.Component"{
  
    // Actions
    function addTask(){
      queryExecute( ... );
    }
}

<!--- Template --->
<div>
    <button wire:click="addTask">Add Task</button>
</div>

Invoking Actions

Some examples of events you can listen for include:

Event

Directive

click

wire:click

keydown

wire:keydown

submit

wire:submit

Here are a few examples of each in HTML:

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

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

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

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

You can listen for any browser events on elements by 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">

Passing Parameters

You can pass parameters to your actions, such as here using addTask('Some Task').

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

// Action
function addTask( taskName ){

}

Return Values

Actions shouldn't return any value. Return values are ignored.

Accessing Data Properties

You can access data properties inside your actions directly using data.

    data = {
        "task": ""
    };

    // Actions
    function clearTasks(){
        data.task = "";
    }

Accessing Computed Properties

You can access Computed Properties inside your actions directly using computed.

    // Computed Properties
    computed = {
        "tasks": function() {
            return queryExecute( "
                select *
                from tasks
            " );

        }
    };

    // Actions
    function deleteTasks(){
        if ( computed.tasks.recordCount ) {
            // query to delete the tasks...    
        } 
    }

Notice that our Computed Property above is defined as a closure function, but once our deleteTasks() action is called, the computed property has already been rendered.

Magic Actions

In CBWIRE, there are some "magic" actions that are usually prefixed with a "$" symbol:

Function

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.

<div>
    #args.message#
    <button wire:click="setMessageToHello">Say Hi</button>
</div>

You can instead call $set and avoid the need to create an Action named setMessageToHello.

<div>
    #args.message#
    <button wire:click="$set( 'message', 'Hello' )">Say Hi</button>
</div>

It can also be used in the backend when listening for an event. For example, if you have one component that emits an event like this:

function someAction() {
    emit( "some-event" );
}

Then in another component you can use a magic action for example $refresh() instead of having to point the listener to a method:

component {
    listeners = {
        "some-event": "$refresh"
    };
}

Templates

Your Wire's HTML. Simple as that. Honestly.

Implicit Path

If you haven't specified your template file name inside your Wire using template, a template will be implicitly loaded based on the Wire's file name.

component extends="cbwire.models.Component" {
    // No template defined.
}

For the example above, the template ./views/wires/tasklist.cfm will be rendered.

File names should be lowercase when using Implicit Lookups. This is to avoid issues on case-sensitive file systems.

Explicit Path

You can specify the path to your Template using template.

component extends="cbwire.models.Component" {
    template = "wires/tasklist"; // This will look for ./views/wires/tasklist.cfm

    // template = "path/to/tasklist"; <--- Can use folders
    
    // template = "tasklist.cfm"; <--- Can use .cfm if you like
}

In CBWIRE 1.x, you would define the template path using view but this has been deprecated and template should be used going forward.

onRender

Prevent Rendering

component extends="cbwire.model.Component"{
    // Action
    function updateSession(){
        // prevent UI updating
        noRender();
    }
}

Outer Element

Be sure your template includes a single outer element such as<div>.

<!--- GOOD --->
<cfoutput>
    <div>
        <button wire:click="addTask">Add Task</button>
    </div>
</cfoutput>

<!--- BAD --->
<cfoutput>
    <div>
        <button wire:click="addTask">Add Task</button>
    </div>
    <div>
        <h1>Tasks</h1>
    </div>
</cfoutput>

If an outer element is not detected, an OuterElementNotFoundexception is thrown.

You can use something other than <div></div>.

Events & Listeners

You can emit events from both your Wires and JavaScript. Superb!

Emitting Events

Actions

Using the emit method:

function someAction() {
    emit( "taskAdded" );
}

You can provide arguments to all listeners by passing an array as the second argument.

function someAction() {
    emit( "taskAdded", [
        "some task",
        now()
    ] );
}

When emitting events, arguments must be passed as an array to ensure proper positioning both within CFML and JavaScript.

Templates

Using the $emit() method:

<button wire:click="$emit( 'taskAdded' )">

JavaScript

Using the global cbwire.emit():

<script>
    cbwire.emit( 'taskAdded' );
</script>

Listeners

You can register event listeners on a Wire by defining listeners.

component extends="cbwire.models.Component"{
    
    listeners = {
        "taskAdded": "clearCache"
    };

    function clearCache(){}
}

The clearCache method will be invoked when a taskAdded event is emitted.

JavaScript keys are case-sensitive. You can preserve the key casing in CFML by surrounding your listener names in quotations.

JavaScript

<script>
    cbwire.on( 'taskAdded', task => {
        console.log( 'A task was added. ');
    })
</script>

Wire Lifecycle

Everything that has a beginning has an end. - The Oracle, Matrix

Order of Operations

onMount()

For background AJAX requests, lifecycle methods are executed in this order.

onHydrate[DataProperty]()
onHydrate()

onMount

Runs only once when the Wire is initially wired.

This does not fire during subsequent renderings for the Wire.

component extends="cbwire.models.Component" {

    data = {
        "taskId": 0
    };

    function onMount( event, rc, prc, parameters ){
        data.taskId = event.getValue( "taskId" );
    }

}

onMount() replaces what was formerly mount(). The mount() method is deprecated and will be removed in future major releases of CBWIRE.

onHydrate

component extends="cbwire.models.Component" {

    data = {
        "hydrated": false
    };

    function clicked() {}

    function onHydrate( data ) {
        // Note that computed properties are not rendered yet
        data.hydrated = true;
    }

    function onRender( args ) {
        return "
            <div>
                <div>Hydrated: #args.hydrated#</div>
                <button wire:click='clicked'>Click me</button>
            </div>
        ";
    }
}

onHydrate[ DataProperty ]

component extends="cbwire.models.Component" {

    data = {
        "count": 1
    };

    function onHydrateCount( data ) {
        // Note that computed properties are not rendered yet
        data.count += 1;
    }  
}

onRender

component extends="cbwire.models.Component" {

    data = {
        "rendered": true
    };
    
    computed = {
        "currentDate": function() {
            return now();
        }
    }

    function onRender( args ) {
        return "
            <div>
                <div>Rendered: #args.rendered# at #args.currentDate#</div>
            </div>
        ";
    }
}

JavaScript

Seamlessly connect between the front-end and your server back-end using JavaScript and CFML.

Lifecycle Hooks

CBWIRE gives you the opportunity to execute JavaScript during various events.

Hook

Description

component.initialized

element.initialized

Called when Livewire initializes an individual element

element.updating

Called before Livewire updates an element during its DOM-diffing cycle after a network roundtrip

element.updated

Called after Livewire updates an element during its DOM-diffing cycle after a network roundtrip

element.removed

Called after Livewire removes an element during its DOM-diffing cycle

message.sent

Called when a Livewire update triggers a message sent to the server via AJAX

message.failed

Called if the message send fails for some reason

message.received

Called when a message has finished its roudtrip, but before Livewire updates the DOM

message.processed

Called after Livewire processes all side effects (including DOM-diffing) from a message

<script>
    document.addEventListener("DOMContentLoaded", () => {
        cbwire.hook('component.initialized', (wire) => {})
        cbwire.hook('element.initialized', (el, wire) => {})
        cbwire.hook('element.updating', (fromEl, toEl, wire) => {})
        cbwire.hook('element.updated', (el, wire) => {})
        cbwire.hook('element.removed', (el, wire) => {})
        cbwire.hook('message.sent', (message, wire) => {})
        cbwire.hook('message.failed', (message, wire) => {})
        cbwire.hook('message.received', (message, wire) => {})
        cbwire.hook('message.processed', (message, wire) => {})
    });
</script>

Interacting With Wires

<script>
    document.addEventListener("livewire:load", function() {
        var thisWire = cbwire.find('#args._id#'); // args._id contains the id of our wire
    
        var count = thisWire.count; // gets the value of a data property called 'count'   
        
        thisWire.count = 5; // updates the values of a data property
    
        thisWire.increment(); // calls the increment action on our wire
        
        thisWire.addTask( 'someTask' ); // calls the addTask action and passes parameters 
        
        thisWire.call( 'increment' ); // same as increment call above 
    
        // On someEvent, console log
        thisWire.on( 'someEvent', function() {
            console.log('Got someEvent');
        } );  
        
        thisWire.emit('someEvent', 'foo', 'bar'); // emits someEvent and pass parameters
    } );
</script>

Testing

Front-end testing of your UI Wires using a beautiful test API.

Test Example

component extends="cbwire.models.BaseWireTest" {

    function run(){

        describe( "TaskList.cfc", function(){
	
	    it( "calling 'clearTasks' removes the tasks", function() {
        
                wire( "TaskList" )
                    // Sets our data properties
                    .data( "tasks", [ "task1" ] )
                    // Verifies output in our template rendering
                    .see( "<li>task 1</li>" )
                    // Runs the 'clearTasks' action
                    .call( "clearTasks" )
                    // Verifies updated template rendering
		    .dontSee( "<li>task 1</li>" );
		} );
	
	} );
    }
}

Test Methods

data

wire( "TaskList" )
    .data( "tasks", [ "task1", "task2" ] ) // one property at a time
    .data( { "tasks" : [ "task1", "task2" ] } ); // struct of properties

computed

wire( "TaskList" )
    .computed( "count", function() { return 3; } ) // one property at a time
    .computed( { "count" : function() { return 3; } } ); // struct of properties

toggle

wire( "TaskList" ).toggle( "showModal" );

call

wire( "TaskList" ).call( "clearTasks" );
wire( "TaskList" ).call( "clearTasks", [ param1, param2 ] );

emit

wire( "TaskList" ).emit( "addedTask" );
wire( "TaskList" ).emit( "addedTask", [ param1, param2 ] );

see

wire( "TaskList" ).see( "<h1>My Tasks</h1>" );

dontSee

wire( "TaskList" ).dontSee( "<h1>Someone Else's Tasks</h1> ");

seeData

wire( "TaskList" ).seeData( "tasksRemoved", true );

dontSeeData

wire( "TaskList" ).dontSeeData( "tasksRemoved", true );

Wire Features

Validation

Defining Constraints

You can define constraints within your wires using this.constraints.

component extends="cbwire.models.Component"{

    this.constraints = {
        "task": { required: true }
    };
    
    // Data Properties
    data = {
        "task": ""
    };
}

Validating

validate

Returns a ValidateResult object.

component extends="cbwire.models.Component"{
    // Action
    function addTask() {
        var result = validate(); // ValidateResult object
        
        if ( !result.hasErrors() ) {
            queryExecute( ... );
        }
    }
}

validateOrFail

component extends="cbwire.models.Component"{
    // Action
    function addTask() {
        validateOrFail();

        queryExecute( ... );        
    }
}

With validateOrFail(),the error is gracefully caught and any further processing of the invoked action is prevented. The XHR response and re-rendered template are still returned. The actual errors themselves are available to the template using args.validation.

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

Validation Manager

You can get a new ValidationManager object to work with, just call getValidationManager();

component extends="cbwire.models.Component"{
    // Action
    function addTask() {
        var data = { "email": "cbwire@rocks.com" };

        var validationManager = getValidationManager();
        
        var result = validationManager.validate(
            target=data,
            constraints={
                "email": { required: true, type: "email" }
            }
        );
    }
}

Displaying Errors

<cfoutput>
<div>
    <input wire:model="task" type="text">
    <button wire:click="addTask">Add</button>
    
    <cfif args.validation.hasErrors( "task" )>
        <cfloop array="#args.validation.getAllErrors( "task" )#" index="error">
            <div>#error#</div>
        </cfloop>
    </cfif>
</div>
</cfoutput>

File Uploads

Basic File Upload

CBWIRE makes uploading and storing files easy.

Here's an example of a simple Wire that handles uploading a photo:

component extends="cbwire.models.Component" {

    data = {
        "photo": "",
        "error": ""
    };
    
    function save() {
        // 'photo' is now an instance of FileUpload@cbwire
        if ( data.photo.getSize() > "100000" ) {
            data.error = "Photo upload too big!";
        } else {
            // Store our file locally
            fileWrite( expandPath( "./somewhere.jpg" ), data.photo.get() );
            
            // Delete our file from CBWIRE's temporary storage and reset 'photo' data property
            data.photo.destroy();
        }
    }
}

<form wire:submit.prevent="save">
    File: <input type="file" wire:model="photo">
    <div><button type="submit">Save</button></div>
    
    <!--- Show thumbnail --->
    <cfif isObject( args.photo ) and args.photo.isImage()>
        <div><img src="#args.photo.getPreviewURL()#"></div>
    </cfif>
    
    <cfif len( args.error ) >
        <div class="error">#args.error#</div>
    </cfif>
</form>

Handling file inputs is no different than handling any other input type with CBWIRE. Add wire:model to the <input> tag and CBWIRE will take care of the rest.

There are several things happening under the hood to make file uploads work:

CBWIRE makes an initial request to the server to get a temporary "signed" upload URL.
Once the URL is received, JavaScript then does the actual "upload" to the signed URL, storing the upload in a temporary directory designated by CBWIRE and returning the new temporary file's unique hash ID.
Once the file is uploaded, and the unique hash ID is generated, CBWIRE makes a final request to the server, telling it to "set" the desired data property to the upload file as an instance of FileUpload ( see below ).
Now the data property (in this case photo ) is set to an instance of FileUpload@cbwire and is ready to be stored or validated at any point.

FileUpload Object

CBWIRE will automatically upload your files and set your associated data property to an instance of FileUpload@cbwire. Here are some of the methods you can use that can get quite helpful.

Method

Description

getComp()

Returns an instance of your current Wire.

getParams()

Returns any params that are passed in, including the data property name.

get()

Returns the contents of the file uploaded.

getBase64()

Returns base64 encoded string of the file.

getBase64Src()

Returns a base64 src string that can be used with <img tag>. It is recommended to use this carefully because with larger objects, this can slow down CBWIRE response times.

getTemporaryStoragePath()

Returns the temporary storage path where the file is stored by CBWIRE.

getMetaPath()

Returns the file path to meta information of the uploaded file. You can find additional details here like the name of the file when it was uploaded, the client file extension, etc.

getMeta()

Returns all captured meta information on the file upload.

getSize()

Returns the size of the file upload.

getMimeType()

Returns the mime type of the file upload.

isImage()

Returns true if this is an image.

getPreviewURL()

Provides a URL to preview the file uploaded. It only works with image uploads.

destroy()

Deletes the temporary storage and metadata of the file upload. It's essential to use this after storing the file upload in permanent storage.

Loading Indicators

You can display a loading indicator scoped to the file input during upload like so:

<input type="file" wire:model="photo">
 
<div wire:loading wire:target="photo">Uploading...</div>

The "Uploading..." message will be shown as the file is uploading and then hidden when the upload is finished.

Redirecting

Similar to ColdBox, you can relocate users using relocate.

relocate

Redirects a user to a different URI, URL, or event.

CBWIRE's relocate() method signature is nearly identical to ColdBox's internal relocate() method, with the exception that status codes cannot be set. Otherwise, most of the arguments that ColdBox accepts can be used.

Dependency Injection

Just as with ColdBox, you can inject your dependencies using WireBox.

WireBox

component extends="cbwire.models.Component" {

    // Property injection
    property name="storage" inject="cbfs:disks:temp";

    // Setter injection
    function setStorage() inject="cbfs:disks:temp" {};

    // Actions
    function someAction() {
        // Use the storage object
        storage.create( "log.txt", "CBWIRE rocks!" );
        // Use getInstance() to get objects.
        var defaultStorage = getInstance( "cbfs:disks:default" ); 
    }

}

onDIComplete

If you want to act immediately after dependency injection has been completed, you can define an onDIComplete method.

component extends="cbwire.models.Component" {

    property name="storage" inject="cbfs:disks:temp";

    function onDIComplete(){
        storage.create( "log.txt", "Dependency Injection Complete!" );
    }

}

Template Features

Directives

CBWIRE's powerful directives allow you to listen for client side events, invoke actions, bind to data properties, and more.

Core Directives

wire:key

Define a key name foo for the element. This provides a reference point for the Livewire DOM diffing system. Useful for adding/removing elements and keeping track of lists.

wire:click

wire:click.prefetch

wire:submit

Listeners for a submit event on a form.

wire:keydown

wire:keydown.enter

wire:foo

You can listen to any JS event, not just those defined by Livewire.

wire:model

wire:model.debounce

The same as wire:model="foo" except that all input events to the element will be debounced for the specified duration. Defaults to 150 milliseconds. Useful for reducing XHR background requests during user input. You can set the milliseconds value to any numeric value.

wire:model.defer

wire:model.lazy

If your input field does not require immediate updating ( such as for instant form validation), we highly recommended you used the lazy modifier to reduce the number of XHR requests .

wire:poll

wire:init

wire:loading

Hides the HTML element by default and makes it visible when XHR requests are performed.

wire:loading.class

Adds the foo class to the HTML element while XHR requests are in transit.

wire:loading.class.remove

Removes the foo class from the HTML element while XHR requests are in transit.

wire:loading.attr

Adds the disabled="true" attribute while XHR requests are in transit.

wire:dirty

Hides the HTML element by default and makes it visible when the element's state has changed since the latest XHR request.

wire:dirty.class

Adds the foo class to the HTML element when the element's state has changed since the latest XHR request.

wire:dirty.class.remove

Removes the foo class from the HTML element when the element's state has changed since the latest XHR request.

wire:dirty.attr

Adds the disabled="true" attribute when the element's state has changed since the latest XHR request. Used in addition to wire:target.

wire:target

wire:ignore

Instructs Livewire to not update the element or any child elements when updating the DOM. Useful when using third-party JavaScript libraries.

wire:ignore.self

Instructs Livewire to not update the element but DOES allow updates to any child elements when updating the DOM.

wire:offline

Event Modifiers

CBWIRE Directives sometimes offer "modifiers" to add extra functionality to an event. Here are the available modifiers that can be used with any event.

Keydown Modifiers

Here is a quick list of some common ones you may need:

Loading States

Help website users during wait times using Loading States.

Loading States can make your apps feel much more responsive and user-friendly.

Toggling Elements

Let's look at an action that takes too long.

We can annotate our <div> with wire:loading to display Adding Task while the checkout action is running.

Toggling Attributes

Targeting Specific Actions

You can target a specific action so that the element is only visible is a specific action is loading using wire:target.

Delaying

If you want to avoid flickering because loading is very fast, you can add a .delay modifier, and it will only show up if loading takes longer than 200ms.

If you wish, you can customize the delay duration with the following modifiers:

Display Property

Loading State elements are set with a CSS property of display: inline-block; by default. You can override this behavior by using various directive modifiers.

Hiding

If you would like to display an element except during a loading state, you can apply the wire:loading.remove directive.

Polling

Poll for state changes based on a specified interval without page refreshes. Hot dog!

You can add a wire:poll directive to your elements to poll for changes using a set interval. The default interval is set to poll every 2 seconds.

You can append a different interval time to your directive as well.

Polling for changes over AJAX can be a resonable alternative to strategies such as Pusher or WebSockets.

Method Invocation

If you would like to invoke a method during each poll interval, you can do so by specifying a method name.

Cancel Polling

If you want stop polling, you can simply no longer render the HTML element that has the wire:poll directive.

Prefetching

Prefetch state changes when the user mouses over an HTML element. Fantastico!

In the example here, the togglePreview action will be prefetched and invoked when the user mouses over the button. The results of the fetch are not displayed until the user clicks the 'Show Preview' button.

Prefetching works well for actions that do not perform any side effects, such as mutating session data or writing to a database. If the action you are "pre-fetching" does have side effects, you may encounter unpredictable results.

Offline State

Toggle UI elements when the user is offline or online. Groovy!

You can use wire:offline to display elements when Livewire detects that the user is offline.

Use .remove to specify classes you want to be removed when offline.