ONOS GUI 2.1.0

This project is based on Angular 7 and ES6 (aka ES2015), as an alternative to the 1.0.0 GUI which was based off AngularJS 1.3.5

Building, testing and running lint are all handled by Bazel. See web/gui2/BUILD file.

To use this new GUI you simply have to start the GUI in a running ONOS at the onos> cli:

app activate gui2

and the gui will be accessible at http://localhost:8181/onos/ui

Gui2 can also be loaded every time ONOS starts by adding it to ONOS_APPS

export ONOS_APPS=${ONOS_APPS:-drivers,openflow,gui2}

The original legacy GUI is also loadable as an app, and is available at the same web resource onos/ui The legacy GUI should be disabled if GUI2 is active and vice versa

app deactivate gui

As usual with ONOS if you want to run it in a different language set the ONOS_LOCALE environment variable to the locale you want before starting onos. e.g.

ONOS_LOCALE=fr_FR SHLVL=1 bazel run onos-local -- clean debug

Architecture

The whole application comprises of a number of modules on the client side

gui2-fw-lib This is a collection of client side component, services and base classes that are reused among all modules more details..
gui2-topo-lib This is the Topology view only more details..
fm_gui_lib This is the Fault Management table more details..
gui2 This is the front end entry point application and brings together all other libraries. It also holds all of the tabular applications such as Applications view and Devices view, and manages the routing between the different views.

All of these modules talk to the backend server mainly through a WebSocket connection passing JSON snippets asynchronously in both directions. In some places the client side code loads data through a plain HTTP GET call, and these are served by servlets on the backend. Similarly raster graphics are loaded through a servlet.

Much of the graphics in the application are made from SVG paths and primitive objects, and are displayed smoothly by HTML5 compatible browsers. Occasionally the d3 libraries (such as d3-force) are used to help position graphics, but an over dependence on d3 is mainly avoided.

The main framework used is Angular 7, with a strong emphasis on making resuable components, directives, services and classes. Angular Routing and animation are also used.

Issues

Issues found on the GUI2 should be added to the existing list on the ONOS GUI Jira Kanban board (requires Jira login)

Development

There are 2 ways to go about development -

rebuild the code and rerun through Bazel (much like can be done with any ordinary ONOS app) (recommended for most people) OR
use Angular 7 CLI (ng command) to rebuild on the fly (faster for development). Be aware that if you are just changing the topology view it does not require all of the steps that gui2 does - see its own README for more details

For 1) if you change the code you can redeploy the application without restarting ONOS with (requires you to be in ~/onos directory):

bazel build //web/gui2:onos-web-gui2-oar && onos-app localhost reinstall! bazel-bin/web/gui2/onos-web-gui2-oar.oar

For 2) it's well worth becoming familiar with Angular CLI.

(this has the advantage of debug symbols and the code not is uglified and minimized)

The project is created with Angular CLI v7 to simplify development of the browser side code. It is complicated to set up, but is worth the effort if you have more than a few days worth of development to do. Since data is retrieved through WebSockets there is a requirement to run ONOS in the background.

There is no need to install node, npm or ng again on your system, and indeed if they are already installed, it's best to use the versions of these that's used by Bazel in ONOS.

Add the following 2 entries to the start of your PATH environment variable.

~/.cache/bazel/_bazel_scondon/8beba376f58d295cf3282443fe02c21a/external/nodejs/bin/nodejs/bin

(where ~/.cache/bazel/_bazel_scondon/8beba376f58d295cf3282443fe02c21a should be replaced by an equivalent folder on your system)

~/onos/web/gui2-fw-lib/node_modules/@angular/cli/bin/

The first time you run this you will have to go to the framework folder and run "npm install"

cd ~/onos/web/gui2-fw-lib && \
npm install

This will install all the vendor Javascript implementations that are listed in package.json (including 'ng' - the Angular CLI command) in to ~/onos/web/gui2-fw-lib/node_modules

After this you should be able to cd in to ~/onos/web/gui2-fw-lib and run 'ng version' and see:

Angular CLI: 7.0.4
Node: 8.11.1
OS: linux x64
Angular: 7.0.2

GUI FW Lib

The GUI2 framework is in ~/onos/web/gui2-fw-lib and the GUI application is in ~/onos/web/gui2 (and depends on the framework).

The GUI2 framework is a library inside its own mini application (unrelated to the main GUI application) - every thing of importance is in projects/gui2-fw-lib. The own application is just a wrapper around the framework library - it has to be there for Angular CLI to work and can be useful for testing parts of the framework in isolation.

For build method 2) above if you make any changes here or are using it for the first time it will need to be built. From ~/onos/web/gui2 run:

pushd ~/onos/web/gui2-fw-lib && \
ng build gui2-fw-lib && \
cd dist/gui2-fw-lib && \
npm pack && \
popd && \
npm install gui2-fw-lib

This packages the Framework up in to ~/onos/web/gui2-fw-lib/dist/gui2-fw-lib/gui2-fw-lib-2.1.0.tgz

GUI2 Topo library

The GUI2 Topology is in ~/onos/web/gui2-topo-lib and the GUI application includes this Topology application through the onos-routing-module. The Topology app has its own README file.

For build method 2) above if you make any changes here or are using it for the first time it will need to be built. From ~/onos/web/gui2 run:

pushd ~/onos/web/gui2-topo-lib && \
ng build gui2-topo-lib && \
cd dist/gui2-topo-lib && \
npm pack && \
popd && \
npm install gui2-topo-lib

This packages the Topo View up in to onos/web/gui2-topo-lib/dist/gui2-topo-lib/gui2-topo-lib-2.1.0.tgz

GUI2 Application

The application contains the ONOS index.html and all of the tabular views and the topology view. It references the gui2-fw-lib and gui2-topo-lib as just other dependencies.

For build method 2) above to use this application in Angular CLI for development on your system, you need to:

Change directory in to onos/web/gui2 - this is where you will run the ng command from.
Run npm install once from this folder to add dependencies
Then run 'ng version' from onos/web/gui2 and an additional version should be shown Angular: 7.0.2
Temporarily make a change to disable authentication in UIWebSocket.java
Temporarily make a change to disable external routes in onos-routing.module.ts
Create symbolic links for some CSS files

Disable authentication and external routes

Remember this is only for build method 2) above

Before the server can be run a couple of small adjustments need to be temporarily made

The file ~/onos/web/gui/src/main/java/org/onosproject/ui/impl/UiWebSocket.java needs to be adjusted to remove authentication
The file ~/onos/web/gui2/src/main/webapp/app/onos-routing.module.ts needs to be adjusted to remove references to routes in external applications

These changes are given in Appendix A at the end of this document - these changes should not be checked in though - as they are not required (and will break) the GUI2 embedded in ONOS.

Create symbolic links for CSS files

Also some files need to be symbolically linked - these should no be checked in

cd ~/onos/web/gui2/src/main/webapp/app && \
mkdir -p fw/widget && mkdir -p fw/layer && \
cd fw/layer && ln -s ~/onos/web/gui2-fw-lib/projects/gui2-fw-lib/src/lib/layer/loading.service.css && \
cd ../widget && \
ln -s ~/onos/web/gui2-fw-lib/projects/gui2-fw-lib/src/lib/widget/panel.css && \
ln -s ~/onos/web/gui2-fw-lib/projects/gui2-fw-lib/src/lib/widget/panel-theme.css && \
ln -s ~/onos/web/gui2-fw-lib/projects/gui2-fw-lib/src/lib/widget/table.css && \
ln -s ~/onos/web/gui2-fw-lib/projects/gui2-fw-lib/src/lib/widget/table.theme.css

After this it will be possible to build/test/lint/run the application inside the Angular CLI without errors.

ng build --prod && \
ng lint && \
ng test --watch=false

Development server

Finally the application can be run, and will be available at http://localhost:4200

ng serve --aot

Run ng serve --aot for a dev server (because we are using ES6, we must use AOT). Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files.

Press Ctrl-Shift-I in Chrome and Firefox to bring up the developer tools and the browser console.

There are certain extra debugging can be turned on by adding the parameter 'debug' For example to turn extra logging for WebSockets add on ?debug=txrx

On the Apps view - icons will appear to be missing - this is because they use a relative path to source the image, and this path is not available in this 'ng serve' mode. The icons work fine in the mode where it's run inside ONOS.

Navigating

In this development mode navigation is not available, and to to jump to other view, replace the 'device' at the end of the URL with the route you want to follow e.g. 'app' for the Applications view or 'topo' for the Topology view

Code scaffolding

Build

The build is handled through the web/gui2/BUILD file. This downloads Node, NPM and Angular CLI It runs ng build --prod --extract-css and copies everything over in to WEB-INF/classes/dist

To run it manually in Angular CLI run ng build (and add on --prod --extract-css --watch as necessary to alter its behaviour)

Running unit tests

This is automatically done when using "bazel test " - see the web/gui2/BUILD file for more details.

To run it manually in Angular CLI run ng test --watch to execute the unit tests via Karma. Running it directly like this will test with both Firefox and Chrome. To use only one use the --browsers argument

Running checkstyle (lint)

This is automatically done when using "bazel test" - see the web/gui2/BUILD file for more details.

To run it manually in Angular CLI run ng lint to run codelyzer on your code, according to the rules in tslint.json

Running end-to-end tests

To run it manually in Angular CLI run ng e2e to execute the end-to-end tests via Protractor.

Generating documentation

To run it manually in Angular CLI run npm run compodoc to generate documentation via Compodoc

Further help

To get more help on the Angular CLI use ng help or go check out the Angular CLI README.

Appendix A - changes needed to run GUI2 application locally

diff --git a/web/gui/src/main/java/org/onosproject/ui/impl/UiWebSocket.java b/web/gui/src/main/java/org/onosproject/ui/impl/UiWebSocket.java
index e53a00756b..63e538a4db 100644
--- a/web/gui/src/main/java/org/onosproject/ui/impl/UiWebSocket.java
+++ b/web/gui/src/main/java/org/onosproject/ui/impl/UiWebSocket.java
@@ -251,9 +251,7 @@ public class UiWebSocket
             ObjectNode message = (ObjectNode) mapper.reader().readTree(data);
             String type = message.path(EVENT).asText(UNKNOWN);
 
-            if (sessionToken == null) {
-                authenticate(type, message);
-            } else {
+
                 UiMessageHandler handler = handlers.get(type);
                 if (handler != null) {
                     log.debug("RX message: {}", message);
@@ -261,7 +259,6 @@ public class UiWebSocket
                 } else {
                     log.warn("No GUI message handler for type {}", type);
                 }
-            }
 
         } catch (Exception e) {
             log.warn("Unable to parse GUI message {} due to {}", data, e);
diff --git a/web/gui2/src/main/webapp/app/onos-routing.module.ts b/web/gui2/src/main/webapp/app/onos-routing.module.ts
index 60ec9d7da6..3abb62376a 100644
--- a/web/gui2/src/main/webapp/app/onos-routing.module.ts
+++ b/web/gui2/src/main/webapp/app/onos-routing.module.ts
@@ -83,10 +83,10 @@ const onosRoutes: Routes = [
         loadChildren: 'app/view/topology/topology.module#TopologyModule'
     },
 /*  Comment out below section for running locally with 'ng serve' when developing */
-    {
+/*    {
         path: 'alarmTable',
         loadChildren: 'fm-gui2-lib#FmGui2LibModule'
-    },
+    },*/
     {
         path: '',
         redirectTo: 'device', // Default to devices view - change to topo in future