kanban — u_pbt_kanban #

← Referencia de componentes · Índice de la guía

kanban es un tablero de tarjetas ordenadas en columnas — las etapas de un trabajo: por hacer, en curso, en revisión, terminado. El usuario arrastra una tarjeta de una columna a otra, o la sube y baja en la suya; ue_card_moved le dice cuál, desde dónde, hacia dónde y en qué lugar. Cada tarjeta muestra un título, etiquetas de color, su responsable, un vencimiento que se pone rojo con retraso y una insignia; cada columna tiene su límite de trabajo en curso y se pliega. El tablero se llena a mano o desde un DataStore, que recibe los movimientos.

▶ Verlo en vivo — Aplicación de demostración, mosaico Kanban board: la vista previa, el código que lo genera y esta página, uno al lado del otro.

De un vistazo #

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

Columnas, tarjetas y posiciones #

Una columna se designa por su clave, una tarjeta también — y la clave de una tarjeta es única en todo el tablero, no solo en su columna: una tarjeta conserva su clave cuando cambia de columna, sus handles siguen siendo válidos y cada evento la nombra sola. La columna de una tarjeta se lee con of_card(key).of_column(), su posición con of_position(); una posición se cuenta desde 1, tarjetas ocultas incluidas.

Una columna tiene un límite de trabajo en curso (il_limit): su encabezado cuenta 3/5, y se pone roja más allá. El límite es flexible — la tarjeta llega de todos modos; para un límite estricto, rechace el movimiento en ue_card_moving comparando il_limit con of_visible_count() de la columna, lo que cuenta el encabezado (una tarjeta oculta no cuenta). ib_done marca la columna del trabajo terminado: sus tarjetas nunca están atrasadas. Una columna se pliega en una franja estrecha (su cheurón, ib_collapsed); todavía se puede soltar una tarjeta en ella, al final.

Un movimiento del usuario (arrastrar, Ctrl + flechas, o la tarjeta levantada con Espacio y soltada) y un movimiento de su código (of_move_card) lanzan el mismo ue_card_moved, como SelectItem lanza el evento del clic. Con ib_veto_moves, ue_card_moving se plantea antes, en ambos casos: devolver FALSE deja la tarjeta donde está, y of_move_card devuelve entonces -4.

Con ib_reorderable = true, el usuario reordena también las columnas: arrastra el encabezado de una columna (una barra de acento vertical muestra dónde caerá, Esc cancela) o pulsa Ctrl + Mayús + Izquierda / Derecha. ue_column_moved da la columna y sus dos posiciones, contadas desde 1 entre todas las columnas; of_move_column hace lo mismo desde su código y lanza el mismo evento, planteándose antes ue_column_moving con ib_veto_moves. Desactivado por defecto: las columnas son el proceso de su aplicación. Lo que el usuario ha organizado — el orden de las columnas y su pliegue — se lee con of_get_layout, se devuelve con of_set_layout, y cada cambio lanza ue_layout_changed con la disposición entera: guárdela y devuélvala en el próximo inicio.

El contenido de una tarjeta #

Una tarjeta muestra su título (is_title), su texto (is_text, cortado tras cuatro líneas), sus etiquetas (is_tags, separadas por comas, coloreadas por is_tag_tones: Bug=danger|UI=info), su responsable (is_assignee, un avatar redondo con las iniciales), su vencimiento (is_due, aaaa-mm-dd: rojo una vez pasado, naranja el mismo día, comparado con is_today o con la fecha del puesto) y una insignia (is_badge). Título, texto e insignia aceptan el texto enriquecido con etiquetas.

El cuerpo de las tarjetas puede escribirse con una plantilla, is_card_template: texto enriquecido donde {customer} es un campo de la tarjeta — uno de los suyos (of_set_field), una columna del DataStore del que procede, o un campo integrado (title, text, tags, assignee, initials, badge, due, column, column_title, key). {due:dddd d mmmm} escribe una fecha como un formato de visualización de DataWindow (los símbolos d dd ddd dddd m mm mmm mmmm yy yyyy, un texto entre comillas dobles — fuera de ellas, una letra d, m o y es un símbolo —, [shortdate] y [longdate] en el idioma de la visualización), {?amount}…{/amount} conserva un fragmento cuando el campo dice algo, {!amount}…{/amount} cuando no dice nada, {x:raw} conserva un valor como etiquetas, {{ }} son llaves. Un valor siempre se muestra tal cual, nunca se lee 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}"

Desde un DataStore #

of_from_datastore hace una tarjeta de cada fila de un DataStore, de un DataWindow o de un DataWindowChild — la misma llamada, y un DataWindow se reescribe él mismo. Su clave es el RowID de la fila — of_card(key).of_row() devuelve el número de su fila mientras el DataStore no se vacíe ni se vuelva a leer — o el valor de la columna ROLE_KEY. Una fila cuya clave está vacía, no es válida, ya se vio o está tomada por una tarjeta añadida a mano no se carga: la llamada devuelve 0 y of_get_last_error la nombra por su número — dé a sus tarjetas a mano claves que no sean números. Una columna desempeña un rol cuando se llama como él (title, text, tags, assignee, due, badge, color, order, column, key) o cuando of_map lo dice. La columna ROLE_COLUMN dice en qué columna del tablero está la tarjeta; un valor que ninguna columna lleva recibe su propia columna, al final — un valor que contiene / o | toma una clave en la que se convierten en - (R&D-QA) y conserva su valor, el que un movimiento vuelve a escribir; un valor vacío no se carga (of_get_last_error lo nombra), un valor CHAR completado con espacios encuentra su columna. Una columna nacida de un valor se va una vez vacía, salvo si su código le puso una propiedad o un color. ROLE_ORDER ordena las tarjetas de una columna: el rango es el lugar de una tarjeta entre las tarjetas del DataStore de su columna, desde 1 (una tarjeta añadida a mano no toma rango). Con una clave ROLE_KEY, una segunda carga, of_map y of_reload_row actualizan las tarjetas en su sitio: una tarjeta que vuelve conserva sus indicadores, sus campos y su handle. Con la clave RowID, un segundo of_from_datastore es una carga nueva: PowerBuilder vuelve a dar los mismos RowID tras un Reset o un Retrieve, a otros registros — todas las tarjetas de las filas antiguas se van (su handle se libera) y las tarjetas se rehacen; of_map y of_reload_row se quedan en su sitio. Una tarjeta que su código quitó no vuelve con of_map: su fila se queda en el DataStore, el siguiente of_from_datastore la vuelve a leer. Las fechas y los decimales se leen según la configuración regional del puesto (un campo decimal se lee 1234.5). Todas las columnas son campos de la plantilla.

Con ib_write_back = true, una tarjeta de una fila escribe su nueva columna en la fila (y, con ROLE_ORDER, los rangos de ambas columnas) antes de moverse — la fila se encuentra por su RowID y por nada más: ue_card_moved lee el DataStore actualizado, el Update sigue siendo cosa suya. La columna recibe el valor de la columna de destino (R&D/QA, nunca su clave R&D-QA). Todo o nada: un valor que el DataStore rechaza — la columna o un rango — repone lo que ya estaba escrito, deja la tarjeta donde estaba (nunca sale para volver) y lanza ue_write_back_failed; of_move_card devuelve entonces -4. Se escribe un solo movimiento del usuario a la vez: un gesto hecho antes de que el anterior se escriba se ignora, y se anuncia. Tras cambiar usted mismo una fila, of_reload_row la vuelve a enviar al tablero.

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

Propiedades #

Propiedades de una columna — n_pbt_kanban_column #

Su handle, mediante of_column(key). Su of_count() cuenta las tarjetas que contiene y su of_keys_at(n) devuelve la clave de la n-ésima, en su orden; of_child_keys las devuelve todas en una sola lectura.

Propiedades de una tarjeta — n_pbt_kanban_card #

Tres lecturas del handle, solo lectura: of_column() devuelve la clave de la columna en la que está la tarjeta ahora, of_position() su lugar en esa columna desde 1 (0 si el tablero no la contiene), of_row() el número de su fila en el DataStore (0 para una tarjeta añadida a mano). Una tarjeta se mueve con of_move_card del tablero.

Métodos #

Eventos #

Teclado y ratón #

• Arrastrar una tarjeta: pasados 5 píxeles, un fantasma sigue al puntero, la columna de destino se ilumina y una barra de acento muestra dónde caerá la tarjeta; el tablero y la columna se desplazan cerca de sus bordes, y siguen mientras el puntero se quede allí. Esc cancela.
• Flechas: la tarjeta de arriba, de abajo, o en el mismo rango en la columna vecina; una columna plegada, o que no dibuja ninguna tarjeta, se alcanza por su encabezado. Inicio / Fin: la primera, la última de la columna.
• Ctrl + Arriba / Abajo sube o baja la tarjeta en su columna; Ctrl + Izquierda / Derecha la pasa a la columna abierta vecina, en el mismo rango (una columna plegada se salta; Espacio y luego las flechas se detienen en ella). De derecha a izquierda, Izquierda y Derecha se invierten.
• Espacio levanta la tarjeta seleccionada: las flechas la llevan (una barra muestra dónde caerá), Espacio o Intro la suelta — la misma pregunta y la misma escritura que un arrastre —, Esc la devuelve a su sitio. Un lector de pantalla oye cada paso.
• Los encabezados siempre se alcanzan: Arriba en la primera tarjeta, Izquierda / Derecha de un encabezado a otro; en un encabezado, Intro o Espacio pliega o despliega la columna, + la despliega, - la pliega, Abajo vuelve a la primera tarjeta.
• Intro o un doble clic abre la tarjeta, Supr pide su eliminación, Insert pide una tarjeta nueva en la columna (en una tarjeta o un encabezado), clic derecho en una tarjeta o un encabezado: su evento.
• El tablero es una sola parada de la tecla Tab: la tarjeta seleccionada la toma, si no la primera tarjeta, si no el primer encabezado.
• Con ib_reorderable: arrastrar el encabezado de una columna la mueve (una barra vertical muestra dónde caerá, Esc cancela); Ctrl + Mayús + Izquierda / Derecha, en una tarjeta o en un encabezado, mueve su columna, invertido de derecha a izquierda.

Ejemplos #

Un límite estricto y una regla de paso #

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

Recuperar las columnas en el próximo inicio #

// 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 una tarjeta en su ventana #

// 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 tablero de equipo: puntos, anchura repartida, añadido rápido #

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

Buenas prácticas #

• Pocas columnas, nombradas por la etapa y no por la persona: cinco o seis se leen de un vistazo.
• Un límite de trabajo en curso en las columnas activas: es lo que convierte un tablero en una herramienta de pilotaje.
• Guarde en ue_card_moved (o deje que ib_write_back escriba el DataStore): el tablero muestra el nuevo estado antes de que la base de datos lo sepa.
• Una plantilla corta: dos líneas de cuerpo bastan, el detalle va en su ventana de edición.
• Etiquetas de tono constante: Bug siempre en rojo, de una ventana a otra.
• Claves que no sean números para sus tarjetas a mano, en un tablero alimentado por un DataStore: una tarjeta de clave 12 impide que se cargue la fila de RowID 12 (of_get_last_error lo dice).
• Una clave de los datos (ROLE_KEY) cuando las filas se vuelven a leer: con la clave RowID, un nuevo of_from_datastore rehace las tarjetas.

Heredado de la base común #

Estos miembros existen en todos los componentes visuales — no son propios de este. Se detallan una sola vez, en los capítulos transversales; esta tabla solo dice dónde leerlos.

Dos ayudas no se heredan: of_icon y of_escape_markup viven en n_pbt_utils. Declare uno — n_pbt_utils lnv_utils, nada que crear — y llámelas sobre él.

← Referencia de componentes · Índice de la guía