rt/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.