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

You can dispatch events directly in your component actions using dispatch().

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

You can dispatch events from your templates using $dispatch().

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

You can also dispatch using the Livewire JavaScript object.

<!--- ./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>

If you use Alpine.js, you can listen for an event like this.

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