v7.3.0

Working with columns

A TaskBoard displays tasks in multiple columns (or lists) and optionally in swimlanes. This guide shows how to define and manipulate columns and how to specify which column a task belongs to.

Defining columns

Columns can be defined as strings or as data objects, by supplying a columns config. Either way, the columns are turned into instances of ColumnModel (column records) loaded into a store.

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

const taskBoard = new TaskBoard({
   columns : [
       'todo',
       'doing',
       'done'
   ]
});

The strings will be converted into column records, using the string as is as the columns id ("doing") and a capitalized version of the string as the columns text ("Doing"):

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

const taskBoard = new TaskBoard({
   columns : [
       { id : 'todo', text : 'Todo' },
       { id : 'doing', text : 'Doing' },
       { id : 'done', text : 'Done' }
   ]
});

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

const taskBoard = new TaskBoard({
   columns : {
       data: {
           todo  : { text : 'Todo' },
           doing : { text : 'Doing' }, 
           done  : { text : 'Done' }
       }
   }
});

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

  • color - Pick from a predefined set of colors, applied as currentColor to the columns element. Useful for styling
  • flex - To specify a flex value for the column (defaults to 1)
  • id - Columns unique id, used to match to tasks (explained further down)
  • text - Columns text, shown in headers and column pickers etc.
  • tasksPerRow - Number of tasks per row in the column (uses TaskBoards setting by default)
  • width - To use a fixed width for the column

For a complete list, see ColumnModel configs.

An example using more options:

const taskBoard = new TaskBoard({
   columns : [
       // Make todo twice as wide as it would be by default
       { id : 'todo', text : 'Todo', flex : 2 },
       // Apply a green currentColor to ongoing tasks (up to the app to
       // use it for some nice look)
       { id : 'doing', text : 'Doing', color : 'green' },
       // Done taks are not as important as the others, make the column
       // narrow and squeeze more cards in
       { id : 'done', text : 'Done', width : 150, tasksPerRow : 3 }
   ]
});

Loading Columns remotely

You can also load Columns data remotely as part of the Project dataset.

const taskBoard = new TaskBoard({
    // Project will load columns, tasks, resources and assignments
    project : {
        loadUrl  : 'data/data.json',
        autoLoad : true
    }
});

data.json

{
  "success" : true,
  "columns" : {
    "rows" : [
      {
        "id"   : "todo",
        "text" : "Todo"
      },
      {
        "id"          : "doing",
        "text"        : "Doing",
        "tasksPerRow" : 2
      },
      {
        "id"          : "review",
        "text"        : "Review",
        "tasksPerRow" : 2
      },
      {
        "id"          : "done",
        "text"        : "Done",
        "tasksPerRow" : 2
      }
    ]
  }
}

You can see this in action in the Remote Columns demo demo in the examples folder.

Linking tasks to columns

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

const taskBoard = new TaskBoard({
    // Match tasks to columns using the status field
    columnField : 'status',

    columns : [
        'todo',
        'done'
    ],

    project : {
        tasks : [
            // Task that will be displayed in the "todo" column
            { id : 1, name : 'Task 1', status : 'todo' },
            // Task that will be display in the "done" column
            { id : 2, name : 'Task 2', status : 'done' }
        ]
    }
});

Accessing and manipulating columns at runtime

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

// The column store
taskBoard.columns

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

// Access the "doing" column
taskBoard.columns.doing

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

// Change the text of the "doing" column
taskBoard.columns.doing.text = 'In progress';

To remove a column, simply delete it from columns:

// Remove the "done" column
delete taskBoard.columns.done;

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

// Append a "considering" column
taskBoard.columns.considering = {
    text  : 'Considering',
    color : 'blue'
};

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 columns store:

// Access the "doing" column
taskBoard.columns.getById('doing');

// Change the text of the "doing" column
taskBoard.columns.getById('doing').text = 'In progress';

// Remove the "done" column
taskBoard.columns.getById('done').remove();

// Append a "considering" column
taskBoard.columns.add({
    id    : 'considering',
    text  : 'Considering',
    color : 'blue'
});

Column widgets & features

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

Features

  • ColumnDrag - Rearrange columns by dragging and dropping their headers:
  • ColumnLock - Allows user to lock columns to the left or right:
  • ColumnRename - Lets users rename a column by using the header menu or by double-clicking the title element
  • ColumnResize - Allows user to change the width of columns by using a resize handle between column headers:
  • ColumnSort - Allows sorting of tasks per individual column on a TaskBoard:

Widgets

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

Contents