kanban — u_pbt_kanban #

← Component reference · Guide contents

kanban is a board of cards sorted into columns — the stages of a piece of work: to do, in progress, in review, done. The user drags a card from one column to another, or up and down in its own; ue_card_moved tells you which one, from where, to where and at which place. Each card shows a title, coloured tags, its assignee, a due date that turns red when late and a badge; each column has its work-in-progress limit and folds. The board is filled by hand or from a DataStore, which receives the moves.

▶ See it live — Demo application, Kanban board tile: the preview, the code behind it and this page, side by side.

At a glance #

Quick start #

// The columns, in the order of the work
uo_board.of_add_column(/*key*/ "todo", /*title*/ "To do")
uo_board.of_add_column(/*key*/ "doing", /*title*/ "In progress")
uo_board.of_add_column(/*key*/ "done", /*title*/ "Done")

// The cards : a key unique on the board, a column, a title
uo_board.of_add_card(/*key*/ "t1", /*column*/ "todo", /*title*/ "Login page")
uo_board.of_add_card(/*key*/ "t2", /*column*/ "doing", /*title*/ "Crash on save")
uo_board.of_card(/*key*/ "t2").is_tags = "Bug"
uo_board.of_card(/*key*/ "t2").is_assignee = "Alan Turing"

// event ue_card_moved of uo_board : (string as_key, string as_from_column,
// string as_to_column, long al_position, long al_from_position)
// Save the new state of the task
UPDATE tasks SET status = :as_to_column WHERE id = :as_key;

Columns, cards and places #

A column is named by its key, a card too — and the key of a card is unique on the whole board, not only in its column: a card keeps its key when it changes column, its handles stay valid and every event names it alone. The column of a card is read by of_card(key).of_column(), its place by of_position(); a place counts from 1, hidden cards included.

A column has a work-in-progress limit (il_limit): its header counts 3/5, and it turns red past it. The limit is soft — the card lands anyway; for a hard limit, refuse the move in ue_card_moving by comparing il_limit with of_visible_count() of the column, what the header counts (a hidden card does not count). ib_done marks the column of finished work: its cards are never late. A column folds into a narrow strip (its chevron, ib_collapsed); a card still drops on it, at the end.

A move of the user (a drag, Ctrl + arrows, or the card lifted with Space and dropped) and a move of your code (of_move_card) raise the same ue_card_moved, as SelectItem raises the event of the click. With ib_veto_moves, ue_card_moving is asked first, in both cases: returning FALSE leaves the card where it is, and of_move_card then returns -4.

With ib_reorderable = true, the user reorders the columns too: he drags the header of a column (a vertical accent bar shows where it will land, Escape cancels) or presses Ctrl + Shift + Left / Right. ue_column_moved gives the column and its two places, counted from 1 among all the columns; of_move_column does the same from your code and raises the same event, ue_column_moving being asked first with ib_veto_moves. Off by default: the columns are the process of your application. What the user arranged — the order of the columns and their fold — is read by of_get_layout, given back by of_set_layout, and every change raises ue_layout_changed with the whole layout: store it, give it back at the next start.

What a card shows #

A card shows its title (is_title), its text (is_text, cut after four lines), its tags (is_tags, separated by commas, coloured by is_tag_tones: Bug=danger|UI=info), its assignee (is_assignee, a round avatar with the initials), its due date (is_due, yyyy-mm-dd: red once past, orange on the day, compared with is_today or the date of the workstation) and a badge (is_badge). Title, text and badge accept the rich text markup.

The body of the cards can be written by a template, is_card_template: rich text where {customer} is a field of the card — one of yours (of_set_field), a column of the DataStore it came from, or a built-in field (title, text, tags, assignee, initials, badge, due, column, column_title, key). {due:dddd d mmmm} writes a date as a DataWindow display format does (the tokens d dd ddd dddd m mm mmm mmmm yy yyyy, a text between double quotes — outside quotes, a letter d, m or y is a token —, [shortdate] and [longdate] in the language of the display), {?amount}…{/amount} keeps a piece when the field says something, {!amount}…{/amount} when it says nothing, {x:raw} keeps a value as markup, {{ }} are braces. A value is always shown as it is, never read as markup.

// A field of our own, then the body of every card
uo_board.of_set_field(/*key*/ "t1", /*field*/ "customer", /*value*/ "Acme")
uo_board.is_card_template = "{?customer}For [b]{customer}[/b]{/customer}{?due} - due {due:d mmm}{/due}"

From a DataStore #

of_from_datastore makes one card of each row of a DataStore, a DataWindow or a DataWindowChild — the same call, and a DataWindow is written back itself. Its key is the RowID of the row — of_card(key).of_row() gives the number of its row as long as the DataStore is neither reset nor retrieved again — or the value of the ROLE_KEY column. A row whose key is empty, not valid, already met or held by a card added by hand is not loaded: the call returns 0 and of_get_last_error names it by its number — give your hand cards keys that are not numbers. A column plays a role when it is named like it (title, text, tags, assignee, due, badge, color, order, column, key) or when of_map says so. The ROLE_COLUMN column says in which column of the board the card stands; a value no column holds gets a column of its own, at the end — a value holding / or | takes a key where they become - (R&D-QA) and keeps its value, the one a move writes back; an empty value is not loaded (of_get_last_error names it), a CHAR value padded with blanks finds its column. A column born of a value goes once empty, unless your code set a property or a colour on it. ROLE_ORDER sorts the cards of a column: the rank is the place of a card among the cards of the DataStore of its column, from 1 (a card added by hand takes no rank). Keyed by ROLE_KEY, a second load, of_map and of_reload_row update the cards in place: a card that comes back keeps its flags, its fields and its handle. Keyed by the RowID, a second of_from_datastore is a new load: PowerBuilder gives the same RowIDs again after a Reset or a Retrieve, to other records — every card of the old rows goes (its handle is freed) and the cards are made anew; of_map and of_reload_row stay in place. A card your code removed does not come back with of_map: its row stays in the DataStore, the next of_from_datastore reads it again. Dates and decimals are read in the regional settings of the workstation (a decimal field reads 1234.5). Every column is a field of the template.

With ib_write_back = true, a card of a row writes its new column into the row (and, with ROLE_ORDER, the ranks of both columns) before it moves — the row is found by its RowID and by nothing else: ue_card_moved reads the DataStore up to date, the Update stays yours. The column receives the value the target column stands for (R&D/QA, never its key R&D-QA). All or nothing: a value the DataStore refuses — the column or a rank — puts back what was already written, leaves the card where it was (it never leaves to come back) and raises ue_write_back_failed; of_move_card then returns -4. One move of the user is written at a time: a gesture made before the previous one is written is ignored, and said. After changing a row yourself, of_reload_row sends it to the board again.

// The columns of the board : the values of the status column
uo_board.of_add_column(/*key*/ "open", /*title*/ "Open")
uo_board.of_add_column(/*key*/ "active", /*title*/ "Active")
uo_board.of_add_column(/*key*/ "closed", /*title*/ "Closed")

// Which column of the DataStore plays which role
uo_board.of_map(/*role*/ u_pbt_kanban.ROLE_COLUMN, /*column*/ "status")
uo_board.of_map(/*role*/ u_pbt_kanban.ROLE_ASSIGNEE, /*column*/ "owner")
uo_board.of_map(/*role*/ u_pbt_kanban.ROLE_ORDER, /*column*/ "rank")

// A move goes into the DataStore, then the rows become cards
uo_board.ib_write_back = true
uo_board.of_from_datastore(/*ads*/ ids_tasks)

Properties #

Properties of a column — n_pbt_kanban_column #

Its handle, through of_column(key). Its of_count() counts the cards it holds and its of_keys_at(n) returns the key of the n-th, in their order; of_child_keys returns them all in one read.

Properties of a card — n_pbt_kanban_card #

Three reads of the handle, read only: of_column() returns the key of the column the card stands in now, of_position() its place in that column counted from 1 (0 when the board does not hold it), of_row() the number of its row in the DataStore (0 for a card added by hand). A card moves through of_move_card of the board.

Methods #

Events #

Keyboard and mouse #

• Drag a card: past 5 pixels, a ghost follows the pointer, the target column lights up and an accent bar shows where the card will land; the board and the column scroll near their edges, and go on while the pointer stays there. Escape cancels.
• Arrows: the card above, below, or at the same rank in the next column; a folded column, or one that draws no card, is reached by its header. Home / End: the first, the last of the column.
• Ctrl + Up / Down moves the card up or down in its column; Ctrl + Left / Right passes it to the next open column, at the same rank (a folded column is jumped over; Space then the arrows stop on it). Read right to left, Left and Right are inverted.
• Space lifts the selected card: the arrows carry it (a bar shows where it will land), Space or Enter drops it — the same question and the same write as a drag —, Escape puts it back. A screen reader hears each step.
• The headers are always reachable: Up on the first card, Left / Right from one header to the next; on a header, Enter or Space folds or opens the column, + opens it, - folds it, Down goes back to the first card.
• Enter or a double click opens the card, Delete asks to delete it, Insert asks for a new card in the column (on a card or a header), a right click on a card or a header: its event.
• The board is one stop of the Tab key: the selected card takes it, else the first card, else the first header.
• With ib_reorderable: dragging the header of a column moves it (a vertical bar shows where it will land, Escape cancels); Ctrl + Shift + Left / Right, on a card or on a header, moves its column, inverted right to left.

Examples #

A hard limit and a rule of passage #

// Once, after the board is built : ask before each move
uo_board.ib_veto_moves = true

// event ue_card_moving of uo_board : a card reaches Done only from Review
if as_to_column = "done" and as_from_column <> "review" then return false

// and a column past its limit takes no more card (what its header counts :
// the visible cards)
if as_to_column <> as_from_column then
	if this.of_column(/*key*/ as_to_column).il_limit > 0 and this.of_column(/*key*/ as_to_column).of_visible_count() >= this.of_column(/*key*/ as_to_column).il_limit then return false
end if
return true

Finding the columns again at the next start #

// Once, after the board is built : the user may move the columns
uo_board.ib_reorderable = true

// The layout stored at the last start, if any
uo_board.of_set_layout(/*layout_json*/ ProfileString(gs_ini, "board", "layout", ""))

// event ue_layout_changed of uo_board : store every change
SetProfileString(gs_ini, "board", "layout", as_layout_json)

Opening a card in your window #

// event ue_card_opened of uo_board : the row of the card, edited in your window
OpenWithParm(w_task_edit, uo_board.of_card(/*key*/ as_key).of_row())

// The row may have changed : the card follows it
uo_board.of_reload_row(/*row*/ uo_board.of_card(/*key*/ as_key).of_row())

A team board: points, shared width, quick add #

// The estimate of a card, a field of our own
uo_board.of_set_field(/*key*/ "t1", /*field*/ "points", /*value*/ "5")

// Every header : its cards, its limit, the sum of the points of its cards
uo_board.is_count_template = "{count}{?limit}/{limit}{/limit} - {sum:points} pts"

// The open columns share the width of the board
uo_board.ii_column_width = 0

// + Add a card opens a title field at the foot of the column
uo_board.ib_add_button = true
uo_board.ib_quick_add = true

// event ue_new_requested of uo_board : the card typed, with a key of ours
uo_board.of_add_card(/*key*/ "new" + String(Cpu()), /*column*/ as_column, /*title*/ as_title)

Good practice #

• Few columns, named by the stage and not by the person: five or six read at a glance.
• A work-in-progress limit on the active columns: it is what turns a board into a steering tool.
• Save in ue_card_moved (or let ib_write_back write the DataStore): the board shows the new state before the database knows it.
• A short template: two lines of body are enough, the detail goes into your edit window.
• Tags with a constant tone: Bug always red, from one window to another.
• Keys that are not numbers for your hand cards, on a board fed by a DataStore: a card keyed 12 keeps the row of RowID 12 from being loaded (of_get_last_error says it).
• A key of the data (ROLE_KEY) when the rows are read again: with the RowID key, a new of_from_datastore makes the cards anew.

Inherited from the common base #

These members exist on every visual component — they are not specific to this one. They are detailed once, in the transverse chapters; this table only says where to read them.

Two helpers are not inherited: of_icon and of_escape_markup live on n_pbt_utils. Declare one — n_pbt_utils lnv_utils, nothing to create — and call them on it.

← Component reference · Guide contents