RDMO is based on Django, which allows a high level of customization by modifying the Django templates as well as the static assets (CSS files, images, etc.). There is a powerful method by which the set of files getting imported can be changed. If you create a
rdmo_theme app in your
rdmo-app directory the framework will use the files in this folder and not their counterparts from the RDMO source code. By doing this you can override any template or static file you desire as long as you get the folder structure right. There are two ways to create a theme. We use
rdmo_theme as name here, but you can use a different one.
In older versions of RDMO, did not use a Django app to create a theme, but simple directories
theme/templates and some additional configuration in
config/settings/__init__.py. While this approach will continue to work and can be kept for existing instance, we encourage the use of Django apps for new themes.
There is a
manage.py script to simplify the theme creation. The script will create the
rdmo_theme/templates folders as well as the
rdmo_theme/__init__.py file which makes it a Python module. It also copies a basic set of files into them and adds the necessary configuration line to
config/settings/local.py to enable the theme. To run the script do:
python manage.py make_theme python manage.py make_theme --name=rdmo_cool # for a cool theme name
If you want to override other files, you can use, e.g.:
python manage.py make_theme --file accounts/templates/account/terms_of_use_en.html python manage.py make_theme --file accounts/templates/account/terms_of_use_de.html # use the same --name as before python manage.py make_theme --name=rdmo_cool --file=...
If you want to manually create a theme you need to do the following:
rdmo_themefolder containing a
templatesdirectory inside your
mkdir -p rdmo_theme/static rdmo_theme/templates touch rdmo_theme/__init__.py
Add the line below to your
import os from . import INSTALLED_APPS INSTALLED_APPS = ['rdmo_theme'] + INSTALLED_APPS
Copy the files you want to modify into the
rdmo_themefolder keeping their relative paths.
Working with themes¶
If you have completed the steps above templates and static files in the
rdmo_theme directory are used instead of the original files as long as they have the same relative path, e.g. the template
rdmo/core/templates/core/base_navigation.html from the original code.
Usually, the RDMO template files are located in your virtual environment, e.g.
/srv/rdmo/rdmo-app/env/lib/python3.6/site-packages/rdmo/core/static/core/css/variables.scss. The exact path depends on your Python version and platform. The
make_theme script will find the files for you. You can also download the original files from the rdmo repository instead. For the example above, this would be https://raw.githubusercontent.com/rdmorganiser/rdmo/master/rdmo/core/static/core/css/variables.scss. Please make sure to use the raw files when downloading from GitHub. If you accidentally grab the website’s html source code RDMO will throw an error.
Some files you might want to override are:
https://github.com/rdmorganiser/rdmo/blob/master/rdmo/core/static/core/css/variables.scss can be copied to
rdmo_theme/static/core/css/variables.scss and be used to customize colors.
Home page text¶
https://github.com/rdmorganiser/rdmo/blob/master/rdmo/core/templates/core/home_text_en.html and https://github.com/rdmorganiser/rdmo/blob/master/rdmo/core/templates/core/home_text_de.html can be copied to
rdmo_theme/templates/core/home_text_de.html and be used to customize text on the home page.
rdmo_theme/templates/account/terms_of_use_en.html. Set the variable
True in your
Note that updates to the RDMO package might render your theme incompatible to the RDMO code and cause errors. In this case the files in
theme need to be adjusted to match their RDMO counterparts in functionality.
The emails, which are send to the users can be customized as well. Of particular interest is the template for mails inviting users to projects located at https://github.com/rdmorganiser/rdmo/blob/master/rdmo/projects/templates/projects/email. The templates can be copied to
rdmo_theme/templates/projects/email/project_invite_message.txt and edited accordingly.
Custom .po file translations inside a theme¶
As described in the Introduction above RDMO themes are now supposed to be Django apps. Using this kind of themes brings another advantage regarding translations. It is possible to create custom .po files holding translations that then can be used along with the translations inside the RDMO core. Here are the steps to make this happen.
Create a theme if you do not have one already
python manage.py make_theme
Make sure you have a folder structure equivalent to the one below. Especially regarding the location of the .po files.
rdmo_theme/ ├── __init__.py ├── locale │ ├── de │ | └── LC_MESSAGES │ | ├── django.mo │ | └── django.po │ └── fr │ └── LC_MESSAGES │ ├── django.mo │ └── django.po ├── static │ └── core └── templates └── core └── your_template.html
Define a locale path inside your
local.pyto point the Django tools to the location of the po files
LOCALE_PATHS = [ '/home/rdmo/rdmo-app/rdmo_theme/locale' ]
Use po edit or another tool of your choice to edit the po files inside the locale folder
Finally make the messages and your translations should be displayed in RDMO. Note that the command has to be run inside the theme’s folder.
cd rdmo_theme django-admin makemessages -l de