kanban — u_pbt_kanban #

← Komponentenreferenz · Inhalt des Handbuchs

kanban ist eine Tafel mit Karten, die in Spalten geordnet sind — den Stufen einer Arbeit: zu erledigen, in Arbeit, in Prüfung, erledigt. Der Benutzer zieht eine Karte von einer Spalte in eine andere oder innerhalb ihrer Spalte nach oben und unten; ue_card_moved sagt Ihnen, welche, woher, wohin und an welche Stelle. Jede Karte zeigt einen Titel, farbige Tags, ihren Zuständigen, einen Termin, der bei Verzug rot wird, und ein Badge; jede Spalte hat ihr WIP-Limit und lässt sich einklappen. Die Tafel wird von Hand oder aus einem DataStore gefüllt, der die Verschiebungen empfängt.

▶ Live ansehen — Demoanwendung, Kachel Kanban board: die Vorschau, der zugehörige Code und diese Seite, nebeneinander.

Auf einen Blick #

Schnellstart #

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

Spalten, Karten und Plätze #

Eine Spalte wird über ihren Schlüssel bezeichnet, eine Karte ebenso — und der Schlüssel einer Karte ist auf der ganzen Tafel eindeutig, nicht nur in ihrer Spalte: Eine Karte behält ihren Schlüssel, wenn sie die Spalte wechselt, ihre Handles bleiben gültig, und jedes Ereignis nennt sie allein. Die Spalte einer Karte liest man mit of_card(key).of_column(), ihren Platz mit of_position(); ein Platz zählt ab 1, ausgeblendete Karten inbegriffen.

Eine Spalte hat ein WIP-Limit (il_limit): Ihre Kopfzeile zählt 3/5, und darüber hinaus wird sie rot. Das Limit ist weich — die Karte kommt trotzdem an; für ein hartes Limit lehnen Sie die Verschiebung in ue_card_moving ab, indem Sie il_limit mit of_visible_count() der Spalte vergleichen, dem, was die Kopfzeile zählt (eine ausgeblendete Karte zählt nicht). ib_done kennzeichnet die Spalte der erledigten Arbeit: Ihre Karten sind nie überfällig. Eine Spalte lässt sich zu einem schmalen Streifen einklappen (ihr Winkel, ib_collapsed); eine Karte lässt sich trotzdem darauf ablegen, ans Ende.

Eine Verschiebung des Benutzers (Ziehen, Strg + Pfeile oder die mit der Leertaste angehobene und abgelegte Karte) und eine Verschiebung Ihres Codes (of_move_card) lösen dasselbe ue_card_moved aus, so wie SelectItem das Ereignis des Klicks auslöst. Mit ib_veto_moves wird ue_card_moving in beiden Fällen vorher gestellt: FALSE zurückzugeben lässt die Karte, wo sie ist, und of_move_card gibt dann -4 zurück.

Mit ib_reorderable = true ordnet der Benutzer auch die Spalten neu: Er zieht die Kopfzeile einer Spalte (ein senkrechter Akzentbalken zeigt, wo sie landet, Esc bricht ab) oder drückt Strg + Umschalt + Links / Rechts. ue_column_moved liefert die Spalte und ihre beiden Plätze, ab 1 gezählt unter allen Spalten; of_move_column tut dasselbe aus Ihrem Code und löst dasselbe Ereignis aus, wobei ue_column_moving mit ib_veto_moves vorher gestellt wird. Standardmäßig aus: Die Spalten sind der Prozess Ihrer Anwendung. Was der Benutzer angeordnet hat — die Reihenfolge der Spalten und ihr Einklappen —, liest man mit of_get_layout, gibt es mit of_set_layout zurück, und jede Änderung löst ue_layout_changed mit dem ganzen Layout aus: Speichern Sie es und geben Sie es beim nächsten Start zurück.

Was eine Karte zeigt #

Eine Karte zeigt ihren Titel (is_title), ihren Text (is_text, nach vier Zeilen abgeschnitten), ihre Tags (is_tags, durch Kommas getrennt, gefärbt durch is_tag_tones: Bug=danger|UI=info), ihren Zuständigen (is_assignee, ein runder Avatar mit den Initialen), ihren Termin (is_due, jjjj-mm-tt: rot, sobald überschritten, orange am Tag selbst, verglichen mit is_today oder dem Datum des Arbeitsplatzes) und ein Badge (is_badge). Titel, Text und Badge akzeptieren die Rich-Text-Auszeichnung.

Der Inhalt der Karten kann über eine Vorlage geschrieben werden, is_card_template: Rich Text, in dem {customer} ein Feld der Karte ist — eines Ihrer eigenen (of_set_field), eine Spalte des DataStores, aus dem sie stammt, oder ein eingebautes Feld (title, text, tags, assignee, initials, badge, due, column, column_title, key). {due:dddd d mmmm} schreibt ein Datum wie ein Anzeigeformat eines DataWindow (die Kürzel d dd ddd dddd m mm mmm mmmm yy yyyy, ein Text zwischen doppelten Anführungszeichen — außerhalb davon ist ein Buchstabe d, m oder y ein Kürzel —, [shortdate] und [longdate] in der Sprache der Anzeige), {?amount}…{/amount} behält ein Stück, wenn das Feld etwas enthält, {!amount}…{/amount}, wenn es nichts enthält, {x:raw} behält einen Wert als Auszeichnung, {{ }} sind geschweifte Klammern. Ein Wert wird immer so angezeigt, wie er ist, nie als Auszeichnung gelesen.

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

Aus einem DataStore #

of_from_datastore macht aus jeder Zeile eines DataStores, eines DataWindow oder eines DataWindowChild eine Karte — derselbe Aufruf, und ein DataWindow wird selbst zurückgeschrieben. Ihr Schlüssel ist die RowID der Zeile — of_card(key).of_row() liefert die Nummer ihrer Zeile, solange der DataStore weder geleert noch neu abgerufen wird — oder der Wert der Spalte ROLE_KEY. Eine Zeile, deren Schlüssel leer, ungültig, schon gesehen oder von einer von Hand hinzugefügten Karte belegt ist, wird nicht geladen: Der Aufruf gibt 0 zurück, und of_get_last_error nennt sie mit ihrer Nummer — geben Sie Ihren Karten von Hand Schlüssel, die keine Zahlen sind. Eine Spalte spielt eine Rolle, wenn sie so heißt (title, text, tags, assignee, due, badge, color, order, column, key) oder wenn of_map es sagt. Die Spalte ROLE_COLUMN sagt, in welcher Spalte der Tafel die Karte steht; ein Wert, den keine Spalte trägt, erhält eine eigene Spalte, am Ende — ein Wert mit / oder | erhält einen Schlüssel, in dem sie zu - werden (R&D-QA), und behält seinen Wert, den eine Verschiebung zurückschreibt; ein leerer Wert wird nicht geladen (of_get_last_error nennt ihn), ein mit Leerzeichen aufgefüllter CHAR-Wert findet seine Spalte. Eine aus einem Wert entstandene Spalte verschwindet, sobald sie leer ist, es sei denn, Ihr Code hat ihr eine Eigenschaft oder eine Farbe gegeben. ROLE_ORDER ordnet die Karten einer Spalte: Der Rang ist der Platz einer Karte unter den Karten des DataStores ihrer Spalte, ab 1 (eine von Hand hinzugefügte Karte nimmt keinen Rang). Mit einem Schlüssel ROLE_KEY aktualisieren ein zweites Laden, of_map und of_reload_row die Karten an Ort und Stelle: Eine Karte, die zurückkommt, behält ihre Kennzeichen, ihre Felder und ihren Handle. Mit dem Schlüssel RowID ist ein zweites of_from_datastore ein neues Laden: PowerBuilder vergibt nach einem Reset oder Retrieve dieselben RowIDs an andere Datensätze — alle Karten der alten Zeilen gehen (ihr Handle wird freigegeben) und die Karten werden neu angelegt; of_map und of_reload_row bleiben an Ort und Stelle. Eine Karte, die Ihr Code entfernt hat, kommt mit of_map nicht zurück: Ihre Zeile bleibt im DataStore, das nächste of_from_datastore liest sie wieder. Datums- und Dezimalwerte werden nach den Regionaleinstellungen des Arbeitsplatzes gelesen (ein Dezimalfeld liest sich 1234.5). Jede Spalte ist ein Feld der Vorlage.

Mit ib_write_back = true schreibt eine Karte einer Zeile ihre neue Spalte in die Zeile (und mit ROLE_ORDER die Ränge beider Spalten), bevor sie sich bewegt — die Zeile wird über ihre RowID gefunden und über nichts anderes: ue_card_moved liest den aktuellen DataStore, das Update bleibt bei Ihnen. Die Spalte erhält den Wert der Zielspalte (R&D/QA, nie ihren Schlüssel R&D-QA). Alles oder nichts: Ein Wert, den der DataStore ablehnt — die Spalte oder ein Rang —, stellt wieder her, was schon geschrieben war, lässt die Karte an ihrem Platz (sie geht nie, um zurückzukommen) und löst ue_write_back_failed aus; of_move_card gibt dann -4 zurück. Es wird immer nur eine Verschiebung des Benutzers geschrieben: Eine Geste, bevor die vorige geschrieben ist, wird ignoriert und angesagt. Nachdem Sie selbst eine Zeile geändert haben, sendet of_reload_row sie erneut an die Tafel.

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

Eigenschaften #

Eigenschaften einer Spalte — n_pbt_kanban_column #

Ihr Handle, über of_column(key). Ihr of_count() zählt die Karten, die sie enthält, und ihr of_keys_at(n) liefert den Schlüssel der n-ten, in ihrer Reihenfolge; of_child_keys liefert sie alle mit einem einzigen Lesen.

Eigenschaften einer Karte — n_pbt_kanban_card #

Drei Lesefunktionen des Handles, nur lesend: of_column() liefert den Schlüssel der Spalte, in der die Karte jetzt steht, of_position() ihren Platz in dieser Spalte ab 1 (0, wenn die Tafel sie nicht enthält), of_row() die Nummer ihrer Zeile im DataStore (0 für eine von Hand hinzugefügte Karte). Eine Karte wird über of_move_card der Tafel verschoben.

Methoden #

Ereignisse #

Tastatur und Maus #

• Eine Karte ziehen: Ab 5 Pixeln folgt ein Schattenbild dem Mauszeiger, die Zielspalte wird hervorgehoben und ein Akzentbalken zeigt, wo die Karte landet; Tafel und Spalte scrollen nahe ihren Rändern, und zwar weiter, solange der Mauszeiger dort bleibt. Esc bricht ab.
• Pfeile: die Karte darüber, darunter oder auf gleichem Rang in der Nachbarspalte; eine eingeklappte Spalte oder eine ohne gezeichnete Karte wird über ihre Kopfzeile erreicht. Pos1 / Ende: die erste, die letzte der Spalte.
• Strg + Auf / Ab schiebt die Karte in ihrer Spalte nach oben oder unten; Strg + Links / Rechts bringt sie in die nächste geöffnete Spalte, auf gleichem Rang (eine eingeklappte Spalte wird übersprungen; Leertaste und dann die Pfeile halten dort an). Bei Rechts-nach-links sind Links und Rechts vertauscht.
• Die Leertaste hebt die ausgewählte Karte an: Die Pfeile tragen sie (ein Balken zeigt, wo sie landet), Leertaste oder Eingabe legt sie ab — dieselbe Rückfrage und dasselbe Schreiben wie beim Ziehen —, Esc legt sie zurück. Ein Bildschirmleser hört jeden Schritt.
• Die Kopfzeilen sind immer erreichbar: Auf auf der ersten Karte, Links / Rechts von einer Kopfzeile zur nächsten; auf einer Kopfzeile klappt Eingabe oder Leertaste die Spalte ein oder auf, + klappt sie auf, - klappt sie ein, Ab führt zur ersten Karte zurück.
• Eingabe oder Doppelklick öffnet die Karte, Entf verlangt ihr Löschen, Einfg verlangt eine neue Karte in der Spalte (auf einer Karte oder einer Kopfzeile), Rechtsklick auf eine Karte oder eine Kopfzeile: ihr Ereignis.
• Die Tafel ist ein einziger Tab-Stopp: Die ausgewählte Karte erhält ihn, sonst die erste Karte, sonst die erste Kopfzeile.
• Mit ib_reorderable: Das Ziehen der Kopfzeile einer Spalte verschiebt sie (ein senkrechter Balken zeigt, wo sie landet, Esc bricht ab); Strg + Umschalt + Links / Rechts auf einer Karte oder einer Kopfzeile verschiebt ihre Spalte, bei Rechts-nach-links vertauscht.

Beispiele #

Ein hartes Limit und eine Übergangsregel #

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

Die Spalten beim nächsten Start wiederfinden #

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

Eine Karte in Ihrem Fenster öffnen #

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

Eine Teamtafel: Punkte, geteilte Breite, schnelles Hinzufügen #

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

Bewährte Praxis #

• Wenige Spalten, nach der Stufe und nicht nach der Person benannt: fünf oder sechs liest man auf einen Blick.
• Ein WIP-Limit auf den aktiven Spalten: Es macht aus einer Tafel ein Steuerungswerkzeug.
• Speichern Sie in ue_card_moved (oder lassen Sie ib_write_back den DataStore schreiben): Die Tafel zeigt den neuen Zustand, bevor die Datenbank ihn kennt.
• Eine kurze Vorlage: zwei Zeilen Inhalt genügen, das Detail gehört in Ihr Bearbeitungsfenster.
• Tags mit festem Ton: Bug immer rot, von einem Fenster zum anderen.
• Schlüssel, die keine Zahlen sind, für Ihre Karten von Hand auf einer von einem DataStore gespeisten Tafel: Eine Karte mit dem Schlüssel 12 verhindert, dass die Zeile mit der RowID 12 geladen wird (of_get_last_error sagt es).
• Ein Schlüssel der Daten (ROLE_KEY), wenn die Zeilen neu gelesen werden: Mit dem Schlüssel RowID legt ein neues of_from_datastore die Karten neu an.

Vom gemeinsamen Sockel geerbt #

Diese Mitglieder gibt es bei jeder visuellen Komponente — sie sind nicht dieser eigen. Sie werden einmal in den übergreifenden Kapiteln beschrieben; diese Tabelle sagt nur, wo man sie liest.

Zwei Helfer werden nicht geerbt: of_icon und of_escape_markup liegen auf n_pbt_utils. Deklarieren Sie eines — n_pbt_utils lnv_utils, nichts zu erzeugen — und rufen Sie sie darauf auf.

← Komponentenreferenz · Inhalt des Handbuchs