xdoc/sass.dox

   1 /** @page sassdoc Ninja - DOJO - Dev. Manual
   2
   3 This manual is about the new layout DOJO for the Nagios GUI NINJA.
   4
   5 DOJO aims to improve the structure, style and semantics of NINJA. Making the layout more dynamic, responsive and remove deprecated
   6 ways of handling layout.
   7
   8 DOJO will effectively make all custom skins unusable due to its enourmous changes to CSS, newly released skins for
   9 ninja include default, classic and hello kitty.
  10
  11 DOJO enforces the earlier experimental NOC behaviour on ninja, it cannot be switched back to the older sidebar menu.
  12
  13 @section layout Layout
  14
  15 @subsection dojo-menus Menus
  16
  17 The menus have move from a sidebar style to a drop-down behaviour (earlier experimental NOC) to give the data as much space as possible.
  18 Some menu-items have been moved (host problems, service problems and unhandled problems) to a joined unhandled problems quickbar icon.
  19
  20 @subsection dojo-quickbar Quickbar
  21
  22 The quickbar contains some of the older top-bar icons and functionality, such as settings and refresh but has been extended with
  23 a shortcut to unhandled problems and tactical overview. In ninja it also links to this documentation.
  24
  25 The aim with the quickbar is that all customers should be able to pin menu items, filtered/saved searches and external links to an icon
  26 in the topbar for easy access to as much as possible based on their needs.
  27
  28 @section install-sass Install SASS
  29
  30 All developers must install SASS and Compass since we don't keep the compiled CSS in the repos, only SASS.
  31
  32 In order to install sass and compass, run the make:
  33
  34 @verbatim
  35 make install-sass
  36 @endverbatim
  37
  38 Or install the gems manually through
  39
  40 @verbatim
  41 gem install sass (may need to sudo)
  42 gem install compass (may need to sudo)
  43 @endverbatim
  44
  45 Once installed you can proceed to browse to the skin folder of your choice and type
  46 in the compass command.
  47
  48 @verbatim
  49 cd ~/<repo>/monitor/ninja/application/views/css/default
  50 compass watch
  51 @endverbatim
  52
  53 Compass will poll for any changes to the SASS and compile to CSS, if no CSS is found it will do a first time
  54 compilation initially.
  55
  56 Or you can run the command make in the root directory after each SASS change
  57
  58 @verbatim
  59 make
  60 @endverbatim
  61
  62 @li Never push CSS, only SASS
  63 @li Never change CSS only SASS
  64
  65 @section about-sass SASS
  66
  67 @subsection sass-syntax SASS syntax
  68
  69 SASS is a white-space sensitive indentation hierarchy language that does not use curly brackets or semi-colons as in regular CSS.
  70 It has support for inheritance, nesting, variables and "mixins".
  71
  72 @subsection sass-guide SASS quick guide
  73
  74 @subsection sass-variables Variables
  75
  76 Variables in SASS are denoted using the dollar-sign and are assigned using the colon, they contain CSS values, i.e. not pure
  77 numbers and text but type-specific values and can be used in place of any comparative value type.
  78
  79 @verbatim
  80 $fontF: "Verdana"
  81 $fontS: 16pt
  82 $fontW: bold
  83
  84 p
  85         font: $fontS $fontW normal $fontF
  86 @endverbatim
  87
  88 @subsection sass-nesting Nesting
  89
  90 In regular CSS there is no nesting, if we want to declare a style to a parent, its children and their children, we have to create
  91 three independent scopes
  92
  93 @verbatim
  94 .container {
  95         properties...
  96 }
  97 .container .content {
  98         properties...
  99 }
 100 .container .content span {
 101         properties...
 102 }
 103 @endverbatim
 104
 105 In SASS we have a nested way of doing this using the indentation hierarchy
 106
 107 @verbatim
 108 .container
 109         properties...
 110         .content
 111                 properties...
 112                 span
 113                         properties...
 114 @endverbatim
 115
 116 @subsection sass-sub-nesting Sub-property nesting
 117
 118 SASS takes CSS nesting to another level, allowing sub-properties to be declared as nests, here we want to declare font properties
 119 to a p tag.
 120
 121 @verbatim
 122 p
 123         font
 124                 family: "Verdana"
 125                 size: 12pt
 126                 weight: normal
 127                 style: italic
 128 @endverbatim
 129
 130 @subsection sass-mixins Mixins
 131
 132 Sort of like functions that can take 0 or more arguments and return a set of (possibly dynamic) CSS properties.
 133
 134 @verbatim
 135 @mixin demo
 136         font
 137                 family: "Verdana"
 138                 size: 12pt
 139                 weight: normal
 140                 style: italic
 141 @endverbatim
 142
 143 In and of itself it does nothing, if it is not used it will <b>not be in the resulting CSS</b>, but if we want this font style to be used
 144 in all table cells, p tags and spans but with different colors we use it as such.
 145
 146 @verbatim
 147 p
 148         @include demo
 149         color: #444
 150 td
 151         @include demo
 152         color: #666
 153 span
 154         @include demo
 155         color: #888
 156 @endverbatim
 157
 158 The reason for using mixins and not only inherited selectors is that mixins can take arguments and return dynamic sets of properties.
 159 Here we declare a global font and size but we want the selector using the mixin to determine the color and style of the font.
 160
 161 @verbatim
 162
 163 $font: "Verdana"
 164 $size: 12pt
 165
 166 @mixin demo($color, $style)
 167         font
 168                 family: $font
 169                 size: $size
 170                 weight: normal
 171                 style: $style
 172         color: $color
 173 @endverbatim
 174
 175 @verbatim
 176 p
 177         @include demo(#444, normal)
 178 td
 179         @include demo(#666, oblique)
 180 span
 181         @include demo(#888, italic)
 182 @endverbatim
 183
 184 @subsection sass-inherit Inheritance
 185
 186 Inheritance is used in much the same way as mixins except that they take existing selectors instead of the compilation level
 187 mixin definition. Here we declare a p tag style and a span tag that inherits the style of the p tag and declares its own.
 188
 189 Both the p and span selectors <b>will be contained in the resulting stylesheet</b>!
 190
 191 @verbatim
 192 p
 193         font
 194                 family: "Verdana"
 195                 size: 12pt
 196                 weight: normal
 197                 style: italic
 198
 199 span
 200         @extend p
 201         color: #567
 202 @endverbatim
 203
 204 Read more on SASS <a href="www.sass-lang.com">website</a>, and more about compass and its support mixins on <a href="compass-style.com">theirs</a>.
 205
 206 @subsection configure-style Configuration
 207
 208 The new CSS is generated using the SASS 'pre-processor', giving it far more power while developing.
 209 One of these powers is variables, and with variables DOJO includes a configuration file, found under
 210 dojo/config.sass.
 211
 212 In this file you can set general configurations, such as the header height, fonts, different colors and more.
 213
 214 @subsection sprites All img tag icons should be replaced by sprite spans
 215
 216 Ninja now uses CSS sprites instead of independent icon images, a first glance test lowered the request count from 94 -> 36 and uncached
 217 load-time by 1.4 seconds. Icon images can be replaced everywhere an icon is used from the icon folders and is a PNG image.
 218
 219 GIF icons cannot be included in spritesheets by compass, use the old icon images for icons, gif icons will be updated to PNG.
 220
 221 In order to utilize this development feature all img tags relating to icons should move from the old e.g.
 222
 223 @verbatim
 224 echo html::image(
 225         $this->add_path('icons/12x12/shield-'.strtolower($row['status']).'.png'),
 226         array(
 227                 'title' => $row['status'], 'alt' => $row['status'],
 228                 'style' => 'margin-bottom: -2px'
 229         )
 230 );
 231 @endverbatim
 232
 233 To the new
 234
 235 @verbatim
 236 echo '<span class="icon-12 x12-'.
 237         strtolower($row['status']).'" '.
 238         '       title="'.$row['status'].'"></span>';
 239 // The style is omitted because inline style is no-no
 240 @endverbatim
 241
 242 Resulting in, maybe something like this
 243
 244 @verbatim
 245 <span class="icon-12 x12-up" title="up"></span>';
 246 @endverbatim
 247
 248 The class is broken down to
 249
 250 <table>
 251 <tr>
 252 <td>icon-12</td><td>x12-</td><td>up</td>
 253 </tr>
 254 <tr>
 255 <td>This is an icon and it is of size 12x12</td>
 256 <td>It is part of the spritesheet x12 (like all 12x12 icons)</td>
 257 <td>And it's the one formerly named up (up.png)</td>
 258 </tr>
 259 </table>
 260
 261 The class for icons such as shield-not-disabled would hence become:
 262
 263 <table>
 264 <tr>
 265 <td>icon-16</td><td>x16-</td><td>shield-not-disabled</td>
 266 </tr>
 267 <tr>
 268 <td>This is an icon and it is of size 16x16</td>
 269 <td>It is part of the spritesheet x16 (like all 16x16 icons)</td>
 270 <td>And it's the one formerly named shield-not-disabled (shield-not-disabled.png)</td>
 271 </tr>
 272 </table>
 273
 274 @subsection css-aux-selectors Global Auxiliary Selectors
 275
 276 @subsubsection css-aux-alpha .alpha
 277
 278 Sets the opacity of the element to 0.4 by default and nothing else, the amount it sets can be configured in the SASS configuration file.
 279
 280 @subsubsection css-aux-right .right
 281
 282 Floats the elements to the right and nothing else. Use .clear to restore.
 283
 284 @subsubsection css-aux-left .left
 285
 286 Floats the elements to the left and nothing else. Use .clear to restore.
 287
 288 @subsubsection css-aux-clear .clear
 289
 290 Clears both on the element and nothing else. Always use after floated elements to restore normal flow.
 291
 292 @subsubsection css-aux-none .none (legacy .white)
 293
 294 Makes the element completely transparent by setting 0 opacity.
 295
 296 @subsubsection css-aux-nullify .nullify (legacy .white)
 297
 298 Removes a lot of things, this one is already in use by all tables by default.
 299
 300 @li background: transparent
 301 @li border-spacing: 0
 302 @li vertical-align: top
 303 @li outline: none
 304 @li border: none
 305 @li margin: 0
 306 @li padding: 0
 307
 308 */