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