"Read this first" uses client-side JavaScript, why not HTML or jekyll _include?

[daniel-montalvo]

From w3c/wai-aria-practices#436

The "Read this first" banner is included using client-side JavaScript. It would be more elegant if we could use HTML or a jekyll _include.

[css-meeting-bot]

The ARIA Authoring Practices (APG) Task Force just discussed "Read this first" code upate.

The full IRC log of that discussion

<jugglinmike> Topic: "Read this first" code upate
<jugglinmike> github: https://github.com//issues/3373
<jugglinmike> Daniel: I think it would be more elegant if we could use static HTML for this
<jugglinmike> Daniel: We're more open to Jekyll "include" directives than we used to be
<jugglinmike> howard-e: I think the Jekyll "include" (or any frontmatter approach) would be going back to what wasn't wanted. There was an ask that the content in "read this first" could be controlled from this repository. We use a JavaScript approach to simplify maintenance for contributors
<jugglinmike> howard-e: if it was done in pure HTML, that would involve duplicating the template content across over 30 patterns
<jugglinmike> Matt_King: So we have client-side JavaScript not just for "read this first" but also for the disclosure on the example pages.
<jugglinmike> Matt_King: We have it in a couple places
<jugglinmike> Matt_King: What is the problem with the client-side JavaScript, Daniel?
<jugglinmike> Daniel: If you've disabled JavaScript, then the content is not available to you
<jugglinmike> Matt_King: But if you've disabled JavaScript, then most of the APG is not useful to you
<jugglinmike> Matt_King: Is there a way for the build process to perform the injection into every page as it's built? Is that somehow preferable?
<jugglinmike> Matt_King: I don't think that we want content repeated across many pages in the source repository. If we want to change content in that scenario, we have to update multiple pages. That makes the content-management more difficult, from an editorial perspective
<jugglinmike> Jem: What is the downside of using "include"?
<jugglinmike> Jem: What I'm hearing from Daniel is, "why don't we just use a simpler approach?"
<jugglinmike> howard-e: All that content was controlled in that repository. There are some assumptions which could be broken
<jugglinmike> howard-e: If we go back to the approach where the "builder" repository injects it, perhaps with a configuration file, then there may be a happy medium, here
<jugglinmike> Matt_King: The builder is just supposed to be an automated thing that transforms the content
<jugglinmike> Matt_King: The build should not be making editorial decisions
<jugglinmike> Matt_King: Is "include" a Jekyll feature?
<jugglinmike> Daniel: Yes
<jugglinmike> Matt_King: Then we'll end up mixing Jekyll directive into our HTML
<jugglinmike> Matt_King: Our content repository doesn't have any Jekyll in it. That was part of the beauty of the separation--that we don't require anybody to know anything about Jekyll in order to contribute to APG
<jugglinmike> Matt_King: Is there a "pure HTML" way of including content?
<jugglinmike> Daniel: I'll have to look into that
<jugglinmike> Daniel: you could argue that this is not exactly content per se...
<jugglinmike> Daniel: I'll reflect on this further and share my thoughts as a comment on the issue
<jugglinmike> Matt_King: In today's world, I wonder if we should be at all concerned about users who disable JavaScript
<jugglinmike> Daniel: They can read about the examples, they just can't interact with them
<jugglinmike> Matt_King: I wonder what that kind of person is even doing. And whether they're even part of the target audience
<jugglinmike> Daniel: This is motivated by discussions around the WAI website
<jugglinmike> Jem: Is this a build process issue?
<jugglinmike> Matt_King: Yes
<jugglinmike> Jem: I used to know people who disable JavaScript, they were mainly security experts

[remibetin]

That was part of the beauty of the separation--that we don't require anybody to know anything about Jekyll in order to contribute to APG

I appreciate the point. I've suggested using a Jekyll include as one approach that inserts content without relying on client-side Javascript, but other approaches might equally work.

There is an existing approach that might be more appropriate considering the custom setup between the w3c/aria-practices and the w3c/wai-aria-practices repositories:

In Example pages, there is a ‘Read this first‘ section: "The code in this example is not intended for production ...". See for instance Breadcrumb example.

This section is displayed to end users even when Javascript is disabled (or not available for diverse reasons). AFAIK, the HTML is inserted during pre-build in the wai-aria-practices repository.

Using a similar approach seems to address some concerns raised during the discussion, while ensuring that the ‘Read this first’ section is displayed even when Javascript is not available:

Our content repository doesn't have any Jekyll in it.

It does not rely on Jekyll features.

There was an ask that the content in "read this first" could be controlled from this repository.

The content of the section is still controlled from the example-usage-warning.html template in the aria-practices repository.

I don't think that we want content repeated across many pages in the source repository

The content is not repeated across all pages in the aria-practices repository (see for example breadcrumb.html).
It is only repeated across Markdown files in the wai-aria-practices repository (see for example breadcrumb.md.

[daniel-montalvo]

Thanks @remibetin for looking into this.

@mcking65 @howard-e Do you think we have a clear path forward for this?

[howard-e]

There was an ask that the content in "read this first" could be controlled from this repository.

The content of the section is still controlled from the example-usage-warning.html template in the aria-practices repository.

A secondary point of surprise/confusion was not being able to view the banner locally when opening the content pages. That led in this direction to have some parity across this content and the builder repositories:

expand for latest discussion

Matt_King: The part of this that became confusing to me is that it seems like we have some of the content being controlled from the build repository
Matt_King: When I review "practices.html" and "patterns.html", at least in the screen reader reading order, the very first thing after the "h1" is the "read this first section"
Matt_King: ...but there isn't anything there on those pages related to "read this first" content
Matt_King: So if I preview those pages that have "read this first" from the content repository--if I preview them locally, that content doesn't show up. "read this first" isn't there
howard-e: yes, that surprised me as well.
howard-e: The "read this first" banner has always been getting injected
howard-e: I'm wondering whether or not we should move that over to the "content" repository entirely
Matt_King: I think that's a good thing--especially if we're ever to move to another build system--to make sure the content is fully controlled from the content repository
howard-e: Got it. I can re-purpose this PR with that in mind

The example-usage-warning currently goes against that ask since you also can't view it locally on the pages. And updating how read-this-first works to match it would be returning it to how it was, so not a big deal there. It would be less confusing if we decide on and document if templates should be used in-place or from the builder's content injection (and to serve the immediate needs of this issue, that seems to be the builder content injection)

The only new thing to consider here is the control over the showImage property that was included in the script. We would either want to include a config to support that or make the current implementation controlled by the builder repo:

• read-this-first with img at top of patterns and practices index pages, under the h1
• read-this-first without img at top of each pattern's page, under the h1

@mcking65 if this is fine, it can certainly be done by the next publication

cc @daniel-montalvo @remibetin

[remibetin]

Thank you @howard-e for exploring this. Here are my initial thoughts on some points you raise. Please let me know if you expect my feedback on other points.

A secondary point of surprise/confusion was not being able to view the banner locally when opening the content pages. That led in this direction to have some parity across this content and the builder repositories:

I understand the initial surprise from a content developer's perspective when viewing the content locally, and I am not against more parity. My point is to prioritize end users when it's difficult to satisfy all needs and there are multiple options. In this context, using client-side JS has a downside for the end users: the ‘Read this first’ content might not be displayed to some users. Inserting the content of the template during pre-build does not have this drawback for users.

The example-usage-warning currently goes against that ask since you also can't view it locally on the pages.

Sure it’s nice to see everything locally. But since this content is repeated across many pages, how important is it to view it when developing the content locally? I may miss a pain.

The ‘WAI Preview Link’ in aria-practices PRs also provides a way to preview the content as it will be displayed on the live website before merging. This includes the ‘example-usage-warning‘ content. That's at least what I notice in this preview. Are those previews actively used when developing content?

[css-meeting-bot]

The ARIA Authoring Practices (APG) Task Force just discussed Issue 3373: "Read this first" uses client-side JavaScript.

The full IRC log of that discussion

<Matt_King> TOPIC: Issue 3373: "Read this first" uses client-side JavaScript
<Matt_King> GITHUB: https://github.com//issues/3373
<arigilmore> Matt_King the "read this first" content on the top of each pattern page and other pages and it's being done by client-side javascript. This should not be done by the client side anymore
<arigilmore> Matt_King: we want the content fully controlled not in the build repository
<arigilmore> Matt_King we should control what the content is and where it goes in the repository and the rest is in the build
<arigilmore> Matt_King we already have a template, but i also noticed that when I do a local preview of the example pages the content shows in local preview. That one is being done in a way that the w3c team is happy with, so how is it happening if it's not client side javascript
<arigilmore> howard: the javascipt file that's there for it to render locally it does reconstruct the html and build it on the page
<arigilmore> Matt_King what's the difference between the read this first and the usage warning?
<arigilmore> Matt_King: see's the usage warning locally in the example file
<arigilmore> Howard: not for me...
<arigilmore> Matt_King: is in his local then goes to content then patterns, accordion, examples in a windows. I have skipTo, related links, design pattern, heading H1. in vscode it shows it but not in windows directly
<arigilmore> Matt_King should we do the read this first the same way as usage warning
<arigilmore> Howard: yes, but there is another comment asking if we are comfortable with contributors viewing this
<arigilmore> Matt_King we should do it the same way
<arigilmore> howard: what controls what page it gets used on on for the usage warning
<arigilmore> Howard it's probably being done through App.js
<arigilmore> Howard: App.js is on all the pages
<arigilmore> checks for a certain path
<arigilmore> Matt_King can we have a separate file
<arigilmore> Howard: yes
<arigilmore> zakim, end meeting

[howard-e]

Hi @remibetin! We just discussed this in today's meeting and we can move forward with doing this in a way that closely matches how the example-usage-warning template is being done.

Sure it’s nice to see everything locally. But since this content is repeated across many pages, how important is it to view it when developing the content locally? I may miss a pain.

It could be, but we can certainly provide separate guidance to folks on such when in their local development environment.

[mcking65]

I can view the example usage warning locally in VSCode when I use the Open In Default Browser extension. So, if we use the same approach for the "Read This First" as we do for the example usage warning, there is still some local preview capability.

For content management by the APG TF, the requirements are:

1. The content (text, images, styling) is in the aria-practices repo and expressed with HTML+CSS+JS.
2. The aria-practices repo content controls on which pages the content is rendered.
3. Contributors can preview content either locally or in the PR.

To make control of which pages render the 'Read This First' content as transparent and simple as possible, it would be helpful if the 'head' element contained a 'script' element that is specific to the 'Read This First' feature, such that if the script is included in the head, the content is rendered on that page and if the script element is not included, the Read This First' is not rendered. I think this approach would be simpler to manage than the example usage warning, which has its rendering control buried in a function within a script that uses the path of the file to determine whether the warning is rendered.

[remibetin]

We just discussed this in #3373 (comment) and we can move forward with doing this in a way that closely matches how the example-usage-warning template is being done.

@howard-e Thanks!