Skip to content

The Map Component is a reusable, flexible and highly configurable Building Block meant to be used throughout CSIS.

Notifications You must be signed in to change notification settings

clarity-h2020/map-component

Repository files navigation

Map Component DOI

The Map Component is a reusable, flexible and highly configurable Building Block meant to be used throughout CSIS. It is an embeddable component that can be easily adapted to different parts of the common CSIS UI. The core functionality of this component is visualization of different maps and layers following to the EU-GL process model.

image

Implementation

Specialised maps for EU-GL Steps EE, HC, HC-LE, RA/IA and AAOP are implemented as separate components. The main components are:

BasicMap

This is the basic class of all specialised map classes. It implements the common way to extract the layers from the CSIS Study. In fact, it is a wrapper component for a component that controls an actual mapping component implementation (e.g a react-leaflet map). In principle it transforms the CSIS Drupal JSON format into a simple internal layer definition format (see example below) that is understood by a JSX Component (e.g. <LeafletMap>) that renders the actual map, e.g. a leaflet-based map.

[ {
    "checked": false,
    "groupTitle": "Backgrounds",
    "layers": "Boundary,Footprint,Image",
    "name": "Digital_Elevation Model",
    "style": ",",
    "title": "Digital Elevation Model",
    "url": "https://copernicus.discomap.eea.europa.eu/arcgis/services/GioLandPublic/DEM/MapServer/WmsServer?"
  }, 
...
]

The component processes the query parameters and, with help of csis-helpers-js, prepares Background layers, Overlay Layers and respective Layer Groups based on Data Package Resources either from a single resource (query parameter resource_uuid) or from a set of resources contained in a Data Package associated with a Study and retrieved from the CSIS Drupal API (query parameters study_uuid or datapackage_uuid).

Thereby, Template Resources are expanded into several layers according to the scenario definition (time_period, emissions_scenarios and event_frequency) provided via query parameters. Only those resources are considered that are associated with a specific Taxonomy term, in general a term from the EU-GL Taxonomy like Hazard Characterization. The taxonomy as well as the specific term are either specified via query parameters overlayLayersTagType and overlayLayersTagName or are pre-set in a specialised Map like the <CharacteriseHazardMap>.

The categorisation of layers into different Layer Groups (Backgrounds, CLARITY Backgrounds, etc.), which is a feature of react-leaflet-grouped-layer-control, is also controlled via taxonomy terms (e.g. from the Hazards that are either provided via query parameters (e.g. &grouping_tag=taxonomy_term--hazards) or also pre-set in a specialised map (<CharacteriseHazardMap>).

image

Leaflet Map

A common map component based on ReactLeaflet v2.7 that understand the JSON layer definition format created by a <BasicMap>. It is mainly responsible for creating <WMSTileLayer> and <WMSLayer> components from the JSON objects received via props overlays and exclusiveGroups. "Exclusive Groups" are a feature of react-leaflet-grouped-layer-control.

WMS Layer

<WMSLayer> is a react wrapper for leaflet.wms, an all-in-one WMS plugin for Leaflet. In contrast to leaflet's built-in <WMSTileLayer>, it support the WMS getFeatureInfo operation which is used to show a popup of layer properties on the map.

image

Generic Map (Synchronised Maps)

<GenericMap> extends <BasicMap> and is actual base class of all specialised map classes. Unless the Simple Table Component, the Map Component does not use functional components but classes. In addition to <BasicMap>, it adds the possibility to show two synchronised components side-by-side with help of Leaflet.Sync:

sync-map

Whether the generic or a specialised map is rendered as two synchronised maps is controlled via the isSynchronised prop. Furthermore, App.js defines separate routes for synchronised and non-synchronised maps, e.g. /CharacteriseHazardMap/ and /SynchronisedCharacteriseHazardMap/.

Specialised Maps

For convenience, specialised Maps currently offer just EU-GL-specific pre-sets of the query parameters and props, respectively, accepted by <BasicMap>. The following specialised maps are currently available:

Study Area Map

<StudyArea> is used by Drupal to show and edit the study area. As the functionality is quite different from the other maps and since it requires more interaction with the Drupal API, it is not derived from <BasicMap>. Since it is integrated into CSIS Drupal with help of React Mount Node, it is developed in a separate branch and deployed independently of master / dev branches.

image

Tests

The same Unit Tests as for csis-helpers-js are performed. UI Integration Tests are implemented with help of cypress.io in repository csis-technical-validation.

Apart from that, the different map components can be manually tested locally with yarn start. Although they are served from localhost, the user must be logged-in in either csis or csis-dev.

Example URL for testing a synchronised '' locally against Study "Urban heat screening Vienna North" with baseline scenario:

http://localhost:3000/SynchronisedCharacteriseHazardMap/?host=https://csis-dev.myclimateservice.eu&study_uuid=9359e741-df40-4bcd-9faf-2093b499c65c&study_area=POLYGON%20((16.346111%2048.223997,%2016.346111%2048.238634,%2016.376667%2048.238634,%2016.376667%2048.223997,%2016.346111%2048.223997))&emikat_id=3183&datapackage_uuid=2434ce93-93d4-4ca2-8618-a2de768d3f16&time_period=Baseline&emissions_scenario=Baseline&event_frequency=Rare&grouping_tag=taxonomy_term--hazards

Installation

Development Environment

The application has been bootstrapped with create-react-app and uses the built-in build process . Node v12.x and yarn v1.x has to be installed locally.

Building

Building and installing the app is straightforward:

yarn install
yarn build
yarn test

The dev branch is automatically built on cismet CI based on this pipeline definition.

Dependencies

Dependencies can be easily upgraded with npm-upgrade:

npx npm-upgrade

The advantage over yarn upgrade is that that package.json is updated with the new dependency version.

Deployment on CSIS

Although Map Component is integrated in CI, deployment on CSIS is not automated. The following manual steps are required on cisis-dev.ait.ac.at and cisis.ait.ac.at.

Study Area Map

The study area map does not use the dev or master branch, but a branch that is based on the map-component version that was integrated into drupal as a module. The current branch is bug/87_improve_edit_mode_of_study_area

sudo su docker
cd /docker/100-csis/drupal-data/web/modules/custom/map-component/

# pull the current branch
git pull

# if the branch has changed (e.g. because of a new bugfix), the new branch should be used
git checkout <new branch>

# it is not necessary to build the application, because the branch contains the builded application 

# clear drupal cache
docker exec --user 999 csis-drupal drush cr

Map Component

sudo su docker
cd /docker/100-csis/drupal-data/web/apps/map-component/

# reset yarn.lock
git reset --hard

# pull dev or master branch
git pull

# install latest dependencies (may update yarn.lock)
yarn install --network-concurrency 1

# build the app
yarn build

# clear drupal cache
docker exec --user 999 csis-drupal drush cr

Note: Commonly on DEV the dev branch and on master the master branch is used.

Usage

Query Parameters

Unless the Scenario Analysis Component, this component does not use seamless.js to communicate with the CSIS Drupal System when embedded as iFrame. Instead, it can be configured by query parameters. Main reasons are that bidirectional communication between iFrame and main site is not required and that query parameters allow the app to be tested independently of CSIS.

The different maps are selected by the corresponding route defined in App.js, e.g. /SynchronisedCharacteriseHazardMap for a synchronised <CharacteriseHazardMap>. The query parameters supported by are:

  • host CSIS API host (e.g. https://csis.myclimateservice.eu/)
  • emikat_id internal EMIKAT Study id (e.g. 3209)
  • time_period (e.g. Baseline)
  • emissions_scenario (e.g. Baseline)
  • event_frequency (e.g. Frequent)
  • study_uuid Drual internal uuid of the study
  • study_area study area WKT for setting the initial map bbox
  • datapackage_uuid Drual internal uuid of the data package
  • clarityBackgroundLayersTagType taxonomy for selecting Background Layers
  • clarityBackgroundLayersTagName taxonomy term for selecting Background Layers
  • clarityBackgroundLayersGroupName name of the Background Layers Group
  • overlayLayersGroupName taxonomy for selecting Overlay Layers, e.g. EU-GL taxonomy
  • overlayLayersTagType taxonomy term for selecting Overlay Layers, e.g. EU-GL Hazard Characterisation
  • overlayLayersTagName name of the Overlay Layers Group, e.g. Hazards
  • overlayLayersGroupingTagType taxonomy for selecting the name of Overlay Layers subgroups, e.g. Hazards

Query parameters are processed in BasicMap.js. For more information on query parameters refer to CSISHelpers.defaultQueryParams.

Integration in CSIS

Map Component

The application is integrated as "Extended iFrame" in CSIS Drupal System. The respective Drupal Nodes that contain the iFrame are listed here.

The application is configured via the aforementioned query parameters. The query parameters are extracted by csis_iframe_connector.js from the studyInfo object which is injected into the main Drupal CSIS Website via the CSIS Helpers Drupal Module, in particular by StudyInfoGenerator.php.

The "Extended iFrame" nodes are used in several EU-GL Step Templates as [Extended iFrame] Map Application, e.g. in EU-GL Steps Impact/Risk Assessment and Adaptation Options Appraisal.

Study Area Map

The application is integrated as "React Mount Node" in CSIS Drupal System. The respective Drupal Node is the "Map Component: Study Area. It is only used as default value of field_study_area_map in the Study Group Type.

License

MIT © cismet GmbH