repeat over lists documentation

BCDA-APS · Aug 7, 2024 · 61046ff · 61046ff
1 parent 655b32a
commit 61046ff
Showing 1 changed file with 53 additions and 38 deletions.
diff --git a/docs/nodes/layouts.md b/docs/nodes/layouts.md
@@ -130,29 +130,35 @@ 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
 will iterate over each of the specified mappings and will provide the children elements of the
 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,31 +199,38 @@ 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
 will iterate over each of the specified mappings and will provide the children elements of the
 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**