DOM Amenders

By far the most open-ended of the superficial version handlers, DOM amenders enable you to manipulate the DOM in one simple way at a time. Not a wide-open API like jQuery itself, but a simple way to execute a jQuery function on the change() event.

Use cases include switching URLs or switching CSS files in the HTML <head>.

Configuring a DOM Amender

To create a straightforward amender, make an entry in site.features.versioning and give it a verb: amend property. The key property for an amender is the func: object. This property must contain the name: of a built-in function or a file: to designate a custom JavaScript snippet.

Built-in Amender Functions

The existing named functions are:

change-url

Alters the browser location. Requires the href: property for passing a URL to which to send the browser.

change-href

Alters the path of a resource file’s source. Requires an element to target (targ:) and a URL path to replace the token with.

The href: property in a built-in function can include Liquid syntax as well as JavaScript syntax. Liquid will be executed at build-time; JavaScript will be executed in the browser.

Here is the source of the syntax skin changer in the right-hand sidebar.

  syntax-skin-amend:
    verb: amend
    form: select
    spot: "#sidebar-right .sidebar-end"
    show:
      text: "Code highlight skin:"
      icon: fa fa-code
    swap:
      data: site.data.theme.syntax-styles
      pick: a11y-light
    func:
      name: change-href
      targ: "#syntax-skin" (1)
      href: >- (2)
        '{{styles_url}}/syntax/hljs/' + $(this).val() + '.css'
1 The targ: property accepts a String in the form of a jQuery selector determining the element to act upon.
2 The syntax >- designates that the String value should be trimmed of internal newlines and surrounding whitespace. This is helpful when passing Liquid or other syntax intended for rendering inline.

Your Own DOM Amender Function

AsciiDocsy provides two key components to establish this functionality. The first is the formfield elements populated by an array and defined by other settings, as with other version handlers.

The version-handler.html partial can generate generate either a select dropdown or radio buttons. Pass it an array of scalars to establish the displayed option and the underlying value as one and the same. Pass an array of dictionary objects bearing text and slug properties, and it will use these values for the option labels and values, respectively.

To register your own DOM amender, add a template file (.html or .js) to the _includes/ directory, and register it as the func.file: value inside your amender block.

Example custom amender definition
  versioning:
    ...
    my-amender:
      verb: amend
      form: select
      func:
        file: my-amender.js
      swap:
        data: site.data.my-array
        pick: some-value

Your handler will be interpreted by _includes/versioning-controls.html and the controller will be generated by _includes/version-handlers.html.

It is called from within a $(function(){ call that executes as the page loads.

This functionality is likely to change by AsciiDocsy v1.0. The JS will be captured inline and expressed in the tail of the document to move it out of the HTML.
Feedback, please.