README.md

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