v7.3.0

Listening for events

Bryntums widgets and classes trigger events to notify you of changes. Listening for these events is a crucial part of writing an application that uses Bryntum TaskBoard. You have plenty of options for doing this in a way that suites your application, as detailed below.

Where to find information on events

In the API docs events are listed at the bottom of each class documentation page, see for example TaskBoard events. You can get there quickly by clicking on the red "e" icon found at the top of each class (if it is grayed out the class triggers no events). Please note that you can click on an event to expand its description and reveal any parameters it is triggered with (like this).

How to listen for events

To catch triggered events you have to add a listener to the object that triggers them. If you for example want to know when a user clicks on a task card on the TaskBoard, then you should add a listener (listen) for the taskClick event on TaskBoard. This can be achieved in multiple ways:

Setting up listeners at configuration time

You can add listeners when constructing a new instance of a class by specifying the listeners config:

const taskBoard = new TaskBoard({
    // other configs...

    listeners : {
        taskClick : myTaskClickFn
    }
});

Because of how JavaScripts this-object works you might want to specify what you expect as this in your listener function:

const taskBoard = new TaskBoard({
    listeners : {
        taskClick : () => {
            console.log('clicked');
        }
    }
});

When specifying a thisObj it is also possible to resolve the function to call by specifying its name as a string:

const taskBoard = new TaskBoard({
    listeners : {
        taskClick : 'myTaskClickFn',
        thisObj   : this
    }
});

Thanks to ES6 syntax for member functions you can also specify the function inline in the config in a nice way:

const taskBoard = new TaskBoard({
    listeners : {
        taskClick() {

        }
    }
});

It is possible to add multiple listeners in one go (using any syntax from above):

const taskBoard = new TaskBoard({
    listeners : {
        taskClick    : 'myTaskClickFn',
        taskDblClick : 'myTaskDblClickFn',
        thisObj      : this
    }
});

Adding listeners at runtime

You can add listeners to an existing instance using addListener or on. Both work the same way, on is a bit shorter to type:

taskBoard.on('taskClick', () => console.log('click'));
taskBoard.addListener('taskDblClick', () =>  console.log('dblclick'));

If you need to specify a thisObj it is possible as the third argument:

taskBoard.on('eventclick', this.onEventClick, this);

You can also pass multiple listeners as a config object in the same way as when specifying them during configuration:

taskBoard.on({
    taskClick    : 'onTaskClick',
    taskDblClick : 'onTaskDblClick',
    thisObj      : this
});

Using "on" functions

Bryntum widgets also supports directly calling functions that match the "on[EventName]" pattern. We recommend using the approaches above, but this way of defining listeners can be convenient for small widgets:

const button = new Button({
    onClick() {
        console.log('click');
    }
});

You can also assign on the fly:

taskBoard.onTaskClick = () => console.log('click');

The listener functions

All listener functions are called with a single argument when an event is triggered. This argument is an object that has at least one property source, which is the object that triggered the event. Most events populate the object with more information, see API docs to find out what. For example taskClick has the following: 

taskBoard.on({
    taskClick(event) {
        // The taskClick event has the following properties:
        // source - Triggering object, a TaskBoard instance
        // taskRecord - Clicked tasks record
        // columnRecord - Column of the clicked task
        // swimlaneRecord - Swimlane of the clicked task (if used)
        // event - The browser click event
    }
});

This single argument approach is a great fit for ES6 destructuring, allowing syntax such as this:

taskBoard.on({
    taskClick({ taskRecord }) {
        // Only interested in the record, leave the others out
    }
});

Additional options

The listener config object has some useful properties such as once and prio:

  • once allows you to specify a listener that will unregister itself after the first call. See addListener for more details.
taskBoard.on({
    taskClick() {
        // Only called on the first click
    },
    // Call once and then unregister
    once : true
});
  • prio lets you specify a listeners priority, which is used to determine the order in which listeners are called. See addListener for more details.
taskStore.on({
    load() {
        // Called before normal load listeners
    },
    // Higher prio is called prior to lower
    prio : 100
});

It is possible to catch all events triggered by an object using a catchAll function:

taskBoard.on({
    catchAll(event) {
        // Any event triggered on taskBoard will pass through here
    }
});

Preventing events

By returning false from a listener for an event documented as preventable the action that would otherwise be executed after the event is prevented. These events names are usually prefixed with before.

Sample code:

onBeforeTaskEdit(event) {
    if (someCondition) {
       return false;
    } 
}

You can see more such events by typing onBefore in the search bar.

Frameworks integration

Check Angular, React and Vue framework integration guides for the details.

Contents