Themes in Allura

Overview

Allura instances may be have a custom theme applied by including replacement css, html, icons, and other resources as needed. To manage themes, Allura has a ThemeProvider class that can be extended. This document explains what functionality can be extended through the ThemeProvider as well as some usage examples.

An example may be seen in the "AlluraSite" repo which has a custom theme to add a copyright line to the footer of Allura's own website.

Creating and using a new theme

To set up a new theme, create a package for the theme with an entry point that goes to the ThemeProvider defined for your custom theme. For instance, if you have a new theme called "mytheme", you would create an entry point like this in the setup.py for that package:

::ini
    [allura.theme]
    mytheme = mytheme:ThemeProvider

Before you can follow any of the steps below to customize the theme, you need to specify the directory where your custom files are stored. Do this by creating a "register_ew_resources" method in your ThemeProvider. This is an example directory layout for mytheme:

    module_root
    - setup.py
    - mytheme
    -- mytheme_main.py (ThemeProvider goes in here)
    -- nf
    --- mytheme
    ---- css
    ---- images
    ---- js
    -- templates
    --- mytheme
    ---- macro.html

Based on that layout, your register_ew_resources would look like:

::python
    @classmethod
    def register_ew_resources(cls, manager, name):
        manager.register_directory(
            'theme/%s' % name,
            pkg_resources.resource_filename(
                'mytheme',
                os.path.join('nf', name)))

Once you have customized your new ThemeProvider, tell your Allura instance to use the new theme by modifying your .ini file:

::ini
    theme = mytheme

CSS

Any custom CSS should be created in the registered resources path for the theme. In the mytheme example we've been working with, that would be mytheme/nf/mytheme/css/ Once you've created your custom css files, you can include them by registering them in the ThemeProvider's "require" method.

::python
    def require(self):
        g.register_theme_css('css/mycustom.css', compress=False)

Icons

The icons used by Allura to represent each tool may be customized. To do so, modify the icons dict in your ThemeProvider. Be sure to provide an option for each size as they are all used through the application.

::python
icons = {
    'admin': {
        24:'images/mytheme/24x24/admin_24.png',
        32:'images/mytheme/32x32/admin_32.png',
        48:'images/mytheme/48x48/admin_48.png'
    },
    'Blog': {
        24:'images/mytheme/24x24/blog_24.png',
        32:'images/mytheme/32x32/blog_32.png',
        48:'images/mytheme/48x48/blog_48.png'
    },
    etc...
}

HTML

You can customize selected parts of the template HTML through jinja macros. To set this up, tell your ThemeProvider where the macros are located:

::python
    class ThemeProvider(plugin.ThemeProvider):
        jinja_macros = 'mytheme:templates/mytheme/macro.html'

A number of macros are available. You should look at Allura's theme_macros.html to see a full list of what they are, and what the default HTML content for each is. Common macros to override are header and footer.

Your theme's macros.html should have a line {% extends 'allura:templates/jinja_master/theme_macros.html' %} and then define the macros that you want to override.

JavaScript, images, and other file includes

Files in the registered resource directory may be used in your HTML macros like <script src="{{path_to_static}}js/mytheme/myscript.js"></script> or elsewhere like <script src="{{g.theme_href('js/mytheme/myscript.js')}}"></script>.

Overriding arbitrary template files is possible with an [allura.theme.override] configuration.

Ideas for future improvement

At SourceForge, we have a custom Allura theme that uses SASS to manage the css. It would be great to start using SASS in Allura to make it easier for others to retheme.