Skip to content

Commit 42d2af4

Browse files
authored
Add data help docs/release notes
2 parents 02bdc25 + bec4bb6 commit 42d2af4

File tree

2 files changed

+45
-1
lines changed

2 files changed

+45
-1
lines changed

source/how-tos/app-development/interactive/dynamic-form-widgets.rst

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -180,7 +180,40 @@ form element based on the selected option in a select widget.
180180
value: 1
181181
182182
In this case, selecting Node Type 'small' will change the label of Cores to
183-
'Number of Cores (1-4)'.
183+
'Number of Cores (1-4)'. Note that you must define a ``data-label`` directive
184+
on each option of the select, as it does not keep a default value.
185+
186+
.. _dynamic-bc-apps-data-help:
187+
188+
Dynamic Help Text
189+
*****************
190+
191+
The ``data-help-*`` directive allows you to change the help text of another
192+
form element based on the selected option in a select widget.
193+
194+
.. code-block:: yaml
195+
196+
form:
197+
- node_type
198+
attributes:
199+
node_type:
200+
widget: select
201+
label: Node Type
202+
options:
203+
- [ 'Small', 'small', data-help-node-type: 'Small machines have 10 cores and 100 GB of RAM' ]
204+
- [ 'Medium', 'medium', data-help-node-type: 'Medium machines have 50 cores and 500 GB of RAM' ]
205+
- [ 'Large', 'large', data-help-node-type: 'Large machines have 100 cores and 1 TB of RAM' ]
206+
207+
In this case, the ``node_type`` form item begins with the help text 'Small machines ...', since this
208+
is the initial value of the select. As you select different options, the help text changes to provide
209+
details of the different choices. While we have the ``node-type`` select changing its own help text in
210+
this example, you can modify the help text of any form item using the same ``data-help-attribute-name``
211+
syntax.
212+
213+
Note that ``data-help`` directives will override the help text provided in the attribute definition, and
214+
any options that do not have a ``data-help`` directive will not change the help text from it's last value.
215+
This means that if we left out the data-help directive on the medium option, the help text will retain its
216+
previous value (either 'Small machines...' or 'Large machines...') when medium is selected instead of clearing.
184217

185218
Dynamic Min and Maxes
186219
*********************

source/release-notes/v4.1-release-notes.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,17 @@ Forms, Widgets, and User Input
5050
* Smart attributes
5151
* Form YAML stuff
5252

53+
New data-help Directive
54+
.......................
55+
56+
Version 4.1 adds the ``data-help`` directive, allowing you to dynamically change
57+
the help text below form items when certain select options are chosen. For example,
58+
you may have a ``node_type`` select widget, where type ``basic`` has older GPUs than
59+
``advanced``. The ``data-help`` directive can change the help text on the ``num_gpus``
60+
option for users who select ``advanced`` so that they can take that info into account
61+
when deciding how many GPUs to select. For full documentation, see :ref: `dynamic-bc-apps-data-help`.
62+
63+
5364
Files, Projects, and Data Management
5465
------------------------------------
5566
* Files App

0 commit comments

Comments
 (0)