kanban — u_pbt_kanban #

← Référence des composants · Sommaire du guide

kanban est un tableau de cartes rangées en colonnes — les étapes d'un travail : à faire, en cours, en revue, terminé. L'utilisateur glisse une carte d'une colonne à l'autre, ou la monte et la descend dans la sienne ; ue_card_moved vous dit laquelle, d'où, vers où et à quelle place. Chaque carte montre un titre, des étiquettes colorées, son responsable, une échéance qui rougit en retard et un badge ; chaque colonne a sa limite de travail en cours et se replie. Le tableau se remplit à la main ou depuis un DataStore, qui reçoit les déplacements.

▶ Le voir en vrai — Application de démonstration, tuile Kanban board : l'aperçu, le code qui le produit et cette page, côte à côte.

En bref #

Démarrage rapide #

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

Colonnes, cartes et places #

Une colonne se désigne par sa clé, une carte aussi — et la clé d'une carte est unique sur tout le tableau, pas seulement dans sa colonne : une carte garde sa clé quand elle change de colonne, ses poignées restent valables et chaque événement la nomme seule. La colonne d'une carte se lit par of_card(key).of_column(), sa place par of_position() ; une place se compte à partir de 1, cartes masquées comprises.

Une colonne a une limite de travail en cours (il_limit) : son en-tête compte 3/5, et elle rougit au-delà. La limite est souple — la carte arrive quand même ; pour une limite stricte, refusez le déplacement dans ue_card_moving en comparant il_limit à of_visible_count() de la colonne, ce que compte l'en-tête (une carte masquée ne compte pas). ib_done marque la colonne du travail terminé : ses cartes ne sont jamais en retard. Une colonne se replie en bande étroite (son chevron, ib_collapsed) ; on y dépose encore une carte, qui va en dernier.

Un déplacement de l'utilisateur (glisser, Ctrl + flèches, ou la carte soulevée par Espace et posée) et un déplacement de votre code (of_move_card) lèvent le même ue_card_moved, comme SelectItem lève l'événement du clic. Avec ib_veto_moves, ue_card_moving est posé avant, aux deux : renvoyer FALSE laisse la carte où elle est, et of_move_card rend alors -4.

Avec ib_reorderable = true, l'utilisateur réordonne aussi les colonnes : il glisse l'en-tête d'une colonne (une barre d'accent verticale montre où elle tombera, Échap annule) ou presse Ctrl + Maj + Gauche / Droite. ue_column_moved donne la colonne et ses deux places, comptées à partir de 1 parmi toutes les colonnes ; of_move_column fait la même chose depuis votre code et lève le même événement, ue_column_moving étant posé avant avec ib_veto_moves. Désactivé par défaut : les colonnes sont le processus de votre application. Ce que l'utilisateur a arrangé — l'ordre des colonnes et leur repli — se lit par of_get_layout, se rend par of_set_layout, et chaque changement lève ue_layout_changed avec la disposition entière : enregistrez-la, rendez-la au prochain lancement.

Le contenu d'une carte #

Une carte montre son titre (is_title), son texte (is_text, coupé après quatre lignes), ses étiquettes (is_tags, séparées par des virgules, colorées par is_tag_tones : Bug=danger|UI=info), son responsable (is_assignee, un avatar rond avec ses initiales), son échéance (is_due, aaaa-mm-jj : rouge une fois dépassée, orange le jour même, comparée à is_today ou à la date du poste) et un badge (is_badge). Titre, texte et badge acceptent le balisage riche.

Le corps des cartes peut s'écrire par un modèle, is_card_template : du texte riche où {customer} est un champ de la carte — un des vôtres (of_set_field), une colonne du DataStore d'où elle vient, ou un champ intégré (title, text, tags, assignee, initials, badge, due, column, column_title, key). {due:dddd d mmmm} écrit une date comme un format d'affichage de DataWindow (les jetons d dd ddd dddd m mm mmm mmmm yy yyyy, un texte entre guillemets doubles — hors guillemets, une lettre d, m ou y est un jeton —, [shortdate] et [longdate] dans la langue de l'affichage), {?amount}…{/amount} garde un morceau quand le champ dit quelque chose, {!amount}…{/amount} quand il ne dit rien, {x:raw} garde une valeur comme balisage, {{ }} sont des accolades. Une valeur est toujours affichée telle quelle, jamais lue comme balisage.

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

Depuis un DataStore #

of_from_datastore fait une carte de chaque ligne d'un DataStore, d'un DataWindow ou d'un DataWindowChild — l'appel est le même, et un DataWindow est écrit en retour lui-même. Sa clé est le RowID de la ligne — of_card(key).of_row() rend le numéro de sa ligne tant que le DataStore n'est ni vidé ni relu — ou la valeur de la colonne ROLE_KEY. Une ligne dont la clé est vide, invalide, déjà vue ou tenue par une carte ajoutée à la main n'est pas chargée : l'appel rend 0 et of_get_last_error la nomme par son numéro — donnez à vos cartes à la main des clés qui ne sont pas des nombres. Une colonne joue un rôle quand elle en porte le nom (title, text, tags, assignee, due, badge, color, order, column, key) ou quand of_map le dit. La colonne ROLE_COLUMN dit dans quelle colonne du tableau est la carte ; une valeur qu'aucune colonne ne porte reçoit sa propre colonne, à la fin — une valeur qui contient / ou | y prend une clé où ils deviennent - (R&D-QA) et garde sa valeur, celle qu'un déplacement réécrit ; une valeur vide n'est pas chargée (of_get_last_error la nomme), une valeur CHAR complétée d'espaces trouve sa colonne. Une colonne née d'une valeur part une fois vide, sauf si votre code lui a posé une propriété ou une couleur. ROLE_ORDER range les cartes d'une colonne : le rang est la place d'une carte parmi les cartes du DataStore de sa colonne, à partir de 1 (une carte ajoutée à la main ne prend pas de rang). Avec une clé ROLE_KEY, un second chargement, of_map et of_reload_row mettent les cartes à jour en place : une carte qui revient garde ses drapeaux, ses champs et sa poignée. Avec la clé RowID, un second of_from_datastore est un nouveau chargement : PowerBuilder redonne les mêmes RowID après un Reset ou un Retrieve, à d'autres enregistrements — toutes les cartes des anciennes lignes partent (leur poignée est libérée) et les cartes sont refaites ; of_map et of_reload_row restent en place. Une carte que votre code a retirée ne revient pas avec of_map : sa ligne reste dans le DataStore, le prochain of_from_datastore la relit. Les dates et les décimaux sont lus selon les réglages régionaux du poste (un champ décimal se lit 1234.5). Toutes les colonnes sont des champs du modèle.

Avec ib_write_back = true, une carte d'une ligne écrit sa nouvelle colonne dans la ligne (et, avec ROLE_ORDER, les rangs des deux colonnes) avant de bouger — la ligne est retrouvée par son RowID et par rien d'autre : ue_card_moved lit le DataStore à jour, l'Update reste à vous. La colonne reçoit la valeur de la colonne visée (R&D/QA, jamais sa clé R&D-QA). Tout ou rien : une valeur que le DataStore refuse — la colonne ou un rang — remet ce qui était déjà écrit, laisse la carte où elle était (elle ne part jamais pour revenir) et lève ue_write_back_failed ; of_move_card rend alors -4. Un seul déplacement de l'utilisateur s'écrit à la fois : un geste fait avant que le précédent soit écrit est ignoré, et dit. Après avoir changé une ligne vous-même, of_reload_row la renvoie au tableau.

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

Propriétés #

Propriétés d'une colonne — n_pbt_kanban_column #

Sa poignée, par of_column(key). Son of_count() compte les cartes qu'elle contient et son of_keys_at(n) rend la clé de la n-ième, dans leur ordre ; of_child_keys les rend toutes en une seule lecture.

Propriétés d'une carte — n_pbt_kanban_card #

Trois lectures de la poignée, en lecture seule : of_column() rend la clé de la colonne où est la carte maintenant, of_position() sa place dans cette colonne à partir de 1 (0 si le tableau ne la contient pas), of_row() le numéro de sa ligne dans le DataStore (0 pour une carte ajoutée à la main). Une carte se déplace par of_move_card du tableau.

Méthodes #

Événements #

Clavier et souris #

• Glisser une carte : au-delà de 5 pixels, un fantôme suit le pointeur, la colonne visée s'éclaire et une barre d'accent montre où la carte tombera ; le tableau et la colonne défilent près de leurs bords, et continuent tant que le pointeur y reste. Échap annule.
• Flèches : la carte au-dessus, au-dessous, ou au même rang dans la colonne voisine ; une colonne repliée, ou qui ne dessine aucune carte, est atteinte par son en-tête. Début / Fin : la première, la dernière de la colonne.
• Ctrl + Haut / Bas monte ou descend la carte dans sa colonne ; Ctrl + Gauche / Droite la passe dans la colonne voisine ouverte, au même rang (une colonne repliée est sautée ; Espace puis les flèches s'y arrêtent). Lu de droite à gauche, Gauche et Droite s'inversent.
• Espace soulève la carte sélectionnée : les flèches la promènent (une barre montre où elle tombera), Espace ou Entrée la pose — la même question et la même écriture qu'un glisser —, Échap la remet en place. Un lecteur d'écran entend chaque étape.
• Les en-têtes sont toujours atteignables : Haut sur la première carte, Gauche / Droite d'un en-tête à l'autre ; sur un en-tête, Entrée ou Espace replie ou rouvre la colonne, + la rouvre, - la replie, Bas revient à la première carte.
• Entrée ou double-clic ouvre la carte, Suppr demande sa suppression, Inser demande une nouvelle carte dans la colonne (sur une carte ou un en-tête), clic droit sur une carte ou un en-tête : son événement.
• Le tableau est un seul arrêt de Tab : la carte sélectionnée le prend, sinon la première carte, sinon le premier en-tête.
• Avec ib_reorderable : glisser l'en-tête d'une colonne la déplace (une barre verticale montre où elle tombera, Échap annule) ; Ctrl + Maj + Gauche / Droite, sur une carte ou sur un en-tête, déplace sa colonne, inversé de droite à gauche.

Exemples #

Une limite stricte et une règle de 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

Retrouver ses colonnes au prochain lancement #

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

Ouvrir une carte dans votre fenêtre #

// 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 tableau d'équipe : points, largeur partagée, ajout rapide #

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

Bonnes pratiques #

• Peu de colonnes, nommées par l'étape et non par la personne : cinq ou six se lisent d'un coup d'œil.
• Une limite de travail en cours sur les colonnes actives : c'est elle qui fait d'un tableau un outil de pilotage.
• Enregistrez dans ue_card_moved (ou laissez ib_write_back écrire le DataStore) : le tableau montre le nouvel état avant que la base ne le sache.
• Un modèle court : deux lignes de corps suffisent, le détail va dans votre fenêtre d'édition.
• Des étiquettes à ton constant : Bug toujours en rouge, d'une fenêtre à l'autre.
• Des clés qui ne sont pas des nombres pour vos cartes à la main, sur un tableau alimenté par un DataStore : une carte de clé 12 empêche la ligne de RowID 12 d'être chargée (of_get_last_error le dit).
• Une clé de la donnée (ROLE_KEY) quand les lignes sont relues : avec la clé RowID, un nouveau of_from_datastore refait les cartes.

Hérité du socle commun #

Ces membres existent sur tous les composants visuels — ils ne sont pas propres à celui-ci. Ils sont détaillés une seule fois, dans les chapitres transverses ; cette table dit seulement où les lire.

Deux aides ne sont pas héritées : of_icon et of_escape_markup vivent sur n_pbt_utils. Déclarez-en une — n_pbt_utils lnv_utils, rien à créer — et appelez-les dessus.

← Référence des composants · Sommaire du guide