Organizational Theming
Why is Theming Necessary?
Elentra JS 2.0 provides a comprehensive Style Library of variables that are designed to provide the building blocks for creating components, modules, and experiences visually in Elentra. However, organizational overrides are often a necessity for various institutions, especially in cases pertaining to branding colors. In Elentra JS 2.0, we have a new, robust way of handling these overrides.
How it Works
Defining Your Theme
Elentra ME 1.16.0 now includes a migration that will add a theme field to your elentra_auth database's organisations table. Your institution should add an applicable kebab-case value for each organisation's database record, that includes your institution's prefix followed by a unique code for that specific organization.
Take for example, a fictional university titled "Mythical University" that has two organizations, "ABC" and "XYZ". Mythical University would have two records in the organisations table, and they would need to update the theme field for both these records, entering mythu-abc for one and mythu-xyz for the other.
ejs-overrides.css
After updating your organizations' table records to include a value for the theme field, your next step is to add a new stylesheet to the www-root/templates/default/css directory,ejs-overrides.css.
This stylesheet will be automatically loaded by Elentra ME, and its purpose is to override the default values set for the variables defined in the Elentra JS Design System. As an example, let's look at one of the Style Library's variable partials, _border.scss.
We can see that the default border radius variable (--ejs-border-radius---d) is mapped to --ejs-border-radius--unit, which is mapped to a calculation that results in a value of 6px.
Following that default variable, we can also see that --ejs-border-radius--sm and --ejs-border-radius--lg are calculated by halving and doubling that default value, respectively.
So let's say that our fictional institution, Mythical University requires the default border radius value to be 5px, and the smaller and larger to be 3px and 7px, respectively - but only for the organization "XYZ", which as we recall has a theme code of mythu-xyz in the database.
What Mythical University needs to do is open up ejs-overrides.scss and add the following:
When the organization "XYZ" is loaded on the page, the <body> element on the page will have a class added of.theme-mythu-xyz, which is whatever the value of theme is in the organisations record for that organisation, prefixed with .theme-.
The values set here will override the Elentra JS Design System's default values, and these values will cascade down, to everywhere those variables are used in components and modules.
If Mythical University had different rules that were needed that were exclusive to their "ABC" organization, they would simply add another rule to the bottom of ejs-overrides.css for .theme-mythu-abc {}.
Last updated