Challenges with comprehensive theming in Eucalyptus

Table of Contents

Background

This document captures reported challenges with using comprehensive theming in the Eucalyptus release, along with some initial recommendations as to how matters might be improved.

Use Cases

Use case 1: Changing fonts

Quote from Florian Haas (Unlicensed):

How do we change the default sans-serif font from the default `"Open Sans" ,Verdana,Geneva,sans-serif`? ... My goal is being able to select my preferred sans-serif font myself, rather than being locked into Open Sans. That, quite frankly, seemed like a trivial goal but it now seems like a Herculean task. I'm still hoping that the actual difficulty is somewhere *between* trivial and Herculean. 

Use case 2: Managing the color palette

Quote from J'aime Ohm:

I’m theming an iOS application based on a themed web application and our front-end web developer is out today. I’m interested in quickly gleaning the color palette and fonts used in this application. Can someone tell me if there is a central/primary “colors” or “fonts” or similar file in edx-platform?

Use case 3: Overriding JavaScript templates

Quote from jjmirandad:

Talking about frustration. Its possible to use .underscore templates in theme folder??? How its this possible, because in all my test this files its loading from lms/templates!

Quotes from MIke Bifulco:

the underscore template thing really is a surprise.  That means that several pages on thegymnasium.com will have a significant regression in theme functionality when we move from Birch→Dogwood/Eucalyptus

and:

I'm surprised [logistration] made it through to production without considering theming

Use Case 4: Theming the wiki

It has been reported that comprehensive theming does not work for the wiki. This appears to be because the wiki uses Django Templates, while comprehensive theming works with Mako.

CRI-53 - Getting issue details... STATUS

Challenges

Mako templating is badly implemented

• themes don't gracefully inherit from main platform because of a recursive bug (possible fix: https://github.com/Stanford-Online/edx-platform/pull/535/files)
• difficult to arbitrarily inject html from a theme

edX platform Sass is poorly structured

• The current platform Sass has a lot of duplication of fonts and colors making it very difficult to change every usage
• There is a whole host of color variables in the SASS (probably too many), but the lms SASS doesn't use them consistently
• When new features are added, they add yet more duplication, and so the themes become broken
• The Pattern Library has variables for the fonts that can be overridden once, but very few pages are using it so far

Pages are a mixture of pattern library and non-pattern library

• The pattern library was intended to simplify the process of theming
• Unfortunately the current partial migration means that the old styles must be themed and then the Pattern Library must be themed too
• The v1 and v2 naming convention is not clearly explained for scss files

The pattern library is inconsistent about how theming is supported

• Recent changes to the color palette broke the ability to provide a single base theme color
• The pattern library is itself not consistent about using variables to allow for simple overriding
• The pattern library does not have an example theme that demonstrates that all the patterns can be themed
• There is an epic to resolve these issues:
  • FEDX-235 - Getting issue details... STATUS

JavaScript templates cannot be overridden using comprehensive theming

• Comprehensive theming works with the Django Pipeline to override Mako templates
• Underscore files are bundled into JavaScript files and so are not affected by the pipeline

It isn't clear how to ensure that themes work with both LTR and RTL files

• Some advice has folks overriding lms-main-v1.scss but that won't affect the RTL version

Platform is not responsive

• some people may want to do it through theming, but it's not powerful enough to do so

Compiling assets with multiple themes is very slow

• Currently 19 minutes of an edxapp production build is spent gathering assets for themes
• 9 minutes of sandbox builds (possibly more, measurement is less precise here) is spent on this (fewer themes)
• This impacts developer velocity

paver update_assets lms --themes=example

Theme integration into the build process is opaque

• The intersection of edx-microsites.git and edx-themes.git in the build process is very unclear

Recommendations

• Update the example theme to demonstrate all the use cases

  • This example theme should work for pattern library pages as well as for legacy pages
  • The process of implementing some of these (e.g. changing the font family) will expose the issues

• Make extensive use of variables in Sass, rather than hard-coding colors, fonts etc into every file

  • This means that the variable can be overridden once, rather than having to override every file. 

  • These variables would themselves be documented so that their purpose is clear for theme authors

• Update the pattern library documentation to include an example theme
• Address any issues with theming the pattern library

• Convert major pre-existing pages to the pattern library

• Use the pattern library for all new front end features

• Determine an approach for overriding JavaScript templates

  • A long term solution is to use HTTP/2 and then stop bundling JavaScript files

  • Maybe there could be a way to build theme versions of each JavaScript bundle (or at least those that have overridden templates)
• Make an OEP that describes how to create themable front end interfaces
• The default theme should be the only theme within edx-platform.  EdX should dogfood theming by applying edx.org's themes through the same mechanisms as the rest of the community.