Developer Tutorial Version 1. 0
Contents Introduction... 3 What is the Mapzania SDK?... 3 Features of Mapzania SDK... 4 Mapzania Applications... 5 Architecture... 6 Front-end application components... 8 Your first Hello World example...10 Step 1: Create an empty Microsoft Visual Studio 2012 project...10 Step 2: Import Mapzania NuGet Packages...11 Step 3: Update the Global.asax file to extend the class Terrascape.Server.Site...12 Step 4: Update the web.config file... 12 Step 5: Create geo-connections and a map schema... 12 Step 7: Create the Hello World application HTML page... 13 Step 7.1: Create a cascading style sheet (CSS) for the Hello World application...13 Step 7.2: Include standard Mapzania CSS files...13 Step 7.3: Include Third Party Library JavaScript files... 13 Step 7.4: Include Mapzania JavaScript files...14 Step 7.5: Define the HTML page content / elements... 14 Step 7.6: Use the JavaScript API to create and instantiate the map...15 Step 8: Run the application...16 Adding a map toolbar...17 Step 1: Create a cascading style sheet (CSS) for the toolbar...17 Step 2: Define the HTML page content / elements... 17 Step 3: Use the JavaScript API to create and instantiate the map and map toolbar...18 Step 4: Binding behavior to toolbar buttons...19 Step 5: Run the application...19 Page 2 Version 1. 0
Introduction What is the Mapzania SDK? The Mapzania Software Development Kit (SDK) is a geo-spatial API, libraries and related set of tools that makes it easy for developers to incorporate a geo-spatial map component to existing and new web-based applications. The Mapzania SDK can be divided into (1) server and (2) web-based client components: The server component is primarily responsible for importing, storing and serving of geospatial data to webbased clients and also provides an API for performing specialized geospatial operations. Geo-spatial data includes vector feature data, such as points, lines and polygons. Raster tile images (typically serving as map backgrounds) is also considered geo-spatial data. This component also serves as a repository for map schemas (that defines the layout and styling associated with each map) and runs on Internet Information Server (IIS) and the Microsoft.NET platform. Multiple database platforms are supported, including Microsoft SQL Server. The web-based client components are primarily responsible for displaying an interactive map that provides users with the ability to interact with the user interface and provides applications the ability to manipulate the content displayed on the map. A number of standard toolbar items are provided. Mapzania supports a number of map renderer options that includes a Canvas, Raphael and Flash renderer, and allows maps to be usable on a wide variety of web browsers and devices. The web-based client side API is primarily JavaScript/HTML/CSS based and supports all major web browsers. This document concentrates on the development of a web-based application, using the Mapzania JavaScript API in the web browser. We assume the user already has some familiarity with Geo-spatial layer sources and map schemas and has the necessary knowledge and skill to configure an interactive map on Mapzania. Two separate documents contains information and detailed steps to successfully create an interactive map. These documents are and can be found at the following locations: Mapzania Implementation Guide (http:www.mapzania.com/resources/mapzania-implementation%20guide.pdf) Mapzania Map Schema Guide (http:www.mapzania/resources/mapzania-map%20schema%20guide.pdf) Several interactive map demos are provided on the site http:www.mapzania.com/. Separate API Reference Guides are provided for the server and web-based client components. These documents are and can be found at the following locations: Mapzania Microsoft.NET platform API document (http:www.mapzania.com/resources/dotnetapi.zip) Mapzania Web-based client Javascript API reference (http:www.mapzania.com/ts/docs/js-api) This document assumes that developers have access to the source code of the Hello World sample project. This project is available at this location: http:www.mapzania.com/training/helloworldproject.zip Page 3 Version 1. 0
Features of Mapzania SDK The Mapzania SDK provides a pluggable architecture for building connectors to third-party service providers (such as Tom Tom, Inrix, Google and other open and free online geospatial services). Additionally, it provides the ability to perform geo-spatial projections and processing of business specific geo-spatial data. Note that this document does not focus on the Mapzania SDK and the Mapzania Microsoft.NET platform API document provides an API reference. Contact Aspire Solutions if you require more information. The client-side (web-based) Mapzania SDK provides a number of features used for web-based map development. These features are listed in the table below. Feature Multiple renderers Description The Mapzania web-based API provides two major rendering platforms: Canvas and Raphael. The Raphael renderer uses the SVG W3C Recommendation and VML as a base for creating graphics and uses the third party JavaScript library http:raphaeljs.com/. The Raphael renderer supports a wide variant of web browsers, including Firefox 3.0+, Safari 3.0+, Chrome 5.0+, Opera 9.5+ and Internet Explorer 6.0+. The Canvas renderer makes use of the HTML 5 Canvas component and is supported on more recent web browser versions. For a summary of web browser support for the Canvas component, see http:caniuse.com/#search=canvas. Generally, the Canvas renderer performs better than the Raphael renderer. The Raphael renderer, on the other hand, supports a wider set of web browsers. A Flash-based renderer also exists for the Mapzania platform. Contact Aspire Solutions if you require more information for this renderer. Interactive map toolbar A number of standard interactive map tools are provided. These tools include: Zoom In Zoom Out Zoom Extents Pan Measure distance (between two points) Measure area Query point Query line Query polygon Page 4 Version 1. 0
Map data export Mapzania provides the ability to export map vector data to various output formats. The standard supported export formats are: ESRI Shapefile Google KMZ file CSV file For more information on exporting map data, view the web endpoint document at the location: Mapzania Web API documentation (http:www.mapzania.com/ts/docs/web-api) The endpoint /api/maps/{mapkey}/export provides this functionality. Static images / print Mapzania provides a web endpoint to produce a static image of a map and download that image as a PNG or GIF image. For more information on this endpoint, view the web endpoint document at the location: Mapzania Web API documentation (http:www.mapzania.com/ts/docs/web-api) The endpoint /api/maps/{mapkey}/image provides this functionality. Dynamic layers Map legends Map data filters Mapzania provides the ability for web based application to dynamically add and remove map layers to user sessions on the web client, without affecting the master map schema on the server. This functionality is useful when applications programmatically needs to adjust the layout and content of an interactive map during a user session. Mapzania provides a standard map user interface legend component, allowing users to view and set the visibility of layers. Applications also have the ability to build map legends that are specialized for an application use case. Applications provides the ability to change filters on map layers dynamically, without affecting the master schema on the server. Filters on vector layers allows applications to filter out features on a vector layer and is useful for creating dynamic maps. Mapzania Applications Mapzania front-end applications are developed using web-based technologies that includes Web 2.0 technologies, HTML / HTML 5, CSS and JavaScript. Mapzania components are built on the Microsoft.NET platform using Internet Information Server (IIS) and the ASP.NET MVC Framework. The recommended development environment for Mapzania web applications is Microsoft Developer Studio 2012. However, the Mapzania SDK does not limit front-end application development to this environment. Page 5 Version 1. 0
Architecture The Mapzania SDK has 5 NuGet packages, with inter-dependencies to make up the Mapzania platform stack. These libraries are shown in the diagram below. The Mapzania web-based API and components are included in the Terrascape.Web NuGet package. Readers should note that although this document does focus on the web browser based client-side SDK of Mapzania, all the packages are listed and provided here for informational purposes and allow readers to gain a better understanding of the Mapzania platform (in its entire). Diagram 1: The Mapzania platform stack Page 6 Version 1. 0
NuGet Package Aspire.Core Terrascape.Core Terrascape.Platforms.Standard Description Contains interfaces for user authentication, caching, database abstractions, Logging and several Microsoft.NET extension methods and helper methods for application development. Contains the core of the Mapzania geospatial server-based library. It includes abstractions and implementations for geometries, spatial algorithms, coordinate systems & projections, static map renderers, layer sources and map schema definitions. Map schema definitions includes interfaces and supporting classes for map schemas, layers (vector, raster and image) and geo-connections. Contains geo-connector implementations. This includes server-based connectors to the following external third party service providers: Open Street Maps (raster tiles) Noterra database tables (vector data) Shape Files (vector data) XML Files (vector data) Map Box (raster tiles) Inrix (raster tiles and vector data) Tom Tom (raster tiles and vector data) Several other third party integrations are supported and are described in the Mapzania Map Schema Guide. Aspire.Mvc Terrascape.Web Contains Microsoft ASP.NET MVC framework additions for Mapzania applications. This includes authentication / site MVC controllers, a large set of utility and helper classes / methods, logging / authentication implementations and JSON / XML formatters. Contains standard ASP.NET MVC controllers for serving geo-spatial data, performing geospatial operations and serving/receiving maps schemas. Additionally, it contains standard web-based map viewers, release notes, the JavaScript API and the corresponding JavaScript API reference. These above listed NuGet packages can be downloaded from the Aspire Solutions NuGet server at the following location: http:197.242.146.94:81/nuget/default Page 7 Version 1. 0
Front-end application components Various loosely coupled application components are provided to make up an interactive map user interface. These components and their responsibilities are listed below. Component Terrascape.Api Description This component provides a programmatic interface to the web-based endpoints exposed by the Mapzania API. Applications usually create a single instance of this component. Functions provided in this class are used mostly by the Mapzania map internally. However, applications can make use of the functions provided in this class. Examples are the ability to save a map schema to the server and perform geo-spatial calculations. Terrascape.Model Applications use the Terrascape.Model component as the primary entry point for interacting with a Mapzania map user interface. Event properties are provided that allows applications to receive various events generated by the interactive map. Examples of these are when a map is panned or zoomed, or when a layer is set visible or hidden. Additional JavaScript functions are provided to perform actions on the map. Examples are the ability to add or removed layers and apply filters to existing vector layers. Mapper / Drawer An interactive map drawer component, responsible for the rendering of features and images on the map interface. Applications typically instantiate this component once, and do not make direct use of any functions defined in this class. Mapzania provides two standard implementations of this component: Canvas.Mapper TRaphael.Mapper Terrascape.Renderer Terrascape.Viewport A component responsible for coordinating the rendering of the interactive map, using the Model, Viewport and Mapper (also known as the drawer, such as Canvas or Raphael). Applications typically instantiate this class once, and do not make direct use of any functionality provided in this class. A component responsible for coordinating the web user interface and the Mapper component (also known as the drawer, such as Canvas or Raphael). Applications typically instantiate this component once, and do not make direct use of any functions provided in this class. The following diagram shows the relationship between these components and the front-end application. Frond-end applications typically only interact with the Model and API components. Page 8 Version 1. 0
Diagram 2: Relationship between the Mapzania SDK client-side components Users can consult the JavaScript API reference documentation for a complete list of components and functions provided by the client-side Mapzania platform. Page 9 Version 1. 0
Your first Hello World example This section describes, using a step-by-step approach, how to create your first Mapzania web-based application. This example demonstrates the creation of a simple Mapzania map user interface, but with no toolbar. Step 1: Create an empty Microsoft Visual Studio 2012 project Create a new ASP.NET MVC 4 Web Application in Microsoft Visual Studio 2012. On the next dialog, when asked to select a project template, select Empty Template. Page 10 Version 1. 0
Step 2: Import Mapzania NuGet Packages After adding the Mapzania NuGet server location (http:197.242.146.94:81/nuget/default) as an additional NuGet Source to the NuGet Package Manager in Microsoft Visual Studio, add the Terrascape.Web NuGet package to the project. By adding this one NuGet package, Visual Studio will ensure that all dependent packages are added as well. This includes all third party libraries and related Mapzania packages. Page 11 Version 1. 0
Step 3: Update the Global.asax file to extend the class Terrascape.Server.Site In this step, you are required to update the main ASP.NET MVC Application class to extend the Mapzania Site base class. An example is provided below. using Aspire.Logging; namespace HelloWorld { public class MvcApplication : Terrascape.Server.Site { protected void Application_Start() { base.application_start(); } } } Log.Message("The Hello World! application has started", "Application"); The method call to Log.Message writes a message to the message log file on the server. Step 4: Update the web.config file The web.config file requires an update to contain the necessary logging framework configuration. Refer to the web.config file in the Hello World sample project for an example on how to configure the Enterprise Logging Framework. This step requires you to complete the loggingconfiguration section in this file. Step 5: Create geo-connections and a map schema Configuring Mapzania geo-connections and map schemas are outside the scope of this document. Two separate documents (namely the Mapzania Implementation Guide and the Mapzania Map Schema Guide) provides the necessary background and detailed steps to configure geo-connections and a map schema. This step requires you to configure a map with a raster layer and one or more vector layers. Label this map with the map key TESTMAP. Refer to the MapSchemas\TESTMAP.terraproj file in the Hello World sample project for an example configuration. To validate this step, you can view the map (once you have start running the Microsoft Visual Studio project) using an URL similar to the one below: http:localhost/api/maps/testmap/interactive/canvas Page 12 Version 1. 0
Step 7: Create the Hello World application HTML page In this step, we will be creating a simple HTML page, containing the map that we have configured in the previous step. No toolbar will be present. The focus is to provide an example that shows how to use and combine the (JavaScript) webbased components. Step 7.1: Create a cascading style sheet (CSS) for the Hello World application The CSS code snippet below contains the styling definition for the HTML DIV element that will contain the map user interface (see the CSS selector #map-container). The map interface, in this example, consumes all the real estate on the web page. body { left: 0px; right: 0px; top: 0px; bottom: 0px; } #map-container { position: absolute; left: 0px; right: 0px; top: 0px; bottom: 0px; } Step 7.2: Include standard Mapzania CSS files The Mapzania SDK contains a Cascading Style Sheet that should be included in all HTML pages containing a Mapzania map component. The HTML snippet below demonstrated the inclusion of this style sheet. <link href="/content/terrascape/mapper.css" rel="stylesheet" type="text/css" /> Step 7.3: Include Third Party Library JavaScript files The Mapzania SDK makes use of a number of third party JavaScript libraries. These needs to be included in all HTML pages containing a Mapzania map component. The HTML snippet below demonstrated the inclusion of these libraries. <script src="/scripts/libs/jquery-1.9.1.min.js" type="text/javascript"></script> <script src="/scripts/libs/can-1.1.6.js" type="text/javascript"></script> <script src="/scripts/libs/raphael-2.1.2.min.js" type="text/javascript"></script> Page 13 Version 1. 0
Step 7.4: Include Mapzania JavaScript files The Mapzania SDK makes up two JavaScript files. These need to be included in all HTML pages containing a Mapzania map component. The HTML snippet below demonstrated the inclusion of these files. <script src="/scripts/aspire/aspire_sdk_combined.js" type="text/javascript"></script> <script src="/scripts/terrascape/terrascape_sdk_combined.js" type="text/javascript"></script> Step 7.5: Define the HTML page content / elements The Mapzania web-based map viewer uses dynamic HTML to inject the map user interface into an existing HTML DIV component that defines the size and location of the interactive map on the map. The HTML snippet below demonstrated the declaration of this HTML component. <!-- The HTML DIV element in which the map will be displayed. It should be left empty, since the map renderer will populate this element with the map UI (using dynamic HTML). --> <div id="map-container"></div> Page 14 Version 1. 0
Step 7.6: Use the JavaScript API to create and instantiate the map The JavaScript snippet below demonstrates the use and combining of the web-based map components. Code comments explains each step. <!-- The JavaScript code, illustrating the wiring of the map components. --> <script type="text/javascript"> $(function () { Create the API component. We assume that the application URL is the Site URL in this example var api = new Terrascape.Api("/"); In this example, we make use of the Canvas map drawer. Alternatively, you can make use TRaphael.Mapper for the Raphael renderer. var mapper = new Canvas.Mapper(); Create the viewport instance. The map UI is injected in the HTML element with the id "map-container". This element var viewport = new Terrascape.Viewport("#map-container", mapper); viewport.init(function () { Create the Model and Renderer var model = new Terrascape.Model(api); var renderer = new Terrascape.Renderer(model, viewport, mapper); Add an event listener to the Model. This particular event is fired when the map schema has changed model.schemaloaded.add(function () { Once the schema was loaded for the map, we start loading the map layer content (i.e. raster tiles and vector content) model.load(); }); Start loading the schema for the map, TESTMAP. model.loadschema("testmap"); }); }); </script> Page 15 Version 1. 0
Step 8: Run the application In this step you are required to run the Hello World application. You should see a map similar to the one below. Page 16 Version 1. 0
Adding a map toolbar This section describes the steps required to add a map toolbar to a Mapzania web map. Step 1: Create a cascading style sheet (CSS) for the toolbar The file HelloToolbar.css in the Hello World sample project contains the CSS styling required for the toolbar that we will add to the Mapzania map. Map toolbars buttons are declared and styled by the application (using HTML and CSS). Applications need to ensure that each toolbar button has the correct CSS class association. For example, the Zoom In toolbar button needs to be associated with the zoomin CSS class. The table below lists the CSS classes that needs to be associated with each toolbar button. Toolbar button Zoom in Zoom out Reset Pan Length Area Query point Query line Query polygon Print map Export map CSS class name zoomin zoomout reset pan length area querypoint queryline querypolygon printmap exportmap Step 2: Define the HTML page content / elements The HTML snippet below demonstrates the declaration of the HTML elements for the map and the map toolbar buttons. The file HelloToolbar.css contains the corresponding CSS declarations. <div id="map-toolbar-container"> <!-- The HTML DIV element in which the map will be displayed. It should be left empty, since the map renderer will populate this element with the map UI (using dynamic HTML). --> <div id="map"></div> <!-- Toolbar User Interface. The toolbar is not "injected" (with dynamic HTML) like the map. --> <div id="toolbar" class="shadow"> <div class="button zoomin">zoom In</div> <div class="button zoomout">zoom Out</div> <div class="button reset">zoom Extents</div> <div class="button pan">pan</div> <div class="button length">measure Distance</div> <div class="button area">measure Area</div> <div class="button querypoint">query Point</div> <div class="button queryline">query Line</div> <div class="button querypolygon">query Polygon</div> <div class="button printmap">print</div> <div class="button exportmap">export</div> </div> </div> Page 17 Version 1. 0
Step 3: Use the JavaScript API to create and instantiate the map and map toolbar The JavaScript snippet below demonstrates the use and combining of the web-based map components and toolbar events. Code comments explains each step. <!-- The JavaScript code, illustrating the wiring of the map components. --> <script type="text/javascript"> $(function () { Create the API component. We assume that the application URL is the Site URL in this example var api = new Terrascape.Api("/"); In this example, we make use of the Canvas map drawer. Alternatively, you can make use TRaphael.Mapper for the Raphael renderer. var mapper = new Canvas.Mapper(); Create the viewport instance. The map UI is injected in the HTML element with the id "map". This element var viewport = new Terrascape.Viewport("#map", mapper); viewport.init(function () { Create the Model and Renderer var model = new Terrascape.Model(api); var renderer = new Terrascape.Renderer(model, viewport, mapper); The ToolsManager and Toolbar are both responsible for managing the tools on the toolbar var toolsmanager = new Terrascape.ToolsManager(model, viewport, mapper); var toolbar = new Terrascape.Toolbar($("#toolbar"), model); Add an event listener to the Model. This particular event is fired when the map schema has changed model.schemaloaded.add(function () { Once the schema was loaded for the map, we start loading the map layer content (i.e. raster tiles and vector content) model.load(); }); The map model fire a statechanged event when toolbar items are selected. No default implementations exists for the print and export toolbar icons. This example demonstrates how to capture these events. model.statechanged.add(function (e) { switch (e.data) { case Terrascape.MapState.printMap: window.alert("the Print Map toolbar icon was clicked!"); break; case Terrascape.MapState.exportMap: window.alert("the Export Map toolbar icon was clicked!"); break; } }); Start loading the schema for the map, TESTMAP. model.loadschema("testmap"); }); }); </script> Page 18 Version 1. 0
Step 4: Binding behavior to toolbar buttons The Mapzania SDK provides default behavior for the Zoom in, Zoom out, Reset and Pan toolbar buttons. The Model fires a gotlength event after the Measure Distance tool was invoked and the user specified two points on the map. The Model fires a gotarea event after the Measure Area tool was invoked and the user specified a set of points on the map. The Model fires a queried event after the Query Point, Query Line and Query Polygon tools was invoked and the user specified points on the map. The Model fires a statechanged event when the Print and Export tools was invoked. The file HelloToolbar.html in the Hello World project contains example uses of these events. Step 5: Run the application In this step you are required to run the Hello World Toolbar application. You should see a map and toolbar buttons similar to the ones shown below. Page 19 Version 1. 0