kanban — u_pbt_kanban #

← Referência dos componentes · Índice do guia

kanban é um quadro de cartões arrumados em colunas — as etapas de um trabalho: a fazer, em curso, em revisão, concluído. O utilizador arrasta um cartão de uma coluna para outra, ou sobe-o e desce-o na sua; ue_card_moved diz-lhe qual, de onde, para onde e em que lugar. Cada cartão mostra um título, etiquetas coloridas, o seu responsável, um prazo que fica vermelho em atraso e um emblema; cada coluna tem o seu limite de trabalho em curso e recolhe-se. O quadro preenche-se à mão ou a partir de um DataStore, que recebe as deslocações.

▶ Ver ao vivo — Aplicação de demonstração, mosaico Kanban board: a pré-visualização, o código que o produz e esta página, lado a lado.

Em resumo #

Início rápido #

// 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;

Colunas, cartões e posições #

Uma coluna designa-se pela sua chave, um cartão também — e a chave de um cartão é única em todo o quadro, não só na sua coluna: um cartão mantém a sua chave quando muda de coluna, os seus handles continuam válidos e cada evento nomeia-o sozinho. A coluna de um cartão lê-se com of_card(key).of_column(), a sua posição com of_position(); uma posição conta-se a partir de 1, cartões ocultos incluídos.

Uma coluna tem um limite de trabalho em curso (il_limit): o seu cabeçalho conta 3/5, e fica vermelha para lá dele. O limite é flexível — o cartão chega na mesma; para um limite estrito, recuse a deslocação em ue_card_moving comparando il_limit com of_visible_count() da coluna, o que o cabeçalho conta (um cartão oculto não conta). ib_done marca a coluna do trabalho concluído: os seus cartões nunca estão em atraso. Uma coluna recolhe-se numa faixa estreita (a sua seta, ib_collapsed); ainda se pode largar um cartão nela, no fim.

Uma deslocação do utilizador (arrastar, Ctrl + setas, ou o cartão levantado com Espaço e pousado) e uma deslocação do seu código (of_move_card) levantam o mesmo ue_card_moved, como SelectItem levanta o evento do clique. Com ib_veto_moves, ue_card_moving é colocado antes, nos dois casos: devolver FALSE deixa o cartão onde está, e of_move_card devolve então -4.

Com ib_reorderable = true, o utilizador reordena também as colunas: arrasta o cabeçalho de uma coluna (uma barra de destaque vertical mostra onde vai cair, Esc cancela) ou prime Ctrl + Shift + Esquerda / Direita. ue_column_moved dá a coluna e os seus dois lugares, contados a partir de 1 entre todas as colunas; of_move_column faz o mesmo a partir do seu código e levanta o mesmo evento, sendo ue_column_moving colocado antes com ib_veto_moves. Desativado por omissão: as colunas são o processo da sua aplicação. O que o utilizador organizou — a ordem das colunas e o seu recolhimento — lê-se com of_get_layout, devolve-se com of_set_layout, e cada alteração levanta ue_layout_changed com a disposição inteira: guarde-a e devolva-a no próximo arranque.

O conteúdo de um cartão #

Um cartão mostra o seu título (is_title), o seu texto (is_text, cortado após quatro linhas), as suas etiquetas (is_tags, separadas por vírgulas, coloridas por is_tag_tones: Bug=danger|UI=info), o seu responsável (is_assignee, um avatar redondo com as iniciais), o seu prazo (is_due, aaaa-mm-dd: vermelho depois de ultrapassado, laranja no próprio dia, comparado com is_today ou com a data do posto) e um emblema (is_badge). Título, texto e emblema aceitam o texto formatado com etiquetas.

O corpo dos cartões pode ser escrito por um modelo, is_card_template: texto formatado onde {customer} é um campo do cartão — um dos seus (of_set_field), uma coluna do DataStore de onde vem, ou um campo integrado (title, text, tags, assignee, initials, badge, due, column, column_title, key). {due:dddd d mmmm} escreve uma data como um formato de apresentação de DataWindow (os símbolos d dd ddd dddd m mm mmm mmmm yy yyyy, um texto entre aspas duplas — fora delas, uma letra d, m ou y é um símbolo —, [shortdate] e [longdate] na língua da apresentação), {?amount}…{/amount} mantém um pedaço quando o campo diz alguma coisa, {!amount}…{/amount} quando não diz nada, {x:raw} mantém um valor como etiquetas, {{ }} são chavetas. Um valor é sempre mostrado tal como é, nunca lido como etiquetas.

// 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}"

A partir de um DataStore #

of_from_datastore faz um cartão de cada linha de um DataStore, de um DataWindow ou de um DataWindowChild — a mesma chamada, e um DataWindow é reescrito ele próprio. A sua chave é o RowID da linha — of_card(key).of_row() devolve o número da sua linha enquanto o DataStore não for esvaziado nem relido — ou o valor da coluna ROLE_KEY. Uma linha cuja chave está vazia, é inválida, já foi vista ou está ocupada por um cartão acrescentado à mão não é carregada: a chamada devolve 0 e of_get_last_error nomeia-a pelo seu número — dê aos seus cartões à mão chaves que não sejam números. Uma coluna desempenha um papel quando tem o seu nome (title, text, tags, assignee, due, badge, color, order, column, key) ou quando of_map o diz. A coluna ROLE_COLUMN diz em que coluna do quadro está o cartão; um valor que nenhuma coluna tem recebe uma coluna própria, no fim — um valor que contém / ou | toma uma chave em que se tornam - (R&D-QA) e mantém o seu valor, o que uma deslocação reescreve; um valor vazio não é carregado (of_get_last_error nomeia-o), um valor CHAR completado com espaços encontra a sua coluna. Uma coluna nascida de um valor desaparece quando fica vazia, a não ser que o seu código lhe tenha dado uma propriedade ou uma cor. ROLE_ORDER ordena os cartões de uma coluna: a ordem é o lugar de um cartão entre os cartões do DataStore da sua coluna, a partir de 1 (um cartão acrescentado à mão não toma ordem). Com uma chave ROLE_KEY, um segundo carregamento, of_map e of_reload_row atualizam os cartões no lugar: um cartão que volta mantém os seus indicadores, os seus campos e o seu handle. Com a chave RowID, um segundo of_from_datastore é um novo carregamento: o PowerBuilder volta a dar os mesmos RowID depois de um Reset ou de um Retrieve, a outros registos — todos os cartões das linhas antigas saem (o seu handle é libertado) e os cartões são refeitos; of_map e of_reload_row ficam no lugar. Um cartão que o seu código retirou não volta com of_map: a sua linha fica no DataStore, o próximo of_from_datastore volta a lê-la. As datas e os decimais são lidos segundo as definições regionais do posto (um campo decimal lê-se 1234.5). Todas as colunas são campos do modelo.

Com ib_write_back = true, um cartão de uma linha escreve a sua nova coluna na linha (e, com ROLE_ORDER, as ordens das duas colunas) antes de se deslocar — a linha é encontrada pelo seu RowID e por nada mais: ue_card_moved lê o DataStore atualizado, o Update continua a ser consigo. A coluna recebe o valor da coluna de destino (R&D/QA, nunca a sua chave R&D-QA). Tudo ou nada: um valor que o DataStore recusa — a coluna ou uma ordem — repõe o que já estava escrito, deixa o cartão onde estava (nunca sai para voltar) e levanta ue_write_back_failed; of_move_card devolve então -4. Escreve-se uma só deslocação do utilizador de cada vez: um gesto feito antes de a anterior estar escrita é ignorado, e anunciado. Depois de alterar você mesmo uma linha, of_reload_row volta a enviá-la para o quadro.

// 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)

Propriedades #

Propriedades de uma coluna — n_pbt_kanban_column #

O seu handle, através de of_column(key). O seu of_count() conta os cartões que contém e o seu of_keys_at(n) devolve a chave do n-ésimo, pela sua ordem; of_child_keys devolve-as todas numa só leitura.

Propriedades de um cartão — n_pbt_kanban_card #

Três leituras do handle, só de leitura: of_column() devolve a chave da coluna onde o cartão está agora, of_position() o seu lugar nessa coluna a partir de 1 (0 se o quadro não o contiver), of_row() o número da sua linha no DataStore (0 para um cartão acrescentado à mão). Um cartão desloca-se com of_move_card do quadro.

Métodos #

Eventos #

Teclado e rato #

• Arrastar um cartão: para lá de 5 píxeis, um fantasma segue o ponteiro, a coluna de destino ilumina-se e uma barra de destaque mostra onde o cartão vai cair; o quadro e a coluna deslizam perto dos seus bordos, e continuam enquanto o ponteiro lá ficar. Esc cancela.
• Setas: o cartão de cima, de baixo, ou na mesma ordem na coluna vizinha; uma coluna recolhida, ou que não desenha nenhum cartão, é alcançada pelo seu cabeçalho. Home / End: o primeiro, o último da coluna.
• Ctrl + Cima / Baixo sobe ou desce o cartão na sua coluna; Ctrl + Esquerda / Direita passa-o para a coluna aberta vizinha, na mesma ordem (uma coluna recolhida é saltada; Espaço e depois as setas param nela). Da direita para a esquerda, Esquerda e Direita invertem-se.
• Espaço levanta o cartão selecionado: as setas transportam-no (uma barra mostra onde vai cair), Espaço ou Enter pousa-o — a mesma pergunta e a mesma escrita que um arrastar —, Esc repõe-no no lugar. Um leitor de ecrã ouve cada passo.
• Os cabeçalhos estão sempre ao alcance: Cima no primeiro cartão, Esquerda / Direita de um cabeçalho para o outro; num cabeçalho, Enter ou Espaço recolhe ou reabre a coluna, + reabre-a, - recolhe-a, Baixo volta ao primeiro cartão.
• Enter ou um duplo clique abre o cartão, Delete pede a sua eliminação, Insert pede um novo cartão na coluna (num cartão ou num cabeçalho), clique direito num cartão ou num cabeçalho: o seu evento.
• O quadro é uma única paragem da tecla Tab: o cartão selecionado fica com ela, senão o primeiro cartão, senão o primeiro cabeçalho.
• Com ib_reorderable: arrastar o cabeçalho de uma coluna desloca-a (uma barra vertical mostra onde vai cair, Esc cancela); Ctrl + Shift + Esquerda / Direita, num cartão ou num cabeçalho, desloca a sua coluna, invertido da direita para a esquerda.

Exemplos #

Um limite estrito e uma regra de passagem #

// 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

Reencontrar as colunas no próximo arranque #

// 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)

Abrir um cartão na sua janela #

// 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())

Um quadro de equipa: pontos, largura partilhada, adição rápida #

// 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)

Boas práticas #

• Poucas colunas, nomeadas pela etapa e não pela pessoa: cinco ou seis leem-se num relance.
• Um limite de trabalho em curso nas colunas ativas: é ele que faz de um quadro uma ferramenta de pilotagem.
• Guarde em ue_card_moved (ou deixe ib_write_back escrever o DataStore): o quadro mostra o novo estado antes de a base de dados o saber.
• Um modelo curto: duas linhas de corpo bastam, o detalhe vai para a sua janela de edição.
• Etiquetas de tom constante: Bug sempre a vermelho, de uma janela para outra.
• Chaves que não sejam números para os seus cartões à mão, num quadro alimentado por um DataStore: um cartão de chave 12 impede que a linha de RowID 12 seja carregada (of_get_last_error di-lo).
• Uma chave dos dados (ROLE_KEY) quando as linhas são relidas: com a chave RowID, um novo of_from_datastore refaz os cartões.

Herdado da base comum #

Estes membros existem em todos os componentes visuais — não são próprios deste. São detalhados uma só vez, nos capítulos transversais; esta tabela apenas diz onde os ler.

Duas ajudas não são herdadas: of_icon e of_escape_markup vivem em n_pbt_utils. Declare um — n_pbt_utils lnv_utils, nada a criar — e chame-as nele.

← Referência dos componentes · Índice do guia