Develop a custom panel using REST (Tags/Users showcase)

mashup, in web development, is a web page, or web application, that uses content from more than one source to create a single new service displayed in a single graphical interface. In this blog post, we show how to develop a mashup panel in VehicleTracker using GpsGate REST API resources.


Introduction

GpsGate releases new API resources every month. (To see a list of available resources, please visit this page on your GpsGate server: http://host_name/comGpsGate/api/v.1/test (replace host_name with your actual server IP address or hostname)). In this example, we use two of the REST API resources (Tags and Users) to create a mashup panel. We recommend that you host all your custom panels under the ”\GpsGateServer\IIS\VehicleTracker\CustomPanels” folder on your GpsGate server. Source code of the example we explain in this blog post can be downloaded here.

Custom panels are simple HTML pages that are hosted on your GpsGate server. Since VehicleTracker and custom panels are both hosted on the same server under the same domain, you can communicate with GpsGate REST API resources without authentication. In practice, authorization is done in the background using the information in your session, which is available after login to VehicleTracker.

Tags/Users Custom Panel

In this Tags/Users example, we read all Tags and Users of an application from GpsGate REST API and visualize them in a graph generated by a third party JavaScript library called D3. GpsGate REST API GET operations return JSON objects in the response body. To read and parse JSON results, we used the embedded JSON reader in D3 library. You can read more about D3 data readers here. We can use the URL of our custom panel to build a URL to the API resource. Again, this is because both the API and our custom panel are under the same domain:

var domain = window.location.origin;
var apiPath = '/comGpsGate/api/v.1/';
var usersResource = domain + apiPath + 'applications/' + applicationid + '/users?pagesize=' + pagesize;

In the above lines, we create a link to the Users resource using current page location where “applicationid” and “pagesize” variables are parsed from query string. This means that when we open this HTML page from a VehicleTracker window script, we need to pass the application id and the page size as parameters. Similar commands are used to create a link to Tags resource:

 
var tagResource = domain + apiPath + 'applications/' + applicationid + '/tags'

The other parameter our custom panel accepts through query string is “User”. Only users with a name including the value of this parameter are visible.

The rest of the page is about building a graph and visualize it using D3 library. Please read the comments in the source code for details of the algorithm. Please note that, as mentioned before, we didn’t use any authorization method in the page as the system falls back on session authorization when no API key is present.

Custom panel deploy

To deploy the mashup page, we simply copy the HTML page and all its resources (css files, js files and third party libraries) to the ”\GpsGateServer\IIS\VehicleTracker\CustomPanels\TagUserPanel” folder. Note that you can open this page directly using its URL if you have a session (i.e . if you are logged in a different tab of your browser).

Using the panel in VehicleTracker

In this step, we have a page ready and we just need to open it within the VehicleTracker application. There are different ways to open a custom page inside a VehicleTracker application. In this example, we use both click script and window script to open our custom panel.

In order to create a window script, follow these steps:

  1. Login to VehicleTracker
  2. Choose “App Builder” from “Development” menu.
  3. Click on “New App” button and choose a name for the App
  4. In the second step, (Click Scripts) press “New Click Script” button
  5. Choose “WindowsMenu” as Kind and press “Edit” button to write your script
  6. Copy and Paste the following script and press “Save”. (remember to replace server_address in the script with your actual server’s address)
 
 
log("OK");

The script is simple: it just opens the page we wrote, and it has the “applicationid” hard coded because scripts are created per application.

Now you have a window script which opens our custom panel. To open the panel, select your script name from window menu. It can be integrated to a workspace, switched to a window, moved around, and saved as any other panel.

Note that it is not possible to embed every URL as an iframe. For example, embedding a page with a HTTP URL into a HTTPS page will not work. To open this kind of pages from Vehicle Tracker, see the section Opening a URL in New Browser Window below

An alternative for opening the custom panel is to use “User Right Click Menu”. In this approach, we can send name of the user as the default search value. Follow these steps to create a “User Right Click Menu”:

  1. Login to VehicleTracker
  2. Choose “App Builder” from “Development” menu.
  3. Click on “New App” button and choose a name for the App
  4. In the second step (Click Scripts) press “New Click Script” button
  5. Choose “UserRightClick” as Kind and press “Edit” button to write your script
  6. Copy and Paste the following script and press “Save”. (remember to replace server_address in the script with your actual server’s address)
 
ui.iframe('myusertags', 'Tags/Users', 'http://server_address/gpsgateserver/VehicleTracker/CustomPanels/TagUserPanel/taguser.html?applicationid=4&user=' + user.name, 100, 100, 1300, 650);
 
log("OK");

The script is very similar to the script we wrote in window script. The only difference is that we send an extra user parameter. The value of this parameter is the name of the user we right clicked on.

The name parameter is used in our custom HTML page to propagate the search field. Now we have a custom panel which we can open either by choosing UserTagsApp from Windows menu:

or by right clicking on a user:

Opening a URL in New Browser Window

You can also trigger opening a specific URL from a script in a new browser window. Here is how to modify the script in the above example to open a new browser window:

 
var url = 'http://www.gpsgate.com'); // here you write your target url
 
if (url != null) {
  ui.open(url)
}