Refactoring Engage's Screen Navigator

Clark, Colin cclark at
Wed May 11 14:25:03 UTC 2011

Hi Anastasia,

Comments inline...

On 2011-05-10, at 2:24 PM, Cheetham, Anastasia wrote:

> 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

The core of Screen Navigator is specifically designed for this use case. At the moment, it also includes navigational functionality more suited to a mobile app mixed in. I'll try to refactor it into a more convenient form soon.

In your mind, is this work a requisite for the 1.4 release?

> 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.

> 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?

It's worth thinking through the details of this one a bit more if you can. I imagine that we might also have some cases where multiple demos share the same same markup and the same component code.Often the difference between demos will actually just be configuration--a different block of JSON for each demo. There should be some nice ways to handle this situation. In other cases, we'll have customized markup for each demo which, as you say, will require different markup.

It seems to me that, either way, we'll want some declarative configuration that specifies each demo and the assets associated with it, including, if necessary, selectors into specific parts of shared markup. The biggest weakness of the current portal design is that all these details are hard-baked into code, making it very hard for us to accommodate different sorts of demos.

The easiest way to figure out what we really need is to have some real-world examples that embody the sorts of variations you point out. They will also help me test the Screen Navigator refactoring. Do you have any examples so far?


Colin Clark
Lead Software Architect,
Inclusive Design Research Centre, OCAD University

More information about the fluid-work mailing list