From 61046ff9428d6a83c3222dde17127eea49e5ca28 Mon Sep 17 00:00:00 2001 From: keenanlang Date: Wed, 7 Aug 2024 14:42:01 -0500 Subject: [PATCH] repeat over lists documentation --- docs/nodes/layouts.md | 91 +++++++++++++++++++++++++------------------ 1 file changed, 53 insertions(+), 38 deletions(-) diff --git a/docs/nodes/layouts.md b/docs/nodes/layouts.md index b581802..e87be18 100644 --- a/docs/nodes/layouts.md +++ b/docs/nodes/layouts.md @@ -130,9 +130,10 @@ not changed. If the macro named by `repeat-over` is parsed and found to be a number, then the node will iterate a number of times specified by the macro. On each loop, the children widgets will be provided with -the macros `N` and `__index__` to use to configure themselves. `__index__` is a number that starts -at zero and increments by one every iteration of the loop. `N` is similar, but starts at a value -specified by the attribute `start-at`. +two macros; `__index__` and another that will be named according to `index-variable` so that the +child widgets can configure themselves. `__index__` is a number that starts at zero and increments +by one every iteration of the loop. The index variable is similar, but starts at a value specified +by the attribute `start-at`. If, instead, `repeat-over` names a macro that is found to be a list of dictionaries, then the dictionaries will be treated as the macros to use to configure the children widgets. The loop @@ -140,19 +141,24 @@ will iterate over each of the specified mappings and will provide the children e group with those macros (alongside any other macros in the data file). The `__index__` macro mentioned above will also be included. +Finally, if `repeat-over` names a macro that is found to be a list of values, then the values will +be made available to each child under a name specified by the attribute `value-variable`. The `__index__` +macro mentioned above will also be included. * **Special Attributes** -| Name | Type | Description| -|--------------|--------|------------| -| children | List | A list of widgets to use as a template to copy along the horizontal axis | -| repeat-over | String | The name of a macro that will be provided within the input data file | -| start-at | Number | An offset value to the loop index to provide children widgets | -| padding | Number | The number of pixels between each widget group | -| background | Color | A fill color behind the entirety of each template copy | -| border-color | Color | The color of the group's border surrounding each template copy | -| border-width | Number | The thickness of the group's border in pixels | -| visibility | String | A pv that determines the visibility of the layout, visibility is turned off if the PV's value is zero. This logic is inverted if the !Not tag is used instead of String | +| Name | Type | Description| +|----------------|--------|------------| +| children | List | A list of widgets to use as a template to copy along the horizontal axis | +| repeat-over | String | The name of a macro that will be provided within the input data file | +| index-variable | String | The name under which to provide the value of the loop index, 'N' by default | +| value-variable | String | The name under which to provide the current value when iterating over a list, 'val' by default | +| start-at | Number | An offset value to the loop index to provide children widgets | +| padding | Number | The number of pixels between each widget group | +| background | Color | A fill color behind the entirety of each template copy | +| border-color | Color | The color of the group's border surrounding each template copy | +| border-width | Number | The thickness of the group's border in pixels | +| visibility | String | A pv that determines the visibility of the layout, visibility is turned off if the PV's value is zero. This logic is inverted if the !Not tag is used instead of String | * **Example** @@ -193,9 +199,10 @@ not changed. If the macro named by `repeat-over` is parsed and found to be a number, then the node will iterate a number of times specified by the macro. On each loop, the children widgets will be provided with -the macros `N` and `__index__` to use to configure themselves. `__index__` is a number that starts -at zero and increments by one every iteration of the loop. `N` is similar, but starts at a value -specified by the attribute `start-at`. +two macros; `__index__` and another that will be named according to `index-variable` so that the +child widgets can configure themselves. `__index__` is a number that starts at zero and increments +by one every iteration of the loop. The index variable is similar, but starts at a value specified +by the attribute `start-at`. If, instead, `repeat-over` names a macro that is found to be a list of dictionaries, then the dictionaries will be treated as the macros to use to configure the children widgets. The loop @@ -203,21 +210,27 @@ will iterate over each of the specified mappings and will provide the children e group with those macros (alongside any other macros in the data file). The `__index__` macro mentioned above will also be included. +Finally, if `repeat-over` names a macro that is found to be a list of values, then the values will +be made available to each child under a name specified by the attribute `value-variable`. The `__index__` +macro mentioned above will also be included. + You may also use the alias "repeat" to reference the vrepeat node. * **Special Attributes** -| Name | Type | Description| -|--------------|--------|------------| -| children | List | A list of widgets to use as a template to copy along the vertical axis | -| repeat-over | String | The name of a macro that will be provided within the input data file | -| start-at | Number | An offset value to the loop index to provide children widgets | -| padding | Number | The number of pixels between each widget group | -| background | Color | A fill color behind the entirety of each template copy | -| border-color | Color | The color of the group's border surrounding each template copy | -| border-width | Number | The thickness of the group's border in pixels | -| visibility | String | A pv that determines the visibility of the layout, visibility is turned off if the PV's value is zero. This logic is inverted if the !Not tag is used instead of String | +| Name | Type | Description| +|----------------|--------|------------| +| children | List | A list of widgets to use as a template to copy along the vertical axis | +| repeat-over | String | The name of a macro that will be provided within the input data file | +| index-variable | String | The name under which to provide the value of the loop index, 'N' by default | +| value-variable | String | The name under which to provide the current value when iterating over a list, 'val' by default | +| start-at | Number | An offset value to the loop index to provide children widgets | +| padding | Number | The number of pixels between each widget group | +| background | Color | A fill color behind the entirety of each template copy | +| border-color | Color | The color of the group's border surrounding each template copy | +| border-width | Number | The thickness of the group's border in pixels | +| visibility | String | A pv that determines the visibility of the layout, visibility is turned off if the PV's value is zero. This logic is inverted if the !Not tag is used instead of String | * **Example** @@ -282,18 +295,20 @@ elements a user provides. * **Special Attributes** -| Name | Type | Description| -|--------------|--------|------------| -| children | List | A list of widgets to use as a template to copy in a grid pattern | -| repeat-over | String | The name of a macro that will be provided within the input data file | -| start-at | Number | An offset value to the loop index to provide children widgets | -| padding | Number | The number of pixels between each widget group | -| aspect-ratio | Double | A ratio indicating the relative number of columns to the number of rows in the grid | -| background | Color | A fill color behind the entirety of each template copy | -| border-color | Color | The color of the group's border surrounding each template copy | -| border-width | Number | The thickness of the group's border in pixels | -| horizontal | Bool | Fill direction of the layout. Macros will be mapped to widgets across columns first, then proceed to the next row, rather than the reverse. True by default | -| visibility | String | A pv that determines the visibility of the layout, visibility is turned off if the PV's value is zero. This logic is inverted if the !Not tag is used instead of String | +| Name | Type | Description| +|----------------|--------|------------| +| children | List | A list of widgets to use as a template to copy in a grid pattern | +| repeat-over | String | The name of a macro that will be provided within the input data file | +| index-variable | String | The name under which to provide the value of the loop index, 'N' by default | +| value-variable | String | The name under which to provide the current value when iterating over a list, 'val' by default | +| start-at | Number | An offset value to the loop index to provide children widgets | +| padding | Number | The number of pixels between each widget group | +| aspect-ratio | Double | A ratio indicating the relative number of columns to the number of rows in the grid | +| background | Color | A fill color behind the entirety of each template copy | +| border-color | Color | The color of the group's border surrounding each template copy | +| border-width | Number | The thickness of the group's border in pixels | +| horizontal | Bool | Fill direction of the layout. Macros will be mapped to widgets across columns first, then proceed to the next row, rather than the reverse. True by default | +| visibility | String | A pv that determines the visibility of the layout, visibility is turned off if the PV's value is zero. This logic is inverted if the !Not tag is used instead of String | * **Example**