Theme packaging
Overriding the default templates and static files with user defined themes
Yoda allows for developers to add themes to the default (Utrecht University) theme. Thus adding the possibility for developers to tweak a Yoda instance to their own look and feel.
Adding themes can be accomplished by overriding the default templates and static files that are supplied within the default (Utrecht University) Yoda.
Overriding can be done on two levels:
1) Template (HTML) overriding
2) Static (css/img/js) overriding
Templates in Yoda
In the default setup, based on a modularly constructed flask environment, the required html templates are organized as follows:
/var/www/yoda
/general/templates/general/*.html
/module_name/templates/module_name/*.html
in which the general directory holds all basic html files, for instance the foundation of the application, in which the modules can reside.
Overriding templates (HTML)
flask.cfg holds the yoda theme (filled by ansible but can be manually overridden):
e.g.
YODA_THEME = ‘vu’
YODA_THEME_PATH = ‘/var/www/yoda/themes’
When building a webpage yoda software first looks into the yoda/themes/vu directory whether a requested template is placed at that location.
If so, this will be used (thus overriding the default supplied template).
If not, the software will use the default template as supplied in the default (Utrecht University) situation.
The structure under yoda/themes/vu must be the same as the default structure as well as the template names must be the same.
E.g.:
/var/yoda/themes
/uu1
/general/base.html
/research/browse.html
…
/uu2
/research/revision.html
/vault/browse.html
…
In the above example following default HTML files will be overridden when uu1 or uu2 is selected as a theme:
For uu1:
/var/www/yoda/general/templates/general/base.html
/var/www/yoda/research/templates/research/browse.html
For uu2:
/var/www/yoda/research/templates/research/revision.html
/var/www/yoda/vault/templates/vault/browse.html
Override static files (js, img, css)
To change the appearance or user experience on the frontend it is necessary to be able to override static files as supplied with yoda.
This is only possible when the blueprint files are equipped with a different static_url_path
stats_bp = Blueprint(‘stats_bp’, __name__,
template_folder=’templates’,
static_folder=’static/stats’,
static_url_path=’/assets’)
On application level, in app.py, the static folder is set to ‘assets’ as well:
app = Flask(__name__, static_folder=’assets’)
When the frontend requests for url’s holding the keyword ‘assets’ it will check whether the set theme holds the requested static file according to following structure:
/var/yoda/themes
/uu1
/static/css
/js/…
/research/static
/css/..
/js/..
/vault/static/img/…
/uu2
/static/css/
/research/static/js/
If the requested file is not found, the default (Utrecht University) static file will be used.
General level url request:
requested url = /assets/css/yoda-portal.css
When present, /yoda/themes/uu1/static/css/yoda-portal.css is returned.
If not present fall back to default, /yoda/static/css/yoda-portal.css is returned
Modular level url request:
requested url = /research/assets/css/research.css
When present, /yoda/themes/uu1/research/static/css/yoda-portal.css is returned.
If not present fall back to default
/yoda/research/static/research/css/yoda-portal.css is returned
Resulting theme package structure
Putting templates and css together results in following theme package structure
/uu1
/static/css/…
/research
/template.html
/static/css/…
/js/…
/img/…
…
/uu2
/static/css/…
/research
/template.html
/static/css/…
/js/…
/img/…
…
/vu
/static/css/…
/research
/template.html
/static/css/…
/js/…
/img/…
…
Compiling theme CSS
Building theme CSS:
sudo su yodadeployment
cd /var/www/yoda/static/src/
# Install npm
nvm install v18
# Install sass compiler
npm install
npm install -g sass
# Build (default) UU theme
sass --style compressed build_uu.scss ../../static/css/yoda-portal.css
# Build (custom) VU theme
sass --style compressed build_vu.scss ../../themes/vu/static/css/yoda-portal.css
Select2 theming in the group manager
To match the select2 fields in the group-manager with the colors of the main theme, the select2 theme must be compiled.
Assuming that the steps to compile the main theme CSS for all of Yoda have already been followed, the following can be run to compile the select2 bootstrap theme, for example for the (default) uu theme:
sudo su yodadeployment
cd /var/www/yoda/static/src/select2-bootstrap-5-theme/src
sass --style compressed select2-theme-uu.scss ../../../../group_manager/static/group_manager/lib/select2-bootstrap-5-theme/select2-bootstrap-5-theme.css
For other themes the css is similarly an override of the default select2 uu theme. For the vu theme:
sass --style compressed select2-theme-vu.scss ../../../../themes/vu/group_manager/static/group_manager/lib/select2-bootstrap-5-theme/select2-bootstrap-5-theme.css
To create another select2 theme first copy the select2-theme-uu.scss file, and then change “uu” to the name of your theme in this line:
@import "../../uu/variables";
The theming is based on this select2 bootstrap 5 theme fork.
Theme change via Admin GUI
From version 1.10 onward, Yoda supports changing themes through the Admin GUI. This feature is accessible to administrators and members of the priv-admin group. To make themes available, add their packages (including templates and static files) to /var/www/yoda/themes, where the Admin GUI recognizes available themes by reading the folder names—as Flask scans this directory for themes. Once you select a new theme, it updates the theme configuration in /var/www/yoda/config/admin_settings.json under the YODA_THEME key (e.g., “YODA_THEME”: “uu”).
DavRODS theming
DavRODS uses different theming logic than the portal. By default, it uses the themed logo of the portal.
The logo is linked to the UU website. Use the yoda_davrods_logo_path and yoda_davrods_logo_link
parameters to change this behaviour.
For more advanced changes, it will be necessary to customize the DavRODS layout templates.