Custom panel example: Tags and Users showcase

Custom panels in GpsGate are mashups that use REST API resources. You can dynamically display data from GpsGate and other business systems directly in applications.

Requisites

• Enable the App Builder as shown here.

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. The 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 tracking applications 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 your application.

The Custom Panel for Users/Tags

In this 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:

In the above lines, we create a link to the Users resource using the 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:

The other parameter our custom panel accepts through the 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 on the page as the system falls back on session authorization when no API key is present.

Custom panel deployment

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 the application

In this step, we have a page ready, and we just need to open it within the application. There are different ways to open a custom page inside an 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. In your application go to the App Builder.
2. Click on the + App button and choose a name for the new app.
3. In the second step, (Click Scripts) press the + Click Script button.
4. Choose WindowsMenu as Kind and press the Edit button to write your script.
5. Copy-paste the following script and press Save afterwards.
6. Replace server_address in the script with your actual server’s address.

The script opens the page specified 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 the 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 the name of the user as the default search value.

Follow these steps to create a “User Right Click Menu”:

1. In your application go to the App Builder.
2. Click on the + App button and choose a name for the new app.
3. In the second step, (Click Scripts) press the + Click Script button.
4. Choose UserRightClick as Kind and press Edit button to write your script.
5. Copy-paste the following script and press Save afterwards.
6. Replace server_address in the script with your actual server’s address.

The script is very similar to the script we wrote in the 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 the 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: