version-handler.html, js/main.js
Class Toggles
| verb | target | forms | description | sources |
|---|---|---|---|---|
element classes in the text |
buttons |
Show/hide elements of classes. |
This handler enables switching the show/hide states of elements assigned certain classes. A classic use case showing different content in the same page depending on the user’s operating system.
With AsciiDocsy class toggles, this choice follows the user throughout the site. You can essentially embed multiple user experiences right into the same pages of your site, assuming the divergence is not too drastic.
Implementation
Class toggles must be registered in the versioning: data object.
Create a new block with an arbitrary name, optionally including -toggle to help keep track.
Add a required block called swap:, under which options can be derived from a data: file or from an explicit opts: list.
The rest of the implementation process involves adding classes to blocks or segments of text. Use inline role syntax to designate a chunk of text as belonging to one or another class.
To toggle an entire section, add a class to the heading and group the rest in an open block, then assign a class to it.
Example
The following content is applicable to only one or two operating systems at a time.
Example 1. Example content (paragraph blocks) bearing registered classes
This site works great on Windows 10, and probably on Windows 7, and likely even on Windows XP. Windows often requires extra/special instructions for developer-oriented stuff.
Windows users are encouraged to explore WSL2 for access to a true Unix-like system right inside their main OS.
This site was built on a Linux desktop, and it probably looks great on FreeBSD. I personally want Mac and Windows users to know that, but other stuff might be noise to non-Linux users, so why rub their noses in it?
MacOS always makes AsciiDocsy look terrific.
The author of AsciiDocsy strongly prefers Unix-like systems, but they would never want Windows users to see such a statement.
The markup behind that content can be readily distinguished and edited.
AsciiDoc source for above example
[.os-win]
--
This site works great on Windows 10, and probably on Windows 7, and likely even on Windows XP.
Windows often requires extra/special instructions for developer-oriented stuff.
Windows users are encouraged to explore WSL2 for access to a true Unix-like system right inside their main OS.
--
[.os-nix]
--
This site was built on a Linux desktop, and it probably looks great on FreeBSD.
I personally want Mac and Windows users to know that, but other stuff might be noise to non-Linux users, so why rub their noses in it?
--
[.os-mac]
--
MacOS always makes AsciiDocsy look terrific.
--
[.os-mac.os-nix]
--
The author of AsciiDocsy strongly prefers Unix-like systems, but they would never want Windows users to see such a statement.
--Class toggling can be performed on inline text elements, as well, but if you plan to do this heavily, you may find it handier to use token swaps in most such cases. To expand the power/precision of your toggles, consider adding a swap slate and then piggybacking that swap onto your toggle.