torrus/doc/stylingprofile.pod.in

   1 #  stylingprofile.pod - Guide to Styling Profiles
   2 #  Copyright (C) 2003 Shawn Ferry
   3 #
   4 #  This program is free software; you can redistribute it and/or modify
   5 #  it under the terms of the GNU General Public License as published by
   6 #  the Free Software Foundation; either version 2 of the License, or
   7 #  (at your option) any later version.
   8 #
   9 #  This program is distributed in the hope that it will be useful,
  10 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 #  GNU General Public License for more details.
  13 #
  14 #  You should have received a copy of the GNU General Public License
  15 #  along with this program; if not, write to the Free Software
  16 #  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
  17
  18 # $Id: stylingprofile.pod.in,v 1.1 2010-12-27 00:04:32 ivan Exp $
  19 # Shawn Ferry <sferry at sevenspace dot com> <lalartu at obscure dot org>
  20 #
  21
  22 =head1 Torrus Styling Profile Guide
  23
  24 =head2 Styling Profiles
  25
  26 Styling profiles allow for symbolic names to be used in place of hard
  27 coded values for C<line-color> and C<line-style>.
  28
  29 =head3 Schema Definitions
  30
  31 The following styles are defined in the default schema.
  32
  33 =over 3
  34
  35 =item * Required Styles  (C<line-style>, C<line-color>)
  36
  37
  38            SingleGraph            HWBoundary             HWFailure
  39               HruleMin           HruleNormal              HruleMax
  40                  BpsIn                BpsOut
  41
  42
  43 =item * Generic Symbolic styles (C<line-color> only)
  44
  45                     in                   out
  46
  47 =item * Symbolic, Symbolic names, for default use in graphs that have up
  48 to ten items (C<line-color> only)
  49
  50                    one                   two                 three
  51                   four                  five                   six
  52                  seven                 eight                  nine
  53                    ten
  54
  55 =item * Symbolic names for combinatorial graphing (C<line-style>,
  56 C<line-color>)
  57
  58                   red1                  red2                  red3
  59                   red4                green1                green2
  60                 green3                green4                 blue1
  61                  blue2                 blue3                 blue4
  62
  63 =item * Color definitions from the TT2 rgb example set (C<line-color> only)
  64
  65 Defined in F<@supdir@/styling/colornames.pl>
  66
  67                  black                grey25                grey50
  68                 grey75                 white                   red
  69                  red25                 red50                 red75
  70                  green               green25               green50
  71                green75                  blue                blue25
  72                 blue50                blue75                 blood
  73                scarlet                  rose                orange
  74                   leaf                   bud                  mint
  75                 marine                   sky                 mauve
  76                  lilac
  77
  78 =item * Color definitions for web html colors (C<line-color> only)
  79
  80 Defined in F<@supdir@/styling/colornames.pl>
  81
  82              aliceblue          antiquewhite                  aqua
  83             aquamarine                 azure                 beige
  84                 bisque        blanchedalmond            blueviolet
  85                  brown             burlywood             cadetblue
  86             chartreuse             chocolate                 coral
  87         cornflowerblue              cornsilk               crimson
  88                   cyan              darkblue              darkcyan
  89          darkgoldenrod              darkgray             darkgreen
  90              darkkhaki           darkmagenta        darkolivegreen
  91             darkorange            darkorchid               darkred
  92             darksalmon          darkseagreen         darkslateblue
  93          darkslategray         darkturquoise            darkviolet
  94               deeppink           deepskyblue               dimgray
  95             dodgerblue             firebrick           floralwhite
  96            forestgreen               fuchsia             gainsboro
  97             ghostwhite                  gold             goldenrod
  98                   gray           greenyellow              honeydew
  99                hotpink             indianred                indigo
 100                  ivory                 khaki              lavender
 101          lavenderblush             lawngreen          lemonchiffon
 102              lightblue            lightcoral             lightcyan
 103   lightgoldenrodyellow            lightgreen             lightgrey
 104              lightpink           lightsalmon         lightseagreen
 105           lightskyblue        lightslategray        lightsteelblue
 106            lightyellow                  lime             limegreen
 107                magenta                maroon      mediumaquamarine
 108             mediumblue          mediumorchid          mediumpurple
 109         mediumseagreen       mediumslateblue     mediumspringgreen
 110        mediumturquoise       mediumvioletred          midnightblue
 111              mintcream             mistyrose              moccasin
 112            navajowhite                  navy               oldlace
 113                  olive             olivedrab             orangered
 114                 orchid         palegoldenrod             palegreen
 115          paleturquoise         palevioletred            papayawhip
 116              peachpuff                  peru                  pink
 117                   plum            powderblue                purple
 118              rosybrown             royalblue           saddlebrown
 119                 salmon            sandybrown              seagreen
 120               seashell                sienna                silver
 121                skyblue             slateblue             slategray
 122                   snow           springgreen             steelblue
 123                    tan                  teal               thistle
 124                 tomato             turquoise                violet
 125                  wheat            whitesmoke                yellow
 126
 127 =back
 128
 129 =head3 Schema Overlay
 130
 131 I<WARNING: Some styles are mandatory>
 132
 133 Schema overlays allow the user to extend or override the styles defined in the
 134 default schema.  The schema overlays are formatted in the form of a hash of
 135 hashes.
 136
 137
 138 =over 4
 139
 140 =item * Extending the schema:
 141
 142 To add the styles, C<##onefish>, C<##twofish>, C<##redfish>, C<##bluefish>
 143 the following entries should be created in a descriptive file located
 144 in the C<styling> directory.
 145
 146 C<fish-schema.pl>
 147
 148   $Torrus::Renderer::graphStyles{'onefish'}{'color'} = '##darkred';
 149   $Torrus::Renderer::graphStyles{'onefish'}{'line'} = 'LINE1';
 150
 151   $Torrus::Renderer::graphStyles{'twofish'}{'color'} = '##red';
 152   $Torrus::Renderer::graphStyles{'twofish'}{'line'} = 'LINE2';
 153
 154   $Torrus::Renderer::graphStyles{'redfish'}{'color'} = '##yellow';
 155
 156   $Torrus::Renderer::graphStyles{'bluefish'}{'color'} = '##deeppink';
 157
 158 Other methods of adding to the hash of hashes are also acceptable.
 159
 160 =item * Overriding Styles:
 161
 162 To override specific styles in the existing schema, C<##in>, C<##out>,
 163 entries similar to the following should be created in a Perl file,
 164 preferably located in the local configuration directory.
 165
 166 C<in_out-override-schema.pl>
 167
 168   $Torrus::Renderer::graphStyles{'in'}{'color'} = '##yellow';
 169   $Torrus::Renderer::graphStyles{'out'}{'color'} = '##maroon';
 170
 171 Other methods of adding to the hash of hashes are also acceptable.
 172
 173 =item * Applying your Overlay
 174
 175 =over 4
 176
 177 =item 1.
 178
 179 In the torrus-siteconfig.pl file, add the variable
 180
 181 $Torrus::Renderer::stylingProfileOverlay =
 182     $Torrus::Global::cfgSiteDir . '/in_out-override-schema.pl';
 183
 184 =item 2.
 185
 186 Restart apache
 187
 188 =back
 189
 190 You may have to wait for the image cache to clear before the changes
 191 take effect.
 192
 193 =back
 194
 195 =head3 Schema Replacement
 196
 197 To replace a schema, create a new schema using torrus-schema.pl as a guide.
 198 Remember some styles are mandatory.
 199
 200 =over 4
 201
 202 =item * Applying your Schema
 203
 204 In the F<torrus-siteconfig.pl> file, add the variable
 205
 206   $Torrus::Renderer::stylingProfile = "Your-schema";
 207
 208 =item 2. Restart apache
 209
 210 =back
 211
 212 You may have to wait for the image cache to clear before the changes
 213 take effect.
 214
 215 =head1 Author
 216
 217 Copyright (c) 2003 Shawn Ferry