Map Settings

This page explains how to change a number of default settings of the Waqwaq GIS application.

Overview

The following table gives an overview of the available settings, the levels where they can be set and the settings overriding hierarchy from left to right, further detailed in the next sections.

(1) Functionality currently not implemented.

Hierarchy

Principle: The ultimate settings retained by the software are the top-most defined settings in the levels stack. For example a language setting defined in the data ini file will override that of the site ini file, but will be itself overridden by a setting passed via URL.

Impact: The level at which a setting is defined has an impact on:

• how many datasets will inherit this setting,
• who can modify a setting,
• how fast the application runs.

The levels hierarchy and their common usage are given in the following table.

Definitions

• JavaScript function: A JavaScript code in another application that the Waqwaq software used to trigger actions in Waqwaq, usually through an iframe that embeds Waqwaq into another website.
• GIS interface: Refers to the part of the webpage containing the legend and action objects, as well as to the sets of actions defined over the map itself, such as clicking a location to open an information window.
• Webservice URL: The URL of the Waqwaq webservice, typed in the browser's URL box, embedded in a hyperlink or programmatically generated.
• Data ini file: File containing the settings specific to your data file to be mapped with Waqwaq.
  Since the data ini files are specific to each dataset, you have to construct them yourself.
  1. Make a copy of /data/site.ini.js and rename it to [your dataset file name].ini.js.
  2. Remove all lines from it that don't correspond to the settings you wish to modify, provided they are modifiable at the data ini level (see the table in "Overview").
  3. Modify the content of the targeted settings variables as desired, following the explanations in the "Syntax" section.
• Site ini file: Settings for the entire website hosting the Waqwaq application. Located in /data/site.ini.js.
• Data header: Section describing the content of a dataset in a georeferences file prepared for Waqwaq, such as mygeoreferences.jsonp. Some information given in the header - the languages of the map legend - influence how the interface or map are rendered.
• Data body: The set of records in your dataset file.
• In-code: Settings variables appearing in the application's code. Not modifiable.
• Programmatic: Settings that result from an algorithm in the code. Not modifiable.

Syntax

Modification of settings is operated differently according to the layer where it is set:

• GIS interface: Through action elements such as buttons, fill-in text boxes or by mouse actions on the map.
  Ex. : To change the "map extent" initial setting hold the Shift key down and move the mouse over the region of interest in the map diagonally.
• Webservice URL: Appending a setting definition to the webservice's address and following the [?|&][setting name]=[setting value] syntax.
  Ex. : http://www.waqwaq.info/ws/main/main.html?lng=eng&bbox=-179.9,-89.9,179.9,89.9
  Precede the string with ? when immediately following the webservice string and with & if following other settings.
• Data ini, Site ini files, Data header, Data body: Modify the content of the variables referencing the setting. The variable can be identified by its name or by their commentaries.
  Ex. 1: To set the initial map extent for all maps to the world extent insert "-179.9,-89.9,179.9,89.9" between the brackets in the following line of the /data/site.ini.js file as follows: var bbox = [-179.9,-89.9,179.9,89.9]; // initial map extent.
  Ex. 2: Supposing your data bounding box has the values -20,35,45,60 you can supply them in the boundingbox variable in the header section of your data file: "boundingbox":[-20,35,45,60]. This will speed up map generation since the software doesn't have to extract this information from the records.
• In-code: Reside at the beginning of the /brain/main.js file. Should not be modified.
  Ex. : URL of the Waqwaq density map webservice.
• Programmatic: Programmatically constructed in /brain/main.js. Should not be modified.
  Ex. : To set the initial map extent if no information is available on the data bounding box the Waqwaq code computes the bounding box by extracting the extreme coordinates values from the data file and forwarding it to the ArcGIS API, which then determines the map extent so that the data fits into the map frame.

Settings

Data

Vectors data URL

Function: Provides the URL for the initial dataset that will be shown when the map is generated.
Syntax:

1. Webservice URL: [?|&]url=[url name].
   Ex. : http://www.waqwaq.info/ws/main/main.html?url=http://www.waqwaq.info/ws/main/data/lion.jsonp.
2. Site ini file: var vectorsUrl = "[url name]";
   Ex. : var vectorsUrl = "http://www.waqwaq.info/ws/main/data/lion.pts.json";.

Note: Upwards relative paths are supported, with the dirctory of main.html as starting point. Ex. : The following two notations are equivalent:

1. var vectorsUrl = "http://www.waqwaq.info/ws/main/data/lion.pts.json";
   
2. var vectorsUrl = "./data/lion.pts.json";

Points data URL

Function: Provides the URL for the data needed to generate density maps.
Syntax:

1. GIS interface: Type the URL of the points data file in the "Density" section box.
2. Webservice URL: [?|&]purl=["[url name]"].
   Ex. : http://www.waqwaq.info/ws/main/main.html?purl=http://www.waqwaq.info/ws/main/data/lion.pts.json.
3. Data & site ini files: var pointsUrl = ["[url name]"];
   Ex. : var pointsUrl = ["http://www.waqwaq.info/ws/main/data/lion.pts.json"];.

Note: See the "Definitions" section above on how to construct a points data file. No support for relative path for points data URLs.

Cartography

Map extent

Function: Defines which geographic area will be visible to the user.
Syntax:

1. GIS interface: Chose among the map navigation methods listed in the "Navigation" section of the map interface.
2. Webservice URL: [?|&]mext=[ [northern-most latitude,eastern-most longitude,southern-most latitude,western-most longitude] ].
   Ex. : http://www.waqwaq.info/ws/main/main.html?mext=-179.9,-89.9,179.9,89.9.
3. Data & site ini files: var mext = [ [northern-most latitude, eastern-most longitude, southern-most latitude, western-most longitude] ];
   Ex. : var mext = [-179.9,-89.9,179.9,89.9];.
4. Programmatic: The map extent is computed by the ArcGIS API on the basis of the data bounding box extracted by the Waqwaq API from the dataset body.

Data bounding box

Function: Specifies the spatial extent of the data in a given dataset file.
Syntax:

1. Data header: "boundingbox":[ [northern-most latitude, eastern-most longitude, southern-most latitude, western-most longitude] ]
   Ex. : "boundingbox":[-179.9,-89.9,179.9,89.9]
2. Data body: "latitude":"[latitude]", "longitude":"[longitude]"; in decimal degrees, with comma (.) decimal separator. This information is implicitly supplied when generating the georeferences file.
   Ex. : "latitude":"48.87"=, ="longitude":"2.33".

Note: See also Metadata > header > boundingbox and Data > items > latitude & longitude on the MapFileFormat page.

Interface language

Function: Language of the user interface.
Syntax:

1. Webservice URL: [?|&]lng=["[language code]"] (follows ISO 639-2/B-alpha-3).
   Ex. : http://www.waqwaq.info/ws/main/main.html?lng=yid to use Yiddish.
2. Data & site ini files: var guiLanguage = "[language code]";
   Ex. : var guiLanguage = "yid";.

Note: Passing this setting through the URL sets also the dataLanguage (see below) to the same setting. MapI18n describes how to create interfaces for any language.

Data language

Function: Selects the language that will be used on the GIS interface to display the metadata supplied in the datasets.
Syntax:

1. Webservice URL: [?|&]lng=["[language code]"] (follows ISO 639-2/B-alpha-3).
   Ex. : http://www.waqwaq.info/ws/main/main.html?lng=apa to use an Apache language.
2. Data & site ini files: var dataLanguage = "[language code]";
   Ex. : var dataLanguage = "apa";.
3. Programmatic: If no setting is given, then the software chooses the first value of the "contentLanguage" field in the metadata section "header > content" of the dataset.

Note: 1. The availability of a specific data language depends on the languages in which the metadata is supplied by the datasets producers. 2. Passing this setting through the URL sets also the guiLanguage (see above) to the same setting.

Regions names

Function: Sets the URL to the nomenclature file of regions names used to decode the regions id-s given in the datasets in "items > regionid".
Syntax:

1. Data & site ini files: var regionsNamesUrl = "[url name]";
   Ex. : var regionsNamesUrl = "./brain/nuts2003.js";.

Note: Waqwaq supplies two region names datasets: /brain/nuts2003.js and /brain/iso3166-1-a2-[***].js. The former contains the extensive NUTS 2003 nomenclature for Europe and supplements with ISO 3166-1 alpha2 for country names not in NUTS. The later is the aforementioned country names ISO scheme translated in individual files to English (ISO 639-2/B-alpha-3 code is 'eng'), French (fra), German (ger), Italian (ita), Russian (rus) and Spanish (spa). See also MapFileFormat > Data > items > regionId.

Colormap

Function: Specifies a colormap for the symbolic location markers on the map.
Syntax:

1. GIS interface: Check "colorblind" in "Symbols" section to switch to a colorblind colormap.
2. Data & site ini files: var cm = [[[red value, green value, blue value],...],[...]];.
   Ex. :
   var cm = [
   [
   [255, 255, 191],
   [202, 0, 32],
   [5, 113, 176],
   [244, 165, 130],
   [146, 197, 222]
   ],
   [
   [128, 128, 128],
   [255, 0, 0],
   [0, 170, 238],
   [51, 204, 0],
   [255, 170, 0]
   ]
   ];

Note: Color values are integers in the 0-255 range. The first value of the colormap is reserved for unknown or zero values. There are two colormaps available concomitantly, the first for the benefit of color-blind viewers. Check Color Brewer for more cartographic color schemes and Vischeck for simulating colorblind vision. The colorblind-safe colormap used by Waqwaq is based on Color Brewer's "Paired" scheme and simulated with Vischeck. See also MapFileFormat > Data > items > theme.

Defaults:

Interface width

Function: Sets the width of the GIS interface.
Syntax:

1. GIS interface: Slide horizontally the vertical divider between the map and the interface areas of the application.
2. Webservice URL: [?|&]guiw=[value in pixels].
   Ex. : http://www.waqwaq.info/ws/main/main.html?guiw=300.
3. Site ini file: var guiWidth = [width in pixels];.
   Ex. : var guiWidth = 300;.

Note: It's not a good practice to totally obscure the interface by setting it to zero. The user will not be able to understand what data is on the map and looses the ability to manipulate it.

Processes

Post point URL

Function: URL of a server application to which the coordinates of the point where the user double-clicked on the map are send for further processing. (This functionality disables the default recenter & zoom-in map navigation method.)
Syntax:

1. Site ini file: ws.postCoordinatesUrl = "[url name]"; .
   Ex. : ws.postCoordinatesUrl = "http://mywebserver.com/getcoordinates.php";.

Note: The server application could for example get point coordinates from the GIS application and use them to extract records from a database near the given point. A php script template is provided in /data/getcoordinates.php.

Geoprocessing URLs

Function: URLs of ArcGIS geoprocessing and map webservices.
Syntax:

1. In-code: ArcGIS services catalog base path: ws.servicesGpUrl = http://[server name]/!ArcGIS/rest/services/;,
   Individual geoprocessing tasks: ws.densityGpUrl = ws.servicesGpUrl + "[toolbox name]/GPServer/[task name]";.

-- VladAtanasiu - 27 Aug 209