v7.3.0

Working with swimlanes

A TaskBoard displays tasks in multiple columns and optionally in swimlanes. This guide shows how to define and manipulate swimlanes and how to specify which swimlane a task belongs to.

Defining swimlanes

Swimlanes works in a very similar way as columns. If you have read the Working with columns guide you will recognize most of the contents here.

Swimlanes can be defined as strings or as data objects, by supplying a swimlanes config. Either way, the swimlanes are turned into instances of SwimlaneModel (swimlane records) loaded into a store.

In the most basic scenarios, you can simply supply an array of strings:

const taskBoard = new TaskBoard({
   swimlanes : [
       'high',
       'medium',
       'low'
   ]
});

The strings will be converted into swimlane records, using the string as is as the swimlanes id("high") and a capitalized version of the string as the swimlanes text ("High"):

For more advanced scenarios, you can instead supply an array of swimlane data objects:

const taskBoard = new TaskBoard({
   swimlanes : [
       { id : 'high', text : 'High' },
       { id : 'medium', text : 'Medium' },
       { id : 'low', text : 'Low' }
   ]
});

To give you even more options, swimlanes can also be specified in object form, keyed by their id:

const taskBoard = new TaskBoard({
   swimlanes : {
       data: {
           high   : { text : 'High' },
           medium : { text : 'Medium' }, 
           low    : { text : 'Low' }
       }
   }
});

The three snippets above all yield the same end result. In the two latter approaches you can also supply more options for the swimlanes. The most common options are:

  • color - Pick from a predefined set of colors, applied as currentColor to the swimlanes element. Useful for styling
  • id - Swimlanes unique id, used to match to tasks (explained further down)
  • text - Swimlanes text, shown in headers and swimlane pickers etc.
  • tasksPerRow - Number of tasks per row in the swimlane (uses TaskBoards setting by default)

For a complete list, see SwimlaneModel configs.

Linking tasks to swimlanes

Tasks are linked to swimlanes by matching the value for the configured swimlaneField to a swimlanes id. Most demos use the prio field for this, but you can use any field:

const taskBoard = new TaskBoard({
    // Match tasks to swimlanes using the prio field
    swimlaneField : 'prio',

    swimlanes : [
        'high',
        'low'
    ],

    project : {
        tasks : [
            // Task that will be displayed in the "high" swimlane
            { id : 1, name : 'Task 1', prio : 'high' },
            // Task that will be display in the "low" swimlane
            { id : 2, name : 'Task 2', prio : 'low' }
        ]
    }
});

Accessing and manipulating swimlanes at runtime

As mentioned above, swimlanes are turned into records used to populate a store. The store that holds the swimlanes can be accessed using the swimlanes property of the TaskBoard:

// The swimlane store
taskBoard.swimlanes

By default the store is configured with objectify : true (docs here), which enables a nice object-like syntax for interacting with the swimlanes. Swimlanes are keyed by id, and can be accessed as you would access a property of any JS object:

// Access the "high" swimlane
taskBoard.swimlanes.high

The settings (fields) for the swimlane can be read/manipulated at runtime, changes will be reflected in the UI automatically:

// Change the text of the "high" column
taskBoard.swimlanes.high.text = 'Important';

To remove a swimlane, simply delete it from swimlanes:

// Remove the "high" swimlane
delete taskBoard.swimlanes.high;

To add, assign a new property on swimlanes (minding reserved names, see store properties:

// Append a "critical" swimlane
taskBoard.swimlanes.critical = {
    text  : 'Critical',
    color : 'red'
};

Using the traditional store syntax

If you opt out of the object-like syntax, or just don't want to use it, you can still use the normal ways that you interact with other Bryntum stores with for the swimlanes store:

// Access the "high" swimlane
taskBoard.swimlanes.getById('high');

// Change the text of the "high" swimlane
taskBoard.swimlanes.getById('high').text = 'Important';

// Remove the "high" swimlane
taskBoard.swimlanes.getById('high').remove();

// Append a "critical" swimlane
taskBoard.swimlanes.add({
    id    : 'critical',
    text  : 'Critical',
    color : 'red'
});

Swimlane widgets & features

Also worth mentioning in this guide are the built-in widgets and features that are associated with swimlanes.

Features

  • SwimlaneDrag - Rearrange swimlanes by dragging and dropping their headers:

Widgets

  • SwimlaneCombo - Combo listing swimlanes, used in the task editor (double click a task in the demo):

Contents