UI2 Sample application

This application, created from the ONOS UI2 archetype can be deployed in 2 ways

• As a [standalone application](#Standalone Application outside of ONOS) outside of ONOS OR
• As an [application embedded](#Application embedded within ONOS) within ONOS

There are 2 main parts to it:

• An ONOS OSGi Java bundle that is packaged as an ONOS OAR file, and can be deployed in to a running ONOS system
• A JavaScript library that may be embedded within an Angular Web project

${symbol_h2} Standalone Application outside of ONOS In the standalone scenario this library can continue to be built with Maven like:

• mvn clean install

The app/BUILD.rename and web/${artifactId}/BUILD.rename files can be discarded or ignored because they are only for building with Bazel.

The ONOS OAR application may be installed with

onos-app localhost install! app/target/${artifactId}-app-1.0-SNAPSHOT.oar

The JavaScript GUI library ${artifactId}-gui-lib-1.0.0.tgz may be included in a new Angular Project by adding the line:

"${artifactId}-gui-lib": "file:../${artifactId}/web/${artifactId}-gui/${artifactId}-gui-lib-1.0.0.tgz"

(ensuring the path is correct) to the dependencies section of the package.json of the new Angular application.

Then in the main folder of the new Angular app run

npm install ${artifactId}-gui-lib gui2-fw-lib d3

Add to routing

Finally to use the ${artifactId}-gui-lib in your new Angular application, add it to the Angular Router and make a link to it

• Add a route to it the new app in the file src/app/app-routing.module.ts add the following to the "routes" array:

  {
    path: '${artifactId}-gui',
    loadChildren: '${artifactId}-gui-lib#${appNameTitle}GuiLibModule'
  }

and

 import { ${appNameTitle}GuiLibModule } from '${artifactId}-gui-lib';

in the imports section at the top of the same file.

• Add a link to the Library in new Application's main page at src/app/app.component.html as <a routerLink="/${artifactId}-gui" routerLinkActive="active">${artifactId} page</a> before <router-outlet>

Add gui2-fw-lib to module

• In the Angular app's main module src/app/app.module.ts add to the providers section:

  providers: [
    { provide: LogService, useClass: ConsoleLoggerService },
    { provide: 'Window', useValue: window }
  ],

and to the imports section:

    Gui2FwLibModule

and to the import section:

import { Gui2FwLibModule, ConsoleLoggerService, LogService } from 'gui2-fw-lib';

Deploy

At this stage you should be able to build the new application:

ng build --prod

and then copy the files to the html folder of an Apache or Nginx web server

cp -r dist/<your-app-name>/* /var/www/html

And you should be able to open it in your browser at http://localhost

${symbol_h2} Application embedded within ONOS To embed the application inside ONOS (permanently add it to the ONOS code base) move the application folder in to the ~/onos/apps directory (ensuring its name does not clash with anything already there).

Run

cd ~/onos/apps/${artifactId} && \
    mvn -pl web/${artifactId}-gui install && \
    mvn -pl web/${artifactId}-gui clean

once inside the folder - this is the easiest way to fetch the dependent node modules for the Angular application.

To ensure it gets built along with ONOS rename the files BUILD.rename, app/BUILD.rename and web/${artifactId}/BUILD.rename to BUILD, and remove the pom.xml files, and some extra files left over from the build.

cd ~/onos/apps/${artifactId} && \
mv BUILD.rename BUILD && \
mv app/BUILD.rename app/BUILD && \
mv web/${artifactId}-gui/BUILD.rename web/${artifactId}-gui/BUILD && \
rm pom.xml && \
rm app/pom.xml && \
rm web/${artifactId}-gui/pom.xml && \
mv web/${artifactId}-gui/gitignore web/${artifactId}-gui/.gitignore && \
chmod +x web/${artifactId}-gui/ng-test.sh && \
rm -rf web/${artifactId}-gui/node_modules/rxjs/src

In the file

• ~/onos/apps/${artifactId}/web/${artifactId}-gui/projects/${artifactId}-gui-lib/package.json change the version to be the current version of ONOS e.g. 2.2.0

Add a reference to the app in ~/onos/tools/build/bazel/modules.bzl at the end of the ONOS_APPS section as:

"//apps/${artifactId}:onos-apps-${artifactId}-oar",

In the file ~/onos/web/gui2/BUILD in the genrule section _onos-gui2-ng-build add to the srcs section:

"//apps/${artifactId}/web/${artifactId}-gui:${artifactId}-gui-lib-build",

and in the cmd section of the same genrule add the following 3 lines (just before the comment "# End of add in modules from external packages"):

" ${appNameAllCaps}_GUI_LIB_FILES=($(locations //apps/${artifactId}/web/${artifactId}-gui:${artifactId}-gui-lib-build)) &&" +  # An array of filenames - sorted by time created
" tar xf $$ROOT/$${${appNameAllCaps}_GUI_LIB_FILES[0]} &&" +
" mv package/ node_modules/${artifactId}-gui-lib/ &&" +

Add to routing

Finally to use the ${artifactId}-gui-lib in the ONOS GUI, add it to the Angular Router

• Add it as a route to ~/onos/web/gui2/src/main/webapp/app/onos-routing.module.ts in the "routes" array as:

  {
    path: '${artifactId}-gui',
    loadChildren: '${artifactId}-gui-lib#${appNameTitle}GuiLibModule'
  },

and in the imports section at the top of the same file

 import { ${appNameTitle}GuiLibModule } from '${artifactId}-gui-lib';

Run the build

Run Bazel build with

cd ~/onos && \
ob

or equivalent.

Run the application

Start ONOS in the normal way.

Using the ONOS command line, activate the application:

app activate ${artifactId}

To turn on ONOS Server side logging, from the same ONOS CLI use:

log:set DEBUG ${package}
log:set DEBUG org.onosproject.ui.impl

On the ONOS GUI the navigation menu should show the new application link. Clicking on it will navigate to the new app (there is a system of lazy-loading implemented here so that applications are not loaded until they are first used).

Rebuild

To rebuild and run the web side of the application do:

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

To rebuild and run the server side of the application do:

bazel build //apps/${artifactId}:onos-apps-${artifactId}-oar && \
    onos-app localhost reinstall! bazel-bin/apps/${artifactId}/onos-apps-${artifactId}-oar.oar

App structure

The application demonstrates some major concepts:

• The use of Angular 7 concepts like Modules, Components, Service

• The top level component - contains the "Fetch Data" button and the connection to the server backend through a WebSocket

• Passing a number in the request

• Receiving a JSON object in reply

• Reuse of items from the gui2-fw-lib - with LogService, WebSocketService and IconComponent

• The use of a child component (WelcomeComponent) in 3 different ways

  • The passing of Inputs to this component
  • The passing of an Event out when the component is clicked

• The embedding of SVG content in to the web page

• The use of TypeScript (as opposed to JavaScript or ECMAScript directly) to ensure type safety