The HTML content commands
toggle-control work as a pair to allow the visibility of an element's contents displayed on a Screen to be toggled, and have the visibility status to be preserved on further evaluations. The
toggle command marks the element whose contents' visibility can be toggled by a checkbox input with the
toggle-control command. As these commands do not do much good alone, please ensure that there's always of a matching pair of a
toggle-control - matching meaning that they have the same primary attribute value.
When on a Screen, the functionality of these two commands is as follows. When the
toggle-control checkbox is checked, the
toggle element's contents are displayed. If it is unchecked, all child elements of the
toggle element will disappear, with the exception of a child element containing the matching
toggle-control checkbox, if it happens to be placed within the element it is toggling. As the Screen is submitted, the
toggle-control checkbox will submit its value and produce a Boolean variable whose name is the same as the command's primary attribute value. If these commands are then displayed on a Screen again, that variable is read and the
toggle-control checkbox will be in the state it ended up in the previous Screen.
While one can use this pair of commands to just create Screen elements that appear and disappear as the user clicks checkboxes, these two can also be used for document editing purposes. The functionality of these commands changes if the HTML resource they're on is evaluated with a composeContent command whose
editable attribute is
false: the checkbox with
toggle-control will disappear, and the contents of the
toggle element will either disappear or remain depending on whether it ended up as visible in a previous Screen. These commands may therefore be placed into document content and allow users to toggle the visibility of document sections in a document-editing Screen.
If using multiple pairs of
toggle-control in an HTML document, please make sure that each pair has its own unique primary attribute value. If multiple pairs of these commands use the same primary attribute value, the involved
toggle commands cannot properly resolve the visibility states set by their
toggle-control counterparts and an error is produced.
Both of these commands have a priority of 900.
A basic example of the use of
<input type="checkbox" dyn-toggle-control="toggleVar"/> <div dyn-toggle="toggleVar"> <p>Text</p> </div>
The paragraph with "Text" would appear and disappear as the
toggle-control checkbox input is checked and unchecked. It is also possible to put the checkbox inside the element with
toggle without causing the toggle-controlling checkbox itself to disappear:
<div dyn-toggle="toggleVar"> <h2>Section A <input type="checkbox" dyn-toggle-control="toggleVar"/></h2> <p>Section A content.</p> </div>
In this case the paragraph "Section A content." would be subject to the visibility toggling, while the heading "Section A", within which the
toggle-control input is, would remain visible regardless of the checkbox's state.