Themes in Allura

There is a newer version of this page. You can find it here.

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.

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'

The following macros are available:

This HTML appears immediately after the body tag. You will probably want to put a header here. The parameters should look like {%- macro header(login_url, logout_url, show_search_box=True, extra_html='') %}.

This HTML appears immediately before the close body tag. The parameters should look like {%- macro footer(year, path_to_static='') %}.

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.