HowTo create a custom Redmine theme » History » Version 11

Toshi MARUYAMA, 2018-01-08 13:22
use code highlight

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 11 Toshi MARUYAMA
<pre><code class="css">
20 11 Toshi MARUYAMA
/* load the default Redmine stylesheet */
21 2 Jean-Philippe Lang
@import url(../../../stylesheets/application.css);
22 1 Jean-Philippe Lang
23 2 Jean-Philippe Lang
/* add a logo in the header */
24 2 Jean-Philippe Lang
#header {
25 2 Jean-Philippe Lang
    background: #507AAA url(../images/logo.png) no-repeat 2px;
26 2 Jean-Philippe Lang
    padding-left: 86px;
27 2 Jean-Philippe Lang
}
28 2 Jean-Philippe Lang
29 10 Go MAEDA
30 2 Jean-Philippe Lang
/* move the project menu to the right */
31 2 Jean-Philippe Lang
#main-menu { 
32 2 Jean-Philippe Lang
    left: auto;
33 2 Jean-Philippe Lang
    right: 0px;
34 2 Jean-Philippe Lang
}
35 1 Jean-Philippe Lang
</code></pre>
36 1 Jean-Philippe Lang
37 2 Jean-Philippe Lang
This example assume you have an image located at @my_theme/images/logo.png@.
38 2 Jean-Philippe Lang
39 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.
40 1 Jean-Philippe Lang
41 5 Jean-Philippe Lang
h2. Adding custom javascript
42 5 Jean-Philippe Lang
43 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).
44 5 Jean-Philippe Lang
45 8 Bernd Kosmahl
h2. Setting a Favicon
46 8 Bernd Kosmahl
47 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.
48 8 Bernd Kosmahl
49 1 Jean-Philippe Lang
h2. Applying the theme
50 1 Jean-Philippe Lang
51 1 Jean-Philippe Lang
Go to "Administration -> Settings" and select your newly created theme in the "Theme" drop-down list. Save your settings.
52 1 Jean-Philippe Lang
Redmine should now be displayed using your custom theme.
53 2 Jean-Philippe Lang
54 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.
55 10 Go MAEDA
56 10 Go MAEDA
h2. Directory structure of themes
57 10 Go MAEDA
58 10 Go MAEDA
A theme consists of the following files:
59 10 Go MAEDA
60 10 Go MAEDA
* @favicon/<favicon file>@ (optional): favicon for the theme
61 10 Go MAEDA
* @javascripts/theme.js@ (optional): custom JavaScript for the theme
62 10 Go MAEDA
* @stylesheets/application.css@ (required): CSS for the theme
63 10 Go MAEDA
64 10 Go MAEDA
65 10 Go MAEDA
<pre>
66 10 Go MAEDA
public/
67 10 Go MAEDA
  +- themes/
68 10 Go MAEDA
       +- <theme name>/
69 10 Go MAEDA
            |
70 10 Go MAEDA
            +- favicon/
71 10 Go MAEDA
            |    +- <favicon file> (e.g. favicon.ico, favicon.png)
72 10 Go MAEDA
            |
73 10 Go MAEDA
            +- javascripts/
74 10 Go MAEDA
            |    +- theme.js
75 10 Go MAEDA
            |
76 10 Go MAEDA
            +- stylesheets/
77 10 Go MAEDA
                 +- application.css
78 10 Go MAEDA
</pre>