MVW mapConfig.js

MVW mapConfig.js

This file, residing in /mukau/js/, can be considered the core of map settings, dealing with:

• definition of JavaScript variables globally used by the MapViewer if not defined in layerDates.js or provided by gisconfigpgp2js.php;
• definition of variables to access the WMS server from which layers are retrieved, i.e.:
  • MUKAU_WMS: URL to call directly MapServer as WMS server reading mukau.map
  • BASE_WMF: URL to call directly MapServer as WMS server reading base.map
  • MUKAU_MSWMS: URL to call mswms.php, a custom WMS server based on PHP MapScript, with mukau.map
  • BASE_MSWMS: URL to call mswms.php, a custom WMS server based on PHP MapScript, with base.map
• definition of the map as OpenLayers.Map object;
• setting projection, extent, zoom level and map centre during map initialization;
• definition of all layers present into the map, each as OpenLayers.Layer object;
• adding layers to the map (OpenLayers map.addLayers method); please note that not all layers are added, because some of them – e.g. graticule, markers, highlight and highlight_int - are managed as functions;
• registering layers to the layer tree (definition of a GeoExt.data.LayerStore for each group of layers, layer tree elements not being a root or a leaf); please note that layers managed as functions and hidden layers are not registered into the layer tree;
• setting some graphics to layer groups;
• functions for exporting the map.

Definition of a new layer

Every time a new layer must be added to the map, the operations to do are:

1. Define the layer as OpenLayers.Layer object. Only OpenLayers.Layer.WMS is present in mapConfig.js at the moment.
2. Push the layer into the array aLayersToAdd, that is used as an argument of OpenLayers map.addLayers method; please note that the first layer pushed into the array is the bottom layer in the stack of layers drawn on the map. By consequence layers should be pushed in this order:
   • Base Layers
   • Geographic Background layers as polygons or filled rasters
   • Thematic layers as polygons or raster
   • Optional National/International or Regional/Local layers as polygons or raster (not present in the current version of Mukau)
   • Geographic Background layers as little areas, lines, non-filled rasters
   • Geographic Background layers as points
   • Optional National/International or Regional/Local layers as lines or points (not present in the current version of Mukau)
   • Thematic layers as lines or points
   • System layers as points (markers)
3. Register the layer into the layer's attribute of the GeoExt store representing its group, i.e.:

groupStore = new GeoExt.data.LayerStore({ layers: [layer1,layer2,…] });

Please note that the last layer in the layers array is the first layer appearing in the layer tree group.

Layer attributes

Each OpenLayers.Layer.WMS object comes with several attributes, with the syntax:

var layerName = new OpenLayers.Layer.WMS( "Layer_name" , "WMS_URL" , { WMS parameters } , { Optional settings } );

layerName is the JavaScript variable that will be used in steps 2) and 3) to add the layer to the map and to register it into the layer tree.

Layer_name, instead, is the human-readable name of the layer and will be displayed into the layer tree and within pop-ups opened by MapVIewer’s functions.

WMS_URL is URL of the source WMS server, usually corresponding to one among MUKAU_WMS, BASE_WFS, MUKAU_MSWMS or BASE_MSWMS seen before.

{ WMS parameters } is an object containing WMS parameters (case insensitive). Only the layers parameter is mandatory, while other parameters like format or transparent are optional.

• layers is crucial because it is the link between mapConfig.js and the source mapfile. Since layers allow more than one layer in its value (as a CSV list), it’s possible to define a single layer in mapConfig.js to load more than one layer from the mapfile simultaneously, without or with scale constraints. Each layer present into the value of the layers parameter must correspond to the value of a NAME reference of a layer object within the source mapfile.
• transparent is important to display raster layers without background. { Optional settings } is an object containing additional attributes to be associated to the layer. They are listed in the next lines and can be optional attributes provided by OpenLayers (mainly by OpenLayers.Layer superclass) or custom attributes defined ad hoc for the Mukau MapViewer.

Optional layer settings

The list adopts an alphabetical order to make finding the attribute faster. The type of attribute is stated by a symbol, as follows:

• ☼ Layer appearance attributes
• ≝ Descriptive attributes
• ⚙ OpenLayers' system attributes
• ◳ Other tools' attributes
• ❔ Query-related attributes
• ≣ Themes
• ◔ Time attributes
• ⚿ Use limitation attributes
• ⋟ “WMS-reminder” attributes
• ⛶ Zoom-related attributes

Attributes provided by OpenLayers are marked by OL, while attributes defined ad hoc for the MapViewer are marked by AH.

• ❔ app (AH): if query results must be highlighted and displayed on the map, this option is used to compose part of the name of the highlighted feature stating the name of the project (e.g. “Mukau”). Its value should be fix and equal to HEADER_DEFAULT_PREFIX.toLowerCase().

• ⚙☼ autoActivate (OL): in a graticule layer (OpenLayers.Control.Graticule) activates (true) or not (false) its control when it is added to a map.

• ≝ attribution (OL): layer attribution, displayed on the map, e.g. for base layers.

• ≣ currentThemeIndex (AH): attribute to get the current active layer theme; see themes attribute for details.

• ◔≣ date (AH): if the layer/theme is loaded as a WMS-Time, this option contains the last available date. Usually the value is set by a JavaScript variable defined into layerDates.js.

• ◔ dateMode (AH): option to specify in which way date/time information is provided for the layer. At the moment only the following CSV is supported: `"available only,dateFormat,sourceQueryId", where the available only`` keyword means that only available dates will be displayed in a select menu, ``dateFormat`` is the format in which dates must be displayed (e.g. ``YYYY-MM-DD``) and ``sourceQueryId`` is the value of ``IDENTIFY_QUERIES.ID``, i.e. the ID of the row where the query to extract the available dates is defined into the table ``IDENTIFY_QUERIES``.

• ◔≝ dateWithoutHyphen (AH): if this option is set to true, the date is passed to the WMS server without hyphens (e.g. 20170130 instead of 2017-01-30). Please note that despite is technically possible and in certain cases useful to execute a WMS GetMap request passing a date without hyphens (or split in different URL parameters, one for each time component), this is not compliant with the OGC standards.

• ⚙ displayInLayerSwitcher (OL): states if the layer should be (value true) displayed into the Layer Tree(s) or not (false).

• ☼ displayLabels (AH): if a layer A has this option set with an array containing one or more layer names B, C, etc., those layers are used to display labels for the features of the layer A. Labels can be visualized using the “Display Labels” tool within the context menu.

• ☼ drivenBy (AH): if this option is set with a name of another layer, this layer is activated/deactivated when the referenced layer is. For example, if the layer "water_surfaces_labels" has drivenBy:"Water surfaces", it is activated or deactivated when "Water surfaces" is activated or deactivated respectively.

• ◔≣ eightdays (AH): if the layer/theme is loaded as a WMS-Time, this option contains the current value of the 8-day period part of date/time. Usually the value is set by a JavaScript variable defined into layerDates.js. The value of eightdays can be changed with the “Select Time” tool available in the context menu and passed to the WMS server.

• ≣ file (AH): file name to be used for a layer theme legend; see themes attribute for details.

• ◔≣ firstYear (AH): if the layer/theme is loaded as a WMS-Time, this option contains the year of the first available date. Usually the value is set as string or number, but can be also a JavaScript variable defined into layerDates.js.

• ◔ fore_month (AH): if the layer is loaded as a WMS-Time for forecast data, this option sets for which month forecast data must be displayed by default: the string value is "01" for the first available month, "02" for the second, and so on.

• ◔ fore_months (AH): if the layer is loaded as a WMS-Time for forecast data, this option sets for how many months in the future forecast data must be proposed (integer value).

• ◳ googleOverlay (AH): if set to true, the layer is enabled to be displayed into Google Earth as a Google Overlay. The value can be also set to "globalGoogleOverlay", in order to use the global configuration defined at the begin of mapConfig.js.

• ≝ group (AH): option stating which group the layer belongs to. Please note that the layer’s group within the Layer Tree is NOT determined by this option but by the registration of the layer in the Layer Tree stores at the end of mapConfig.js.

• ◔≝ hideYear (AH): if this option is set to true, the year is not present in the current date displayed close to the layer name.

• ❔ highlightingLayer (AH): if the layer is used to display query results on the map, this option must be set to true to make it easily detectable by the MapViewer among all the layers.

• ❔ highlightRandom (AH): if query results must be highlighted and displayed on the map, this option is used to compose part of the name of the highlighted feature with a random number. Its value should be fix and equal to "highlightRandom", JavaScript variable defined at the begin of mapConfig.js.

• ≝ iconLegend (AH): object with options for the keyimage to introduce a layer within the Layer Tree. The attributes of such an object are:

  • ≝ offCls (AH): name of the CSS (defined in mvw.style.css) to be used when the layer is off (i.e. not active): the icon set in that CSS is visualized;
  • ≝ onCls (AH): name of the CSS (defined in mvw.style.css) to be used when the layer is on (i.e. active): the icon set in that CSS is visualized; please note that if the layer is active but not visible because the current map scale is outside of a visibility scale range defined for that layer, a grey bulb icon is displayed.

• ≝ iconLegOffCls (AH): name of the CSS (defined in mvw.style.css) to be used for the layer keyimage when the layer is not active.

• ≝ iconLegOnCls (AH): name of the CSS (defined in mvw.style.css) to be used for the layer keyimage when the layer is active.

• ❔ identifyAllDroughtIndicators (AH): set this option to true to register the layer to the “Identify All Drought Indicators” function.

• ❔ identifyQueriesId (AH): reference to the ID of the row of IDENTIFY_QUERIES table where the query to provide an "Identify" function related to this layer is defined.

• ≝ infoIcon (AH): if set, an “info i“ is associated to the layer name in order to quickly open the layer description. Possible values are right (i written after the layer name; this is the default) and left (before the layer name).

• ⚙ isBaseLayer (OL): says if a layer is (value is true) or not (false) an OpenLayers’ baseLayer. The MapViewer’s Layer Tree has a dedicated group, named “Base layers”, where users can choose among different OpenLayers’ baseLayers the active baseLayer. Please note that the projection of the active baseLayer is automatically set also to the map, with possible side effects in scale, extent and zoom properties and functions.

• ⚙ isGraticule (AH): states if the layer is (value true) an OpenLayers.Control.Graticule or not (false).

• ❔ isQueryable (AH): says if a query can (value is true) or cannot (false) be executed on this layer.

• ⚙☼ labelSymbolizer (OL): introduces or constructs an OpenLayers.Symbolizer.Text (see OpenLayers documentation for details).

• ◔≣ lastYear (AH): if the layer/theme is loaded as a WMS-Time, this option contains the year of the last available date. Usually the value is set by a JavaScript variable defined into layerDates.js and corresponds to the year option.

• ≣ layer (AH). Layer name to be used in a MapServer CGI call to get a layer theme legend; see themes option for details.

• ≣ layers (AH). List of layer names to be used in a WMS call involving a layer theme; see themes option for details.

• ≝ legend (AH): specifies the legend to be displayed under the layer name or selecting the “Layer Legend” tool in the contextual menu. Legends can be taken from image files or generated on-the-fly using MapServer CGI in legend mode (&mode=legend).

  • File-based legends usually are referred by means of the function getLegendTag(legFile,padding,ms_no_mvw,legId,width) defined in ol_geMapViewer.js, where legFile is the path of the legend image as value of img’s src attribute ~ padding is the CSS padding property to be set in img’s style attribute (default 10) ~ ms_no_mvw is a flag: if the value of legFile contains a relative path and this argument is true, the project specific mapserver/ directory is considered (true is the value usually set in mapConfig.js because legends normally stay in mapserver/legends/ directory) ~ legId is the value of id attribute of an optional span tag in which the legend’s img tag must be included as a child element (usually not set in mapConfig.js for calls of getLegendTag) ~ width is the CSS width property to be set in img’s style attribute (usually not set in mapConfig.js).

  • On-the-fly legend generation is triggered setting the function getMsCgiLegendTag(mapfile,layer,env,padding,ms_no_mvw,fixext,applyEiu,width) defined in ol_geMapViewer.js, where mapfile is the CGI call (mapserv/mapserv?map=<mapfile_path>); layer is the layer name within the called mapfile ~ env is the environment where the CGI call must be executed (“int” for internal, “ext” for external; usually the variable "globalWmsEnv" - defined at the begin of mapConfig.js and sets the target environment for the whole mapfile - is used) ~ padding is the CSS padding property to be set in img’s style attribute (default: 10) ~ ms_no_mvw is a flag: if true states that the project specific mapserver/ directory must be used (true is the value usually set in mapConfig.js) ~ **fixext*8 is a flag: if set and true, an extent of 1 dd x 1 dd is used in the CGI call (e.g. &mapext=9+45+10+46); otherwise, the current map extent is used (usually this argument is not set in mapConfig.js) ~ applyEiu is a flag: if set and true, the function getExtIntUrl (defined in util.js) is called with the value of env in order to set the target web server where the CGI call must be executed (usually this argument is not set in mapConfig.js) ~ **width is the CSS width property to be set in img’s style attribute, usually not set in mapConfig.js.

• ≣ legend (AH): layer’s theme legend; see themes option for details.

• ⚙☼ lineSymbolizer (OL): introduces or constructs an OpenLayers.Symbolizer.Line (see OpenLayers documentation for details).

• ⚿ locked (AH): if this option is set and true, the layer is visible only to developers (or registered users) and marked with a lock icon.

• ☼ maxscaledenom (OL): denominator of the minimum scale at which the layer must be visible.

• ≝ metadata (OL): layer description, displayed by the “Layer Info” tool in the contextual menu or clicking the “info i“ close to the layer name, if present. Its value can be a free text or an instruction to get the description from a metadata of the source layer object within the mapfile read by the WMS server. In the latter case, the value of metadata must be a string like >FROM_MAPFILE;layer_name;source_metadata_name, where >FROM_MAPFILE is a fix keyword, layer_name is the name of the source layer within the mapfile and source_metadata_name is the name of the metadata of the mapfile’s layer object from which the description must be taken. Usually source_metadata_name reads the WMS standard wms_abstract metadata or a metadata defined ad hoc by Mukau developers, for example DESCRIPTION.

• ≣ metadata (AH): layer’s theme description; see themes option for details.

• ☼ **``minscaledenom (OL): denominator of the maximum scale at which the layer must be visible.

• ≣ mode (AH): attribute necessary to set from where a layer’s theme legend must be retrieved; see themes option for details.

• ◔≣ month (AH): if the layer/theme is loaded as a WMS-Time, this option contains the current value of the month part of date/time. Usually the value is set by a JavaScript variable defined into layerDates.js. The value of month can be changed with the “Select Time” tool available in the context menu and passed to the WMS server.

• ≣ name (AH): name of a layer theme; see themes option for details.

• ☼ opacity (OL): opacity of layer tiles(s), ranging from 0 (completely transparent) to 1 (completely opaque). The value can be also set to "globalRasterOpacity", in order to use the global opacity configuration defined at the begin of mapConfig.js.

• ❔ queryableMultiple (AH): set this option with an array of two layer names or more in order to associate to the layer two or more Identify functions. For example, if you want to associate two independent Identify instances to the layer “Faults and volcanoes”, set queryableMultiple: ["Volcanoes", "Faults"]. Warning: this option is not available in Mukau, but can be asked to be imported from GDO (Global Drought Observatory) if necessary.

• ◳ sbsm (AH): specifies the name/identifier of this layer within the Side-by-Side Maps (SBSM) tool. The value is a string composed by one name or by two names separated by a pipe character, |. In the latter case, the second name is the layer name, while the first name says in which Layer Tree of the MapViewer this layer resides (Monitoring or Forecast). Since Side-by-Side Maps is not present in Mukau, this option is not active in mapConfig.js.

• ☼ scaleVariableLegend (AH): if this option is set to true, the layer legend is displayed only when the layer is actually visible, i.e. when it is active and the current map scale falls inside the visibility scale range defined for the layer. If false or not set, the legend is displayed when the layer is active independently from the scale.

• ≝ session (AH): if query results must be highlighted and displayed on the map, this option is used to refer the queried geographical feature by its ID. Please set this attribute with the fix keyword LAST_FEATURE_ID (variable defined at the begin of mapConfig.js).

• ☼ singleTile (OL): says if the layer must be drawn as mosaic of different tiles (value is false) or with a unique tile covering all the map (true). If defined in gisconfig.php, the PHP constant GE_MAP_SINGLETILE_ALL can be used here as global setting for singleTile/multiTile property. Multiple tiles allow a faster visualization especially if the layer drawing is heavy because there are many and/or complex features to draw. A single tile is better if the layer is not heavy and if there are labels that can be cut or repeated in multiple tiles. Please note that a layer in singleTile mode could be not generated if its extents covers the whole world and the scale is very small (global or quasi-global).

• ☼ slidingChange (AH): use this option to allow (set true) or avoid (false) date update and map regeneration when moving a time slider or an opacity slider. Continuous map regeneration can create a useful animation effect if the map drawing is almost immediate or very fast. But if it is slow, this provokes a bad user experience and system instability. If slidingChange=true, date update and map regeneration are done during every change event of GeoExt, while if slidingChange=false, date update and map regeneration are done with the changeComplete event. If this option is not set, the global PHP constant GE_SLIDER_SLIDINGCHANGE, defined in gisconfig.php, is considered.

• ◔ starting_month (AH): if the layer is loaded as a WMS-Time for forecast data, this option contains the value of the first month from which forecast data are available. Usually the value is set by a JavaScript variable defined into layerDates.js.

• ◔ starting_year (AH): if the layer is loaded as a WMS-Time for forecast data, this option contains the value of the first year from which forecast data are available. Usually the value is set by a JavaScript variable defined into layerDates.js.

• ◔≣ tendays (AH): if the layer/theme is loaded as a WMS-Time, this option contains the current value of the dekad (10-day period) part of date/time. Usually the value is set by a JavaScript variable defined into layerDates.js. The value of tendays can be changed with the “Select Time” tool available in the context menu and passed to the WMS server.

• ◔≝ tendays_abbreviation (AH): use this option to abbreviate the word referring to a 10-day period in the Layer Tree. The value is an array of two elements, i.e. the full word and its abbreviation, e.g. ["period","p."].

• ≣ themes (AH). A layer can be set to be the entry point of different themes: for example Mukau has the “FAO Land Management” layer with ten themes defined. Users can select a theme using the “Select Layer Theme” option of the context menu. The themes option of mapConfig.js is an array of objects, each of them representing the definition of a theme. The attributes of theme objects are:

  • ≣ currentThemeIndex (AH): used by the MapViewer to get and set the current active theme; please leave it null in mapConfig.js;
  • ≣ layers (AH): has the same utility than the WMS layers parameter set for the layer: when the WMS call is executed, the value of layers attribute of the active theme is set as value of &LAYERS URL (WMS) parameter;
  • ≣≝ legend (AH): attribute to set the theme's legend. Its value is an object with the following attributes: env (AH): allows to set a local value for the env argument of getMsCgiLegendTag() ~ file (AH): if the legend is taken from a file, this attribute is used to set the file path or just its name if residing within mapserver/legends/ ~ layer (AH): if the legend is taken from a MapServer CGI calls, this attribute is used to set the target layer name, corresponding to the layer argument of getMsCgiLegendTag() call ~ mode (AH) can have two possible values (string): “getLegendTag” to get the legend from a file name, “getMsCgiLegendTag” to get the legend by means of a CGI call; see layer’s legend option for details on calling getLegendTag() and getMsCgiLegendTag() functions ~ width (AH): value of legend's width CSS property, corresponding to the width argument when calling one of the two functions seen before ~ wmsServer (AH): if the legend is taken from a MapServer CGI call, this attribute is used to set the fix part of the CGI call, corresponding to the mapfile argument of getMsCgiLegendTag().
  • ≣≝ metadata (AH): theme description; value can be a free text or a string >FROM_MAPFILE;layer_name;source_metadata_name as seen for the layer’s metadata attribute;
  • ≣≝ name (AH): the theme name as visualized in green below the layer name and in the “Select Layer Theme” tool;
  • ≣◔⋟ wmsTimeFormat (AH): specifies how to pass time/date information to the WMS call. For example, if wmsTimeFormat: "YYYY,MM,DD", a URL parameter for each time component is added to the WMS call.

• ◔ timeFormat (AH): specifies the format time/date information related to this layer must be displayed.

• ◔ timescale (AH): sets the default timescale for a layer, e.g. "03" for SPI. The value of timescale can be changed with the “Select Time” tool available in the context menu and passed to the WMS server.

• ◔ timescales (AH): array of timescales available for this layer, e.g. ["01","03","06","12"].

• ◳ timeseries (AH): specifies the identifier of this layer within the Timeseries tool, not available in this instance of Mukau.

• ◳ timeseriesName (AH): specifies the name of this layer within the Timeseries tool, not available in this instance of Mukau. For example, for SPI you could set timeseries: "spi" and timeseriesName: "SPI blended and interpolated".

• ◳ ugc (AH): specifies the name of this layer within the Unified Graph Creator (UGC) tool, not available in this instance of Mukau.

• ≝ uom (AH): unit of measurement associated to the indicator/physical quantity represented by the layer. This option is mainly used for layer names and descriptions.

• ☼ visibility (OL): sets if the layer must be on (value is true) or off (false) after initialization.

• ≣ width (AH): width of a layer’s theme legend; see themes option for details.

• ⋟ wmsLayer (AH): reminder of the WMS layer name (value of &LAYERS in WMS call).

• ◔≣⋟ wmsTimeFormat (AH): specifies how to pass time/date information to the WMS call. For example, if wmsTimeFormat: "YYYY,MM,DD", a URL parameter for each time component is added to the WMS call (e.g. &YEAR=2017&MONTH=01&DAY=30). Please note that despite is technically possible and useful to execute a WMS GetMap request passing a date split in different URL parameters (or with a unique parameter but without hyphens), this is not compliant with the OGC standards.

• ⋟ wmsTitle (AH): reminder of the WMS layer title (value of &LAYERS in WMS call).

• ◔≣ year (AH): if the layer/theme is loaded as a WMS-Time, this option contains the current value of the year part of date/time. Usually the value is set by a JavaScript variable defined into layerDates.js. The value of year can be changed with the “Select Time” tool available in the context menu and passed to the WMS server.

• ⛶ zoomLayer (AH): set this option to true to enable the “Zoom to Layer” tool within the context menu.

• ⛶ zoomLayerExtent (AH): array of the layer’s bounding box coordinates, e.g. [-74,0,-68,5], taken by OpenLayers when “Zoom to Layer” is executed.

At the end of mapConfig.js there is a section named “SUBGROUP GRAPHICS” with settings of Layer Tree subgroups. We call Layer Tree each panel on the left of the MapViewer containing layers organized in groups. At the moment only one panel is present, the "Monitoring" Layer Tree, but for example a "Forecast" Layer Tree could be also defined. Each Layer Tree allows a “3½-level” hierarchy, with the following terminology:

• A 1st-level object is named group and contains subgroups or layers; at the moment the following groups are defined in Mukau: “Continental DLDD Products”, “Regional, National, Local Products”, “Geographic Background” and “Base layers”; the first is divided in subgroups, the second is empty.
• A 2nd-level object containing layers is named subgroup; for example, “Precipitation” is a subgroup of “Continental DLDD Products”.
• A leaf in the Layer Tree is a layer: it can be a 3rd-level object in a subgroup (like “SPI” in “Precipitation”) or a 2nd-level object in a group without subgroups (like “Towns” in “Geographic Background”).
• The last ½ level of the hierarchy is a theme: it is a subdivision of a layer, but does not appear directly in the Layer Tree, being selectable through the “Select Layer Theme” option of the context menu.

The "SUBGROUP GRAPHICS” settings are definitions of an associative array named a_SUBGROUPGRAPHICS and used by layerTreeConfig.js. Each definition has this syntax:

a_SUBGROUPGRAPHICS[sgIdentifier]=oDefinitions;

where sgIdentifier is a string (mostly corresponding to the name) identifying the group or subgroup, while oDefinitions is an object of properties to be assigned to the group/subgroup.

The properties available for oDefinitions are:

• keyimage_on: CSS used to set the icon associated to the group/subgroup when it is expanded;
• text: the text to be displayed for this group/subgroup within the Layer Tree;
• treeExpanded: says if the group/subgroup must be expanded (value = true) or collapsed (false or not set) during initialization. If the group/subgroup is present in more than one Layer Tree (e.g. in “Monitoring” and “Forecast” Layer Trees), the value of treeExpanded can be an object where a Boolean value is set for each Layer Tree (e.g. treeExpanded: {monitoring:true,forecast:false} );
• treeHidden: says if the group/subgroup must be hidden (value = true) or displayed (false or not set) during initialization. If the group/subgroup is present in more than one Layer Tree (e.g. in “Monitoring” and “Forecast” Layer Trees), the value of treeHidden can be an object with a Boolean value set for each Layer Tree.