1 Display Platform Kit

How to add custom display components with your own content

2 Introduction
GpsGate Server Display Platform Kit can be used to add your own customizations to VehicleTracker, and in the future other GpsGate Server applications. Windows can be added to interact with the VehicleTracker application. In this way you can easily do things like displaying information from your business system for a selected vehicle. You can also customize the appearance and functionallity of the VehicleTracker application using the available Javascript APIs or the GpsGate Server .NET API.

Content of downloaded zip file

This guide: Vehicle Info Window example: \DisplayKit Guide.pdf \examples\VehicleInfoWindows\

The street view sample is distributed with GpsGate Server.

Prerequisites
You need an installation of GpsGate Server v2.2 build 1750 or later with Site Administrator rights. The server can be hosted by GpsGate or self hosted. You are assumed to know how to administrate a GpsGate Server installation. You can find more information here: http://franson.com/gpsgateserver/guide.asp You are assumed to have basic JavaScript programming language knowledge.

3 JavaScript plugin framework

A JavaScript plugin consists of one XML file which specifies which JavaScript files are included, both local and remote files located on other web servers. And for which applications, and on which aspx pages the plugin will work, e.g. in VehcleTracker on page VehicleTracker.aspx. JavaScript plugins can be used for all kind of extensions of GpsGate Server, but in this guide we only focus on the Display Platform Kit. In SiteAdmin you can activate a plugin for a selected number of applications. This is done under Script Plugins in SiteAdmin. Plugins distributed with GpsGate Server is located in http://[host]/GpsGateServer/Resources/ScriptPlugins/com.GpsGate/[plugin] Third party plugins should be placed in http://[host]/GpsGateServer/Resources/ScriptPlugins/ [com.YourCompany]/[your_plugin]

4 Windows
The Window handling is based on MochaUI user interface library. More information including reference documentation and examples can be found at http://mochaui.com/ A window is a movable area which is overlayed on top of the page. See Figure 1. The content of a window is loaded from a separate file as HTML containing markup and optional JavaScript. The content can be generated dynamically from an aspx page, PHP page or similar as well as from plain HTML file. The window can either include the content directly into the host page or by wrapping it in an iframe allowing standard HTML forms. See MochaUI reference for more information about windows and load methods: http://mochaui.com/docs/files/Window/Window-js.html Code 1: Window creation example JavaScript.
new MochaUI.Window({ id: 'winMyWindow', title: 'My Window', loadMethod: 'xhr', contentURL: 'MyContent.html', width: 400, height: 400, onContentLoaded: function(win) { // Do something }, onClose: function(win){ // Do something } });

Figure 1: Window containing Google earth and street view for the selected vehicle.

Manage windows in the context of an application When the application have initialized the standard user interface components in the startup sequence the /GpsGateServer/App/UI/initialized global event is fired to let third party user interface plugins register itself into the context of the application. The event passes an UIHandle object where user interfacer plugins should register it self. For windows the UIHandle.addWindow function will register a window and create a menu item where the end user can open it. In context of VehicleTracker application the UIHandle concrete implementation is the Franson.VehicleTrackerUI object. Code 2: Register window on startup. (com.GpsGate/StreetViewWindow/StreetView.js)
Franson.Event.subscribe('GpsGateServer/App/UI/initialized', function(UIHandle) { UIHandle.addWindow({ // Name of the menu item name:'Street View', // Method called when user clicks the menu item open: Franson.StreetViewWindow.open }); });

Samples
Street view window sample This sample demonstrates how to create a window, register it in VehicleTracker and display google street view for the current selected user (vehicles are also users in GpsGate Server). The plugin also monitors position updates and updates the views when the user moves. The sample is part of the standard GpsGate Server distribution and is located in GpsGate default plugin diretory.

[install_path]\IIS\Resources\ScriptPlugins\com.GpsGate\StreetViewWindow Sample content StreetView.xml This XML file describes your plugin for GpsGate Server. It contains information about plugin name and version and description etc. Most importantly it specifies which other scripts your plugin is dependent on (and in which order they should be loaded). StreetView.js Startup script. Sets up the window and listen to startup event to add it to VehicleTracker application. StreetViewContent.html The HTML/JavaScript content of the window. In this file the streetview JavaScript logic is implemented along with the markup.

Install and run the sample - step by step: 1. Login to SiteAdmin. Go to the Script Plugin tab. Click on Refresh Scrip Plugins. A plugin named Street View Window should be present in the drop down. 2. Select Street View Window in the drop down. Check the applications for which to enable the plugin. Click Save. The plugin is now enabled for the selected applications. 3. Login to an application for which you enabled the plugin. 4. A menu named "Windows" should have been created with a sub menu item named "Street View" 5. Click the "Street View" menu item and the window should now pop up. Vehicle info window sample This is a very simple sample that loads HTML pages with extended information for a user, this applies to vehicles also since vehicles are also users in GpsGate Server. The pages should be put in the plugin directory and be named as [username]_info.html where username is Login ID of the user. Sample Content VehicleInfo.xml This XML file describes the plugin for GpsGate Server. VehicleInfo.js Sets up the window and load the current selected user extended information HTML page. It also listen to onactivevehiclechange and reload the content of the window with the newly selected vehicles extended information. Car1_info.html Example of an information page for a user named Car1.

Install and run the sample - step by step: 1. Copy the files found in "examples\VehicleInfoWindow\" to "[install_path]\IIS\Resources\ScriptPlugins\[com.yourname]\VehicleInfoWindow\" Where install_path is where you installed GpsGate Server, and com.yourname is a unique name of your own plugin folder. For each user in the application create a HTML page named "[username]_info.html" and put all extra info such as images, driver information etc into that page. Login to SiteAdmin. Go to the Script Plugin tab. Click on Refresh Script Plugins. A plugin named Vehicle Info Window should be present in the drop down. Select Street View Window in the drop down. Check the applications for which to enable the plugin. Click Save. The plugin is now enabled for the selected applications. Login to the application for which you enabled the plugin. A menu named "windows" should exist with an item named "Vehicle Info" Click the "Windows" -> "Vehicle Info" menu item and the window should now pops up and load the page for the currentley selected vehicle. Note. If no page exist the content of the window will be an 404 error message and you must create a page named [username]_info.html in the plugin directory.

2. 3. 4. 5. 6.

Speed Alarm window sample This sample is downloadable from the GpsGate Server web site: http://franson.com/gpsgateserver/samples/SpeedAlarmWindow.zip The sample demonstrates how an aspx page can be used for generating dynamic content in a window, allowing an administrator user to create, edit and delete speed alarms in VehicleTracker in a straight-forward way. Sample Content SpeedAlarm.xml This XML file describes the plugin for GpsGate Server. SpeedAlarm.js Startup script. Sets up the window and listen to startup event to add it to VehicleTracker application. ErrorPage.htm A page which the window displays if a user is not logged in or the user does not have administrator rights. SpeedAlarmContent.aspx SpeedAlarmContent.aspx.cs SpeedAlarmContent.aspx.designer.cs

Install and run the sample - step by step: 1. Download and unzip SpeedAlarmWindow.zip into to a directory [install_path]\IIS\Resources\ScriptPlugins\com.GpsGate\SpeedAlarmWindow\ where install_path is where you installed GpsGate Server.

2. Login to SiteAdmin. Go to the Script Plugin tab. Click on Refresh Script Plugins. A plugin named "Speed Alarm Window" should be present in the drop down. 3. Select Speed Alarm Window in the drop down. Check the applications for which to enable the plugin. Click "Save". The plugin is now enabled for the selected applications. 4. Login with an administrator user to the application for which you enabled the plugin. A menu named "windows" should exist with an item named "Speed Alarm". Click the "Windows" -> "Speed Alarm" menu item and the window should pop up. Bambuser live video window sample This sample is downloadable from the GpsGate Server web site: http://franson.com/gpsgateserver/samples/Bambuser.zip This plugin lets you associate bambuser accounts with your vehicles, and display live bambuser video stream for the selected vehicle in a window inside VehicleTracker. The sample makes use of an .ashx web handler to let javascript in the browser communicate with the server asynchronously in an ajax fashion. Authorization on the server side makes sure that only an administrator user can edit bambuser info for vehicles. Sample Content Bambuser.xml This XML file describes the plugin for GpsGate Server. Specifies which javascript file and the locations of any web handler/web service that shoudl be used by the plugin. Bambuser.js Startup script and client side logic. Sets up the window and listens to startup event to add it to VehicleTracker application. BambuserContent.html JsonBambuserHandler.ashx Handles ajax requests and forwards them to server objects responsible for authorization and database access. BambuserFacade.cs bambusermodule.xml bambuserpackage.xml Used by script plugin manager to run database scripts for creating needed database tables. BambuserModuleMSSQL.sql BambuserModuleMySQL.sql SQL scripts for creating the required database tables. bambuserLogin.jpg editBambuserInfo.jpg publicBambuserChannel.jpg Icons used in the user interface. DAO/BambuserReaderDAOSQL.cs

DAO/BambuserWriterDAOSQL.cs BO/BambuserInfo.cs BO/BambuserReader.cs BO/BambuserWriter.cs Souce code for server side classes. Bambuser.dll The compiled server side classes for authorization and database read/write etc.

Install and run the sample - step by step: 1. Download and unzip Bambuser.zip into to a directory [install_path]\IIS\Resources\ScriptPlugins\MyPlugins\Bambuser.zip\ where install_path is where you installed GpsGate Server. 2. Login to SiteAdmin. Go to the Script Plugin tab. Click on Refresh Script Plugins. A plugin named "Bambuser Window" should be present in the drop down. 3. Select Bambuser Window in the drop down. Check the applications for which to enable the plugin. Click "Save". The plugin is now enabled for the selected applications. 4. Login preferably with an administrator user to the application for which you enabled the plugin. A menu named "windows" should exist with an item named "Bambuser". Click the "Windows" -> "Bambuser" menu item and the window should pop up. 5. Click icons to edit bambuser account info for the currently selected vehicle, show the public bambuser broadcast of the currently selected vehicle, or log in to the private bambuser channel page of the currently selected vehicle to see bambuser private mode broadcast.

5 Setting up your .NET development environment for plugins

This section describes how to set up your development environment so that you can easily develop and debug .NET plugin components for GpsGate Server. For a .Net plugin example, you can download the source code for the Speed Alarm Window plugin described in section Speed Alarm window sample" of this guide. Developing and debugging When developing script plugins to VehicleTracker you can for example make use of a server side web form (.aspx) or a web handler (.ashx). The project may preferably be developed at the location where the files will actually be run by your GpsGateServer installation. The following steps describe how this can be done. 1. Create a new Web Application project in Visual Studio called [MyPlugin]. Set the location of the project to where the files (.aspx, .ashx etc) will actually be run by your GpsGateServer installation. That is, the project root folder should be [install_path]\IIS/GpsGateServer\Resouces\ScriptPlugins\myPlugins\MyPlugin\ 1. Add a web form called for example MyPluginContent.aspx. 2. In your project, add references to every DLL in your GpsGateServer installation found at [install_path]\IIS/GpsGateServer\bin\. 3. In order to debug your page you should configure the project URL for use with your IIS web

server. Configure this by doing the following steps: 3.1 Go to the Properties Web section for your [MyPlugin] web application project. Select to Use IIS Web Server and specify Project Url to the location of your project: http://localhost/gpsgateserver/Resources/ScriptPlugins/MyPlugins/MyPlugin 3.2 Set Start Action to Don't open a page. 4. If your project will contain classes that need to be compiled in order to run you should set the project build output path to your server installation bin directory by performing the following steps: 4.1: Go to the Properties Build section for your [MyPlugin] web application project. For Output path: enter the location of your GpsGate server installation bin directory, for example if you installed GpsGate server in the default location on C:\ you should enter C:\inetpub\wwwroot\GpsGateServer\IIS\bin\ You can now debug your web page by doing the following: 1. Start a web browser and log in to your VehicleTracker application. This will create a session that will be used by your plugin. 2. Attach your source code to the web process that was started by your logging in to VehicleTracker: In Visual Studio, go to the Debug menu and choose Attach to process, tick checkboxes Show processes from all users and Show processes in all sessions. In the list of available processes, double-click the process w3wp.exe. Visual Studio should now be listening for requests to the page from the browser and you should be able to set debug it (for example, set a breakpoint in Page_Load). 3. Browse to your page http://localhost/gpsgateserver/Resources/ScriptPlugins/MyPlugins/MyPlugin/MyPluginCon tent.aspx The above steps will let you quickly get started with developing the logic of your .aspx page. Later on, you will probably be accessing the page from a menu inside VehicleTracker, which will require some more plumbing through xml and javascript files. If the plugin will only be using an .aspx page for the server side logic, deployment can be greatly simplified by changing the attribute CodeBehind=MyPluginContent.aspx.cs of your MyPluginContent.aspx page to CodeFile=MyPluginContent.aspx.cs. This will allow you to avoid any compiling your code beforehand. If this is the case, simply let the MyPluginContent.aspx, MyPluginContent.aspx.cs and MyPluginContent.aspx.designer.cs files stay in the folder, together with the other required plugin files. Debugging JavaScript/HTML Firebug is a very good tool when developing JavaScript/HTML applications. Firebug is a Firefox extension. If you use Firebug and want to debug JavaScript included in your content page of a Display Kit user interface component I recommend to place the JavaScript code in a separate file loaded from the JavaScript plugin architecture. The content is loaded dynamically into the page and can't bee debugged if it is not included on startup of the application. When you are done, move your code to be included dynamically again for performance reasons.

6 References
MochUI documentation and examples GpsGate Server JavaScript API http://mochaui.com/ http://franson.com/gpsgateserver/jsapi/

Thanks for reading this! Please post your feedback to support@gpsgate.com Regards Franson Technology AB, GpsGate.com / Bjrn Andersson and Jonas Johansson