[Edit: 27.9.2012: Updated JSON API blog article]
(The following article refers to the Code Sample Browser on the Developer Zone website and was provided by Matthias David, developer Logistics Components Server. Thank you!)
Overview
With the code sample browser, PTV has created a new way of discovering PTV xServers. The completely redesigned user interface includes practical samples that demonstrate the functionality of PTV xServers. Each sample can be opened and tested in a separate window with tabbed browsing. Brief explanatory texts at the bottom of the screen describe the content and the mode of operation of the sample in question.
A detail of the code sample browser which is particularly interesting for developers is located to the right of each sample. Here the code editor can open the complete code of the sample, which he can edit as he wishes. The samples all consist of a single HTML page with embedded JavaScript code. Changes are saved and the sample is updated with the “Save” button. If something has gone wrong, it is always possible to restore the sample to its original condition with the “Revert” button.
JSON objects have been applied for the first time in the code sample browser, implemented here as a prototype. The extension of the PTV xServers with a JSON API is planned for the 1.16 version (beginning 2013); a productive implementation of JSON in JavaScript code should therefore be straightforward from then onwards.
Information on the code
The PTV xServer add-on AJAX Maps makes it possible to display the map. It is integrated
<!-- Ajaxmaps -->
<script type="text/javascript" src="/ajaxmaps/webcomponent/ script/qooxdoo/script/qx-transport.js"></script>
<script type="text/javascript" src="/ajaxmaps/.qxrpc"></script>
<script type="text/javascript" src="/ajaxmaps/webcomponent/ script/map.js"></script>
into the HTML page with the following lines: For the display, the following div then has to be included in the body:
<div id="mapContainer" style="top: 0; left: 0; bottom: 0; right: 0; position: absolute;"></div>
Next the map can be accessed via the API of PTV AJAX Maps. With the following lines the map can, for example, be centred on Luxemburg:
map = new mapApi.Map(document.getElementById('mapContainer'));
map.setCenter({ x : 4303250, y : 5486500 });
map.setZoom(11);
The interfaces of PTV xRoute and PTV xLocate Server can be accessed in a similar manner. At first, several scripts have to be included (currently implemented as prototypes and not publically available):
<!--xRoute JSON -->
<script type="text/javascript" src=".qxrpc?key=xroute"></script>
<script type="text/javascript" src="../../js/xRoute.js"></script>
<!--xLocate JSON -->
<script type="text/javascript" src=".qxrpc?key=xlocate"></script>
<script type="text/javascript" src="../../js/xLocate.js"></script>
And the relevant clients
var xroute = new xRouteService();
var xlocate = new xLocateService();
are initialised with. Then the API of PTV xServers can be used. The JavaScript API corresponds exactly to the SOAP API. The only difference: the method parameters are transferred as JSON objects. A call to the PTV xLocate interface therefore looks like this, for example:
var callerContext = {
properties : [{
key : 'CoordFormat',
value : 'PTV_SMARTUNITS'
}, {
key : 'ResponseGeometry',
value : 'PLAIN'
}, {
key : 'Profile',
value : 'default'
}]
};
var location = {
coordinate: {
point : {
x : 4303250,
y : 5486500
}
}
};
var response = xlocate.findLocation(location, null, null, null, callerContext);
A special feature of JavaScript API is that it can make calls asynchronously. In this way, the sample can still be used while, for example, a request is being sent to the PTV xRoute Server in the background. For this, each method has a second version with an “async” suffix. The first parameter of these methods is always the call-back method. Here is an example from the “Simple Routing” sample:
xroute.calculateRouteAsync(calculateRouteCallback, waypoints, ro, null, rlo, cc);
function calculateRouteCallback(result, exc) {
drawRoute(result);
zoomOnRoute(result);
document.body.style.cursor = 'default';
}
For any questions concerning the article, please comment on this post, visit the forum or contact our support team. And of course you are allowed to recommend this post and the code sample browser to your colleagues 😉
