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:

    [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:

    @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:

    theme = mytheme

CSS

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.

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

Alternatively, your theme can re-use all the CSS from a "parent" theme (e.g. if you are using the default allura theme, but overriding the header macro HTML only). To do that, you don't need any require method. Instead define an href method in your ThemeProvider like this:

    def href(self, href):
        # use URL paths to the 'allura' theme
        return super(AlluraSiteTheme, self).href(href, theme_name='allura') 

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.

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:

    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.

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

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>.

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.