Events

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

Dispatching Events

You can dispatch events directly in your component Actions.

component extends="cbwire.models.Component" {

    // Action
    function addPost() {
        dispatch( "post-added" );
    }

}

You can dispatch events from your Templates.

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

You can also dispatch using the the global cbwire JavaScript object.

<!--- Javascript --->
<script>
    cbwire.emit( 'post-added' );
</script>

Passing Parameters

You can send parameters as your dispatching an event.

component extends="cbwire.models.Component" {

    function addPost() {
        dispatch( "post-added", { "id": post.getId() } );
    }

}

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

<script>
    cbwire.dispatch( 'post-added', { id: '#post.getID()#' } );
</script>

dispatchTo

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

component extends="cbwire.models.Component" {

    function addPost() {
        dispatchTo( "TopBar", "post-added", {} );
    }

}

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

<script>
    cbwire.dispatchTo( 'TopBar', 'post-added', { id: '#post.getID()#' } );
</script>

dispatchSelf

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

component extends="cbwire.models.Component" {

    function addPost() {
        dispatchSelf( "post-added", { "id": post.getId() } );
    }

}

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

Listeners

You register event listeners using the listeners struct of 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.

component extends="cbwire.models.Component" {

    listeners = {
        "post-added": "incrementPostCount" 
    };
    
    function incrementPostCount() {
        // Increment the post count
    }

}

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

Dispatching Browser Events

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

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

    data = {};

    function submitForm(){
        // Dispatch a 'form-submitted' browser event. Pass parameters
        dispatch( "form-submitted", { "submittedBy": "Grant" } );
    }

}

<!--- wires/MyComponent.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 are using AlpineJS, you can listen to an event like this.

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