Page tree
Skip to end of metadata
Go to start of metadata

The current structure of Lens does not accommodate extra themes. In order to integrate School of Managements (SoM) theme we need to update the structure of Lens.

Recommendations

  • Update Lens structure to facilitate file-type based theming and to be consistent with other repository structures
  • Version School of Management's theme, alongside Lens
  • Release the structural changes as Lens 105

Considerations

  • SoM's theme in relation to Lens, whether it uses a live copy, a snapshot or nothing
  • Whether SoM's theme should be versioned with Lens, if at all
  • How we handle other themes that could exist in the future

How are SoM and Lens connected?

SoM's theme currently uses a snapshot of Lens, but once integrated it will pull in the latest Lens partials to compiled into CSS - this is managed in the manifest file.

The current (development) link between the treatments is as follows:

What they do useWhat they don't use
universal/scss/components/colours
universal/scss/components/structure
universal/scss/components/typography
site/components/typography
site/components/links
site/components/global-structure
site/components/footer
site/components/header
site/components/lists
site/components/navigation
site/components/search
site/components/utility
site/components/cards
site/components/asides
site/components/articles
site/components/badges
site/components/buttons
site/components/cards
site/components/call-to-action
site/components/details
site/components/dividers
site/components/embedded
site/components/entry-reqs
site/components/figures
site/components/hero
site/components/icons
site/components/location
site/components/pagination
site/components/pinned-items
site/components/pop-ups
site/components/schema-data
site/components/search-filters

The way that the above partials are connected, mean that SoM is effectively a child theme of Lens and needs Lens to exist.

Versioning

As SoM and Lens are intrinsically connected, we should increment versions of Lens and SoM in tandem.

As both will be using the same version number and therefore the same variable, this will not affect the lens-config.json file.

Future-proofing

We need a solution that is easy to scale and add to so that we are future-proofed for other themes. This means having a plan or guide on how to add new themes to Lens.

Conclusion

There are two approaches to the structuring of Lens:

  1. Structure by organisational relationships
  2. Structure by theme

Structuring by organisational relationships would reduce the changes required to Lens to accommodate SoM. We would be able to add the new theme to our current structure and there would be less chance of breaking existing pages (although there is confusion around how themes relate to files in the /universal directory). However, the organisational structure of the university is irrelevant to developers and would require knowledge of the organisation to navigate - this would be particularly difficult for new starters or sharing our code-base with external parties. Sticking to the organisational structure would make it more complex to scale in the future, and would require some work deciding where the project sits in the organisation which could have political or managerial implications.

Structuring by theme would require initial changes to multiple repositories, however this would simplify scaling up (or adding new themes) in the future. Additions would be straight forward and require no extra decisions or politcal discussions. This is also the structure that we are using in other repositories affected by the SoM theming - an example of this is the erb_templates directory in cms-publisher where the files are separated by file-type and then by theme, it makes sense to maintain this consistency.

On this basis we have chosen to restructure by theme as proposed below:

Structural changes

Current structureProposed structure

lens/

bath/

apps/

components/

This directory contains files for generating course editor application styles

site/

components/

This directory contains scss files for the individual and common page components.

types/

This directory is empty and should be removed.

widgets/

This directory contains files for generating stand-alone widgets (i.e. the five star rating system).

universal/

images/

js/

scss/

components/

This directory contains scss files for variables and settings specific to the university-of-bath theme.

lens/

assets/

school-of-management/

fonts/

images/

js/

university-of-bath/

images/

js/

scss/

apps/

components/

This directory contains files for generating course editor application styles

school-of-management/

components/

This directory contains scss files for the individual and common page components.

settings/

This directory contains scss files for variables and settings specific to the school-of-management theme.


university-of-bath/

components/

This directory contains scss files for the individual and common page components.

settings/

This directory contains scss files for variables and settings specific to the university-of-bath theme.

widgets/

This directory contains files for generating stand-alone widgets (i.e. the five star rating system).


ProsCons

Logical - Everything is tidy and you know where to find specific filetypes

Scalable - Structures across themes are mirrored, and easily expandable

Reduces complexity and confusion

Work is required to change

  • Grunt (largely done)
  • Lens
  • Lens-design-system
  • CI pipelines - where to copy the Grunt generated files


Output URL structure

The current CSS output URL structure is as follows:

  • [Bath url]/lens/[version number]/css/bath/site/site.css

With the restructure of Lens, we needed to review the CSS output URL as it would change to include the theme name.

We took this opportunity to improve the URL to make it more more understandable:

This follows the structure:

[Bath URL]/lens/[version number]/[file type]/[theme name]/[theme name.css]

How to make these changes

  1. Make the changes to Lens
  2. Make URL changes to
    1. cms-publisher
    2. cms-site-templates
    3. CI pipelines
    4. Lens design system
  3. Increment Lens version
  4. Ship
    1. Lens
    2. Lens design system
    3. cms-site-templates
    4. cms-publisher

We have decided to increment the Lens version so that <104 versions are preserved, just in case we have users, that we are not aware of, using Lens as a CDN.


  • No labels