diff --git a/documentation/docs/authors/advanced/data-generators.md b/documentation/docs/authors/advanced/data-generators.md new file mode 100644 index 0000000000..195a4a43b2 --- /dev/null +++ b/documentation/docs/authors/advanced/data-generators.md @@ -0,0 +1,101 @@ +# Data Generators + +As seen in [Looping Data](../looping-data), it is possible to use data_lists as a basis for iterative content loops within a single template. + +Data generators extend this idea further, to create multiple content flows from a single input data_list. The generated outputs can be templates, other data_lists or any other flow type. + +## Defining Generators +A generator minimally requires an `input_data_list` source and a `generator` flow type + +*example content_list* + +| flow_type | flow_name | parameter_list | +| --------- |--------- |-------------- | +| data_list | module_list | | +| generator | module_home_gen | input_data_list: module_list | + +**Input Parameters** + +A full list of available parameters is listed below: + +| parameter | description | default | +| ------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------- | +| input_data_list | Source data_list to loop over for generator | (none) | +| output_flow_type | Specify flow_type to save output as | template | +| output_flow_subtype | Specify flow_subtype to save output as | generated | +| output_flow_name | Specify flow_name to save template as. Can reference data from input data_list | {{flow_name}}_{{@gen.id}} | + +!!! Tip + Each row of the input data_list will be processed to generate an output flow. The `@gen` dynamic prefix can be used to refer to values from within the input list row. + +## Example +In this example we will use start with a list of modules, and use a generator to create individual templates to show content from the module + +### Input + +*module_list* + +| id | title | description | +| --------- |--------- |-------------- | +| module_1 | Welcome | Welcome to the course... | +| module_2 | Let's get started | In this unit we will... | + +*module_home_gen* + +The generator provides a simple template to display the module title and text descriptions, and a button that will later be used for navigation + +| type | name | value | +| ----------- | --------| --------------------- | +| title | | @gen.title | +| text | | @gen.description | +| button | | Continue | + + +### Output +Each row of input data will be processed to produce an output template flow + +*module_home_gen_module_1* + +| type | name | value | +| ----------- | --------| --------------------- | +| title | | Welcome | +| text | | Welcome to the course... | +| button | | Continue | + +*module_home_gen_module_2* + +| type | name | value | +| ----------- | --------| --------------------- | +| title | | Let's get started | +| text | | In this unit we will... | +| button | | Continue | + +We could further develop this example to include images, add actions for the button click, mark content as hidden or conditional on data etc. + +## Special Cases + +**Generate output with dynamic references** +If the generated output includes dynamic references that need to be preserved then it may be necessary to double-wrap the reference in the generator. + +For example, a generator is used to create `data_pipe` flows for further processing data. +References to `@row` local processing must use `{{@row}}` to populate correctly. + +| operation | args_list | +| -------------- | ---------------------------------------------- | +| append_columns | task_child: {@gen.id}_{{@row.id}}_article_tasks; | + + +## Additional Info + + +[Google Sheet Demo](#) - *Not currently available* + + +[Live Preview Demo](#) - *Not currently available* + +See details in original [RFC Proposal Doc](https://docs.google.com/document/d/1cK_Mk3nTZIKxux8bygKvujUFkVENMOE_xIgM6w9PlRw/edit) + + + + + diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml index 6cfc061097..0719cdda81 100644 --- a/documentation/mkdocs.yml +++ b/documentation/mkdocs.yml @@ -17,6 +17,7 @@ nav: - authors/feedback.md - Advanced: - authors/advanced/looping-data.md + - authors/advanced/data-generators.md - authors/advanced/overrides.md - authors/local-sheets.md - Contributors: