Reorganize patterns and examples to reflect site architecture

[mcking65]

This issue documents one portion of the reorganize repository project.

Objective

Build a content tree containing the home page, patterns, examples, and index. The practices and about sections of the site will be handled in subsequent steps.

Directory Structure

• "content" directory at root level: This will hold all content in a tree that matches the IA of the web site. It has subdirectories for:
  • patterns
  • index
  • shared (for js, css, scripts that need to be referenced by multiple resources. Did not name "common" because we have not yet eliminated aria-common)
• There will be a directory for each pattern that contains:
  • A file for the pattern, e.g., "accordion-pattern.html". Originally considered naming "index.html" but decided a more specific file name could avoid confusion with bulk file operations.
  • An examples directory for the examples.

Plan

1. Create subdirectories for patterns under /patterns directory. Note: name the pattern directory the same way it is named in w3c/aria-practices/examples/. For example, the modal dialog pattern directory should be named "dialog-modal", not "dialogmodal". If the new pattern directory name differs from the path name in the currently published wai/aria/apg, add a note about the need for pattern redirect in the redirect notes comment below.
2. For each pattern, create a pattern file from content in aria-practices.html, e.g., /content/patterns/accordion/accordion-pattern.html. Copy content from respec file into the new pattern file and edit as needed.
3. In each pattern subdirectory, create an examples directory and move the example files into that directory.
4. Move shared js and css into shared directory.
5. Edit example html files to fix references and minimize scripted content transformation (instructions in comment below).
6. Reconfigure regression tests to run test against examples in new location (regression-tests.sh)
7. Update create-gh-project.js to use new examples location.
8. Update reference-tables.js to use new pattern and example locations and create output in /content/index/generated-content-index.html
9. Update coverage-report.js to use new pattern and example locations and create output in /content/about/coverage-reports/
10. Update github actions to utilize new locations
11. Modify build process to:
    • pull pattern content from new pattern content files;
    • pull example content from new example locations;
    • pull index content from new index location;
    • Stop making content additions or modifications to patterns, examples, and index.
12. Configure redirect for pattern if the pattern URL will be different from the URL for that pattern when the WAI site was launched (e.g., for modal dialog because the directory name changed from dialogmodal to dialog-modal.
13. Configure redirect for examples since they are no longer in the examples-index path.

[mcking65]

@richnoah @alflennik
I started work in PR #2417.

I'd like to discuss this PR and how to divide up the work on it during Tuesday's meeting.

[mcking65]

Editing example files

Following are instructions for plan step:

5. Edit example html files to fix references and minimize scripted content transformation.

There are 30 pattern subdirectories in the /content/patterns directory.

As of July 31, when revising these instructions, work to revise the example files for the following patterns in the '"move-examples" branch has already ben completed:

1. accordion
2. alert
3. breadcrumb

Note that the following pattern subdirectories do not contain subdirectories for examples:

1. alert-dialog (the example for this pattern is under dialog-modal because it uses the same js and css as other modal dialog examples)
2. Tooltip (this pattern does not have examples)
3. window-splitter (this pattern does not yet have examples)

Note that there is no pattern for landmarks. We probably don't need to make changes to landmark example files to achieve the goals of this issue. The landmark example files need to be redesigned as part of a separate project.

As of July 31, the following steps need to be performed for the examples contained in the other 24 patterns.

Here are the work items to complete for each /content/patterns/PATTERN_NAME/examples/EXAMPLE_NAME.html file within those 25 pattern subdirectories:

1. In the head element, edit href and src attributes for the Core js and css shared by all examples: change path prefix from ../ to ../../../shared/
2. Delete the following two list items from the <ul> in <nav aria-label="Related Links" class="feedback"> (please leave the other list items in place):
   1. <li><a href="../../#browser_and_AT_support">Browser and Assistive Technology Support</a></li>
   2. <li><a href="https://github.com/w3c/aria-practices/issues/new">Report Issue</a></li>
3. Edit href of all links to the design pattern. The new href should be ../pattern-PatternName.html. Note there may be two or more links to the design pattern.
4. In the list of similar examples, if any of the examples belong to a different pattern, edit href of those links. The current href is of form ../other-pattern-name/example-name.html. The new form would usually be ../../pattern-name/examples/example-name.html.
5. If there are links to any other patterns, revise the links to those patterns.
6. Delete the string " | WAI-ARIA Authoring Practices 1.2" from the title tag content.
7. On line after <h1> element:
   1. Add a <section> tag to open the about this example section.
   2. add a line at the start of the section with <h2>About This Example</h2
   3. Add a </section> tag before the opening tag of the example section.
   4. Note: please pay attention to white space; the section content will need to be indented two spaces.
8. Delete the unnecessary <nav> element that follows the </main> tag.

Note: Since we are not yet migrating the practices and other content, do not edit the href of links to any practices-related content. Those will continue to be resolved by the site build script.

[mcking65]

Notes for redirect planning

• The pattern directory name in the path for the modal dialog pattern is changing from /dialogmodal/ to /dialog-modal/. This affects the path of the pattern and all its examples.
• The pattern directory name in the path for the menu button pattern is changing from /menubutton/ to /menu-button/. This affects the path of the pattern and all its examples.
• All examples are moving from /wai/aria/apg/examples-index/PATTERN_DIRECTORY_NAME/EXAMPLE_NAME.html to /wai/aria/apg/patterns/PATTERN_DIRECTORY_NAME/examples/EXAMPLE_NAME.html. Exceptions to this pattern follow.
  • The alert dialog example is moving from the modal dialog pattern to be under the alert dialog pattern, so the path is changing from: WAI/ARIA/apg/example-index/dialog-modal/alertdialog.html to WAI/ARIA/apg/patterns/alertdialog/examples/alertdialog.html
  • The file name of the breadcrumb example is changing from "index.html" to "breadcrumb.html", so the path is changing from: WAI/ARIA/apg/example-index/breadcrumb/index.html to WAI/ARIA/apg/patterns/breadcrumb/examples/breadcrumb.html
  • The multi-thumb slider example is moving from the slider pattern to be under the multithumb-slider pattern, so, the path is changing from: WAI/ARIA/apg/example-index/slider/slider-multithumb.html to WAI/ARIA/apg/patterns/slider-multithumb/examples/slider-multithumb.html
  • The treeview-1 directory is removed from the path of the File Directory Treeview Example Using Computed Properties, so the path is changing from: WAI/ARIA/apg/example-index/treeview/treeview-1/treeview-1a.html to WAI/ARIA/apg/patterns/treeview/examples/treeview-1a.html
  • The treeview-1 directory is removed from the path of the File Directory Treeview Example Using Declared Properties, so the path is changing from: WAI/ARIA/apg/example-index/treeview/treeview-1/treeview-1b.html to WAI/ARIA/apg/patterns/treeview/examples/treeview-1b.html

[mcking65]

Based on discussion in today's meeting, I changed the plan to name the pattern files using the form /content/patterns/PATTERN_NAME/PATTERN_NAME-pattern.html, e.g., /content/patterns/accordion/accordion-pattern.html.

I have now created stub pattern files for all 30 patterns in the "move-examples" branch used for PR #2417.

I have started making notes about needs for redirects in a comment above.

[mcking65]

@a11ydoer, the "move-examples" branch is now ready for you to edit example files.

git Checkout move-examples and follow the instructions in this comment above, and then commit with the "-n option. The -n option will skip all checking, which is necessary because this branch fails all checks. Then push the changes so they show up in #2417.

Make sure you pull just before you push, just in case we happen to be working at the same time. I will only be working on the pattern files. @alflennik is focused on scripts and actions. You are the only person working on the example files, so we should easily be able to avoid conflicts.

[mcking65]

@alflennik

I am thinking about the site build scripts and wondering whether increasing the scope of PR #2417 might actually simplify scripting and reduce risks associated with this restructuring.

Consider processing for the following two links in this file: aria-practices/grid-pattern.html at move-examples

• On line 29, there is a same page link (<a href="#kbd_general_within">manages focus movement inside it</a>)
• On line 109, there is a link that looks like a same page link (<a href="#kbd_common_conventions">Key Assignment Conventions for Common Functions</a>), but that link is actually to practices content that PR Replace aria-practices.html with a new content tree and move examples into the patterns branch of the tree #2417 is not yet moving out of aria-practices.html.

The current plan is to move the practices content in a separate PR. So, for PR #2417, the site build script will need to reliably distinguish between the above links to modify the href of the link on line 109 but not modify the href of the link on line 29.

Does this introduce unnecessary complexity? Typically, we reduce risk by keeping PRS scoped more narrowly, but since this PR is already enormous, would it be less risky to expand the scope of this PR and move practices content at the same time?

[mcking65]

@a11ydoer

Note that I just revised the step related to the "about this example" section my comment about editing example files.

I also went ahead and did the work for the breadcrumb example because I saw need to change the name of the example file and wanted to reference it from the pattern.

I won't touch any other examples until we coordinate. Again, I recommend pushing after each time you complete the changes for one example file. That will help ensure we don't run into problems. I am pushing after each pattern is complete. Patterns are now half done.

[a11ydoer]

3. Edit href of all links to the design pattern. The new href should be ../pattern-PatternName.html. Note there may be two or more links to the design pattern.

@mcking65 update on documentation - The new href should be '../PatternName-pattern.html', not '../pattern-PatternName.html'. Those are the way three other examples are done. (ex: Accordion, alert, and breadcrum pattern)

[a11ydoer]

@mcking65 I finished the example file update till radio group pattern. Next pattern which will be updated is the slider pattern. I plan to work on the rest example file update tonight.

[alflennik]

Hi @mcking65, I looked at the two links you pointed out. If you look on the published version of the page you can find the link on line 29 by searching for "manages focus movement inside it" and you can find the link on line 109 by searching for "Key Assignment Conventions for Common Functions". In the current version of this page, neither of the links is a same page link - both link to other pages on the site. So I'm a little bit confused when you say one is a link to another page and another is a same page link. I think the confusion emphasizes the need for the links to actually work, so I would definitely advocate that we try to find a way to make sure as many as possible of the links remain functional. Does that help resolve anything?

[a11ydoer]

@mcking65 @alflennik I am working on the rest of examples files this morning. I will let you know two when all are completed.

[a11ydoer]

@alflennik @mcking65 I finished all the example file updates. Please feel free to work on the "move-examples" branch.

[mcking65]

Note: After reviewing #2450, I updated step 11 in the plan with more detail.

Previously, step 11 was:

11. Modify build process to pull pattern content from new pattern file and example from new example location

Now, step 11 is:

11. Modify build process to:

• pull pattern content from new pattern content files;
• pull example content from new example locations;
• pull index content from new index location;
• Stop making content additions or modifications to patterns, examples, and index.

[mcking65]

@alflennik

I want to move treview-1a and treview-1b examples up a level so the directory structure is consistent with other patterns. However, several of your PRs include fixes to example pages, so I'm going to wait till we merge your PRs into move-examples.

Moving the treeview examples might re-break a few things, e.g., regression testing for them. So, we'll need to circle back on that. I figure that is easier than me moving them now and potentially creating need to rebase some of your work.

[mcking65]

Steps 1 through 5 are now complete except for above mentioned changes to two of the treeview examples.

[alflennik]

I want to move treview-1a and treview-1b examples up a level

After discussing this in the task force meeting we decided to tackle this last after the other PRs have been merged into the move-examples branch.

[mcking65]

@alflennik @s3ththompson

The patterns, examples, and practices are now all moved out of aria-practices.html and all links across content, (e.g., patterns to practices and vice versa) should be in good shape now.

Next steps:

• Apply css to patterns and practices (also noted in Create new pages for practices content #2424)
• Include card images for patterns and practices in the new content tree (also noted in Create new pages for practices content #2424)
• Create content/patterns/patterns.html and content/practices/practices.html
• Make Netlify preview work for the move-examples branch

[mcking65]

@alflennik @s3ththompson

Note that I have created #2487 and #2488 and assigned to @alflennik. Now that I am done with content edits and link updates, I think we are ready for those two tasks. Note that we will also need to track the need for redirects for those two changes as well.