Redmine

h1. HowTo create a custom Redmine theme

Redmine offers basic support for themes. Themes can override stylesheets (application.css) and add some custom javascript.

h2. Creating a new theme

Create a directory in @public/themes@. The directory name will be used as the theme name.

Example:

  public/themes/my_theme

Create your custom @application.css@ and save it in a subdirectory named @stylesheets@:

  public/themes/my_theme/stylesheets/application.css

Here is an example of a custom stylesheet that only override a few settings:

<pre><code class="css">

/* load the default Redmine stylesheet */

@import url(../../../stylesheets/application.css);

/* add a logo in the header */

#header {

    background: #507AAA url(../images/logo.png) no-repeat 2px;

    padding-left: 86px;

}

/* move the project menu to the right */

#main-menu { 

    left: auto;

    right: 0px;

}

</code></pre>

This example assume you have an image located at @my_theme/images/logo.png@.

You can download this sample theme as a starting point for your own theme. Extract it in the @public/themes@ directory.

*NOTE*: If you have enabled caching per [[BrowserCaching]], make sure you append a ?version to the include and update it whenever you update redmine to avoid your user's browsers grabbing the old application.css file whenever you upgrade redmine.  @@import url(../../../stylesheets/application.css?4.3.2);@

h2. Adding custom javascript

Simply put your javascript in @javascripts/theme.js@ and it will automatically be loaded on each page  (Redmine >= 1.1.0 only).

h2. Setting a Favicon

Put your favicon in @favicon@ directory and it will automatically be loaded instead of default one on each page. The name of the favicon file can be anything.

h2. Applying the theme

Go to "Administration -> Settings" and select your newly created theme in the "Theme" drop-down list. Save your settings.

Redmine should now be displayed using your custom theme.

If you are using Redmine < 1.1.0, you may need to restart the application so that it shows up in the list of available themes.

h2. Directory structure of themes

A theme consists of the following files:

* @favicon/<favicon file>@ (optional): favicon for the theme

* @javascripts/theme.js@ (optional): custom JavaScript for the theme

* @stylesheets/application.css@ (required): CSS for the theme

<pre>

public/

  +- themes/

       +- <theme name>/

            |

            +- favicon/

            |    +- <favicon file> (e.g. favicon.ico, favicon.png)

            |

            +- javascripts/

            |    +- theme.js

            |

            +- stylesheets/

                 +- application.css

</pre>