dojo/index.html

   1 <!DOCTYPE html>
   2 <html>
   3         <head>
   4                 <title>NINJA &raquo; DOJO &raquo; Dev. Manual</title>
   5                 <style type="text/css">
   6                         body {
   7                                 font: normal normal 11pt 'Century Gothic', 'Lucida Grande', sans-serif;
   8                                 padding: 16px 32px;
   9                                 margin: 0;
  10                                 width: 768px;
  11                                 background: #f5f5f5;
  12                         }
  13                         h1, h2, h3, h4 {
  14                                 color: #666;
  15                                 font-weight: normal;
  16                                 margin: 8px 0;
  17                         }
  18                         p {
  19                                 color: #444;
  20                                 margin: 4px 16px;
  21                         }
  22                         code {
  23                                 display: block;
  24                                 margin: 16px 32px;
  25                                 padding: 8px;
  26                                 font-size: 90%;
  27                                 border: 2px dotted #ddd;
  28                                 background: #eee;
  29                                 color: #555;
  30                         }
  31
  32                         table {
  33                                 border: 2px solid #ccc;
  34                                 border-right: none;
  35                                 border-bottom: none;
  36                                 margin: 16px 32px;
  37                                 padding: 0;
  38                                 border-spacing: 0;
  39                         }
  40
  41                         tr {
  42                                 padding: 0;
  43                                 margin: 0;
  44                                 border-spacing: 0;
  45                         }
  46
  47                         td {
  48                                 border-spacing: 0;
  49                                 margin: 0;
  50                                 padding: 4px;
  51                                 color: #444;
  52                                 background: #eee;
  53                                 border-right: 2px solid #ccc;
  54                                 border-bottom: 2px solid #ccc;
  55                                 font-size: 90%;
  56                         }
  57
  58                         div {
  59                                 margin-left: 16px;
  60                         }
  61
  62                         .warning, .note, .critical {
  63                                 font-style: normal;
  64                                 color: #222;
  65                                 margin: 16px 32px;
  66                                 padding: 8px;
  67                                 overflow: auto;
  68                         }
  69
  70                         a, a:visited, a:active {
  71                                 color: #47f;
  72                                 text-decoration: none;
  73                         }
  74
  75                         a:hover {
  76                                 border-bottom: 1px dotted #47f;
  77                         }
  78
  79                         .warning {
  80                                 background: #fd9;
  81                                 border: 2px solid #fa7;
  82                         }
  83
  84                         .note {
  85                                 background: #ada;
  86                                 border: 2px solid #7b7;
  87                         }
  88
  89                         .critical {
  90                                 background: #daa;
  91                                 border: 2px solid #c44;
  92                         }
  93
  94                         .warning em, .note em, .critical em {
  95                                 font-style: normal;
  96                                 font-weight: bold;
  97                                 font-size: 11pt;
  98                                 padding: 0 6px;
  99                                 float: left;
 100                         }
 101
 102                 </style>
 103         </head>
 104         <body>
 105                 <h1>Ninja &raquo; DOJO &raquo; Dev. Manual</h1>
 106
 107                 <p>
 108                         This manual is about the new layout DOJO for the Nagios GUI NINJA.
 109                 </p>
 110
 111                 <p>
 112                         DOJO aims to improve the structure, style and semantics of NINJA. Making the layout more dynamic, responsive and remove deprecated
 113                         ways of handling layout.
 114                 </p>
 115
 116                 <div class="critical">
 117                         <em>(X) Critical: </em>
 118                                 DOJO will effectively make all custom skins unusable due to its enourmous changes to CSS, newly released skins for
 119                                 ninja include default, classic and hello kitty.
 120                 </div>
 121
 122                 <div class="critical">
 123                         <em>(X) Critical: </em>
 124                                 DOJO enforces the earlier experimental NOC behaviour on ninja, it cannot be switched back to the older sidebar menu.
 125                 </div>
 126
 127                 <h2>Layout</h2>
 128
 129                 <div>
 130
 131                         <h3>Menus</h3>
 132
 133                         <p>
 134                                 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.
 135                                 Some menu-items have been moved (host problems, service problems and unhandled problems) to a joined unhandled problems quickbar icon.
 136                         </p>
 137
 138                         <h3>Quickbar</h3>
 139
 140                         <p>
 141                                 The quickbar contains some of the older top-bar icons and functionality, such as settings and refresh but has been extended with
 142                                 a shortcut to unhandled problems and tactical overview. In ninja it also links to this documentation.
 143                         </p>
 144
 145                         <p>
 146                                 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
 147                                 in the topbar for easy access to as much as possible based on their needs.
 148                         </p>
 149
 150                 </div>
 151
 152                 <h2>Install SASS</h2>
 153
 154                 <div class="note">
 155                                         <em>Note: </em>
 156                                         All developers must install SASS and Compass since we don't keep the compiled CSS in the repos, only SASS.
 157                                 </div>
 158                 </div>
 159
 160                 <p>
 161                         In order to install sass and compass, run the make:
 162                 </p>
 163
 164                 <code>
 165                         make install-sass
 166                 </code>
 167
 168                 <p>
 169                         Or install the gems manually through
 170                 </p>
 171
 172                 <code>
 173                         gem install sass (may need to sudo)<br />
 174                         gem install compass (may need to sudo)<br />
 175                 </code>
 176
 177                 <p>
 178                         Once installed you can proceed to browse to the skin folder of your choice and type
 179                         in the compass command.
 180                 </p>
 181
 182                 <code>
 183                         cd ~/&lt;repo&gt;/monitor/ninja/application/views/css/default<br />
 184                         compass watch
 185                 </code>
 186
 187                 <p>
 188                         Compass will poll for any changes to the SASS and compile to CSS, if no CSS is found it will do a first time
 189                         compilation initially.
 190                 </p>
 191
 192                 <p>
 193                         Or you can run the command make in the root directory after each SASS change
 194                 </p>
 195
 196                 <code>
 197                         make
 198                 </code>
 199
 200                 <div class="critical">
 201                                         <em>(X) Critical: </em><br />
 202                                         <ul>
 203                                                 <li>Never push CSS, only SASS</li>
 204                                                 <li>Never change CSS only SASS</li>
 205                                         </ul>
 206                                 </div>
 207                 <div>
 208
 209                         <h2>CSS</h2>
 210
 211                         <div>
 212
 213                                 <h3>SASS syntax</h3>
 214
 215                                 <p>
 216                                         SASS is a white-space sensitive indentation hierarchy language that does not use curly brackets or semi-colons as in regular CSS.
 217                                         It has support for inheritance, nesting, variables and "mixins".
 218                                 </p>
 219
 220                                 <div>
 221
 222                                         <h3>SASS quick guide</h3>
 223
 224                                         <h4>
 225                                                 Variables
 226                                         </h4>
 227
 228                                         <p>
 229                                                 Variables in SASS are denoted using the dollar-sign and are assigned using the colon, they contain CSS values, i.e. not pure
 230                                                 numbers and text but type-specific values and can be used in place of any comparative value type.
 231                                         </p>
 232
 233                                         <code>
 234                                                 $fontF: "Verdana"<br />
 235                                                 $fontS: 16pt<br />
 236                                                 $fontW: bold<br />
 237                                                 <br />
 238                                                 p<br />
 239                                                 &nbsp;&nbsp;font: $fontS $fontW normal $fontF<br />
 240                                         </code>
 241
 242                                         <h4>
 243                                                 Nesting
 244                                         </h4>
 245
 246                                         <p>
 247                                                 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
 248                                                 three independent scopes
 249                                         </p>
 250
 251                                         <code>
 252                                                 .container {<br />
 253                                                 &nbsp;&nbsp;properties...<br />
 254                                                 }<br />
 255                                                 .container .content {<br />
 256                                                 &nbsp;&nbsp;properties...<br />
 257                                                 }<br />
 258                                                 .container .content span {<br />
 259                                                 &nbsp;&nbsp;properties...<br />
 260                                                 }<br />
 261                                         </code>
 262
 263                                         <p>
 264                                                 In SASS we have a nested way of doing this using the indentation hierarchy
 265                                         </p>
 266
 267                                         <code>
 268                                                 .container<br />
 269                                                 &nbsp;&nbsp;properties...<br /><br />
 270                                                 &nbsp;&nbsp;.content <br />
 271                                                 &nbsp;&nbsp;&nbsp;&nbsp;properties...<br /><br />
 272                                                 &nbsp;&nbsp;&nbsp;&nbsp;span <br />
 273                                                 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;properties...<br />
 274                                                 <br />
 275                                         </code>
 276
 277                                         <h4>
 278                                                 Sub-property nesting
 279                                         </h4>
 280
 281                                         <p>
 282                                                 SASS takes CSS nesting to another level, allowing sub-properties to be declared as nests, here we want to declare font properties
 283                                                 to a p tag.
 284                                         </p>
 285
 286                                         <code>
 287                                                 p<br />
 288                                                 &nbsp;&nbsp;font<br />
 289                                                 &nbsp;&nbsp;&nbsp;&nbsp;family: "Verdana"<br />
 290                                                 &nbsp;&nbsp;&nbsp;&nbsp;size: 12pt<br />
 291                                                 &nbsp;&nbsp;&nbsp;&nbsp;weight: normal<br />
 292                                                 &nbsp;&nbsp;&nbsp;&nbsp;style: italic<br />
 293                                         </code>
 294
 295                                         <h4>
 296                                                 Mixins
 297                                         </h4>
 298
 299                                         <p>
 300                                                 Sort of like functions that can take 0 or more arguments and return a set of (possibly dynamic) CSS properties.
 301                                         </p>
 302
 303                                         <code>
 304                                                 @mixin demo<br />
 305                                                 &nbsp;&nbsp;font<br />
 306                                                 &nbsp;&nbsp;&nbsp;&nbsp;family: "Verdana"<br />
 307                                                 &nbsp;&nbsp;&nbsp;&nbsp;size: 12pt<br />
 308                                                 &nbsp;&nbsp;&nbsp;&nbsp;weight: normal<br />
 309                                                 &nbsp;&nbsp;&nbsp;&nbsp;style: italic<br />
 310                                         </code>
 311
 312
 313                                         <div class="note">
 314                                                 <em>Note: </em>
 315                                                         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
 316                                                 in all table cells, p tags and spans but with different colors we use it as such.
 317                                         </div>
 318
 319                                         <code>
 320                                                 p<br />
 321                                                 &nbsp;&nbsp;@include demo<br />
 322                                                 &nbsp;&nbsp;color: #444<br />
 323                                                 td<br />
 324                                                 &nbsp;&nbsp;@include demo<br />
 325                                                 &nbsp;&nbsp;color: #666<br />
 326                                                 span<br />
 327                                                 &nbsp;&nbsp;@include demo<br />
 328                                                 &nbsp;&nbsp;color: #888<br />
 329                                         </code>
 330
 331                                         <p>
 332                                                 The reason for using mixins and not only inherited selectors is that mixins can take arguments and return dynamic sets of properties.
 333                                                 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.
 334                                         </p>
 335
 336                                         <code>
 337
 338                                                 $font: "Verdana"<br />
 339                                                 $size: 12pt<br />
 340                                                 <br />
 341                                                 @mixin demo($color, $style)<br />
 342                                                 &nbsp;&nbsp;font<br />
 343                                                 &nbsp;&nbsp;&nbsp;&nbsp;family: $font<br />
 344                                                 &nbsp;&nbsp;&nbsp;&nbsp;size: $size<br />
 345                                                 &nbsp;&nbsp;&nbsp;&nbsp;weight: normal<br />
 346                                                 &nbsp;&nbsp;&nbsp;&nbsp;style: $style<br />
 347                                                 &nbsp;&nbsp;color: $color
 348                                         </code>
 349
 350                                         <code>
 351                                                 p<br />
 352                                                 &nbsp;&nbsp;@include demo(#444, normal)<br />
 353                                                 td<br />
 354                                                 &nbsp;&nbsp;@include demo(#666, oblique)<br />
 355                                                 span<br />
 356                                                 &nbsp;&nbsp;@include demo(#888, italic)<br />
 357                                         </code>
 358
 359                                         <h4>
 360                                                 Inheritance
 361                                         </h4>
 362
 363                                         <p>
 364                                                 Inheritance is used in much the same way as mixins except that they take existing selectors instead of the compilation level
 365                                                 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.
 366                                         </p>
 367
 368                                         <div class="note">
 369                                                 <em>Note: </em>
 370                                                         Both the p and span selectors <b>will be contained in the resulting stylesheet</b>!
 371                                         </div>
 372
 373                                         <code>
 374                                                 p<br />
 375                                                 &nbsp;&nbsp;font<br />
 376                                                 &nbsp;&nbsp;&nbsp;&nbsp;family: "Verdana"<br />
 377                                                 &nbsp;&nbsp;&nbsp;&nbsp;size: 12pt<br />
 378                                                 &nbsp;&nbsp;&nbsp;&nbsp;weight: normal<br />
 379                                                 &nbsp;&nbsp;&nbsp;&nbsp;style: italic<br />
 380                                                 <br />
 381                                                 span<br />
 382                                                 &nbsp;&nbsp;@extend p<br />
 383                                                 &nbsp;&nbsp;color: #567
 384                                         </code>
 385
 386
 387                                 </div>
 388
 389                                 <p>
 390                                         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>.
 391                                 </p>
 392
 393                                 <h3>Configuration</h3>
 394
 395                                 <p>
 396                                         The new CSS is generated using the SASS 'pre-processor', giving it far more power while developing.
 397                                         One of these powers is variables, and with variables DOJO includes a configuration file, found under
 398                                         dojo/config.sass.
 399                                 </p>
 400
 401                                 <p>
 402                                         In this file you can set general configurations, such as the header height, fonts, different colors and more.
 403                                 </p>
 404
 405                                 <h3>All img tag icons should be replaced by sprite spans</h3>
 406
 407                                 <p>
 408                                         Ninja now uses CSS sprites instead of independent icon images, a first glance test lowered the request count from 94 -> 36 and uncached
 409                                         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.
 410                                 </p>
 411
 412                                 <div class="warning">
 413                                         <em>(!) Warning: </em>
 414                                         GIF icons cannot be included in spritesheets by compass, use the old icon images for icons, gif icons will be updated to PNG.
 415                                 </div>
 416
 417                                 <p>
 418                                         In order to utilize this development feature all img tags relating to icons should move from the old e.g.
 419                                 </p>
 420
 421                                 <code>
 422                                         echo html::image(<br />
 423                                         &nbsp;&nbsp;$this->add_path('icons/12x12/shield-'.strtolower($row['status']).'.png'),<br />
 424                                         &nbsp;&nbsp;array(<br />
 425                                                 &nbsp;&nbsp;&nbsp;&nbsp;'title' => $row['status'], 'alt' => $row['status'], <br />
 426                                                 &nbsp;&nbsp;&nbsp;&nbsp;'style' => 'margin-bottom: -2px'<br />
 427                                         &nbsp;&nbsp;)<br />
 428                                         );
 429                                 </code>
 430
 431                                 <p>
 432                                         To the new
 433                                 </p>
 434
 435                                 <code>
 436                                         echo '&lt;span class="icon-12 x12-'.
 437                                                 <br />&nbsp;&nbsp;strtolower($row['status']).'" '.
 438                                                 <br />&nbsp;&nbsp;'     title="'.$row['status'].'"&gt;&lt;/span&gt;';<br /><br />
 439                                         // The style is omitted because inline style is no-no
 440                                 </code>
 441
 442                                 <p>
 443                                         Resulting in, maybe something like this
 444                                 </p>
 445
 446                                 <code>
 447                                         &lt;span class="icon-12 x12-up" title="up"&gt;&lt;/span&gt;';<br />
 448                                 </code>
 449
 450                                 <p>
 451                                         The class is broken down to
 452                                 </p>
 453
 454                                 <table>
 455                                         <tr>
 456                                                 <td>icon-12</td><td>x12-</td><td>up</td>
 457                                         </tr>
 458                                         <tr>
 459                                                 <td>This is an icon and it is of size 12x12</td>
 460                                                 <td>It is part of the spritesheet x12 (like all 12x12 icons)</td>
 461                                                 <td>And it's the one formerly named up (up.png)</td>
 462                                         </tr>
 463                                 </table>
 464
 465                                 <p>
 466                                         The class for icons such as shield-not-disabled would hence become:
 467                                 </p>
 468
 469                                 <table>
 470                                         <tr>
 471                                                 <td>icon-16</td><td>x16-</td><td>shield-not-disabled</td>
 472                                         </tr>
 473                                         <tr>
 474                                                 <td>This is an icon and it is of size 16x16</td>
 475                                                 <td>It is part of the spritesheet x16 (like all 16x16 icons)</td>
 476                                                 <td>And it's the one formerly named shield-not-disabled (shield-not-disabled.png)</td>
 477                                         </tr>
 478                                 </table>
 479
 480                                 <h3>Global Auxiliary Selectors</h3>
 481
 482                                 <h4>.alpha</h4>
 483                                 <p>
 484                                         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.
 485                                 </p>
 486
 487                                 <h4>.right</h4>
 488                                 <p>
 489                                         Floats the elements to the right and nothing else. Use .clear to restore.
 490                                 </p>
 491
 492                                 <h4>.left</h4>
 493                                 <p>
 494                                         Floats the elements to the left and nothing else. Use .clear to restore.
 495                                 </p>
 496
 497                                 <h4>.clear</h4>
 498                                 <p>
 499                                         Clears both on the element and nothing else. Always use after floated elements to restore normal flow.
 500                                 </p>
 501
 502                                 <h4>.none (legacy .white)</h4>
 503                                 <p>
 504                                         Makes the element completely transparent by setting 0 opacity.
 505                                 </p>
 506
 507                                 <h4>.nullify (legacy .white)</h4>
 508                                 <p>
 509                                         Removes a lot of things, this one is already in use by all tables by default.
 510                                 </p>
 511                                 <ul>
 512                                                 <li>background: transparent</li>
 513                                                 <li>border-spacing: 0</li>
 514                                                 <li>vertical-align: top</li>
 515                                                 <li>outline: none</li>
 516                                                 <li>border: none</li>
 517                                                 <li>margin: 0</li>
 518                                                 <li>padding: 0</li>
 519                                         </ul>
 520
 521                         </div>
 522                 </div>
 523
 524         </body>
 525 </html>