Themes in Allura Log in to Edit

Themes in Allura


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 for that package:

    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:

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

Based on that layout, your register_ew_resources would look like:

    def register_ew_resources(cls, manager, name):
            'theme/%s' % name,
                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


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.

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


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': {
    'Blog': {


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'

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.