[Draft] The Minimal 'standalone_resource' Layout

Background and what’s what

The WAI website header and navigation prided in the default theme layout take up a fair bit of screen real estate and add some visual complexity to pages. Some WAI resources use the simplified header and navigation of the standalone_resource layout; for example, the ARIA Authoring Practices Guide (APG) and Supplemental Guidance to WCAG 2.

The standalone_resource layout uses the Minimal Header component and also provides options for simplified navigation

Resources using the WAI Website Theme

Resources that are fully integrated into the WAI website use the WAI theme, that provides page layouts and components. These can simply use the ‘stand-alone resources’ layout instead of the default to provide an alternative header and navigation

With this layout, you can:

• use a simple tab like navigation
• provide data for a pager control navigation (up, previous, next)
• enable an automatically-generated “Page Contents” (TOC)

These are all configured declaratively using page variables in the usual Jekyll way. They can be specified per page in the frontmatter, or across pages in the _config.yml file. (See Jekyll - Front Matter Defaults). Specifying them in the config file is usually best.

Specify the ‘stand-alone resources’ layout

layout: standalone_resource

Header content

See Supplemental Guidance which uses all the features

Required: title Optional: title-ref - for pager style nav this appears on the first item in the nav Required: subtitle Optional: link

standalone_resource_header:
  title: Supplemental Guidance to WCAG 2
  title-ref: /WCAG2/supplemental/#-cognitiveaccessibilityguidance
  subtitle: Additional ways to improve accessibility, not required to meet WCAG
  link:
    ref: /WCAG2/supplemental/about/
    title: About Supplemental Guidance and WCAG

Navigation

Two style are supported: Tab and pager

Tab style

As used in the ARIA Authoring Practices Guide:

standalone_resource_nav_links:
  - name: APG Home
    ref: /ARIA/apg/
  - name: Patterns
    ref: /ARIA/apg/patterns/
  - name: Practices
    ref: /ARIA/apg/practices/
  - name: Index
    ref: /ARIA/apg/example-index/
  - name: About
    ref: /ARIA/apg/about/

Pager style

As used in the Supplemental Guidance:

All required except the icon is optional.

standalone_resource_pager:
  icon: /content-images/wai-wcag-supplemental/brain.svg
  name: All Cognitive
  ref: /WCAG2/supplemental/#-cognitiveaccessibilityguidance

The pager provides ‘up’, ‘next’ and ‘previous’ links for navigation within the set of documents. It is data driven, using a set of Jekyll arrays to provide the names and URLs.

To use it, specify an include file that provides the arrays.

standalone_resource_pager:
  include: dg-pager.liquid

For example: Here’s the code from at the end of the Supplemental Guidance pager file dg-pager.liquid:

{% comment %}
Set up tuples for pager
{% endcomment %}
{% if is_pattern %}
    {% assign item_type = "Pattern" %}
    {% assign context_type = "Objective" %}
{% else %}
    {% assign item_type = "Objective" %}
{% endif %}
{% if prev_item %}
    {% assign prev = "Previous " | append: item_type | append: "??" | append: prev_item.url | append: "??" | append: prev_item.title | split: "??" %}
{% endif %}
{% if next_item %}
    {% assign next = "Next " | append: item_type | append: "??" | append: next_item.url | append: "??" | append: next_item.title | split: "??" %}
{% endif %}
{% if context_item %}
    {% assign context = context_type | append: "??" | append: context_item.url | append: "??" | append: context_item.title | split: "??" %}
{% endif %}
{% endif %}

@@ TODO: explain this

Type of document (guidance) in h1, optional

Most document sets have different types of documents, for example the cognitive guidance has ‘Objectives’ and ‘Design Patterns’. The type of document is included at the beginning of the h1. It can also be used for other logic purposes in the resource pages.

Provide the type_of_guidance and if it is proposed.

type_of_guidance: Technique

In addition, if defined, “proposed” is use as a prefix.

proposed: true

Generated Page Contents, optional

A right-hand sidebar can be enabled that provides navigation to headings. By default, it includes h2. You can set it to include other heading levels. In addition to the the sidebar menu, it adds the fragment id’s for the URLs to the headings.

sidebar: true

Tools that do not use the WAI Website Theme

Some tools — currently WCAG-EM Report Tool and ATAG Report Tool — do not use the WAI website theme. Instead they are implemented in other technologies and linked into the WAI website via W3C redirects. They use the Tool version of the Minimal Header and use the theme styles, including those for the Minimal Header for visual consistency with the WAI website.

Tool navigation, depreciated

For tools that have all pages in the navigation area, a set of tab-like links are created thus:

standalone_resource_nav_links:
  - name: Tab1
    ref: /path/to/page1
  - name: Tab2
    ref: /path/to/page2

This is not compatible with the navigation described above.

Examples

• Document set integrated, using standalone-resource: Cognitive Accessibility Design Pattern in Supplemental Guidance to WCAG 2
• Tool not integrated, using minimal header: WCAG-EM Report Tool