Customizing the Web App

The Web App demonstrates the full capability of the Gecko OS HTTP RESTful API. See Web App . The layout and operation of the web app can be 100% customized to suit your application and your business.

The following simple examples show how to re-style the original Gecko OS styling to match the style of another brand.

If this layout or style does not suit your requirements, the entire web application can be replaced simply by modifying the root file of the Gecko OS webserver with http.server.root_filename .

The Web App Development System

The Web App development system provides a rapid edit-build-test cycle, using a local Web server on the development test machine.

The diagrams below show how the Web App development system works, and how it differs from the Web App production system.

In the development system, the test HTTP server serves the Web App from the development file system, and requires CORS to make REST requests to the Gecko OS HTTP server , in order to run Gecko OS commands.

The Web App Production System

In the production system, the Gecko OS HTTP server serves the Web App from the Gecko OS device file system, and REST requests to the Gecko OS device are made to the same origin.

Set Up and Prerequisites

Obtain a copy of the Web App development system from https://github.com/zentri/ZentriOSWebApp

In the following it is assumed that your working copy is in the directory /ZentriOSWebApp .

Web App Languages and Libraries

The Web App development system uses Jade templates and the Less CSS pre-processing language.

For more information on Jade templates, see https://pugjs.org . Note that Jade has been renamed Pug due to trademark issues.

You can, if you prefer, use traditional HTML and CSS for development. See the /ZentriOSWebApp/README.md file for details.

The Web App uses the following JavaScript libraries:

The style modifications described in this tutorial can be made without detailed knowledge of JavaScript, CSS or Jade.

However to make advanced modifications to the Web App, familiarity with these languages and frameworks is recommended.

Setting up the Web App Development Environment

The Gecko OS WebApp development system uses Node.js , Grunt and Bower for package management and build automation. These tools are free.

To set up the Web App development system, follow the /ZentriOSWebApp/README.md instructions, available on github and in the top level directory of the working copy.

This involves downloading and installing Node.js , then using the node package manager, npm , to install Bower (front end package manager) and Grunt (task runner). Then run npm install and bower install from a command prompt in the /ZentriOSWebApp directory.

Setting up the Gecko OS device

The Web App development system runs a server at http://localhost:5002 , on the machine on which the build system is running.

The Web App development system communicates with a Gecko OS device on the same network. The module needs to run the HTTP server, and Cross Origin Resource Sharing (CORS) must be enabled for the development host domain. The simplest way is to enable CORS for all domains.

Open a Gecko OS Terminal and issue the following Gecko OS command sequence on the device:

Gecko OS Commands Description 

set wlan.ssid               <NETWORK NAME>
set wlan.passkey            <NETWORK PASSWORD>
set wlan.auto_join.enabled  1
set http.server.enabled     1
set mdns.name               mymodule
set mdns.enabled            1
set http.server.cors_origin *
save
reboot


Set your Wi-Fi network name
Set your Wi-Fi network password
Enable WLAN auto join
Enable HTTP server
Set mDNS name
Enable mDNS
Enable CORS for all
Save
Reboot

After rebooting, the module Gecko OS terminal displays output similar to: 

Gecko OS-2.1.0.15, Built:2015-02-02 20:23:14 for AMW006.4, Board:AMW006-E03.2
[Ready]
[Associating to Silabs]
> Security type from probe: WPA2-AES
Obtaining IPv4 address via DHCP
IPv4 address: 10.5.6.55
Starting mDNS
mDNS domain: mymodule.local
HTTP and REST API server listening on port: 80
[Associated]

Configuring the Module and Development Host Addresses

The Web App development system needs the IP address or name of both the Gecko OS device and the development host.

The Gecko OS device address allows the HTTP RESTful API calls to the module from the development host Web server test Web App.

The development host address allows deployment of the changed web app files to the module from the localhost development Web server.

Open the file /ZentriOSWebApp/config.json and set the addresses. For example: 

{
  "device": "mymodule",
  "localIP": "10.5.6.60",
  "port": "5002"
}

You can also change the development Web server port if desired.

Building the Web App and Running the Test Server

To build the Web App, at a command prompt, in the /ZentriOSWebApp directory, issue the command: grunt

Grunt runs tasks and displays output accordingly, similar to: 

Running "build" task
...
other tasks
....
Running "less:build" (less) task
File out/webapp/Gecko OS.css created: 428.36 kB → 420.99 kB

Running "jade:build" (jade) task
File ./out/index.html created.
File ./out/webapp/unauthorized.html created.

Running "compress:build" (compress) task
Created out/webapp/Gecko OS.js.gz (64.6 kB)
Created out/webapp/Gecko OS.css.gz (151.3 kB)

Running "server" task
Web server running at http://localhost:5002.

The "server" task continues until you halt it. While it is running you can view the test Web App Page.

To halt the "server" task and grunt execution, type Ctrl-C .

Opening the Test Web App Page

While the "server" task is running, in a web browser, open http://localhost:5002 .

The Silabs logo appears at the top left corner of the Web App. You can change this to a logo of your choice.

The logo is specified in the file /ZentriOSWebApp/public/less/logo.less/ .

It is set up as a background image for the .logo css class.

The first lines of the logo.less file are as follows: 

.logo {
  height: 100px;
  // background-image: url('logo.png');
  background-image: url('data:image/svg+xml;...
...

In the unmodified logo.less file partially shown above, the logo image is created with an inline svg file specified with a data url.

Logo Image File

To substitute your own logo image, in logo.less , uncomment the line: 

 // background-image: url('logo.png');

and comment out the line that begins: 

background-image: url('data:image/svg+xml;

Place your own logo image file in the directory /ZentriOSWebApp/out/webapp/ . Stylesheet relative URLs are determined relative to the /ZentriOSWebApp/out/Gecko OS.css file, which is the product created from the various /ZentriOSWebApp/public/less/*.less/ files during the build process.

Replace the filename 'logo.png' with the name of your substitute logo file. For example: 

background-image: url('sdc_logo.png');

Logo Dimensions and Aspect Ratio

The logo dimensions are by default: height:100px; width:280px;

Create a logo of the specified proportions to fit into the available space, or modify the dimensions in the logo.less file if you prefer.

If your logo has a different aspect ratio, you can leave the width of 280px unchanged and calculate a new height as follows: 

new_height = my_logo_height*(my_logo_width/280)

Set the new height in the logo.less .logo class height parameter. For example, 

.logo {
  height: 69px;
  ...
}

Logo Background Color

You can change the logo background-color parameter in the logo.less .logo class.

To allow the background of the navigation pane (div.nav element) to show through, remove the background-color style setting. For example: 

.logo {
  height: 69px;
  ...
  //background-color: #333;
  ...
}

To see the results of any change, rebuild the web app: stop the "server" task and grunt if it is running ( Ctrl-C ) and run grunt again. Then refresh the Web App page in your web browser.

The link from the logo is specified in the jade template for the index.html file, /ZentriOSWebApp/public/views/index.jade

Open the index.jade file and locate the following lines: 

  body
    div.nav
      a.wlan(href="//zentri.com", data-bypass, target="_blank")
        div.logo

To change the logo link, change the href attribute value. For example: 

...
      a.wlan(href="//sensors.com", data-bypass, target="_blank")
...

Jade templates determine structure from indentation, so be careful not to alter the indentation.

To see the change, run grunt to rebuild the Web App, and refresh the Test Web App page.

For more information on Jade templates, see https://pugjs.org . Note that Jade has been renamed Pug due to trademark issues.

Changing Styles

The styles of the Web App are determined by /ZentriOSWebApp/out/Gecko OS.css . This is built from the /ZentriOSWebApp/public/less/ files.

To change styles, first identify the css class to be altered. You can use your web browser developer tools to identify css classes associated with elements.

Then modify the *.less file that defines the css class definition.

For example, the navigation menu background (div.nav element) is determined by the .nav css class, which is defined in app.less . 

 .nav {
...
    .gradient(@nav-light, @nav-dark);
...
}

The Less variables @nav-light and @nav-dark are defined in variables.less , included at the top of the app.less file: 

@import "variables.less";

In variables.less , change the variables as desired, e.g. 

//@nav-light: #3e3c3d;
@nav-light: #0db8d3;
//@nav-dark: #2d2c2d;
@nav-dark: #0881b6;

The highlights and shadows of the menu items are also set in variables.less as @nav-highlight and @nav-shadow . You can define a Less variable to have the value of another defined Less variable. For example: 

//@nav-highlight: @dark;
@nav-highlight: @nav-dark;
//@nav-shadow: @darkest;
@nav-shadow: @nav-light;

To see the change, run grunt to rebuild the Web App, and refresh the Test Web App page.

Changing Features

Each Web App feature corresponds to a Backbone.js view.

Each view corresponds to a menu item in the main navigation menu, defined in app.js , and to a JavaScript view definition file in the /ZentriOSWebApp/public/js/views folder.

For example, the "Cloud Services" menu item corresponds to the 'cloud' element in the app.js definition of the appViews array: 

var appViews = [
      ...
      {el: 'cloud',  nav: 'Cloud Services',  view: App.Views.Cloud, modes: ['wlan']}
      ...
    ]

The "Cloud Services" feature is also supported by the view definition file /ZentriOSWebApp/public/js/views/cloud.js .

Removing a Feature

To remove a feature, delete the corresponding appViews array element and the corresponding JavaScript view definition file.

For example, to remove the "Cloud Services" feature:

To see the change, run grunt to rebuild the Web App, and refresh the Test Web App page.

Adding a Feature

To add a feature, add a corresponding element to the appViews array, and add a view to the /ZentriOSWebApp/public/js/views/ folder.

For example, to add a simple page called "My Feature", add the following element to the appViews array: 

  {el: 'myfeature',  nav: 'My Feature', view: App.Views.MyFeature, modes: ['wlan']},

Ensure that the array syntax is maintained correctly.

The parameters are as follows:

Download the myfeature.js file and add it to the /ZentriOSWebApp/public/js/views/ folder. This is a minimal view that displays some text.

To see the change, run grunt to rebuild the Web App, and refresh the Test Web App page.

Deploying the Modified Web App to the Gecko OS device

Ensure that the module and development host addresses are correctly configured. See Configuring the Module and Development Host Addresses above.

Ensure that the grunt "server" task is running the development test Web server. To do this, run grunt at the command prompt.

At a separate command prompt, run: 

grunt deploy

In the background, the Web App development system runs the http_download command, on the Gecko OS device, to download files from the development Web server to the module.

You may also need to download other files, such as your logo file. You can do this in a Gecko OS Terminal on the module, using the http_download command. The files must be in the /ZentriOSWebApp/out/ folder. For example, if the development host IP address is 10.5.6.60 : 

hdo http://10.5.6.60:5002/webapp/sdc_logo.png webapp/sdc_logo.png

When deployment is complete, you can open the modified Web App directly from the module. For example, if mDNS is used as described above, open: http://mymodule.local

The Web App operates as shown in the Web App Production System diagram in The Web App Development System above.

Supporting Gecko OS Editions and Versions

Change Log

Modified Changes
2015-Mar-09 Created