Style guide demo embeds

[triblondon]

We need to create a style guide that demos living styles, so that we're all on the same page. I've been thinking about this and have this proposal:

First, we have a demo page committed to each component's repo, which uses the build service to provide a standalone demo, and a new property in origamiconfig to point at it.

The registry can show the demo in an IFRAME, because it would be loadable from the build service proxy via a URL such as:

http://buildservice.ft.com/files/o-colors@1.0.3/demos/demo.html

The build service, when proxying a file requested at a specific version number, will also search the content of that file for further references to the file proxy for the same module (ie the pattern https?://buildservice.ft.com/files/o-colors[@/], and insert the same version number or error if (the wrong) one is already present. This will ensure that demos load their resources from the same version of the module that the demo was loaded from, without the need for the demo file to be changed on every release.

This gives us demos in the registry, but the design team are also looking for a way to provide more high level guidance (effectively a getting started guide) to provide to third parties and other newbies. To satisfy this, we could also have a bespoke 'style guide' site maintained by design in whatever form they want, that embeds the same demos as the registry. So then you can send the design.ft.com URL to third parties that need 'the big picture', and link to the registry for more technical info on each component. The embeds would be served by the registry in an iframe like this:

<iframe src='http://origamiregistry.svc.ft.com/components/o-colors@1.0.0/demo'></iframe>

This would render the demo along with a link to the appropriate page on the registry, and keep that link up to date.

That leaves the need for composite demos - demos that show multiple components being used together. I'm still somewhat unconvinced that we need many of these, but we can do it by saving demo pages directly into the style guide site, and loading them into the guide directly using IFRAMEs that don't go via the registry. The design team would need to ensure that those demos request versions of modules that are compatible with their demo markup, since the markup will not be versioned with the CSS.

To do this we need to:

1. Add new property demos in origamiconfig, array, with paths to demo page in repo
2. Create demo pages, which must use the build service to load the module, and use minimal markup to demo it.
3. Add support for the demos to registry
4. Modify build service proxy to version-sync subresource loads on proxied HTML pages
5. Add 'embeddable iframe' feature to registry that can be used by design team

[triblondon]

@wheresrhys, @dansearle-ft, @richard-still-ft, @danskinner, @pauloneillft - could you review and post your thoughts?

[dan-searle]

    First, we have a demo page committed to each component's repo, which uses the build service to provide a standalone demo, and a new property in origamiconfig to point at it.

I think I've misunderstood something, but if you're working on a new version of a module, and you're updating the demo page, how can you use the build service for that demo page - if you haven't yet committed & tagged your changes? You'd have to commit & tag without the demo, and then commit the demo after?

[triblondon]

Consider having the demo page built automatically, based on a standard and footer combined with a rendering of the module's main template with it's main data set.

[wheresrhys]

https://github.com/Financial-Times/grunt-origami-demoer pretty much does this already (though locally as opposed to using buildservice)

[manalishi79]

If I've understood everything correctly the demos will exist in isolation. We would need to combine "demos" together and put them in context on a real page. So the third party or uninitiated can get a presentation of what they'll eventually look like on an FT page.

How can I combine them? automated would be best

[triblondon]

@pauloneillft - composite demos would be part of your style guide. No way to automate these as we don't know how you'd want to combine them. You'll need to maintain some markup samples for composite demos in the style guide itself. If you want, I could set up a style guide jeykll site for you, based on the Origami spec one, to get you started.

[triblondon]

Regarding how demos are constructed, we can't use the same template as would be offered for production use of the module, since for demo purposes we'll probably want to display the module several times in different styles by using responsive classes. I'm returning to the view that we should have a static demo, and I think the compromise is to have an automation task to build the demo if you want to do that.

There is also scope for multiple possible demos per component, especially for complex components, like they do for jQuery UI (see the demos page for Droppable, for example). So I'd like to return to my original proposal for this, with the addition that you can generate the demo page if you want.

@wheresrhys, @kavanagh, @markstephens, @richard-still-ft could you approve this?

[markstephens]

Yep, good if it includes ability to generate the demo page.

[triblondon]

Added https://redmine.labs.ft.com/issues/20692 to get the demos embedded in the registry and to provide the demo endpoint.

[triblondon]

Added https://redmine.labs.ft.com/issues/20712 to get the build service to version-lock subresource loads in demo pages.

[triblondon]

After discussion with @pornel the build service requirement is dropped in favour of simply using relative links. The registry requirement stands, and is needed to allow the style guide to proceed.

[triblondon]

Implemented