From 0cd1d4a241b4c66d7d3ac8e79b72eb0f11823d90 Mon Sep 17 00:00:00 2001 From: chrismclarke Date: Wed, 28 Aug 2024 23:45:12 -0700 Subject: [PATCH 1/2] docs: wip tasks system docs --- documentation/docs/authors/advanced/tasks.md | 123 +++++++++++++++++++ documentation/mkdocs.yml | 1 + 2 files changed, 124 insertions(+) create mode 100644 documentation/docs/authors/advanced/tasks.md diff --git a/documentation/docs/authors/advanced/tasks.md b/documentation/docs/authors/advanced/tasks.md new file mode 100644 index 000000000..428f63446 --- /dev/null +++ b/documentation/docs/authors/advanced/tasks.md @@ -0,0 +1,123 @@ +# Tasks System + +A set of utilities exist to help facilitate common data interactions around a set of *tasks* + +## Definition +A `task` list is an extension of a `data_list` that specifically includes a column for tracking a completion variable. By default this column should be called `completed`. + +Additionally tasks support a level of hierarchy and grouping, so that a single list of tasks is marked as `active` until all it's child tasks are complete, before proceeding to the next task list. + + +## Basic Example + +Given a workshop with a set of modules, use tasks to track which modules have been completed and which module should be marked as currently active + +### Task Lists + +An initial workbook called `workshop_tasks` includes a content list of module tasks + +*contents_list* + +| flow_type | flow_name | +| --------- | --------------------------- | +| data_list | module_1_tasks | +| data_list | module_2_tasks | +| data_list | module_3_tasks | + +Within the module tasks data is stored, including a column for tracking task completion. + +*module_1_tasks* + +| id | text | completed | +| --- | ----------------------- | ---------- | +| task_1a | Example task text 1 | FALSE | +| task_1b | Example task text 2 | FALSE | + +!!! Note + The name of the data_list that defines the initial list of tasks must be recorded within the `AppConfig`. The default value is `workshop_tasks` + + +### Templating +With the list of tasks in place, we use the templating system to interact with the completion state. This is managed in the same way as `data_items` loops **(TODO - docs required)** + + +| id | text | completed | +| --- | ----------------------- | ---------- | +| task_1a | Example task text 1 | FALSE | + + +See the full list of components available for use with tasks below + +| type | value | action_list | +| ------ | -------- | --------------------------------- | +| begin_items| @data.module_1_tasks | | +| button | Toggle Task Complete | click \| set_item \| completed : !@item.completed | +| end_items | @data.module_1_tasks | | + + +**(TODO)** - how to mark a task as completed from outside the list? (not currently possible) + +### Active Task Group +**(TODO)** - Using field variables and pre-built components + + +## Use Cases +(TODO) + + + + +## Task Priority +(TODO) - is it possible? + + +## Actions + +**Re-evaluate list** +When tasks are marked as complete the full list is not automatically re-evalauted. +Instead a manual `task: evaluate` must be triggered to update relevant fields + +*Example* + + +| type | action_list | +| ------ | -------------------------------------------------------------- | +| button | click \| task: evaluate \| data_list_name: example_task_list | + +This will evaluate all tasks within the data_list. It is also possible to pass a `row_id` parameter to limit evaluation just to a specific entry, e.g. + +| type | action_list | +| ------ | -------------------------------------------------------------- | +| button | click \| task: evaluate \| data_list_name: example_task_list; row_id: task_1 | + + +## Parent-Child Tasks +It is also possible to create a task relationship, so that a given parent task is only marked as completed when all of the child tasks are marked as completed. + +*parent_task_list* + +| id | task_child | completed | +| --- | ------------------ | --------- | +| parent_task_1 | child_tasks_1 | FALSE | +| parent_task_2 | child_tasks_2 | FALSE | + +*child_tasks_1* + +| id | completed | +| --- | --------- | +| child_task_1a | FALSE | +| child_task_1b | FALSE | +| child_task_1c | FALSE | + + +**NOTE** (to format) +If evaluating the task list make sure you include 2 actions to evaluate both child and parent actions in order + +| type | action_list | +| ------ | -------------------------------------------------------------- | +| button | click \| task: evaluate \| data_list_name: child_task_list
click \| task: evaluate \| data_list_name: parent_task_list | + + +## Components + + diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml index 6cfc06109..318ccae9e 100644 --- a/documentation/mkdocs.yml +++ b/documentation/mkdocs.yml @@ -18,6 +18,7 @@ nav: - Advanced: - authors/advanced/looping-data.md - authors/advanced/overrides.md + - authors/advanced/tasks.md - authors/local-sheets.md - Contributors: - contributors/documentation/running-server.md From cd2181ae42f6d3cd0c6ddf308de0201619f04653 Mon Sep 17 00:00:00 2001 From: chrismclarke Date: Thu, 29 Aug 2024 00:00:46 -0700 Subject: [PATCH 2/2] chore: fix typo --- documentation/docs/authors/advanced/tasks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/docs/authors/advanced/tasks.md b/documentation/docs/authors/advanced/tasks.md index 428f63446..2e64c9a71 100644 --- a/documentation/docs/authors/advanced/tasks.md +++ b/documentation/docs/authors/advanced/tasks.md @@ -74,7 +74,7 @@ See the full list of components available for use with tasks below ## Actions **Re-evaluate list** -When tasks are marked as complete the full list is not automatically re-evalauted. +When tasks are marked as complete the full list is not automatically re-evaluated. Instead a manual `task: evaluate` must be triggered to update relevant fields *Example*