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-portal/static/src/

# Install npm
nvm install v16

# 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

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.