[Rt-commit] rt branch, 4.0/add-styling-rt-docs, updated. rt-4.0.8-218-g888ccc3

[Alex Vandiver]

The branch, 4.0/add-styling-rt-docs has been updated
       via  888ccc3b41ab6130c111f9aa25db5d7fa96c37c9 (commit)
       via  d8cdb11605707e839ef5649aea5116c1cce04e1b (commit)
      from  ff960b2b752ef57ad19eeb442d92888ee3d2bfff (commit)

Summary of changes:
 docs/customizing/styling_rt.pod | 72 +++++++++++++++++++++++++----------------
 1 file changed, 44 insertions(+), 28 deletions(-)

- Log -----------------------------------------------------------------
commit d8cdb11605707e839ef5649aea5116c1cce04e1b
Author: Alex Vandiver <alexmv at bestpractical.com>
Date:   Mon Dec 24 16:01:46 2012 -0500

    Mention and encourage use of @CSSFiles

diff --git a/docs/customizing/styling_rt.pod b/docs/customizing/styling_rt.pod
index 078887f..eee2020 100644
--- a/docs/customizing/styling_rt.pod
+++ b/docs/customizing/styling_rt.pod
@@ -79,17 +79,33 @@ changes.
 
 Below are a few approaches to customizing RT's CSS.
 
-=head1 Callbacks
+=head2 Additional files
 
-RT's CSS files are actually Mason templates and the main CSS file,
+RT allows you to conveniently include additional CSS files after the
+default CSS styles, via the C<@CSSFiles> configuration option.  To add
+an extra CSS file, for example F<my-site.css>, create the local overlay
+directory:
+
+    $ mkdir -p local/html/NoAuth/css/
+
+And place your F<my-site.css> file in it.  Finally, adjust your
+C<@CSSFiles> in your F<RT_SiteConfig.pm>:
+
+    Set( @CSSFiles, ('my-site.css') );
+
+This technique is preferred to callbacks (below) because CSS included
+via this way will be minified.  It is also included across all styles,
+unlike the callback technique.
+
+If you are writing an extension, see L<RT/AddStyleSheets> for how to
+simply and programmatically add values to C<@CSSFiles>.
+
+=head2 Callbacks
+
+RT's CSS files are also 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:
 
@@ -100,11 +116,8 @@ 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:
+of the C<@import> statements in C<main.css>.
 
-    local/html/NoAuth/css/
 
 =head1 Designing Your Own Theme
 

commit 888ccc3b41ab6130c111f9aa25db5d7fa96c37c9
Author: Alex Vandiver <alexmv at bestpractical.com>
Date:   Mon Dec 24 16:02:12 2012 -0500

    Minor wording, consistency, and content changes

diff --git a/docs/customizing/styling_rt.pod b/docs/customizing/styling_rt.pod
index eee2020..14bbfd7 100644
--- a/docs/customizing/styling_rt.pod
+++ b/docs/customizing/styling_rt.pod
@@ -4,20 +4,21 @@ 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.
+F<RT_SiteConfig.pm> file.
 
-RT comes with the following themes:
+RT 4.0 comes with the following themes:
 
 =over
 
 =item web2
 
-The default layout for RT 3.8
+An approximation of the 3.8 style
 
 =item aileron
 
@@ -31,13 +32,14 @@ Theme which doesn't rely on JavaScript for menuing
 
 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.
+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.
+to Tools -> Configuration -> Tools -> Theme.
 
 =for html <img alt="RT theme editor, defaults" src="images/theme_editor_defaults.png">
 
@@ -52,8 +54,9 @@ 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
+Until you click "Save", color changes are temporary and are only shown
+to you.  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
@@ -67,15 +70,15 @@ 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.
+to just change 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.
 
@@ -121,8 +124,8 @@ of the C<@import> statements in C<main.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
+The above approaches work well if you need to change the look of
+part of RT, 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.
 
@@ -134,9 +137,9 @@ 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.
+You can call your "localstyle" directory whatever you want and you don't
+have to copy the aileron theme to start from, but it's a good place to
+start off for RT4.
 
 Now set C<$WebDefaultStylesheet> in RT_SiteConfig.pm to the new directory
 name you selected, for example:

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