kanban — u_pbt_kanban #

← Riferimento dei componenti · Sommario della guida

kanban è un tabellone di schede ordinate in colonne — le fasi di un lavoro: da fare, in corso, in revisione, fatto. L'utente trascina una scheda da una colonna all'altra, o la sposta su e giù nella sua; ue_card_moved vi dice quale, da dove, verso dove e in quale posizione. Ogni scheda mostra un titolo, etichette colorate, il suo assegnatario, una scadenza che diventa rossa in ritardo e un badge; ogni colonna ha il suo limite di lavoro in corso e si comprime. Il tabellone si riempie a mano o da un DataStore, che riceve gli spostamenti.

▶ Vederlo dal vivo — Applicazione dimostrativa, riquadro Kanban board: l'anteprima, il codice che lo produce e questa pagina, affiancati.

In breve #

Avvio rapido #

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

Colonne, schede e posizioni #

Una colonna si designa con la sua chiave, una scheda anche — e la chiave di una scheda è unica su tutto il tabellone, non solo nella sua colonna: una scheda mantiene la sua chiave quando cambia colonna, i suoi handle restano validi e ogni evento la nomina da sola. La colonna di una scheda si legge con of_card(key).of_column(), la sua posizione con of_position(); una posizione si conta da 1, schede nascoste comprese.

Una colonna ha un limite di lavoro in corso (il_limit): la sua intestazione conta 3/5, e diventa rossa oltre. Il limite è morbido — la scheda arriva comunque; per un limite rigido, rifiutate lo spostamento in ue_card_moving confrontando il_limit con of_visible_count() della colonna, ciò che conta l'intestazione (una scheda nascosta non conta). ib_done marca la colonna del lavoro finito: le sue schede non sono mai in ritardo. Una colonna si comprime in una striscia stretta (la sua freccia, ib_collapsed); vi si deposita ancora una scheda, in fondo.

Uno spostamento dell'utente (trascinamento, Ctrl + frecce, o la scheda sollevata con Spazio e posata) e uno spostamento del vostro codice (of_move_card) sollevano lo stesso ue_card_moved, come SelectItem solleva l'evento del clic. Con ib_veto_moves, ue_card_moving è posto prima, nei due casi: restituire FALSE lascia la scheda dov'è, e of_move_card restituisce allora -4.

Con ib_reorderable = true, l'utente riordina anche le colonne: trascina l'intestazione di una colonna (una barra d'accento verticale mostra dove cadrà, Esc annulla) o preme Ctrl + Maiusc + Sinistra / Destra. ue_column_moved dà la colonna e le sue due posizioni, contate da 1 tra tutte le colonne; of_move_column fa lo stesso dal vostro codice e solleva lo stesso evento, con ue_column_moving posto prima con ib_veto_moves. Disattivato per impostazione predefinita: le colonne sono il processo della vostra applicazione. Ciò che l'utente ha sistemato — l'ordine delle colonne e la loro compressione — si legge con of_get_layout, si restituisce con of_set_layout, e ogni cambiamento solleva ue_layout_changed con la disposizione intera: salvatela, restituitela al prossimo avvio.

Il contenuto di una scheda #

Una scheda mostra il suo titolo (is_title), il suo testo (is_text, tagliato dopo quattro righe), le sue etichette (is_tags, separate da virgole, colorate da is_tag_tones: Bug=danger|UI=info), il suo assegnatario (is_assignee, un avatar rotondo con le iniziali), la sua scadenza (is_due, aaaa-mm-gg: rossa una volta superata, arancione il giorno stesso, confrontata con is_today o con la data della postazione) e un badge (is_badge). Titolo, testo e badge accettano il testo formattato con tag.

Il corpo delle schede può essere scritto da un modello, is_card_template: testo formattato dove {customer} è un campo della scheda — uno dei vostri (of_set_field), una colonna del DataStore da cui proviene, o un campo predefinito (title, text, tags, assignee, initials, badge, due, column, column_title, key). {due:dddd d mmmm} scrive una data come un formato di visualizzazione di DataWindow (i simboli d dd ddd dddd m mm mmm mmmm yy yyyy, un testo tra virgolette doppie — fuori dalle virgolette, una lettera d, m o y è un simbolo —, [shortdate] e [longdate] nella lingua di visualizzazione), {?amount}…{/amount} mantiene un pezzo quando il campo dice qualcosa, {!amount}…{/amount} quando non dice nulla, {x:raw} mantiene un valore come tag, {{ }} sono parentesi graffe. Un valore è sempre mostrato così com'è, mai letto come tag.

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

Da un DataStore #

of_from_datastore fa una scheda di ogni riga di un DataStore, di un DataWindow o di un DataWindowChild — la stessa chiamata, e un DataWindow viene riscritto esso stesso. La sua chiave è il RowID della riga — of_card(key).of_row() restituisce il numero della sua riga finché il DataStore non viene svuotato né riletto — o il valore della colonna ROLE_KEY. Una riga la cui chiave è vuota, non valida, già vista o tenuta da una scheda aggiunta a mano non viene caricata: la chiamata restituisce 0 e of_get_last_error la nomina con il suo numero — date alle vostre schede a mano chiavi che non siano numeri. Una colonna svolge un ruolo quando ne porta il nome (title, text, tags, assignee, due, badge, color, order, column, key) o quando of_map lo dice. La colonna ROLE_COLUMN dice in quale colonna del tabellone si trova la scheda; un valore che nessuna colonna porta riceve una propria colonna, in fondo — un valore che contiene / o | prende una chiave in cui diventano - (R&D-QA) e conserva il suo valore, quello che uno spostamento riscrive; un valore vuoto non viene caricato (of_get_last_error lo nomina), un valore CHAR completato da spazi trova la sua colonna. Una colonna nata da un valore se ne va una volta vuota, a meno che il vostro codice le abbia dato una proprietà o un colore. ROLE_ORDER ordina le schede di una colonna: il rango è la posizione di una scheda tra le schede del DataStore della sua colonna, da 1 (una scheda aggiunta a mano non prende rango). Con una chiave ROLE_KEY, un secondo caricamento, of_map e of_reload_row aggiornano le schede sul posto: una scheda che torna mantiene i suoi indicatori, i suoi campi e il suo handle. Con la chiave RowID, un secondo of_from_datastore è un nuovo caricamento: PowerBuilder ridà gli stessi RowID dopo un Reset o un Retrieve, ad altri record — tutte le schede delle vecchie righe se ne vanno (il loro handle è liberato) e le schede vengono rifatte; of_map e of_reload_row restano sul posto. Una scheda che il vostro codice ha tolto non torna con of_map: la sua riga resta nel DataStore, il prossimo of_from_datastore la rilegge. Le date e i decimali sono letti secondo le impostazioni regionali della postazione (un campo decimale si legge 1234.5). Tutte le colonne sono campi del modello.

Con ib_write_back = true, una scheda di una riga scrive la sua nuova colonna nella riga (e, con ROLE_ORDER, i ranghi delle due colonne) prima di muoversi — la riga è ritrovata dal suo RowID e da nient'altro: ue_card_moved legge il DataStore aggiornato, l'Update resta a voi. La colonna riceve il valore della colonna di destinazione (R&D/QA, mai la sua chiave R&D-QA). Tutto o niente: un valore che il DataStore rifiuta — la colonna o un rango — rimette ciò che era già scritto, lascia la scheda dov'era (non parte mai per tornare) e solleva ue_write_back_failed; of_move_card restituisce allora -4. Si scrive un solo spostamento dell'utente alla volta: un gesto fatto prima che il precedente sia scritto è ignorato, e annunciato. Dopo aver cambiato voi stessi una riga, of_reload_row la rimanda al tabellone.

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

Proprietà #

Proprietà di una colonna — n_pbt_kanban_column #

Il suo handle, tramite of_column(key). Il suo of_count() conta le schede che contiene e il suo of_keys_at(n) restituisce la chiave dell'n-esima, nel loro ordine; of_child_keys le restituisce tutte in una sola lettura.

Proprietà di una scheda — n_pbt_kanban_card #

Tre letture dell'handle, in sola lettura: of_column() restituisce la chiave della colonna in cui si trova la scheda ora, of_position() la sua posizione in quella colonna a partire da 1 (0 se il tabellone non la contiene), of_row() il numero della sua riga nel DataStore (0 per una scheda aggiunta a mano). Una scheda si sposta con of_move_card del tabellone.

Metodi #

Eventi #

Tastiera e mouse #

• Trascinare una scheda: oltre 5 pixel, un'immagine segue il puntatore, la colonna di destinazione si illumina e una barra d'accento mostra dove cadrà la scheda; il tabellone e la colonna scorrono vicino ai loro bordi, e continuano finché il puntatore vi resta. Esc annulla.
• Frecce: la scheda sopra, sotto, o allo stesso rango nella colonna vicina; una colonna compressa, o che non disegna alcuna scheda, si raggiunge con la sua intestazione. Home / Fine: la prima, l'ultima della colonna.
• Ctrl + Su / Giù sposta la scheda su o giù nella sua colonna; Ctrl + Sinistra / Destra la passa nella colonna aperta vicina, allo stesso rango (una colonna compressa è saltata; Spazio poi le frecce vi si fermano). Da destra a sinistra, Sinistra e Destra si invertono.
• Spazio solleva la scheda selezionata: le frecce la portano (una barra mostra dove cadrà), Spazio o Invio la posa — la stessa domanda e la stessa scrittura di un trascinamento —, Esc la rimette al suo posto. Un lettore di schermo sente ogni passo.
• Le intestazioni sono sempre raggiungibili: Su sulla prima scheda, Sinistra / Destra da un'intestazione all'altra; su un'intestazione, Invio o Spazio comprime o riapre la colonna, + la riapre, - la comprime, Giù torna alla prima scheda.
• Invio o doppio clic apre la scheda, Canc ne chiede l'eliminazione, Ins chiede una nuova scheda nella colonna (su una scheda o un'intestazione), clic destro su una scheda o un'intestazione: il suo evento.
• Il tabellone è una sola fermata del tasto Tab: la scheda selezionata la prende, altrimenti la prima scheda, altrimenti la prima intestazione.
• Con ib_reorderable: trascinare l'intestazione di una colonna la sposta (una barra verticale mostra dove cadrà, Esc annulla); Ctrl + Maiusc + Sinistra / Destra, su una scheda o su un'intestazione, sposta la sua colonna, invertito da destra a sinistra.

Esempi #

Un limite rigido e una regola di passaggio #

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

Ritrovare le colonne al prossimo avvio #

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

Aprire una scheda nella vostra finestra #

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

Un tabellone di squadra: punti, larghezza condivisa, aggiunta rapida #

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

Buone pratiche #

• Poche colonne, nominate per fase e non per persona: cinque o sei si leggono a colpo d'occhio.
• Un limite di lavoro in corso sulle colonne attive: è lui che fa di un tabellone uno strumento di guida.
• Salvate in ue_card_moved (o lasciate che ib_write_back scriva il DataStore): il tabellone mostra il nuovo stato prima che il database lo sappia.
• Un modello breve: due righe di corpo bastano, il dettaglio va nella vostra finestra di modifica.
• Etichette dal tono costante: Bug sempre rosso, da una finestra all'altra.
• Chiavi che non siano numeri per le vostre schede a mano, su un tabellone alimentato da un DataStore: una scheda di chiave 12 impedisce il caricamento della riga di RowID 12 (of_get_last_error lo dice).
• Una chiave dei dati (ROLE_KEY) quando le righe vengono rilette: con la chiave RowID, un nuovo of_from_datastore rifà le schede.

Ereditato dalla base comune #

Questi membri esistono su tutti i componenti visivi — non sono propri di questo. Sono descritti una sola volta, nei capitoli trasversali; questa tabella dice solo dove leggerli.

Due aiuti non sono ereditati: of_icon e of_escape_markup vivono su n_pbt_utils. Ne dichiari uno — n_pbt_utils lnv_utils, niente da creare — e li chiami su di esso.

← Riferimento dei componenti · Sommario della guida