WAI Policies Prototype technical insights

(For archival to the EO list, which I forgot to CC.)

Hi Robert, Andrew, and Mary Jo,

Here are some insights into the [WAI Policies Prototype] ([GitHub 
Repository]), in list form:

* The prototype uses [Jekyll], which means that all changes of the 
Github Repository are almost instantaneously reflected on the prototype.

* The project basically consists of two things that work together: 
[Data] and (currently one) [Template].

* The data is in YAML files, which are (rater complex) text files, for 
example: 
https://raw.githubusercontent.com/w3c/wai-policies-prototype/gh-pages/_policies/australia.md

   * Indentation matters: In this file we have multiple policies, those 
are indented by two spaces and then a - and another space. Basically 
each data sub-block begins with a dash. I think it is much easier to see 
in the example document above than I can explain it here.

* The templates use a simple templating language called [Liquid]. Think 
about it like PHP but not on steroids (it is not an actual programming 
language). Example:

     <ul>
        {% for policy in site.policies %}
        <li data-updated="{{policy.updated}}"><a href="#x{{policy.title 
| slugify }}">{{policy.title}}</a></li>
        {% endfor %}
     </ul>


   * This example uses the loops through the policies (they are all in 
the site.policies variable) and then outputs various sub-variables from 
any individual policy, which are dot (“.”) separated, so 
policy.updated gives back the updated date of the policy. The curly 
quotes {{}} means that the variable is shown in the HTML output. 
Anything in {%%} is not output and is only instructional, like for loops 
or ifs.

   * Variables can be modified using the pipe character “|” – here 
`{{policy.title | slugify }}` means that the title of the policy (here: 
the country name is used and then “slugified”. Spaces are replaced 
with dashes and certain international characters are changed to make it 
work as an id.

* Note that the prototype does not support states yet, neither in the 
data format, nor in the templating.

* In the template,

   * [Line 7ff.] creates the sidebar with links to the individual 
sections,
   * [Line 20ff.] and following create the sortable table (the sorting 
is done using JavaScript),
   * [Line 45ff.] create the expandable sections on the bottom of the 
page,

   at the moment.

I hope that helps a bit. You can always press the edit button and make 
changes, I will give you all writing permissions. If you need something 
else from me, feel free to drop me an email. We can also meet on WebEx, 
if necessary.

As always, it is much easier when actually play around with the 
prototype than explaining it here.



— Eric




[WAI Policies Prototype]: https://w3c.github.io/wai-policies-prototype/
[GitHub Repository]: https://github.com/w3c/wai-policies-prototype
[Jekyll]: http://jekyllrb.com
[Data]: 
https://github.com/w3c/wai-policies-prototype/tree/gh-pages/_policies
[Template]: 
https://github.com/w3c/wai-policies-prototype/blob/gh-pages/index.html
[Liquid]: https://shopify.github.io/liquid/
[Line 7ff.]: 
https://github.com/w3c/wai-policies-prototype/blob/gh-pages/index.html#L7
[Line 20ff.]: 
https://github.com/w3c/wai-policies-prototype/blob/gh-pages/index.html#L20
[Line 45ff.]: 
https://github.com/w3c/wai-policies-prototype/blob/gh-pages/index.html#L45




--

Eric Eggert
Web Accessibility Specialist
Web Accessibility Initiative (WAI) at World Wide Web Consortium (W3C)