Version Handlers

Version handlers are front-end features that enable site users to see only the content that applies to their product version, role, use case, environment, preference, or other condition. You can use version handlers however you want, but we present here some guidance for choosing among the options to suit your application. Further topics detail the configuration of each handler type.

Handlers are named for their duty, not the form their controllers take. The handler types perform distinct actions on the selected jQuery JavaScript ready, change, focus, or similar event.

You do not need to know JavaScript or jQuery to implement handlers. AsciiDocsy pre-customizes and extends Bootstrap features to provide configuration-based adaptation to your use case.

The rest of this topic provides an overview of attributes and functions common across version handlers as well as a guide for choosing between the various handler types.

Version Handler Verbs

Version handlers are named for what they do, not what they look like. For instance, the user can swap tokens, tab through a set of content blocks, toggle classes to show/hide, or amend the HTML document object model (DOM). These labels are imperfect, but they allow us to distinguish function from form.

Tab Block Content in Place

Most common with code listings and log samples, if you need to alternate versions of content inside a fixed block without forcing the user to scroll, your optimal solution is tabbing.

These handlers use JavaScript to glean combinations of selector tabs and content panes out of the HTML rendered from conventional AsciiDoc syntax.

Example 1. Tabbed panes sourced entirely as AsciiDoc
- app: Asciidoctor
  use: THE AsciiDoc markup converter
  url: https://www.asciidoctor.org
  git: https://github.com/asciidoctor/asciidoctor
  vrsn: '2.0'
- app: Jekyll
  use: world-class static-site generator (SSG)
  url: https://jekyllrb.com
  git: https://github.com/jekyll/jekyll
  vrsn: '4.0'
[
   {
      "app": "Asciidoctor",
      "use": "THE AsciiDoc markup converter",
      "url": "https://www.asciidoctor.org",
      "git": "https://github.com/asciidoctor/asciidoctor",
      "vrsn": "2.0"
   },
   {
      "app": "Jekyll",
      "use": "world-class static-site generator (SSG)",
      "url": "https://jekyllrb.com",
      "git": "https://github.com/jekyll/jekyll",
      "vrsn": "4.0"
   }
]

Any tabset or tab/pane class that is repeated throughout a page (and the rest of the site if cookies are enabled) will pre-select the last-chosen tab until altered by the user.

Learn more about pane tabs.

Toggle Classes

Sometimes you need a combination of tabsets and swaps, alternating and muting larger blocks or shorter strings of text throughout a page. A toggle lets you show elements of one class while hiding the rest of the classes in a group.

Example 2. Give it a try!

In the sidebar to your right is a set of buttons labeled with the three most popular families of operating systems.

Toggle through them and see the content change here.

Operating System

Windows MacOS Linux
Unix-like?

False True

If inline content or various parts of an entire page need to be customized for user experience, apply classes (“roles” in AsciiDoc parlance) to the content.

Toggles are centrally defined in the Jekyll config, but you choose which pages the controllers appear on.

Dive deeper into toggles.

Swap Tokens in Place

In some cases, one simple string needs to be altered in numerous parts of a page, but it makes no sense to generate a whole version of the docs just to display this alternate content. A swap changes the value of tokenized content throughout the page.

This feature is most commonly used to alter patch-revision numbers, such as in product-download paths and installation instructions. Drop something like [.tok.vrsn]*0.2.0* into your page, and watch the version change as you switch between versions using the buttons to the right, below the table of contents: 0.2.0.

Swaps can be user triggered by a radio button set or a selectbox.

Swap Token Slates

If you have more than one string to swap when a version changes, use token slates. This capability could be invaluable to the process of “white labeling” a docset. Replace key terms related to your or a customer’s company, brand, or specific implementation of your product.

Token sets are defined in data files and can be swapped using buttons or selectboxes.

See the swaps configuration page for examples.

When you need to go big, version-dommer.html is your tool. At this time, Dommers can target the browser’s location (URL) or any element in the current page’s HTML5 DOM.

Taking the form of a selectbox or buttons, amenders are like an open-ended token swapper, targeting any discrete aspect of an HTML element that you can latch onto with jQuery.

The AsciiDocsy skin selectors are examples of changers that target CSS link refs in the header. If you have not yet played with the theme skin changers that are in the right-hand sidebar throughout this site, select an alternative theme skin and review this same page. Alternatively, choose a syntax skin and take another look at our YAML and JSON data listings.

These cases alter a CSS filename, but other functions are available. Any system that changes URLs between docsets (substantial versioning) would use this handler to bump locations to a parallel revision directory.

A DOM amender toggle could also be used to switch between the light and dark themes of a website.

Learn more about customizing DOM amenders.

Establishing & Overriding Defaults

All version handlers respect the same cascade hierarchy for establishing active options.

Every handler plants a cookie on the visiting browser so their choice is recalled for subsequent URLs during the session or until they clear their cookies. This cookie becomes the effective, overriding default until another choice is actively made by the user (or a until link sends them to a URL that alters the choice).

In their configuration, every handler gets a pick: parameter to set the base system default. If no pick: property exists or if the value is not an option, the first option will be selected by default.

If a query string parameter is provided in the URL, it will override any system default or cookie. Query strings are formatted as ?<handler-id>=<option-slug>[&<handler-id>=<option-slug>].

Example 3. Try it out!

Use the following URL to pre-select options on this very page and anywhere else the same set of tab classes is used in the site.

?user-os-toggle=os-nix&data-format-tabber=data-json

Any time a user selects (or a URL determines) an option, that option becomes active and the cookie is instantly updated.

If you use form: none, no controller will appear to enable users to change versions from within the page, and only a URL change will make or alter a version choice. Tempting as this capability may seem, NOTE that it is not a secure way to hide information from end users. The code decrypted by their browser will contain all of the alternate options they are not seeing on the front end.
By AsciiDocsy 1.0, an additional means of overriding a default option will include the domain or CNAME (subdomain) that is calling the page, so nothing as obvious as a ?parameter=value need be used.

Version Handlers Review

verb target forms description sources

amend

URL/head elements

select , buttons

Change a string in a DOM element or add your own function.

version-handler.html, your custom JS

swap

tokens in the text

select , buttons

Change the expression of a token already rendered in HTML.

version-handler.html

toggle

element classes in the text

buttons

Show/hide elements of classes.

version-handler.html, js/main.js

tab

a block element in place

tabs

Determine which block in tabset to show in pane.

js/tabber.js
Feedback, please.