Developer HowTo for UI Module

From OSM Public Wiki
Jump to: navigation, search

Getting Started

Check out the UI module from: https://osm.etsi.org/gitweb/?p=osm/UI.git;a=summary

e.g. you can use the command:
git clone https://osm.etsi.org/gerrit/osm/UI.git

Programming Language/Technologies Used

UI modules are written with following languages and frameworks/libraries:

  • Browser/Client-side code: SASS, ReactJS with Alt.js as the Flux framework
  • Server side code: Node.js with ExpressJS, SockJS
  • Packaging code: Webpack
  • Build, deploy code: Bash scripts + optionally make/cmake
  • Testing code: JavaScript with Intern.js for server-side unit tests, Storybook for React components

Code Style

Please use ECMAScript5 (ES5) for the Node.js code and ECMAScript 6 (ES6) for the the user-facing browser code.

Directory Organization

The code is organized into the following high level directories:
| - skyquake/framework/core (Contains the code for the UI framework, plugins and scripts to build and launch the UI framework and plugins.)
| - skyquake/framework/style (Contains common style assets that can be reused by plugins.)
| - skyquake/framework/widgets (Contains common ReactJS components that can be reused by plugins.)
| - skyquake/framework/utils (Contains common utilities that can be reused by plugins.)
| - skyquake/scripts (Contains scripts to build, install and launch the built UI components in the install path.)
| - skyquake/tests (Contains tests for server and client components)
| - skyquake/plugins (Contains several plugins that provide a RESTful API along with views that can be used to drive a certain set of functionality. eg. Account management, LCM, Catalog Composition)


A plugin is distinguished by the directory name under the plugins directory and will contain the following:

  • config.json (required) - Required to expose navigable routes to other plugins as well as to the global navigation component. Look at the one under the launchpad plugin for a comprehensive example.
  • webpack.production.json (required) - Used by the build scripts to webpack the webapp. In most cases, you can just copy this from another plugin such as launchpad.
  • package.json (required) - Contains specifications of third-party node module dependencies for the plugin's API and UI components if your plugin is a node webapp. At a minimum your plugin's API must be exposed through a Express API and hence you will require express here. Look at helloworld plugin for a simple example.
  • routes.js (required) - Declares your Express routes and ties them to specific API helpers.
  • api (optional/recommended) - Only required to keep the organization of API helpers out of the routes file. This contains your actual middleware APIs that may aggregate/filter/massage data from other backends including the SO REST service, external services, etc.
  • src (required) - Contains the browser-side code that will be webpacked and served by the UI framework.

UI Module Architecture

Component Diagram v2.png

Development Environment

Architecturally, the UI module is split up into:

  • A framework sub-component.
  • Several plugin sub-components that are served within the context of the framework and loaded and run in the browser.
  • An API component that creates aggregations and serves a RESTful interface as well as a Websocket interface to code running in the browser.

Framework

The code for the UI framework can be found under skyquake/framework.

The framework sub-component consists of:

  • Plugin Discovery Module, that discovers and loads UI plugins and manages their lifecycle throughout the lifetime of the plugin.
  • Common Assets, such as styles, fonts, icons and common utility functions that plugin developers can use.
  • Plugin Asset Manager, that loads browser-side asset bundle from installed plugins and serves it at a location known to the in-browser code.
  • Plugin REST API Manager + Websocket API Manager (Data Manager), that loads all REST APIs declared in a plugin's routes.js file and serves them at a location known to the in-browser code.
  • Plugin Route Manager, that discovers all declared UI routes in a plugin and serves a RESTful API to a navigation and URL routing component that runs in the browser.
  • Plugin Config Manager, that provides an abstraction for already developed Single Page Applications (SPAs) to be converted to a plugin in the UI framework.
  • View Component Library, that is a set of reusable ReactJS components that plugin developers can use to build UI views and workflows.
  • A Navigation Component, that uses the routes exposed by the Plugin Route Manager and provides a common navigation bar to all plugins.

See below diagram for the interactions that happen between framework components when the UI starts: 

Message Diagram.png

Building the Framework

In the skyquake folder, run the following command: 

npm install

Running the Framework and installed plugins

In the skyquake folder, after you have built the framework, run the following command: 

node skyquake.js

Once running the UI can be accessed in a browser by navigating to: 

http(s)://<ip_or_fqdn>:8000


UI Plugins

UI plugins can be found under skyquake/plugins

A plugin is an encapsulated set of functionality and can be equated to a Single Page Application (SPA). A developer can use the common components from the view component library to speed up the development of a plugin.

A plugin is packaged as a webpack.

Release 0 consists of the following plugins provided in source:

  1. about
  2. composer
  3. debug
  4. launchpad
  5. login
  6. helloworld
  7. goodbyeworld

Developing a UI plugin

To develop a UI plugin:

  1. Add a new folder under skyquake/plugins. Note that the name of the folder must be unique. We recommend using the name of the plugin for naming the folder.
  2. Under the newly created folder add a config.json file with parameters required skyquake to load the plugin. Look at skyquake/plugins/helloworld/config.json for an example.
  3. Under the newly created folder add a routes.js file that declares and implements RESTful routes for the plugin's browser-side code. Look at skyquake/plugins/helloworld/routes.js for an example.
  4. Under the newly created folder add a webpack config file (we recommend the name of the file to be webpack.production.config.json) that will be used to package the plugin into a webpack. Look at skyquake/plugins/helloworld/webpack.production.config.js for an example.
  5. Add your browser-side code that uses the RESTful APIs under the newly created folder and refer to it from config.json. Look at the code under skyquake/plugins/helloworld/src/ for an example.
  6. Add a package.json file with npm dependencies. At a minimum, you should have the webpack npm module in your package.json file. Look at skyquake/plugins/helloworld/package.json for an example.

Building a UI Plugin

To build a single UI plugin, follow these steps:

  1. Change your directory to the plugin folder.
  2. Run the following command to install npm dependencies:
npm install
  1. Run the following command to compile and package the plugin code. The line below assumes your webpack config file is named webpack.production.config.json. Otherwise change it to the appropriate name:
./node_modules/.bin/webpack --config webpack.production.config.json

Running a UI Plugin

When the framework is started, it will run all plugins. A plugin can be accessed in a supported browser (see Supported Browsers section below) by navigating to: 

http(s)://<ip_or_fqdn>:8000/launchpad/? api_server=http(s)://<ip_or_fqdn>&upload_server=http(s)://<ip_or_fqdn>#/


API Component

In Release 0, API's used by all plugins other than helloworld and goodbyeworld plugins are collocated under the api folder.
We recommend to collocate your API implementations along with your plugin as described in the "Developing a UI plugin" section above.

However, to run serve the API's for plugins developed in Release 0, you need to build and run the API server as in the following sections.

Building the API Component

To build the API Component:

  1. Change your directory to api/
  2. Run the following command:
npm install

Running the API Component

Once built, run the following command in the api folder: 

node server.js

The APIs can then be accessed at http(s)://<ip_or_fqdn>:3000


Building the complete UI

For building the complete UI, follow these steps:

  1. Go to the root folder of your repository.
  2. Run the following commands:
./rift-shell
make

For any incremental builds of the UI, follow these steps when in rift-shell:

  1. Go to modules/ui/rw.ui
  2. Run the following command:
cdbuild
  1. Run the following command:
make


Installing the complete UI

For installing the built files from the UI module into the install location, follow these steps when in rift-shell:

  1. Go to modules/ui/rw.ui.
  2. Run the following commands:
cdbuild
make install

The UI gets installed under: .install/usr/share/rw.ui

Running the installed UI components

To run the UI installed in .install/usr/share/rw.ui, follow these steps:

  1. Change your directory to .install/usr/share/rw.ui
  2. Run the following command:
./skyquake/scripts/launch_ui.sh

Supported Browsers

Retrieved from "http:///wikipub/index.php?title=Developer_HowTo_for_UI_Module&oldid=1743"