README.md

   1 # OpenDaylight DLUX \r
   2 \r
   3 OpenDaylight DLUX is a Javascript stateless user interface that communicates with the service backend to provide a consistent and user-friendly interface to interact with OpenDaylight projects and base controller.\r
   4 \r
   5 \r
   6 ## Quick Start\r
   7 \r
   8 Install Node.js then:\r
   9 \r
  10 ```sh\r
  11 $ sudo npm -g install grunt-cli karma bower\r
  12 $ npm install\r
  13 $ bower install\r
  14 $ grunt watch\r
  15 ```\r
  16 \r
  17 Finally, open `file:///path/to/ng-boilerplate/build/index.html` in your browser.\r
  18 \r
  19 If you want to run the dlux on local node server, use command\r
  20 \r
  21 $ grunt live\r
  22 \r
  23 It will start server at http://localhost:9000/. It expects your controller to be running at localhost:8080. We can change it in app.js.\r
  24 \r
  25 To generate OSGi bundle for controller, run\r
  26 \r
  27  $ mvn clean install\r
  28 \r
  29 It will generate dlux-web-0.1.0-SNAPSHOT.jar under target/.\r
  30 Copy this jar bundle to plugins directory inside your controller distribution. Then, you can access Dlux UI at http://localhost:8080/dlux/index.html.\r
  31 \r
  32 ## Overall Directory Structure\r
  33 \r
  34 At a high level, the structure looks roughly like this:\r
  35 \r
  36 ```\r
  37 dlux/\r
  38   |- grunt-tasks/\r
  39   |- karma/\r
  40   |- src/\r
  41   |  |- app/\r
  42   |  |  |- <app logic>\r
  43   |  |- assets/\r
  44   |  |  |- <static files>\r
  45   |  |- common/\r
  46   |  |  |- <reusable code>\r
  47   |  |- less/\r
  48   |  |  |- main.less\r
  49   |- vendor/\r
  50   |  |- angular-bootstrap/\r
  51   |  |- bootstrap/\r
  52   |  |- placeholders/\r
  53   |- .bowerrc\r
  54   |- bower.json\r
  55   |- build.config.js\r
  56   |- Gruntfile.js\r
  57   |- module.prefix\r
  58   |- module.suffix\r
  59   |- package.json\r
  60 ```\r
  61 \r
  62 What follows is a brief description of each entry, but most directories contain\r
  63 their own `README.md` file with additional documentation, so browse around to\r
  64 learn more.\r
  65 \r
  66 - `karma/` - test configuration.\r
  67 - `src/` - our application sources. [Read more &raquo;](src/README.md)\r
  68 - `vendor/` - third-party libraries. [Bower](http://bower.io) will install\r
  69   packages here. Anything added to this directory will need to be manually added\r
  70   to `build.config.js` and `karma/karma-unit.js` to be picked up by the build\r
  71   system.\r
  72 - `.bowerrc` - the Bower configuration file. This tells Bower to install\r
  73   components into the `vendor/` directory.\r
  74 - `bower.json` - this is our project configuration for Bower and it contains the\r
  75   list of Bower dependencies we need.\r
  76 - `build.config.js` - our customizable build settings; see "The Build System"\r
  77   below.\r
  78 - `Gruntfile.js` - our build script; see "The Build System" below.\r
  79 - `module.prefix` and `module.suffix` - our compiled application script is\r
  80   wrapped in these, which by default are used to place the application inside a\r
  81   self-executing anonymous function to ensure no clashes with other libraries.\r
  82 - `package.json` - metadata about the app, used by NPM and our build script. Our\r
  83   NPM dependencies are listed here.\r
  84 \r
  85 \r
  86 ### The Build System\r
  87 \r
  88 The best way to learn about the build system is by familiarizing yourself with\r
  89 Grunt and then reading through the heavily documented build script,\r
  90 `Gruntfile.js`. But you don't need to do that to be very productive with\r
  91 `ngBoilerplate`. What follows in this section is a quick introduction to the\r
  92 tasks provided and should be plenty to get you started.\r
  93 \r
  94 The driver of the process is the `delta` multi-task, which watches for file\r
  95 changes using `grunt-contrib-watch` and executes one of nine tasks when a file\r
  96 changes:\r
  97 \r
  98 * `delta:gruntfile` - When `Gruntfile.js` changes, this task runs the linter\r
  99   (`jshint`) on that one file and reloads the configuration.\r
 100 * `delta:assets` - When any file within `src/assets/` changes, all asset files\r
 101   are copied to `build/assets/`.\r
 102 * `delta:html` - When `src/index.html` changes, it is compiled as a Grunt\r
 103   template, so script names, etc., are dynamically replaced with the correct\r
 104   values configured dynamically by Grunt.\r
 105 * `delta:less` - When any `*.less` file within `src/` changes, the\r
 106   `src/less/main.less` file is linted and copied into\r
 107   `build/assets/ng-boilerplate.css`.\r
 108 * `delta:jssrc` - When any JavaScript file within `src/` that does not end in\r
 109   `.spec.js` changes, all JavaScript sources are linted, all unit tests are run,\r
 110   and the all source files are re-copied to `build/src`.\r
 111 * `delta:coffeesrc` - When any `*.coffee` file in `src/` that doesn't match\r
 112   `*.spec.coffee` changes, the Coffee scripts are compiled independently into\r
 113   `build/src` in a structure mirroring where they were in `src/` so it's easy to\r
 114   locate problems. For example, the file\r
 115   `src/common/titleService/titleService.coffee` is compiled to\r
 116   `build/src/common/titleService/titleService.js`.\r
 117 * `delta:tpls` - When any `*.tpl.html` file within `src/` changes, all templates\r
 118   are put into strings in a JavaScript file (technically two, one for\r
 119   `src/common/` and another for `src/app/`) that will add the template to\r
 120   AngularJS's\r
 121   [`$templateCache`](http://docs.angularjs.org/api/ng.$templateCache) so\r
 122   template files are part of the initial JavaScript payload and do not require\r
 123   any future XHR.  The template cache files are `build/template-app.js` and\r
 124   `build/template-common.js`.\r
 125 * `delta:jsunit` - When any `*.spec.js` file in `src/` changes, the test files\r
 126   are linted and the unit tests are executed.\r
 127 * `delta:coffeeunit` - When any `*.spec.coffee` file in `src/` changes, the test\r
 128   files are linted, compiled their tests executed.\r
 129 \r
 130 As covered in the previous section, `grunt watch` will execute a full build\r
 131 up-front and then run any of the aforementioned `delta:*` tasks as needed to\r
 132 ensure the fastest possible build. So whenever you're working on your project,\r
 133 start with:\r
 134 \r
 135 ```sh\r
 136 $ grunt watch\r
 137 ```\r
 138 \r
 139 And everything will be done automatically!\r
 140 \r
 141 ### Build vs. Compile\r
 142 \r
 143 To make the build even faster, tasks are placed into two categories: build and\r
 144 compile. The build tasks (like those we've been discussing) are the minimal\r
 145 tasks required to run your app during development.\r
 146 \r
 147 Compile tasks, however, get your app ready for production. The compile tasks\r
 148 include concatenation, minification, compression, etc. These tasks take a little\r
 149 bit longer to run and are not at all necessary for development so are not called\r
 150 automatically during build or watch.\r
 151 \r
 152 To initiate a full compile, you simply run the default task:\r
 153 \r
 154 ```sh\r
 155 $ grunt\r
 156 ```\r
 157 \r
 158 This will perform a build and then a compile. The compiled site - ready for\r
 159 uploading to the server! - is located in `src/main/resources/pages`, taking a cue from\r
 160 traditional software development. To test that your full site works as\r
 161 expected, open the `src/main/resources/pages/index.html` file in your browser. Voila!\r
 162 \r
 163 ### Maven Build\r
 164 \r
 165 Maven is added to generate an OSGi compatible bundle that can be shipped with Opendaylight Controller.\r
 166 Maven internally runs grunt production ready build and generate a jar out of it.\r
 167 Once you successfully run 'mvn clean install', the OSGi bundle jar gets generated under target/.\r
 168 ### Live Reload!\r
 169 \r
 170 DLUX also includes [Live Reload](http://livereload.com/), so you no\r
 171 longer have to refresh your page after making changes! You need a Live Reload\r
 172 browser plugin for this:\r
 173 \r
 174 - Chrome - [Chrome Webstore](https://chrome.google.com/webstore/detail/livereload/jnihajbhpnppcggbcgedagnkighmdlei)\r
 175 - Firefox - [Download from Live Reload](http://download.livereload.com/2.0.8/LiveReload-2.0.8.xpi)\r
 176 - Safari - [Download from Live Reload](http://download.livereload.com/2.0.9/LiveReload-2.0.9.safariextz)\r
 177 - Internet Explorer - Surely you jest.\r
 178 \r
 179 Note that if you're using the Chrome version with `file://` URLs (as is the\r
 180 default with `ngBoilerplate`) you need to tell Live Reload to allow it. Go to\r
 181 `Menu -> Tools -> Extensions` and check the "Allow access to file URLs" box next\r
 182 to the Live Reload plugin.\r
 183 \r
 184 When you load your page, click the Live Reload icon in your toolbar and\r
 185 everything should work magically. w00t!\r
 186 \r
 187 If you'd prefer to not install a browser extension, then you must add the\r
 188 following to the end of the `body` tag in `index.html`:\r
 189 \r
 190 ```html\r
 191 <script src="http://localhost:35729/livereload.js"></script>\r
 192 ```\r
 193 \r
 194 Boom!\r
 195 \r
 196 ### Testing\r
 197 \r
 198 Tests can be run via grunt-watch command. It opens separate Chrome instance for running tests. This instance need to be open\r
 199 at all times (or at least during the time you want tests to be executed). Note on test execution speed - Chrome is at lower CPU \r
 200 priority when minimalized, or tab where are test executed is not active. This grealy decreases test execution speed, so in that \r
 201 case, just bring up the Chrome and/or activate tab with tests. Test are executed every time on Grunt jshint command.\r
 202 \r
 203 If you want to create/alter new task or command in Gruntfile and want to plug in test execution, you can add karma:unit to new \r
 204 Grunt task or karma:unit:run to Grunt command.\r
 205 \r
 206 If you are writing tests, they should be in same folder as tested file in form <TESTED_FILE>.spec.js