toggle & toggle-control

The HTML content commands toggle and 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 and 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 and 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.

Examples

A basic example of the use of toggle and toggle-control commands:

<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.