The forgotten files.
[usit-rt.git] / docs / customizing / styling_rt.pod
1 =head1 Customizing the Look of Your RT
2
3 While the default RT color scheme nicely matches the Best Practical colors,
4 you may want to personalize your RT instance to make it better fit with
5 your company colors.
6
7
8 =head1 Selecting a Theme
9
10 The fundamental look of RT comes from the selected theme. Different
11 RT versions have a default, and the RT admin can set the system-wide
12 theme with the C<$WebDefaultStylesheet> configuration value in the
13 F<RT_SiteConfig.pm> file.
14
15 RT 4.0 comes with the following themes:
16
17 =over
18
19 =item web2
20
21 An approximation of the 3.8 style
22
23 =item aileron
24
25 The default layout for RT 4.0
26
27 =item ballard
28
29 Theme which doesn't rely on JavaScript for menuing
30
31 =back
32
33 If you have granted the ModifySelf right to users on your system,
34 they can pick a different theme for themselves by going to
35 Logged in as -> Settings -> Options and selecting a different theme.
36
37
38 =head1 RT Theme Editor
39
40 RT has some built-in controls to manage the look of the theme you select.
41 To use the Theme Editor, log in as a SuperUser (like root), and navigate
42 to Tools -> Configuration -> Tools -> Theme.
43
44 =for html <img alt="RT theme editor, defaults" src="../images/theme_editor_defaults.png">
45
46 =for :text [RT theme editor image at F<docs/images/theme_editor_defaults.png>]
47
48 =for :man [RT theme editor image at F<docs/images/theme_editor_defaults.png>]
49
50 =head2 Logo and Colors
51
52 From there you can upload a logo and pick colors for the various page
53 sections.  RT will automatically pick out the six most frequent primary
54 colors from your logo and offer them as options next to the color wheel.
55 In less than a minute, you can upload a logo and set a few colors.
56
57 Until you click "Save", color changes are temporary and are only shown
58 to you.  When you find the color scheme you want, click Save to make it
59 the new theme for the entire RT instance. If you ever want to wipe the
60 slate clean, you can use one or both of the "Reset to default" buttons.
61
62 =head2 Basic CSS Customization
63
64 The theme editor lets you do a bit more if you know your way around CSS
65 or have a web designer who does.  By writing your own styles in the
66 Custom CSS box, you can quickly customize the RT look and feel pretty
67 extensively. The primary RT elements are stubbed out for you in the
68 edit box.
69
70 After making CSS changes, click Try to see how they look, and click Save
71 when you're done.
72
73
74 =head1 Advanced CSS Customization
75
76 If you're more ambitious and good at CSS, you can go even further and
77 create your own theme. As with all modifications to RT, it's a bad idea
78 to just change the CSS for one of the standard RT themes in place. When
79 you upgrade, if you protect your modifications from being over-written,
80 you may miss out on updates that are required for new features. In the
81 worst case, an upgrade might wipe out all of your changes.
82
83 Below are a few approaches to customizing RT's CSS.
84
85 =head2 Additional files
86
87 RT allows you to conveniently include additional CSS files after the
88 default CSS styles, via the C<@CSSFiles> configuration option.  To add
89 an extra CSS file, for example F<my-site.css>, create the local overlay
90 directory:
91
92     $ mkdir -p local/html/NoAuth/css/
93
94 And place your F<my-site.css> file in it.  Finally, adjust your
95 C<@CSSFiles> in your F<RT_SiteConfig.pm>:
96
97     Set( @CSSFiles, ('my-site.css') );
98
99 This technique is preferred to callbacks (below) because CSS included
100 via this way will be minified.  It is also included across all styles,
101 unlike the callback technique.
102
103 If you are writing an extension, see L<RT/AddStyleSheets> for how to
104 simply and programmatically add values to C<@CSSFiles>.
105
106 =head2 Callbacks
107
108 RT's CSS files are also Mason templates and the main CSS file,
109 conveniently called C<main.css>, has a C<Begin> and C<End> callback
110 allowing you to inject custom CSS.
111
112 To create an End callback, create the callback directory and an
113 End file in that directory:
114
115     $ mkdir -p local/html/Callbacks/MyRT/NoAuth/css/aileron/main.css
116     $ touch local/html/Callbacks/MyRT/NoAuth/css/aileron/main.css/End
117
118 You can use any name you want for the C<MyRT> directory and the theme
119 directory should correspond with the theme you want to change.
120
121 RT will now evaluate the contents of that file after it processes all
122 of the C<@import> statements in C<main.css>.
123
124
125 =head1 Designing Your Own Theme
126
127 The above approaches work well if you need to change the look of
128 part of RT, but you may want to design your own RT theme
129 and leave the standard RT themes available to users unmodified. In
130 this case, you'll want to create your own CSS directory.
131
132 As shown above, the C<local> directory is the place to put
133 local modifications to RT. Run the following commands in your
134 C</opt/rt4> directory (or wherever your RT is installed) to get
135 started:
136
137     $ mkdir -p local/html/NoAuth/css/localstyle
138     $ cp -R share/html/NoAuth/css/aileron/* local/html/NoAuth/css/localstyle/
139
140 You can call your "localstyle" directory whatever you want and you don't
141 have to copy the aileron theme to start from, but it's a good place to
142 start off for RT4.
143
144 Now set C<$WebDefaultStylesheet> in RT_SiteConfig.pm to the new directory
145 name you selected, for example:
146
147     Set( $WebDefaultStylesheet, 'localstyle' );
148
149 If you restart your RT it should look just the same (assuming you copied
150 your current default theme), but if you go to your Options page you'll
151 see that the system default theme is now your new "localtheme."
152
153 If you look at the CSS being loaded, you'll also see that the main css
154 file is now being loaded from your local directory. But you'll also see
155 that files are still being loaded from the main RT css directories as
156 well. Why?
157
158 The place to start understanding the loading order of RT's CSS is the
159 C<main.css> file. You'll see it first loads C<..base/main.css> which
160 are the base styles for RT along with styles for other tools RT uses
161 like jQuery. After loading all of the base styles, C<main.css> then
162 imports a theme-specific version with overrides and new style elements
163 for the selected theme. So as long as you follow the CSS precedence rules
164 and use the correct specificity, you get the last chance to modify things.
165
166 You can start modifying things by editing the CSS files in your new
167 localstyle directory. When you upgrade RT, you'll want to look specifically
168 at any changes to the style you started from to see if there are any new
169 styles you want to merge into your new style.