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