Customizing the WiConnect Web App

The WiConnect Web App demonstrates the full capability of the WiConnect HTTP RESTful API. See WiConnect 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 ACKme styling to match the sensors.com style.

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 WiConnect 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 WiConnect HTTP server, in order to run WiConnect commands.

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

Set Up and Prerequisites

Obtain a copy of the WiConnect Web App development system from https://github.com/ackme/WiConnectWebApp

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

Web App Languages and Libraries

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

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

The WiConnect Web App uses the following JavaScript libraries:

Backbone.js - Web App development framework - MV* (Models Views etc)
jQuery - backbone dependency - DOM management
Underscore - backbone dependency - js utility functions
Async.js - handles synchronous and asynchronous tasks - allows WiConnect commands to run synchronously
WiConnect JavaScript API - Framework for controlling a WiConnect device using the HTTP RESTful API

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 WiConnect Web App, familiarity with these languages and frameworks is recommended.

Setting up the WiConnect Web App Development Environment

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

To set up the WiConnect Web App development system, follow the /WiConnectWebApp/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 /WiConnectWebApp directory.

Setting up the WiConnect Module

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 WiConnect module 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 WiConnect Terminal and issue the following WiConnect command sequence on the device:

WiConnect Commands Description

WiConnect 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`


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 WiConnect terminal displays output similar to:

WiConnect-2.1.0.15, Built:2015-02-02 20:23:14 for AMW006.4, Board:AMW006-E03.2
[Ready]
[Associating to ackme]
> 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 WiConnect module and the development host.

The WiConnect module 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 /WiConnectWebApp/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 /WiConnectWebApp 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/wiconnect.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/wiconnect.js.gz (64.6 kB)
Created out/webapp/wiconnect.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.

Changing the Logo

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

The logo is specified in the file /WiConnectWebApp/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 /WiConnectWebApp/out/webapp/. Stylesheet relative URLs are determined relative to the /WiConnectWebApp/out/wiconnect.css file, which is the product created from the various /WiConnectWebApp/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.

Changing the Logo Link

In the default WiConnect Web App, the logo links to the http://ack.me site.

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

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

  body
    div.nav
      a.wlan(href="//ack.me", 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 http://jade-lang.com/.

Changing Styles

The styles of the WiConnect Web App are determined by /WiConnectWebApp/out/wiconnect.css. This is built from the /WiConnectWebApp/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 WiConnect 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 /WiConnectWebApp/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 /WiConnectWebApp/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:

delete the ''array item in theapp.js appViews'' array.
Be sure to maintain the JavaScript array syntax: elements are comma-separated and there is no comma after the final element.
delete the /WiConnectWebApp/public/js/views/cloud.js file.

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 /WiConnectWebApp/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:

el: DOM element id, used in the view definition
nav: the title as it appears in the navigation menu
view: the Backbone.js View object - must match the object defined in the view definition
modes: lists the WiConnect Web App modes for which the element is displayed:
- setup (Setup mode)
- softap (Local mode)
- wlan (Internet mode)

Download the myfeature.js file and add it to the /WiConnectWebApp/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 WiConnect Module

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 WiConnect module, 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 WiConnect Terminal on the module, using the http_download command. The files must be in the /WiConnectWebApp/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.

Change Log

Modified	Changes	WiConnect Version Required
2015-Mar-09	Created	2.0+