Recent changes to Themes in Allura

Themes in Allura modified by Dave Brondsema

Dave Brondsema — Thu, 11 Dec 2014 20:35:40 -0000

--- v3
+++ v4
@@ -54,12 +54,22 @@
 ~~~~

 ## 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.
+
+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)
+~~~~
+
+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:
+
+~~~~
+::python
+    def href(self, href):
+        # use URL paths to the 'allura' theme
+        return super(AlluraSiteTheme, self).href(href, theme_name='allura') 
 ~~~~

 ## Icons
@@ -95,11 +105,10 @@

 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\]](https://forge-allura.apache.org/docs/api/lib/package_path_loader.html) 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>`.

-Overriding arbitrary template files is possible with an [\[allura.theme.override\]](https://forge-allura.apache.org/docs/api/lib/package_path_loader.html) 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.

Themes in Allura modified by Dave Brondsema

Dave Brondsema — Thu, 11 Dec 2014 20:32:03 -0000

--- v2
+++ v3
@@ -4,6 +4,8 @@

 ## 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](https://forge-allura.apache.org/docs/api/lib/plugin.html#allura.lib.plugin.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](https://forge-allura.apache.org/p/allura/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](https://forge-allura.apache.org/docs/api/lib/plugin.html#allura.lib.plugin.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:
@@ -89,18 +91,15 @@
         jinja_macros = 'mytheme:templates/mytheme/macro.html'
 ~~~~

-The following macros are available:
+A number of macros are available.  You should look at Allura's [theme_macros.html](https://forge-allura.apache.org/p/allura/git/ci/master/tree/Allura/allura/templates/jinja_master/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`.

-### Header
+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.

-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='') %}`.
-
-### Footer
-
-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>`.

+Overriding arbitrary template files is possible with an [\[allura.theme.override\]](https://forge-allura.apache.org/docs/api/lib/package_path_loader.html) 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.

Themes in Allura modified by Dave Brondsema

Dave Brondsema — Mon, 08 Dec 2014 23:06:23 -0000

--- v1
+++ v2
@@ -3,12 +3,13 @@
 # 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.
+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](https://forge-allura.apache.org/docs/api/lib/plugin.html#allura.lib.plugin.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:
+To set up a new theme, create a package for the theme with an entry point that goes to the [ThemeProvider](https://forge-allura.apache.org/docs/api/lib/plugin.html#allura.lib.plugin.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
 ~~~~
@@ -33,6 +34,7 @@
 Based on that layout, your register_ew_resources would look like:

 ~~~~
+::python
     @classmethod
     def register_ew_resources(cls, manager, name):
         manager.register_directory(
@@ -45,6 +47,7 @@
 Once you have customized your new ThemeProvider, tell your Allura instance to use the new theme by modifying your .ini file:

 ~~~~
+::ini
     theme = mytheme
 ~~~~

@@ -52,6 +55,7 @@
 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)
 ~~~~
@@ -60,6 +64,7 @@
 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',
@@ -79,6 +84,7 @@
 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'
 ~~~~

Themes in Allura modified by Dave Brondsema

Dave Brondsema — Fri, 13 Sep 2013 15:45:27 -0000

Themes in Allura

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:

    [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

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)

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'

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.