Creating Wialon App

Wialon Apps are one page web-applications that work in a browser like common sites. In this article we will describe how to create an application for Wialon from the ground up.

To work with external applications, Wialon provides Remote API, which is a set of HTTP requests that permit you to fully interact with Wialon. For a convenient usage of Remote API you can use in browser a special JavaScript library Wialon SDK JS — a set of classes and methods that wrap and execute the Remote API's requests.

In the following example we will create a simple application which authorizes to the Wialon server and displays the current user's name and the list of units available to him.

Step 1: Creating an empty page

First, we will create a folder for our project with the following structure and contents:

    app/               # root folder of the project
       js/
          script.js    # JavaScript file that contains the working logic of the application
       css/
          style.css    # css styles
       index.html      # html markup

index.html — simple layout template

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>New Wialon App</title>
    <link rel="stylesheet" type="text/css" href="css/style.css"/>
  </head>
  <body>
    <p>New Wialon App</p>
    <script src="js/script.js"></script>
  </body>
</html>

style.css — full screen styles

html, body {
  margin: 0;
  padding: 0;
  width: 100%;
  height: 100%;
  color: #333;
  font-family:Arial;
}

script.js

(function() {
  alert('Hello, Wialon!');
})();

Attention! To isolate the logic and the variables of the application from the global context, we have wrapped the JavaScript code in an anonymous self-invoking function.

To check the application, open it in a browser. If everything is correct, a page with the notice New Wialon App will appear on the screen together with the pop-up message Hello, Wialon!

Attention! It is not correct just to open the file in a browser. The applications that use Wialon SDK JS, work correctly only with the protocol http (s) . For a correct work any convenient web server can be used.

Step 2: Connection to Wialon

Script wialon.js

In order to work with the server Wialon, you need to download to the page wialon.js, which contains Wialon SDK JS.

<!-- index.html -->
...
    <p>New Wialon App</p>
    <script src="https://hst-api.wialon.com/wsdk/script/wialon.js"></script>    <script src="js/script.js"></script>
  </body>
</html>

Attention! We have used wialon.js from the server Wialon Hosting. For a correct work with Wialon, indicate your server's address, for example, http://local.wialon.com/wsdk/script/wialon.js.

wialon.js adds to the page a new namespace wialon with a set of classes. We will mostly use wialon.core.Session — a singleton, which contains all the information about the active session and in which the basic authorization, search, creation, etc. methods are realized.

After loading the page it is necessary to initialize the session.

// script.js
(function() { // anonymous self-invoking function
  alert ('Hello, Wialon!');
 
  // session initialization  var session = wialon.core.Session.getInstance();  session.initSession('https://hst-api.wialon.com');})();

Authorization

There are several authorization methods in Wialon. In this example we will use the authorization by token, the method loginToken on js which is called by the query token/login.

// script.js
...
  // session initialization
  var session = wialon.core.Session.getInstance();
  session.initSession('https://hst-api.wialon.com');
 
  // sending an authorization request token/login  var token = 'authorization token';  session.loginToken(token, function(code) {    console.log(code);  });})();

Attention! You can read more about a new authorization method and tokens in the documentation.

Now we will declare the function loginCallback, which will be called after the response to the authorization request and will change the call tokenLogin.

// script.js
...
  // authorization response handler  function loginCallback(code) {    if (code) {      alert('Authorization error: ' + code);    } else {      alert('Successful authorization');    }  }   // sending authorization request token/login
  var token = 'authorization token';
  session.loginToken(token, loginCallback);
})();

Receiving and displaying information

After the authorization one part of the data, for example, the current user, is already available in wialon.core.Session. Other data (like the list of units) must be requested from the server at first.


In order the user's name to be displayed on the screen, we will add a new element div, then add CSS styles for it and display the username.

<!-- index.html -->
...
  <body>
    <div id="username" class="username"></div>    <script src="https://hst-api.wialon.com/wsdk/script/wialon.js"></script>
...
/* style.css */
.username {  border:1px solid #666;}
// script.js
...
  // authorization response handler
  function loginCallback(code) {
    if (code) {
      alert('Authorization error: ' + code);
      } else {
      alert('Successful authorization');
      var user = session.getCurrUser();      document.getElementById('username').innerHTML = user.getName();    }
  }

In order to display the list of available objects, it's necessary to execute the units' search query. To do this, we will declare a new function printItems(), which we will call after a successful authorization in the function loginCallback(code). It will request from the server the list of units with the data from the last message and display it in form of a table.

Attention! You can find the complete information about the method searchItems on the pages of the documentation Wialon SDK JS

// script.js
...
function printItems() {
    var searchSpec = {
      itemsType:"avl_unit", // the type of required elements of the system Wialon
      propName: "sys_name", // the name of the property that will be used as a basis for the search
      propValueMask: "*",   // the value of the property — can be used * | , > < =
      sortType: "sys_name"  // the name of the property that will be used for sorting the response
    };
    var dataFlags = wialon.item.Item.dataFlag.base |        // basic properties' flag
                    wialon.item.Unit.dataFlag.lastMessage;  // data flag of the last message
 
    // units' search request
    session.searchItems(searchSpec, true, dataFlags, 0, 0, function(code, data) {
      if (code) {
        alert(wialon.core.Errors.getErrorText(code));
        return;
      }
      // generating a data table
      var table = '<table><tr><td>Unit</td><td colspan="3">Last message</td></tr>';
      var pos;
      for (var i = 0; i < data.totalItemsCount; i++){
        pos = data.items[i].getPosition();
        table += '<tr><td>' + data.items[i].getName() + '</td>';
        if (pos) {
          table += '<td>' + pos.y + '</td><td>' + pos.x + '</td><td>' +
                   wialon.util.DateTime.formatTime(pos.t);
        } else {
          table += '<td colspan="3">';
        }
        table += '</td></tr>';
      }
      table += '</table>';
      document.querySelector("#units").innerHTML = table;
    });
  }
...
...
  // script.js
  function loginCallback(code) {
    if (code) {
      alert('Authorization error: ' + code);
    } else {
      alert('Successful authorization');
      var user = session.getCurrUser();
      document.querySelector("#username").innerHTML = user.getName();
      printItems();    }
  }
...

In order the table to be displayed we will add the element to the page

<!-- index.html -->
...
  <body>
    <div id="username" class="username"></div>
    <div id="units"></div>    <script src="https://hst-api.wialon.com/wsdk/script/wialon.js"></script>

and will slightly change the style sheets.

/* style.css */
.username, td {  border:1px solid #666;
}