The theming process

Work in progress...

The process

Challenge: make theming WebGUI easy!

Once the template project is done, we will have:

  • A set of cleaned up templates
  • Styles for positioning, a stylesheet per asset / macro / operation (if positioning is necessary), living in the /extras folder.
  • There will also be stylesheets that do include colors, fonts etc. For instance for error messages (because building a theme is a lot of work already, without having to design every little thing).
  • Documentation on the templates and CSS.

Based on that, we will:

  • Turn the documentation into a searchable reference (“This template contains these classes, you can find the CSS here” etc.)
  • Make a styleguide / manual: how to build a WebGUI theme

At this point we have to think about the theming process and how it's going to work. I can think of two scenario's. These are based on three ideas:

  • The default stylesheets are in the /extras folder (this is wg-base.css, style.css and *.css for all assets)
  • We will create the wg-core bundle, which will be included in the style template via the FilePump macro as: 
    <html>
    <head>

    ..
    </head>
    <body>
    ..
    ^filePump(wg-core, js);
    </html>
  • We shouldn't make the theming process too difficult; instead both simple ("adding some colors") and advanced ("changing the whole layout of an asset") themes should be possible

Scenario 1: simple theming

For a simple theme, a designer makes 1 stylesheet. In that stylesheet they only add to the default CSS or overrides it by using stronger selectors.

Add the stylesheet to the head of the style template and leave the bundle of default stylesheets in there:

<html>
<head>

<link rel="stylesheet" type="text/css" href="zen.css" />
..
</head>

Using the file pump is optional in this scenario:

<html>
<head>


..
</head>

Scenario 2: advanced theming

For an advanced theme, a designer can (optionally) download a package with all the default stylesheets (from webgui.org, the style guide site/wiki page, whatever). This is a WebGUI package with all the stylesheets as snippets for easy editing. They can edit those stylesheets at will and add a main stylesheet of their own, if necessary.

The reason for making this package available is that the /extras folder is not very accessible for a designer with no access to the server. They would need to manually download each stylesheet and then manually add them as snippets to be able to edit.

The designer makes a theme and then adds all stylesheets (which are snippets) to a bundle. This bundle now contains:

  • a custom stylesheet or customized versions of the default stylesheets,
  • and: all the default stylesheets (in the extras folder) for the assets that have no custom styles.

Example bundle:

  • mytheme.css
  • custom-article.css (customized default stylesheet)
  • custom-gallery.css (customized default stylesheet)
  • thingy.css (default from /extras)
  • matrix.css (default from /extras)
  • ...etc.

Making this bundle can be automated to an extent, by building a WebGUI theme manager. This would require:

...

How does FilePump fit into all this?

In our current plan we will create the wg-core bundle, which will be included in the style template via the FilePump macro as:

<html>
<head>

..
</head>
<body>
..
^filePump(wg-core, js);
</html>

I suggest that a designer avoids touching this core bundle.

In Scenario One, they either add their css directly to the Style template:

<html>
<head>

<link rel="stylesheet" type="text/css" href="zen.css" />
..
</head>

Or they add it to the global head tags in Settings, or they add a new bundle of their own to the Style template:

<html>
<head>


..
</head>

In the extreme case they could leave out wg-core altogether, but I think the idea that JT prefers is that the core css is left untouched since base functionality will depend on it.

The "zen" bundle above contains new styles and rules that override the core rules (plus javascript and images and any other bundle collateral, e.g. flash, xml, ..).

So in terms of a skin, you have the modified Style template, plus the FilePump bundle and its collateral, plus other related meta-data such as global head tags. The Theme doesn't need to include the core bundle, since we expect every site to have that in its untouched form.

All of this would work regardless of whether the per-asset css files were snippets or physical files in /extras, as FilePump supports both (see the FilePump core asset dynamic bundle RFE for more discussion of this).

Scenario Two is identical to this, except that he introduces the concept of a downloadable package that is used as the basis for creating a new theme. I think we can avoid this step by building a Theme Manager into WebGUI.. for example imagine that you click "Export My Site As A Theme" and are then prompted for which FilePump bundles, Style Templates and other templates you want to include in your theme. The Theme Manager then bundles up all the information that you chose to include into a theme package which can be imported into another site, shared, etc.. The Theme Manager could also maintain a list of Themes that have been imported, and allow you to activate them (all it really needs to do is update what templates are being used across the site).

About this project

Once the templates are (largely) done and the structural stylesheets are in the /extras folder, designers can start theming WebGUI. What should this process look like? What should we provide designers with (style-guide/manual, downloadable empty theme.css file etc.)?

To do:

First we need to work out what the stylesheets are going to be like: where will they live (import or extras), will they contain basic element selectors (h1, h2, p etc.) and so on.

Then we take a look at FilePump and figure out how we can use it to keep the theming process easy, and our sites fast. Ideally there would be a theming mechanism (theming console/theme manager) in WebGUI.

The goal is to figure out what we need to provide a designer with, to make theming WebGUI as easy and intuitive as possible.

This is Rogier's and Patrick's project.