Introduction

This tutorial illustrates the ease with which a map can be added to a GeoStream web page, and user interaction with this map enabled or disabled. It will also briefly detail to steps required to set the initial map center (as a LatLon location) and zoom level.

Prerequisites

This tutorial assumes familiarity with JavaScript. You will need a moderately-specified desktop computer. Experience with digital mapping technology is assumed only at a low level.

Setup

Before we can start using GeoBase we must obtain a copy of the software development kit (SDK). A 30-day trial of the SDK is available for download on the GeoZone website. Download and install the SDK. If you don’t already have a license you will be guided through the simple process to obtain a trial license. Choose your sample data set (HERE or TomTom) and region (California and Nevada, or the UK and Ireland; this tutorial assumes and requires USA map data).

The SDK installer will configure IIS on your local machine to host a GeoStream server. GeoStream is a GeoBase technology that allows remote access (through a web-browser, or .NET application) to your application and associated map data.

You can test your GeoStream installation by visiting this address.

http://localhost/GeoStream/scripts/tutorial.simple-map.aspx

Creating the Project

This project will consist of a single ASPX file. Open a text editor and create a file named ‘individual-map.aspx’. Save this file in ‘C:\Program Files\Telogis\GeoBase\GeoStream\server\scripts’.

Throughout this tutorial we'll add code to this file to create our application.

Note: The GeoBase SDK installer configured Microsoft IIS to host a website on your local computer. This website is accessible through the URL ‘http://localhost/GeoStream’. The files contained in this website are the files in your ‘C:\Program Files\Telogis\GeoBase\ GeoStream\server\’ directory. For this tutorial we ask that you create your ASPX file in the scripts subdirectory to make your code easier to write.

GeoStream Settings

First, several settings such as the paths to the GeoStream API include file and GeoStream servers are defined by the AuthenticatedPage ASP.NET class. This allows the same definition to be used across all your webpages. The AuthenticatedPage class is also responsible for generating the webpage's authentication token. This token is required by all GeoStream servers and should be placed at the top of your page, above the opening html tag.

<%@ Page Language="C#" Src="AuthenticatedPage.aspx.cs" Inherits="AuthenticatedPage" %>

HTML

The HTML and skeleton JavaScript code for this tutorial is shown below. Add this to your file after the definition above.

Note that the JavaScript code is typically placed between the head tags and that the main() function will be called after the page has loaded (using the body's onload property). Note that you may separate the HTML code and JavaScript code into separate files if you wish, using a regular JavaScript include construct:

<script type="text/javascript" src="path_to_js_file" />

The call to GetAPISource writes the path of the GeoBase includes to the webpage source. This line of code is required.

  <html xmlns="http://www.w3.org/1999/xhtml">
    <head>
      <title>Simple Map Demo</title>

      <script type="text/javascript" src="<% GetAPISource (); %>"></script>
      <script type="text/javascript">

        var main = function () {
              
              // JavaScript code goes here

        };
        
      </script>
              
    </head>
    <body onload="main ();">
    </body>
  </html>

JavaScript

Place the following code inside the main JavaScript function. This code performs the following actions:

  • • defines the GeoBase namespace, Map object and Size class
  • • sets the GeoStream server and authentication tokens. Note that this should be done at the start of the entry function (in this case, at the start of main) as these settings are a prerequisite for any GeoStream server requests.
  • • creates a new Map object - 640 pixels wide and 480 pixels high

By default a new Map object will be appended to the document body. To customize this behavior, create a div in the HTML section with the same id or specify a parent configuration option to the Map Constructor.

var GeoBase = Telogis.GeoBase;
var Map     = Telogis.GeoBase.Widgets.Map;
var Size    = Telogis.GeoBase.Size;

GeoBase.setService (<% GetService (); %>);
GeoBase.setAuthToken (<% GetToken (); %>);

var map = new Map ({
  id:   "main_map",
  size:  new Size (640, 480)
});

Testing

Load the newly created page in a web browser and you should see something similar to the following:

Note that the map has panning (click and drag the map) and zooming (use the mouse scroll wheel) behavior enabled by default.

Centering the Map

As a quick introduction to working with the map object we will center the map on a specified location when the map loads.

You could, for example, use this on your company web site to help visitors find your offices.

Modify the map constructor as follows to center the map on a given latitude/longitude coordinate when loaded:

var map = new Map ({
  id:   "main_map",
  size:  new Size (640, 480),
  center: new Telogis.GeoBase.LatLon(34,-117.5)
});

With this change, your map should appear similar to the following when refreshed:

Simple Map 2

Setting Zoom Level

You may wish to also increase the zoom level (0-19), using map.setZoomIndex(level)). For example:

var map = new Map ({
  id:   "main_map",
  size:  new Size (640, 480),
  center: new Telogis.GeoBase.LatLon(34,-117.5)
});
map.setZoomIndex (15); // set an initial zoom level: higher number is closer zoom

Which results in the following:

Simple Map 3

Disabling User Interaction

In some instances it may be desirable to prevent the user from panning and zooming by interacting directly with the Map object. In these instances, use the setUiEnabled property of the Map to disable interaction. This may be done like so:

var map = new Map ({
  // ... constructor arguments, as usual
});

map.setUIEnabled(false); // disables mouse panning and zooming

Complete Code

<%@ Page Language="C#" Src="AuthenticatedPage.aspx.cs" Inherits="AuthenticatedPage" %>
          
  <html xmlns="http://www.w3.org/1999/xhtml">
    <head>
      <title>Simple Map Demo</title>

      <script type="text/javascript" src="<% GetAPISource (); %>"></script>
      <script type="text/javascript">

      var main = function () {

        var GeoBase = Telogis.GeoBase;
        var Map     = Telogis.GeoBase.Widgets.Map;
        var Size    = Telogis.GeoBase.Size;

        // the call to set the internal GeoBase authentication token should be made at 
        // the start of the entry function, as it is a prerequisite for any requests 
        // made to the server.

        GeoBase.setService (<% GetService (); %>);
        GeoBase.setAuthToken (<% GetToken (); %>);
  
        // by default, a newly created map object has its DOM tree appended to the 
        // document body. To customize where the map is located, either create in the 
        // HTML section a div with the same ID, or specify a "parent" configuration option.
    
        var map = new Map ({
            id:   "main_map",
            size:  new Size (640, 480)
        });
        
      };

      </script>
    </head>
    <body onload="main ();">
    </body>
  </html>

Published, Jul 7th 2016, 22:31

Tagged under: geobase javascript maps