Spectrum Technology Platform

Spectrum Technology Platform Version 8.0.0 SP2 RIA Getting Started Guide

Information in this document is subject to change without notice and does not represent a commitment on the part of the vendor or its representatives. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, without the written permission of Pitney Bowes Software Inc., One Global View, Troy, New York 12180-8399. 2013 Pitney Bowes Software Inc. All rights reserved. Pitney Bowes Software Inc. is a wholly-owned subsidiary of Pitney Bowes Inc. Pitney Bowes, the Corporate logo, MapInfo, Group 1 Software, and MapInfo Professional are [registered] trademarks of Pitney Bowes Inc. or a subsidiary. All other trademarks are the property of their respective owners. United States: Phone: 518.285.6000 Fax: 518.285.6070 Sales: 800.327.8627 Government Sales: 800.619.2333 Technical Support: 518.285.7283 Technical Support Fax: 518.285.7575 www.pb.com/software Canada: Phone: 416.594.5200 Fax: 416.594.5201 Sales: 800.268.3282 Technical Support:.518.285.7283 Technical Support Fax: 518.285.7575 www.pb.com/software Europe/United Kingdom: Phone: +44.1753.848.200 Fax: +44.1753.621.140 Technical Support: +44.1753.848.229 www.pitneybowes.co.uk/software Asia Pacific/Australia: Phone: +61.2.9437.6255 Fax: +61.2.9439.1773 Technical Support: 1.800.648.899 www.pitneybowes.com.au/software Contact information for all Pitney Bowes offices is located at: www.pb.com/contact-us. Products named herein may be trademarks of their respective manufacturers and are hereby recognized. Trademarked names are used editorially, to the benefit of the trademark owner, with no intent to infringe on the trademark. April 02, 2013

Contents Chapter 1: RIA Controls...5 What Are the RIA Controls?...6 Getting Started with the RIA Controls...7 Developing with the RIA Controls...7 Chapter 2: Using the RIA Proxy...9 Installing the RIA Proxy...10 Why use the RIA Proxy?...11 Origin Concept...11 Why is this Important?...12 Using the RIA Proxy in your Web Application...12

RIA Controls 1 This section describes what the RIA controls are, and how to get started using the RIA controls in your web applications. In this section: What Are the RIA Controls?.........................6 Getting Started with the RIA Controls................7 Developing with the RIA Controls....................7

What Are the RIA Controls? What Are the RIA Controls? The RIA (Rich Internet Application) controls provide a set of browser-based user interface components for easily embedding maps and other location-based capabilities in web pages. A JavaScript API is also provided which, together with the user interface components, enable you to create custom browserbased mapping applications. The RIA controls can be used in a wide range of scenarios, from simply embedding maps in your web site to show locations, to creating rich web applications. Built entirely in JavaScript, the controls work without the need for any browser plug-ins and without having to write any server-side code. The RIA controls use Web 2.0 techniques to provide functionality such as seamless map panning and the ability to search and display information without requiring a web page refresh. The following controls are available: Control LegendControl FeatureService Multi-table FeatureService OpenLayers layer types Generic data formatting REST Services Description A user interface control containing descriptive information about features appearing on a map. It also provides the means to show and hide individual overlays on a map. A non-user interface control, that lets developers write Javascript code to call the FeatureService REST API. This control can be used to query tables for features. Search results are returned as GeoJSON FeatureCollections. The search call is performed asynchronously. A non-user interface control, that lets developers make FeatureService REST calls against multiple tables simultaneously. This is a convenience class, allowing a feature search on multiple tables which is useful when a feature search is triggered by interactions with a map, that typically display the features of multiple tables stacked on top of each other. For example, a SearchNearest against TABLE1 and TABLE2 at a given point (x,y). An easy way to display either a MappingService NamedMap or a TileService map tile on an OpenLayers map. Template formatting controls for developers to display JSON data in an OpenLayers popup (for example) but intelligently styled. For example, a Table name underlined, field names in italics, and field values in bold. REST-ful service control for developers to send cross-domain calls to the REST services. These calls will be performed as asynchronous XMLHttpRequest calls. 6 Spectrum Technology Platform 8.0.0 SP2

Chapter 1: RIA Controls Getting Started with the RIA Controls The RIA controls are installed with Spectrum Technology Platform. To get started using these controls, you are provided with the following: 1. Java Servlet Proxy download located at http://localhost:8080/ria-examples/riaproxy/riaproxy.war 2. IIS (.NET) Proxy download located at http://localhost:8080/ria-examples/riaproxy/riaproxy.zip 3. Controls JavaScript hosted at http://localhost:8080/ria/ria.js 4. JavaScript API Documentation hosted at http://localhost:8080/ria/api/, or can be accessed at the Spectrum Technology Platform documentation site here: http://reference.mapinfo.com/software/spectrum/lim/8_0/ria/api/index.html. 5. RIA example application hosted at http://localhost:8080/ria-examples/. Using these resources and the instructions provided in this guide, you will be able to get the RIA proxy installed in your environment, run the example RIA controls, and start developing your own RIA-controlbased application. Developing with the RIA Controls To develop with the RIA controls on your own machine or to place applications developed with RIA controls on another server, you will need to install the RIA proxy. The following link from Yahoo provides background information on why proxy pages are needed: http://developer.yahoo.com/javascript/howto-proxy.html The RIA proxy is required to start working with the RIA Controls. Simply reference the relevant JavaScript file hosted by Spectrum Technology Platform in your html pages, and the browser takes care of the rest. To get started developing an RIA control based application: 1. Have a web application server (for example, Tomcat) installed on your machine. 2. Create a new service folder in your webapps (or equivalent) directory for your application (for example, myapp). 3. Create your application pages in your newly created service folder, using the functionality of the Spectrum Technology Platform JavaScript API. You can use the RIA examples that ship with Spectrum Technology Platform as a starting point for your applications. View the page source of the examples here: http://localhost:8080/ria-examples/. 4. Download the riaproxy.war file from Spectrum Technology Platform and copy it to your webapps (or equivalent) directory. For information on how to download the RIA proxy, and on why you must use the proxy, see the section: Using the RIA Proxy on page 9. 5. Restart your application server. RIA Getting Started Guide 7

Using the RIA Proxy 2 Several RIA controls depend on a server side component to be fully functional. For example, the FeatureService calls a server in order to query spatial data that isn't directly available in the browser. However, due to security restrictions that are put in place by all modern browsers, it is not possible to call any arbitrary server on the web. The RIA controls require a proxy in order to work around those security restrictions. The following sections describe why this is necessary and how a proxy can be used for your own application development. In this section: Installing the RIA Proxy...........................10 Why use the RIA Proxy?..........................11 Using the RIA Proxy in your Web Application.........12

Installing the RIA Proxy Installing the RIA Proxy Spectrum Technology Platform ships with two proxy implementations, one for Java Servlet containers (2.4 and higher) and one for IIS. Java Servlet Proxy Download the proxy binary from your Spectrum Technology Platform installation at: http://localhost:8080/ria-examples/riaproxy/riaproxy.war. Once downloaded, you can deploy it to a web application server of your choice. Please refer to the documentation of the application server for details on deploying WAR files. If you are using Apache Tomcat, copy the WAR file into the %CATALINA_HOME%\webapps directory. As long automatic application deployment is enabled and you keep the WAR file name intact, the proxy will be made available under the default context path of riaproxy. Note: If you decide to deploy the proxy under a different context path, please make sure to provide the correct value when following the step to define the path to the proxy in your web application. This step is defined in the section: Define the Path to your Proxy on page 13 Once the proxy has been installed, a trusted base URL needs to be set. URLs that do not start with this value will not be relayed by the proxy. This is necessary to prevent the proxy from being abused to request resources from other domains than the one required by the RIA controls. To configure this: 1. Open the proxy.properties file located within the...\riaproxy\web-inf folder. 2. Set the value of the trusted.base.url property to http://servername, where servername is a placeholder for the hostname RIA is installed on. 3. Restart the proxy application. For example: trusted.base.url=http://localhost:8080 To enable HTTP Basic Authentication, the following properties need to be set: 1. auth.type=basic 2. anonymous_username=username 3. anonymous_password=password Replace username and password with the actual login credentials to be used by the proxy. Please note that this performs HTTP basic authentication against the RIA server-side component on behalf but transparent to the client. Requests by the client to the proxy are not protected and additional steps have to be taken if that is necessary. Please consult the documentation of your application server for further details. IIS Proxy Download the proxy binary from your Spectrum Technology Platform installation at: http://localhost:8080/ria-examples/riaproxy/riaproxy.zip. 10 Spectrum Technology Platform 8.0.0 SP2

Chapter 2: Using the RIA Proxy Once downloaded, unzip the file and run setup.exe to install the proxy into IIS. You can deploy it to a web application server of your choice. Please refer to the documentation of the application server for details on deploying WAR files. The configuration of the IIS proxy is equivalent to the Java Servlet proxy, in that you need to configure the base URL and authentication. The only difference is the configuration file is located at \ProxyService\Web.config. The Web.config file is an XML file and configuration properties are set with <add> elements nested inside the <appsettings> element of the file. For example: <add key= trusted.base.url value=http://localhost:8080/> Verification Once you have installed the proxy and set it to forward the requests to the RIA application, you can test it by accessing the RIA JavaScript file, ria.js directly and through the proxy. Suppose RIA is installed on 'myserver' on port 8070 and the proxy is installed on the localhost using the default name of riaproxy on default port 80, the two URLs are as shown below: http://myserver:8070/ria/ria.js http://localhost/riaproxy/proxy.aspx?url=http%3a%2f%2fmyserver%3a8070%2fria%2fria.js Compare the pages loaded by the two URLs and make sure they are same. Why use the RIA Proxy? The same-origin policy is a security restriction on what web content JavaScript code can interact with. Essentially, it dictates that a running script can only interact with data coming from the same origin as the server hosting the page or application upon which the code is running. This is especially important for applications using AJAX (Asynchronous JavaScript and XML) techniques like RIA controls as it means that our requests may only be made back to the host server. The RIA controls require a proxy in order to work around those security restrictions. The following sections describe why this is necessary and how a proxy can be used for your own application development. Origin Concept The origin in the same-origin policy means the same host, but there are a few specifics that should be noted. The following table illustrates whether the same origin when compared with a base origin of www.example.com: URL http://www.example.com/dir/page.html http://www.example.com/dir2/other.html Same-Origin true true Note Same protocol and host Same protocol and host RIA Getting Started Guide 11

Why is this Important? URL http://www.example.com:81/dir2/other.html https://www.example.com/dir2/other.html http://en.example.com/dir2/other.html http://example.com/dir2/other.html http://v2.www.example.com/dir2/other.html Same-Origin false false false false false Note Same protocol and host but different port Different protocol Different host Different host (exact match required) Different host (exact match required) Why is this Important? In order to host applications on a different machine than directly on the server hosting RIA controls, we need a way to bypass the same-origin policy. This is particularly useful during application development, where developers typically want to run their code on a local machine. The local machine will typically use a hostname of localhost, or a machine name, and the server with the controls will have a different hostname, therefore and entirely different origin. To achieve this, a proxy has been provided that will forward requests to a remote host and appear to the browser to still be in the domain. The Java proxy can be deployed to any Java servlet container that implements the Servlet 2.4 specification or higher. The proxy simply takes a URL as a parameter and requests the page, passing the contents back to the requester. Given the proxy is installed on a server of a local machine on port 80, you can access the web page http://myserver:8765/some/path/example.html by calling http://localhost/riaproxy?url=http://myserver:8765/some/path/example.html. The result sent by the proxy will be the same as if the target URL was accessed directly. The important difference is the second URL will be seen by a browser as part of the local domain http://localhost/ instead of http://myserver:8765/. Please note that the URL parameter needs to be encoded properly to follow the syntax rules of Internet URLs (conf. RFC 1738: Uniform Resource Locators). Using the RIA Proxy in your Web Application This section describes how to use the RIA proxy in your web application. Import ria.js The first step is to import OpenLayers and the main RIA JavaScript library. This can be done as follows: <script type="text/javascript" src="http://localhost:8080/ria/openlayers/open- Layers.js"></script> <script type="text/javascript" src="http://localhost:8080/ria/ria.js"></script> 12 Spectrum Technology Platform 8.0.0 SP2

Chapter 2: Using the RIA Proxy Replace localhost:8080 with the actual hostname and port number RIA is installed on. Define the Path to your Proxy To indicate that cross-domain calls should be routed through a proxy, the path to the proxy has to be registered like this: ria.restservice.addproxy("/riaproxy?url="); Rather than calling a URL to a different domain directly, the RIA library code will append the encoded URL to the end of the path registered above and use the result to perform the request. The proxy takes the URL from the request parameter (by default url), requests the resource associated with it and sends the result back to the RIA library code without any modifications. The exact path passed to the addproxy() method depends on which proxy is being used and how the proxy was deployed. Note: The path above is the default for the Java Servlet proxy. For the IIS proxy, use the path /riaproxy/proxy.aspx?url=. Final Code Sample A simple page for performing a Feature Search: <!DOCTYPE html> <html> <head> <script src="http://localhost:8080/ria/openlayers/openlayers.js"></script> <script src="http://localhost:8080/ria/ria.js"></script> </head> <body> <button onclick="search();">search</button> <script> ria.restservice.addproxy("/riaproxy?url="); function search() { var fs = new ria.search.featureservice( "http://localhost:8080/rest/spatial/featureservice"); 47.813155), var d = fs.searchnearest({ table: "/NamedTables/WorldcapTable", geometry: new OpenLayers.Geometry.Point(12.875977, srs: "epsg:4326", attributes: ["Capital"], withindistance: "2000 mi", distanceattributename: "dist", maxfeatures: 10 }); d.addcallback(function(result) {alert(result.features.length + " result(s)")}); } </script> </body> </html RIA Getting Started Guide 13