Theme System for Helix Pages

[trieloff]

@ramboz's presentation at the AES Hackathon made me think about adding a theme system to Helix Pages.

Background

Theming systems should not just allow to create static file overlays as we have in Helix Pages right now, but they should be able to change the fundamental structure of the generated HTML to reflect different needs and usage patterns of sites.

While it is possible to build a blog using Helix Pages right now (see theblog), it requires larger amounts of client-side scripting that are non ideal. With a proper theming system, a user can select what kind of site they are building (collection of micro sites, blog post, documentation site, etc) and the HTML will follow the best practices.

It also allows us to establish a developer ecosystem of developers who are creating their own themes as forks of Helix Pages, deployed to Adobe I/O Runtime, that can be swapped in dynamically, without any coding or deployment required from the author.

Requirements

• users should be able to preview a theme before applying it
• users should be able to select a theme by placing a THEME file into their repository. The THEME file will point to the theme URL

Theme Rendering Implementation

• Theme preference can be indicated through a X-Theme cookie. The VCL will use the X-Theme cookie value to resolve the correct action to execute.
• If no X-Theme cookie has been set, the helix-theme web action will be called. This action reads the THEME file and returns the value in the X-Theme header. The response will be cached for a reasonable amount of time (1 hour to start).

Theme Selection UI

• web based
• requires GH authentication and selection of repository
• theme URL is provided as a URL parameter (enabling "preview in Helix" links on the theme home page)
• UI drops the correct Cookie and loads the preview in an IFrame
• On save, the THEME file will be written and the theme cache will be cleared

[kptdobe]

While I like the general idea, there are 2 fundamental things we need to explore first to achieve this:

1. "page template": for now, we extensively used selectors to distinguish between different page templates (i.e. homepage has one rendering, other pages have another rendering): the main html_pre.js and html.htl are used to dispatch on the correct selector via an ESI include. We all agree this is not the good solution but we do not have something better yet. This would be needed for themes
2. "where is the code": in local dev, the "code repo" config from the strain does not allow to test "remote" code, while this is somehow what happens (via Runtime actions) in production. It is even conflicting and confusing when you start using branches (you need to checkout the branch or not depending on what you do). From there, another step needs to be taken for Themes: we need to "merge" multiple code repos. I expect helix-pages to provide a theme basis but I can build my own theme on top, depend on helix-pages code and simply override a piece (one of the "page template").

[trieloff]

1. We would still use selectors for page templates, but a theme is a complete collection of page templates, basically a code repository with HTL, pre.js and the like. It can (but most often won't) have selectors.
2. I wouldn't want to have any merging for themes. We simply pick the correct action URL – not based on the strain config, but based on the X-Theme cookie or header. Any static file that a theme would need to deliver must be in the theme's repository. I think any kind of inheritance or merging mechanism would make things too complicated.

[davidnuescheler]

i would like to be very careful here that we are sure what we mean by themes and how far we want this to go. i think manipulating the markup in helix pages may be an enabler for themes but is somewhat unrelated and to be perfectly honest, i am not sure that i would support the idea of general purpose our of the box (helix pages branded) theming that requires markup manipulation.

considering that for any theme good general purpose design is crucial, i think in a first step i would like to replicate all the spark page themes as a starting point, and i would be very surprised if that would require manipulations of the markup.

even beyond that, i would then like to explore the spark brand system to get the general purpose theme customization to the next level.

https://theblog.adobe.com/creating-your-brand-in-adobe-spark/

i definitely appreciate the value of markup customization and agree with it as reported in https://github.com/adobe/helix-pipeline/issues/516 but i am not sure that we should produce themes that are not generally applicable under the helix pages umbrella and if they are generally applicable within the context of helix pages then they should style the default markup. maybe i am being nit-picky here...

[ramboz]

Maybe to give a bit more background on my initial idea here, since I'm not sure I got it covered during the hackathon demo, I'm really looking at this from the agency's point of view that will be developing the themes for helix, and how much knowledge expertise would be required for each kind of theme "levels".

Theming Level	Description	Expertise required	Target Audience
White labeling	Simple CSS/logo/icons/fonts adjustments on top of a provided Helix Pages template Extension points: styles.css static resources for icons/fonts frontmatter props to add CSS classes	CSS YAML	Consumer
Customize layout (SEO/A11y)	Capability to override part of the markup to inject domain-specific semantics on top of the provided Helix Pages template, i.e. create a carousel from a list of images, inject microdata, add WAI tags, etc. Maybe some basic scripting to initialize/configure vendor libs Extension points: all previous frontmatter props to change tags and configure "modules" scripts.js HTL templates	CSS YAML HTML WCAG microdata basic JS	SMB
Full theming	Fully control 100% of the output markup, including different layouts for different page types (blog, gallery, etc.) Extension points: all previous pre.js Helix Hooks	CSS YAML HTML WCAG microdata JS Helix Hooks	Enterprise

Then for each target audience, I guess the expectations on how to use the themes may be a bit different:

• Consumer: just select a theme from a list and have instant previews before I validate the change
• SME/Enterprise: it's ok to also require some more changes to the config/content (frontmatter props), and I may need to have current and "preview" themes in parallel so I can gradually change my content as needed and get validation before going live… basically need a stage step before I apply the theme

[anfibiacreativa]

Hi David, I already did replicate a spark theme together with Conrad, for the Basel hackathon in September 2018, and we definitely needed to do markup manipulation. Even when it's true that the CLI was different at that time and the output too, I do believe you always need a certain level of manipulation to achieve a theme.

Having said that a certain theming could be achieved with a single wrapping class, much like the one you can add with the style system when used at a template level. Using that pattern, you wouldn't need to manipulate the markup at all.