[Rt-commit] rt branch, 4.0/add-styling-rt-docs, created. rt-4.0.8-216-gff960b2

Jim Brandt jbrandt at bestpractical.com
Mon Dec 10 11:15:17 EST 2012


The branch, 4.0/add-styling-rt-docs has been created
        at  ff960b2b752ef57ad19eeb442d92888ee3d2bfff (commit)

- Log -----------------------------------------------------------------
commit ff960b2b752ef57ad19eeb442d92888ee3d2bfff
Author: Jim Brandt <jbrandt at bestpractical.com>
Date:   Fri Dec 7 17:00:00 2012 -0500

    Add docs on ways to style and theme RT

diff --git a/docs/customizing/styling_rt.pod b/docs/customizing/styling_rt.pod
new file mode 100644
index 0000000..078887f
--- /dev/null
+++ b/docs/customizing/styling_rt.pod
@@ -0,0 +1,153 @@
+=head1 Customizing the Look of Your RT
+
+While the default RT color scheme nicely matches the Best Practical colors,
+you may want to personalize your RT instance to make it better fit with
+your company colors.
+
+=head1 Selecting a Theme
+
+The fundamental look of RT comes from the selected theme. Different
+RT versions have a default, and the RT admin can set the system-wide
+theme with the C<$WebDefaultStylesheet> configuration value in the
+C<RT_SiteConfig.pm> file.
+
+RT comes with the following themes:
+
+=over
+
+=item web2
+
+The default layout for RT 3.8
+
+=item aileron
+
+The default layout for RT 4.0
+
+=item ballard
+
+Theme which doesn't rely on JavaScript for menuing
+
+=back
+
+If you have granted the ModifySelf right to users on your system,
+they can pick a different theme for themselves by going to
+Logged in as > Settings > Options and selecting a different theme.
+
+=head1 RT Theme Editor
+
+RT has some built-in controls to manage the look of the theme you select.
+To use the Theme Editor, log in as a SuperUser (like root), and navigate
+to Tools > Configuration > Tools > Theme.
+
+=for html <img alt="RT theme editor, defaults" src="images/theme_editor_defaults.png">
+
+=for :text [RT theme editor image at F<docs/images/theme_editor_defaults.png>]
+
+=for :man [RT theme editor image at F<docs/images/theme_editor_defaults.png>]
+
+=head2 Logo and Colors
+
+From there you can upload a logo and pick colors for the various page
+sections.  RT will automatically pick out the six most frequent primary
+colors from your logo and offer them as options next to the color wheel.
+In less than a minute, you can upload a logo and set a few colors.
+
+When you find the color scheme you want, click Save to make it the
+new theme for the entire RT instance. If you ever want to wipe the
+slate clean, you can use one or both of the "Reset to default" buttons.
+
+=head2 Basic CSS Customization
+
+The theme editor lets you do a bit more if you know your way around CSS
+or have a web designer who does.  By writing your own styles in the
+Custom CSS box, you can quickly customize the RT look and feel pretty
+extensively. The primary RT elements are stubbed out for you in the
+edit box.
+
+After making CSS changes, click Try to see how they look, and click Save
+when you're done.
+
+=head1 Advanced CSS Customization
+
+If you're more ambitious and good at CSS, you can go even further and
+create your own theme. As with all modifications to RT, it's a bad idea
+to just start changing the CSS for one of the standard RT themes in
+place. When you upgrade, if you protect your modifications from being
+over-written, you may miss out on updates that are required for new
+features. In the worst case, an upgrade might wipe out all of your
+changes.
+
+Below are a few approaches to customizing RT's CSS.
+
+=head1 Callbacks
+
+RT's CSS files are actually Mason templates and the main CSS file,
+conveniently called C<main.css>, has a C<Begin> and C<End> callback
+allowing you to inject custom CSS.
+
+These callbacks can be particularly useful if you are writing an
+RT extension, but they are also useful if you just want to customize
+your RT. Because of the CSS precedence rules, you can add your own
+CSS with the C<End> callback and override specific RT styles.
+
+To create an End callback, create the callback directory and an
+End file in that directory:
+
+    $ mkdir -p local/html/Callbacks/MyRT/NoAuth/css/aileron/main.css
+    $ touch local/html/Callbacks/MyRT/NoAuth/css/aileron/main.css/End
+
+You can use any name you want for the C<MyRT> directory and the theme
+directory should correspond with the theme you want to change.
+
+RT will now evaluate the contents of that file after it processes all
+of the C<@import> statements in C<main.css>. You can put some raw CSS
+there or an import statement to pull in a CSS file or files with your
+customizations. You can put new CSS files in:
+
+    local/html/NoAuth/css/
+
+=head1 Designing Your Own Theme
+
+The callback approach works well if you need to change the look of
+one of RT's themes, but you may want to design your own RT theme
+and leave the standard RT themes available to users unmodified. In
+this case, you'll want to create your own CSS directory.
+
+As shown above, the C<local> directory is the place to put
+local modifications to RT. Run the following commands in your
+C</opt/rt4> directory (or wherever your RT is installed) to get
+started:
+
+    $ mkdir -p local/html/NoAuth/css/localstyle
+    $ cp -R share/html/NoAuth/css/aileron/* local/html/NoAuth/css/localstyle/
+
+You can call your "localstyle" directory whatever you want and you
+don't have to use with the aileron theme, but it's a good start for
+RT4.
+
+Now set C<$WebDefaultStylesheet> in RT_SiteConfig.pm to the new directory
+name you selected, for example:
+
+    Set( $WebDefaultStylesheet, 'localstyle' );
+
+If you restart your RT it should look just the same (assuming you copied
+your current default theme), but if you go to your Options page you'll
+see that the system default theme is now your new "localtheme."
+
+If you look at the CSS being loaded, you'll also see that the main css
+file is now being loaded from your local directory. But you'll also see
+that files are still being loaded from the main RT css directories as
+well. Why?
+
+The place to start understanding the loading order of RT's CSS is the
+C<main.css> file. You'll see it first loads C<..base/main.css> which
+are the base styles for RT along with styles for other tools RT uses
+like jQuery. After loading all of the base styles, C<main.css> then
+imports a theme-specific version with overrides and new style elements
+for the selected theme. So as long as you follow the CSS precedence rules
+and use the correct specificity, you get the last chance to modify things.
+
+You can start modifying things by editing the CSS files in your new
+localstyle directory. When you upgrade RT, you'll want to look specifically
+at any changes to the style you started from to see if there are any new
+styles you want to merge into your new style.
diff --git a/docs/images/theme_editor_defaults.png b/docs/images/theme_editor_defaults.png
new file mode 100644
index 0000000..0fed8dc
Binary files /dev/null and b/docs/images/theme_editor_defaults.png differ

-----------------------------------------------------------------------


More information about the Rt-commit mailing list