MORIS/OLIVER Developers Documentation

Last Updated: 6/26/2013
For questions about this documentation contact Aleda.Freeman@state.ma.us

Please note: OLIVER is one of a family of applications, all built on the same template. Some of the other versions include MORIS (the MassGIS Online Data Viewer) and various MuniMappers such as Great Barrington. This user guide applies to all of these applications, so you may substitute MORIS, MuniMappers, etc. for OLIVER as you read this guide.

 

Background

 

This document explains the technology behind the new OLIVER online data viewer. The code is: (c) 2010 Third Sector New England, Inc. on behalf of the Massachusetts Ocean Partnership (now SeaPlan). This code was developed by Applied Science Associates, Inc. and Charlton Galvarino. License: This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. In addition to the terms of the GNU General Public License, licensee agrees to be subject to this Additional Term: Licensee shall notify and provide Third Sector New England and the SeaPlan via email to info@tsne.org and info@seaplan.org, with a copy of all "modified versions" of the earlier work that is subject this license or a work "based on" the earlier work that is subject to this license. Download the OLIVER/MORIS code.

 

OpenLayers/GeoExt OLIVER is an online mapping tool created by the Massachusetts Office of Coastal Zone Management (CZM), the Office of Geographic Information (MassGIS), the SeaPlan (formerly Massachusetts Ocean Partnership), Applied Science Associates (ASA) and Charlton Galvarino. The viewer is configurable and so currently there are several similar viewers sharing the same code base. We currently have these variations (others are in the planning stages):

 

OLIVER: http://maps.massgis.state.ma.us/map_ol/oliver.php

MORIS: http://maps.massgis.state.ma.us/map_ol/moris.php

Boston Harbor Habitat Atlas: http://maps.massgis.state.ma.us/map_ol/habitatatlas.php

Great Barrington MuniMapper: http://maps.massgis.state.ma.us/map_ol/great_barrington.php
As of 6/26/2013, MuniMappers for 63 municipalities were available.

 

Configuration

 

While it is possible to run the MORIS/OLIVER code on a server that is not the MassGIS maps.massgis.state.ma.us server, this documentation is not meant to explain all the changes that would be required. MORIS/OLIVER versions run most easily on the maps server as certain pregenerated files are stored there. This documentation is meant to familiarize users with the configuation options available in MORIS/OLIVER MassGIS is available to work with agencies to design their own "MORIS/OLIVER" application to be hosted on maps.massgis.state.ma.us.

The viewer is configured to get maps and map data from an Open Geospatial Consortium (OGC) web map service (WMS) and web features service (WFS). Currently the MassGIS GeoServer-based WMS/WFS at giswebservices.massgis.state.ma.us is used.

 

Configuration by Permalink

 

The viewer can create permalinks that will open the viewer with certain initial layers, extent, basemap and units. A smaple permalink is as follows: http://maps.massgis.state.ma.us/map_ol/moris.php?lyrs=Lighthouses~massgis:GISDATA.LIGHTHOUSES_PT~GISDATA.LIGHTHOUSES_PT::Default|Shipping%20Lanes~massgis:MORIS.OM_SHIPPING_LANES_POLY~MORIS.OM_SHIPPING_LANES_POLY::Default&bbox=-71.22945277771358,42.22168078128292,-70.67498653023294,42.448062415013&coordUnit=dms&measureUnit=m&base=googleSatellite&\center=-7898364.9625328,5211289.6665746&zoom=12&opacity=,.50 This permalink shows two default layers Lighthouses and Shipping Lanes, in the lyrs parameter. First is the title, then a ~ symbol, then the GeoServer layer name, then another ~ and then the GeoServer style name. The bbox parameter describes the extent with lower left and upper right coordinates. The coordUnit parameter specifies the coordinate system - the available values currently are: 'dms','dd','m'. The measureUnit parameter sets the default measure units - the available values currently are 'm','mi','nm','yd','ft'. The base parameter specifies the basemap type the available values currently are: custom, bingHybrid, bingRoads, bingAerial, CloudMade, googleSatellite, googleTerrain, googleRoadmap, googleHybrid, openStreetMap, TopOSM-MA. The center parameter (here with an extra \, please disregard) describes the center point (here in Google coordinates) and the zoom parameter is the zoom level for Google maps.

 

A permalink created from the Custom basemap which is MA State Plane Mainland NAD 83 meters would look different:

 

http://maps.massgis.state.ma.us/map_ol/moris.php?lyrs=Lighthouses~massgis:GISDATA.LIGHTHOUSES_PT~GISDATA.LIGHTHOUSES_PT::Default|Shipping%20Lanes~massgis:MORIS.OM_SHIPPING_LANES_POLY~MORIS.OM_SHIPPING_LANES_POLY::Default&bbox=-71.23322214489919,42.25624962423178,-70.66987482633337,42.413583951989004&coordUnit=m&measureUnit=m&base=custom&\center=245170.66772379,898452.59314803&zoom=5.477373832034868&opacity=,

 

The lyrs and bbox parameter values are the same, but the base is different (and I also changed the coordUnit to match the base). The center parameter is now described in MA State Plane Mainland NAD 83 meters coordinate system (the coordinates used match the base map used). The opacity parameter lists the percent opaque for each layer.

 

It would be possible to construct permalinks ahead of time for a group of geographic areas (for example counties) without having to manually zoom to those areas in the viewer and ask for the permalinks.

 

Note that the value of the lyrs parameter is the title of the layer. This is not the same as the GeoServer title. This title comes from the folderset XML file. For MORIS this folderset is http://maps.massgis.state.ma.us/temp/moris_folderset.xml. For OLIVER the folderset is http://maps.massgis.state.ma.us/temp/oliver_folderset.xml. A title captures both the dataset and style information. For example, these two permalinks both use the massgis:GISDATA.LANDUSE_POLY GeoServer layer.

 

Permalink 1971 landuse:

 

http://maps.massgis.state.ma.us/map_ol/oliver.php?lyrs=Land%20Use%201971%2021%20Classes~massgis:GISDATA.LANDUSE_POLY~GISDATA.LANDUSE_POLY::21_Classes_1971_Solid&bbox=-70.1940443008258,42.05406660236499,-70.17197442632964,42.06328551857349&coordUnit=m&measureUnit=m&base=custom&\center=309005.45338622,868428.06555454&zoom=9.917277226297156

 

Permalink 1999 landuse:

 

http://maps.massgis.state.ma.us/map_ol/oliver.php?lyrs=Land%20Use%201999%2021%20Classes~massgis:GISDATA.LANDUSE_POLY~GISDATA.LANDUSE_POLY::21_Classes_1999_Solid&bbox=-70.1940443008258,42.05406660236499,-70.17197442632964,42.06328551857349&coordUnit=m&measureUnit=m&base=custom&\center=309005.45338622,868428.06555454&zoom=9.917277226297156

 

In the URLs spaces have been URL encoded to the value %20. The title used in the 1971 example is Land Use 1971 21 Classes and in the 1999 example is Land Use 1999 21 Classes. These can be see in the http://maps.massgis.state.ma.us/temp/oliver_folderset.xml

 

The XML folderset needs to have unique titles for each layer/style combination. It is not possible therefore to create a permalink for a layer/style combination that is not represented in the folderset XML document. This is a necessary limitation based on the way the viewer was constructed. However, lines can easily be added to the folderset XML document. See below for more information on the folderset XML document.

 

Configuration of the .php

 

In addition, the .php files listed above have some configuration parameters that can or do make the viewers different from each other:

 

- Folderset of datalayers

Which folders and datalayers in the Available data layers window is configurable. Point the foldersetLoc variable to a web-accessible XML file. Study http://maps.massgis.state.ma.us/temp/moris_folderset.xml or http://maps.massgis.state.ma.us/temp/oliver_folderset.xml as examples of formatting. The titles of the datalayers must be unique if different styles are used. The available values for the parameter type include pt, line, polygon, raster and layergroup (this refers to a GeoServer layergroup which is a collection of layers and styles grouped together under one name).

- Initial datalayers
Which datalayers show when the application is launched can be configured using the defaultLyrs variable. The variable holds a list of layers consisting of the WMS name and the title (which will be shown in the Active data layers window). The titles of the datalayers listed in the .php must match titles in the folderset. The datalayers will draw in opposite order from the list. In other words, the first datalayer in the list will be the bottom-most datalayer drawn on the map.

- Initial extent
The initial extent or geographic area that shows when the application is launched can be configured in the defaultBbox variable. The units should be specified in decimal degrees, with the lower left coordinate then upper right coordinate, with commas separating all numbers. Sample: [-71.863711,41.028298,-69.174525,43.075512]

- Maximum extent
The maximum extent or geographic area (the farthest out that the user can zoom) can be configured in the maxBbox variable. The units should be specified in decimal degrees, with the lower left coordinate then upper right coordinate, with commas separating all numbers. Sample: [-71.863711,41.028298,-69.174525,43.075512]

- Initial basemap
The initial basemap can be configured in the defaultBase variable. The available values currently are: custom, CloudMade, googleSatellite, googleTerrain, googleRoadmap, googleHybrid, openStreetMap, TopOSM-MA. Due to a GeoExt software toolkit bug the Bing layers cannot be currently used as defaulty layers (however, they do work in permalinks). Currently custom is Massachusetts State Plane Mainland NAD83 meters. defaultBaseOpacity sets the opacity of the basemap. Values from 0 to 1, with 1 being completely opaque and 0 being completely transparent.

- External WMS layers
External WMS layers can be presented from non-MassGIS servers. Because the maps.massgis.state.ma.us server is not allowed to access the Internet, the GetCapabilities documents for those services should be downloaded and stored locally on the maps.massgis.state.ma.us server. External WMS servers offered in 26986 or a Web Mercator projection (900913, 102113, 3857 for example) can be supported. The external WMS layers will draw on the appropriate basemaps.

- Initial coordinate system
The initial coordinate system can be configured in the defaultCoordUnit variable. The available values currently are: 'dms','dd','m'.

- Default measure units
The default measure units can be configured in the defaultMeasureUnit variable. The available values currently are 'm','mi','nm','yd','ft'.

- Browser title
The value in the browser's title bar can be configured in the siteTitle variable. The value of this variable is also used in the value of the Help menu, About choice.

- Site URL
The site URL should be configured in the siteURL variable. For example, if the application is launched from http://maps.massgis.state.ma.us/map_ol/moris.php, this should also be the value in the siteURL variable. The siteURL variable is a component of the permalink URL.

- Help links
The value of the help links (under the Help menu, Help choice) can be configured in the helpUrl1 and helpUrl2 variable. helpUrl1 points to an HTML document and helpUrl2 points to a PDF document as indicated on the user interface.

- About link
The value of the info in Help menu / About choice dialog box can be configured in the moreInfoHTML variable. The value of the variable should be HTML and can include tables, image tags and links. The moreInfoWidth variable can be used to specify the width of the info box.

- WMS/WFS/WCS/KML location
The viewers at maps.masasgis.state.ma.us point to the MassGIS GeoServer-backed web mapping services. However, this can be changed. The variables wfsUrl, wmsUrl, wcsUrl, kmlUrl, namespaceUrl, and featurePrefix can be changed to another GeoServer instance or probably another WMS instance. Note: The map projection is not configurable at this time, additional code modification would be needed to change the Custom map projection from MA State Plane Mainland NAD83 meters (EPSG 26986) to another projection.

- proxy location
Because of the browser same-origin policy a proxy script is required for the client (currently served from maps.massgis.state.ma.us) to request XML data from giswebservices.massgis.state.ma.us. If hosting the client application on your own, modify the value of the proxyLoc variable. Currently MassGIS uses a Python script called proxy.cgi.

- Bing usage
The client application uses the Microsoft Bing service for geocoding. MassGIS has a Perl script called get that assists in this. To change this setting, edit the value of the proxyLocBing variable.Also, edit the value of the bingKey variable to hold the key for your Bing registration. Make sure the bingDisabled variable is set to true if using Bing.

- Zip service
The client application uses a Perl script called mkzip to zip up the extracted data and supporting metadata and additional files into a .zip file if the users chooses that option. To change the location of the mkzip script edit the value of the mkzipCGI variable. The mkzip script specifies the location of the zipped output. It is recommended that a script clean out the contents of the mkzipLoc periodically. The mkzipLoc variable should be set to the server name where the application is hosted. It is used to build a link to downloadable files.

- OpenLayers, ExtJS and Proj4JS links
If running this application on your own server it would be wise to point to local copies of these libraries. Edit these values:

<script type="text/javascript" src="http://openlayers.org/api/OpenLayers.js"></script>
 
<link rel="stylesheet" type="text/css" href="http://www.sencha.com/deploy/dev/resources/css/ext-all.css" />
src="http://www.sencha.com/deploy/dev/adapter/ext/ext-base.js"></script>
<script type="text/javascript" src="http://www.sencha.com/deploy/dev/ext-all.js"></script>
 
<script src="http://proj4js.org/lib/proj4js-compressed.js"></script>

 

Configuration of the toolConfig_default.js

 

In addition to modifying the .php to configure the viewer, another file called toolConfig_yourname.js can be edited. Buttons and tools can be hidden or shown or zoom dropdowns can be added. The reference to which toolConfig file is being used in a viewer is set in the .php file. It is recommended to have a custom toolConfig file for each viewer.

 

- Buttons or tools that can be shown / hidden:

Identify tool, Identify by Poly tool, Bing search tool, Add External datalayers tool, Print tool, Data Export tool, Measure tool, Comment tool, Draw tool, Edit tool, ScaleBar tool, MapUnits tool, Basemaps tool. We may add configure other buttons and tools to be optional in the future.

 

- QuickZoom tools:

QuickZoom tools can be set up. They are dropdowns that read their values from the database. OLIVER includes a QuickZoom to allow the user to zoom to a town. QuickZoom tools can also be linked to each other. For example, if two datalayers share a field, such as towns and schools share the TOWN_ID field, then one dropdown for towns can spark a subset in the second dropdown. For example, the user picks Malden from the first dropdown, then the second dropdown's values narrow to include only schools in Malden. The user then chooses a school and then the zoom occurs. Alternately, independent (unlinked) QuickZoom can be displayed if the user needs to zoom to more than one type of geographic extent.

 

- Comment Tool:

The Comment tool is an option to enter data into a point datalayer. Is it meant to enter a comment at a particular place. "My house is here." "This school is closed." Only one datalayer can be commented upon per viewers. The data is entered into the SDE database by means of a test_comment.php script. The name and location of the script is specified in the toolConfig file. In this way is it different than the Draw/Edit tools described below. This method is meant to enter a point which cannot be retrieved and re-edited. A subset of datalayer fields can be specified and fields can be made mandatory to fill out. Dropdowns can be populated with values, but the values must be listed in the toolConfig (they are not read from the database). Another datalayer can be shown on the map with a superset of the name, if the original data values should be hidden but the user should see the point show up on the map (so they are convinced it was entered). The current demo does not use a username/password protected GeoServer layer but the test_comment.php could be updated to accomodate this. Currently the datalayer can be limited to one-feature-at-a-time query.

 

- Draw / Edit Tools:

Draw and Edit tools can be added to an application. The datalayer can be protected with a username and password so that only authorized users can add or edit data. More than one layer can be edited in an application, however in that case they must share the same username/password. Points, lines or polygons may be edited. Snapping and splitting may be used (this is optional). Limitations: Current limitations include: all fields are editable (no fields can be excluded from being edited), all fields are optional (the user cannot be forced to enter data for any particular field), there are no dropdown values to fill in fields. These improvements will be added in Spring 2012. If username/password is used then https must be used in both the .php and the URL to access the application. Snapping can be set up for each datalyaer edited. Snapping can happen to more than one layer, including the layer being edited. Snapping will occur even if the layer being snapped to is not draw on the map. Snapping will occur to both lines and vertices. When snapping the user is asked to draw a geogrpahic area within which snapping should occur (to collect the appropriate vertices into the viewer). However, features that are selected by this drawn rectangle are used in their entirety. Currently it is possible to split only lines with lines.

 

Demo Viewers

 

An Excel spreadsheet has been created listing several sample viewers which demonstrate the various configurations explained in this documentation.

 

- GetCapabilities cache location

In order for the client application to work more efficiently, MassGIS runs a Perl script called slice_getcaps.pl as a preproduction step. The slice_getcaps.pl script takes the output of the GetCapabilities request to the MassGIS GeoServer (http://giswebservic es.massgis.state.ma.us/geoserver/wms?request=GetCapabilities&service=WMS&version=1.1.1) and applies some logic to slice the information into separate pieces and include style information and scale dependencies with those styles. The location of the output of the slice_getcaps.pl script can be modified in the xmlCacheLoc variable. Also a getCapsBbox.js Javascript file in that cache dir is used so this line should be modified: <script type="text/javascript"

src="/temp/OL_MORIS_cache/getCapsBbox.js?1296487021"></script>

 

Download all the scripts mentioned in this documentation.

 

Browser types and versions

 

As of June 2013 MORIS has been extensively tested in the latest versions of the browsers Firefox 21, Internet Explorer 10, Chrome 27 and Safari 5.1.7 It has been found to work well in all 4 browsers. It should also work well in earlier versions of these browsers.

 

Acknowledgments

 

The tool icons are courtesy of Custom Icon Design, FatCow Web Hosting, Robert Szczepanek, VisualPharm, and Yusuke Kamiyamane.