HowTo create a custom Redmine theme » History » Version 10

Go MAEDA, 2018-01-08 00:38
Added directory structure

1 1 Jean-Philippe Lang
h1. HowTo create a custom Redmine theme
2 1 Jean-Philippe Lang
3 5 Jean-Philippe Lang
Redmine offers basic support for themes. Themes can override stylesheets (application.css) and add some custom javascript.
4 1 Jean-Philippe Lang
5 1 Jean-Philippe Lang
h2. Creating a new theme
6 1 Jean-Philippe Lang
7 4 Jean-Philippe Lang
Create a directory in @public/themes@. The directory name will be used as the theme name.
8 1 Jean-Philippe Lang
9 1 Jean-Philippe Lang
Example:
10 1 Jean-Philippe Lang
11 1 Jean-Philippe Lang
  public/themes/my_theme
12 1 Jean-Philippe Lang
13 4 Jean-Philippe Lang
Create your custom @application.css@ and save it in a subdirectory named @stylesheets@:
14 1 Jean-Philippe Lang
15 1 Jean-Philippe Lang
  public/themes/my_theme/stylesheets/application.css
16 1 Jean-Philippe Lang
17 2 Jean-Philippe Lang
Here is an example of a custom stylesheet that only override a few settings:
18 1 Jean-Philippe Lang
19 2 Jean-Philippe Lang
<pre><code>/* load the default Redmine stylesheet */
20 2 Jean-Philippe Lang
@import url(../../../stylesheets/application.css);
21 1 Jean-Philippe Lang
22 2 Jean-Philippe Lang
/* add a logo in the header */
23 2 Jean-Philippe Lang
#header {
24 2 Jean-Philippe Lang
    background: #507AAA url(../images/logo.png) no-repeat 2px;
25 2 Jean-Philippe Lang
    padding-left: 86px;
26 2 Jean-Philippe Lang
}
27 2 Jean-Philippe Lang
28 10 Go MAEDA
29 2 Jean-Philippe Lang
/* move the project menu to the right */
30 2 Jean-Philippe Lang
#main-menu { 
31 2 Jean-Philippe Lang
    left: auto;
32 2 Jean-Philippe Lang
    right: 0px;
33 2 Jean-Philippe Lang
}
34 1 Jean-Philippe Lang
</code></pre>
35 1 Jean-Philippe Lang
36 2 Jean-Philippe Lang
This example assume you have an image located at @my_theme/images/logo.png@.
37 2 Jean-Philippe Lang
38 1 Jean-Philippe Lang
You can download this sample theme as a starting point for your own theme. Extract it in the @public/themes@ directory.
39 1 Jean-Philippe Lang
40 5 Jean-Philippe Lang
h2. Adding custom javascript
41 5 Jean-Philippe Lang
42 5 Jean-Philippe Lang
Simply put your javascript in @javascripts/theme.js@ and it will automatically be loaded on each page  (Redmine >= 1.1.0 only).
43 5 Jean-Philippe Lang
44 8 Bernd Kosmahl
h2. Setting a Favicon
45 8 Bernd Kosmahl
46 9 Go MAEDA
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.
47 8 Bernd Kosmahl
48 1 Jean-Philippe Lang
h2. Applying the theme
49 1 Jean-Philippe Lang
50 1 Jean-Philippe Lang
Go to "Administration -> Settings" and select your newly created theme in the "Theme" drop-down list. Save your settings.
51 1 Jean-Philippe Lang
Redmine should now be displayed using your custom theme.
52 2 Jean-Philippe Lang
53 5 Jean-Philippe Lang
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.
54 10 Go MAEDA
55 10 Go MAEDA
h2. Directory structure of themes
56 10 Go MAEDA
57 10 Go MAEDA
A theme consists of the following files:
58 10 Go MAEDA
59 10 Go MAEDA
* @favicon/<favicon file>@ (optional): favicon for the theme
60 10 Go MAEDA
* @javascripts/theme.js@ (optional): custom JavaScript for the theme
61 10 Go MAEDA
* @stylesheets/application.css@ (required): CSS for the theme
62 10 Go MAEDA
63 10 Go MAEDA
64 10 Go MAEDA
<pre>
65 10 Go MAEDA
public/
66 10 Go MAEDA
  +- themes/
67 10 Go MAEDA
       +- <theme name>/
68 10 Go MAEDA
            |
69 10 Go MAEDA
            +- favicon/
70 10 Go MAEDA
            |    +- <favicon file> (e.g. favicon.ico, favicon.png)
71 10 Go MAEDA
            |
72 10 Go MAEDA
            +- javascripts/
73 10 Go MAEDA
            |    +- theme.js
74 10 Go MAEDA
            |
75 10 Go MAEDA
            +- stylesheets/
76 10 Go MAEDA
                 +- application.css
77 10 Go MAEDA
</pre>