Refactoring Engage's Screen Navigator

[Cheetham, Anastasia]

Engage's Screen Navigator contains some functionality that could be factored out and used in our upcoming documentation website, for the Instructional Demos. Colin has offered to look into doing this factoring, so here's a summary of what is required for the demos, starting with a bit of the background.

There will undoubtably still be questions about exactly what is required, even after you read this email, so ask away, and we'll clarify and refine the specification.


1. User experience of the Instructional Demos:

We want visitors to the documentation to see, on a single page:
  a) a working demo of one of a component's options, and
  b) displays of the HTML, JS and CSS used to create that working demo.

This would look something like this:
  http://wiki.fluidproject.org/download/attachments/23561101/tech-docs-final-DEMOS-COMPONENT-VARIATION.png?version=1&modificationDate=1302895468273

We will have roughly one of these demo pages per option, per component.


2. Instructional Demos in the code base

We'd like developers who check the code out of github to get the source for all of these demos. The plan, so far, is to split the current "demos" folder into two subfolders: "showcase" and "instructional." The current demos, which are more showcase-style, will move into the "showcase" folder, and these new instructional demos will go into the "instructional" folder.


3. Automatic insertion of the markup and code into the documentation pages

We obviously don't want to duplicate the markup and code that's in the "demos/instructional" folder by copying and pasting it into the documentation website. We want a component that can extract the relevant bits from the files in "demos/instructional" subfolders and inject them into the documentation pages.

The component will need to:
  - load the 'source' file
  - inject any required script tags into the header of the target page
  - inject any required CSS links into the header of the target page
  - inject the relevant HTML into the 'working' area of the target page
  - inject the relevant HTML, JS and CSS into the 'display' areas of the target page


Things to note, in no particular order:

- The display of HTML and JS in the documentation pages is stripped down to only the essentials, so the component will need to be able to detect which portion of the source HTML is the "relevant" part. If the source page contains only the one demo (see point to ponder A, below), this should be pretty straightforward.

- Some demos will have CSS, some will not.

- Some demos (i.e. FSS demos) will not have any JS.


Points to ponder:

A) There will be many, many of these little demos. Within the documentation, we should definitely have one demo per page, but within the codebase, I wonder if that might be excessive. It might make more sense to have one HTML file per component, say, with multiple demos within the file. The question arises: How would this affect the design of the script that will extract the demos?

A') Might we want to have multiple demos on a single documentation page? Different variations of customizing the same option? How would this affect the design of the script that will extract the demos?

B) The target pages will all have an extremely similar layout, which seems to cry out for a Renderer template.

-- 
Anastasia Cheetham     Inclusive Design Research Centre
acheetham at ocad.ca            Inclusive Design Institute
                                        OCAD University