Skip to content

Commit

Permalink
Merge pull request #8 from Dataport/feature/prepare-meldemichel-alpha
Browse files Browse the repository at this point in the history 
Prepare Meldemichel Alpha
  • Loading branch information
@warm-coolguy
warm-coolguy authored Nov 15, 2023
2 parents 4fa40fb + 391a872 commit de36368
Show file tree
Hide file tree
Showing 19 changed files with 229 additions and 8,223 deletions.
1 change: 1 addition & 0 deletions package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
"buildPages": "rimraf ./pages_output && bash ./scripts/buildPages.sh",
"clean": "lerna clean && rimraf --glob packages/**/{.cache,dist,docs} && rimraf --glob {.cache,dist,pages_output} && node ./scripts/clean",
"docs:afm": "node ./scripts/makeDocs ./packages/clients/afm",
"docs:meldemichel": "node ./scripts/makeDocs ./packages/clients/meldemichel && npm run meldemichel:build && cp -r ./packages/clients/meldemichel/dist ./packages/clients/meldemichel/example ./packages/clients/meldemichel/docs",
"docs:sbom": "npx @cyclonedx/cyclonedx-npm --output-file sbom.json",
"docs:snowbox": "node ./scripts/makeDocs ./packages/clients/snowbox",
"lint": "npx eslint . --cache --ext .js,.ts,.vue",
Expand Down
190 changes: 81 additions & 109 deletions packages/clients/meldemichel/API.md
View file
Original file line number Diff line number Diff line change
@@ -1,20 +1,24 @@
# Meldemichel MapClient API 🗺️ `@polar/client-meldemichel`

This client is based on [POLAR](example.com/TODO) and subsequently the [masterportalAPI](https://bitbucket.org/geowerkstatt-hamburg/masterportalapi/src/master/). Please check the [common POLAR documentation](example.com/TODO) for details. The following documentation only contains how this specific client can be used, and the minimal information required to get it running.
This client is based on [POLAR](https://github.com/Dataport/polar) and subsequently the [masterportalAPI](https://bitbucket.org/geowerkstatt-hamburg/masterportalapi/src/master/). The following documentation only contains how this specific client can be used, and the minimal information required to get it running.

For all additional details, check the [full documentation](https://dataport.github.io/polar/docs/meldemichel/client-meldemichel.html).

For the development test deployments, [see here](./example/index.html).

## Basic usage

The NPM package `@polar/client-meldemichel` can be installed via NPM. When using `import mapClient from '@polar/client-meldemichel'`, the object `mapClient` contains a method `createMap`. This is the main method required to get the client up and running. Should you use another import method, check the package's `dist` folder for available files.
The NPM package `@polar/client-meldemichel` can be installed via NPM or downloaded from the [release page](https://github.com/Dataport/polar/releases). When using `import mapClient from '@polar/client-meldemichel'`, the object `mapClient` contains a method `createMap`. This is the main method required to get the client up and running. Should you use another import method, check the package's `dist` folder for available files.

The method expects a single object with the following parameters.

| fieldName | type | description |
| --------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| containerId | string | ID of the container the map is supposed to render itself to. |
| mode | enum["COMPLETE", "SINGLE", "REPORT"] | See chapters below for an overview of the modes. |
| afmUrl | string? | COMPLETE mode only. URL used in the AfM Button. |
| reportServiceId | string? | COMPLETE mode only. ID of the report layer to display. |
| configOverride | object? | You will probably not need this object. It is included to override any internal configuration, should the need for quick reconfiguration arise. Please refer to the general documentation on what can be done here. If you need it, please communicate back with us what the issue was. |
| mode | enum["REPORT", "SINGLE", "COMPLETE"] | See chapters below for an overview of the modes. |
| afmUrl | string? | TODO `COMPLETE` mode only. URL used in the AfM Button. |
| reportServiceId | string? | TODO `COMPLETE` mode only. ID of the report layer to display. |
| configOverride | object? | This can be used to override the configuration of any installed plugin; see full documentation. It is also used to set initial pins in `SINGLE` mode. See documentation of `SINGLE` further below. |

It returns a Promise of a map instance. This returned instance is required to retrieve information from the map.

Expand All @@ -24,29 +28,7 @@ The package also includes a `style.css` and an `index.html` file. The `style.css
<link data-polar="true" href="./style.css" rel="stylesheet" />
```

The `index.html` is used in COMPLETE mode, which is not run in the AfM. You may, however, use it for testing.

## Rendering COMPLETE mode

The `index.html` included in the package's `dist` folder has been prepared for this mode and must merely be hosted.

// TODO translate after implementation (details might change)

Dieser [AfMButton] wird dann gerendert, wenn in der mapConf das Feld `afmUrl` befüllt ist, zum Beispiel mit dem String `"https://afm.hamburg.de/intelliform/forms/mml_melde_michel/standard/mml_melde_michel/index"`. Diese URL ist in die Konfiguration gezogen worden, falls sich die Adresse des Prozesses einmal ändern sollte.

Der URL werden folgende Query-Parameter (hier mit Beispielwerten) hinzugefügt:

- `mapCenter=569029.708,5932888.959`
- `mapZoomLevel=9`
- `mapBaseLayer=452`
- Wert ist ID in der https://geoportal-hamburg.de/lgv-config/services-internet.json
- `vendor_maps_position=569029.708,5932888.959`
- `vendor_maps_address_str=Berlinertordamm`
- `vendor_maps_address_hnr=4`
- `vendor_maps_address_plz=12345`
- `vendor_maps_address_to=0` (Entfernung zum Hit im Falle von )

Analog liest der Klient im Modus `complete` beim Start auch alle bis auf die letzten zwei Query-Parameter wieder ein. Dabei wird die Adresse überschrieben, falls sie nicht zur `vendor_maps_position` passt.
The `index.html` is used in `COMPLETE` mode, which is not run in the AfM. You may, however, use it for testing or inspecting an example.

## Rendering in SINGLE or REPORT mode

Expand All @@ -72,101 +54,91 @@ A document rendering the map client could e.g. look like this:
</head>
<body>
<div id="meldemichel-map-client"></div>
<p>Communicated data:</p>
<p>Coordinates: <span id="test-display-coordinate">null</span></p>
<p>Address: <span id="test-display-address">null</span></p>
<p>Address data: <span id="test-display-address-data">null</span></p>
<script type="module">
import meldemichelMapClient from './client-meldemichel.mjs'
meldemichelMapClient.createMap({
const meldemichelMapInstance = await meldemichelMapClient.createMap({
containerId: 'meldemichel-map-client',
mode: 'REPORT', // or 'SINGLE'
// TODO additional parameters
mode: 'REPORT', // or 'SINGLE',
// For 'SINGLE' mode where a singular coordinate is inspected/worked on
configOverride: {
pins: {
initial: {
centerOn: true,
// The coordinate that is inspected/worked on
coordinates: [569028, 5932885],
},
movable: 'drag', // or 'none' to have an immovable pin
style: {
fill: '#0392cf' // or (optionally) '#ff0019' if 'none' is set
},
},
},
})
// If an old view state should be set, use this snippet:
meldemichelMapInstance.$store.dispatch('meldemichel/setMapState', {
vendor_maps_position: '566167.224436667,5935872.419250831',
vendor_maps_address_str: 'Alte Rabenstraße',
vendor_maps_address_hnr: '28',
mapZoomLevel: 6,
mapBaseLayer: 452,
mapCenter: '566808.8386735287,5935896.23173797',
// NOTE: vendor_maps_address_to and -_plz are not read
})
// TODO example of subscribing to store values and putting them in the paragraphs above
// to retrieve map state updates, use this snippet:
mapInstance.$store.watch(
(_, getters) => getters["meldemichel/mapState"],
({
mapCenter,
mapZoomLevel,
mapBaseLayer,
vendor_maps_position,
// The following fields are not changed/set in 'SINGLE' mode
vendor_maps_address_hnr,
vendor_maps_address_str,
vendor_maps_address_plz,
vendor_maps_address_to
}) => {
// do anything with the map values here; example print
console.info(`MapState Update
Center coordinate: ${mapCenter}
Zoom level: ${mapZoomLevel}
Base layer: ${mapBaseLayer}
Pin coordinate: ${vendor_maps_position}
Address: ${vendor_maps_address_str + ' ' + vendor_maps_address_hnr}
PLZ: ${vendor_maps_address_plz}
Distance to address: ${vendor_maps_address_to}`)
},
// will return initial values; delete parameter if not desired
{ immediate: true }
)
</script>
</body>
</html>
```

### report

// TODO translate after implementation (details might change)

Der Reportmodus ist für die Verwendung im AfM gedacht. In diesem Modus fehlen alle bereits existierenden Meldungen, d.h. die Karte beinhält keine Schäden und keine dazugehörigen Elemente Filter, Meldungstoggler, Liste. Ebenso wird der Button "Neues Anliegen" nicht angezeigt. Dieser Modus wird mit dem Schlüsselwertpaar `mode: 'report'` in der `mapConf` hergestellt. Die Angabe der `reportLayerId` und des entsprechenden Eintrags in `overlays` und `attributions` muss in diesem Fall entfernt werden.

Previously supplied map client values can be used to reconstruct a previous view.
## Rendering COMPLETE mode

```js
import meldemichelMapClient from '@polara/client-meldemichel'
The `index.html` included in the package's `dist` folder has been prepared for this mode and must merely be hosted.

const mapInstance = await meldemichelMapClient.createMap({
// ... see `createMap` description
})
// TODO update this block after implementation (TO BE IMPLEMENTED)

mapInstance.$store.dispatch('meldemichel/setMapState', {
vendor_maps_position: '566167.224436667,5935872.419250831',
vendor_maps_address_str: 'Alte Rabenstraße',
vendor_maps_address_hnr: '28',
mapZoomLevel: '4',
mapBaseLayer: '453',
mapCenter: '566808.8386735287,5935896.23173797',
})
```
Dieser [AfMButton] wird dann gerendert, wenn in der mapConf das Feld `afmUrl` befüllt ist, zum Beispiel mit dem String `"https://afm.hamburg.de/intelliform/forms/mml_melde_michel/standard/mml_melde_michel/index"`. Diese URL ist in die Konfiguration gezogen worden, falls sich die Adresse des Prozesses einmal ändern sollte.
### single

// TODO translate after implementation (details might change)

In diesem Modus wird nur ein einzelnes Feature angezeigt und ist, je nach Berechtigung, bearbeitbar. Der Feature-Umfang ist stark reduziert; verfügbar sind die FullScreen-Funktion, Zoom-In/Out, der Vermerk rechtlicher Hinweise, und Marker-Features.

Die `mapConf` kann wegen des stark reduzierten Umfangs dann zum Beispiel so aussehen:

```js
var mapConf = {
mode: 'single', // aktueller Modus
editable: true, // neu // TODO the field in Pins is called "movable"
pinCoordinate: [565699.2, 5933923.69], // neu
boundaryLayerId: '6074',
baseLayers: [
{ id: '453', displayName: 'mcapi.meldemichel.layer.cityplan' },
{ id: '452', displayName: 'mcapi.meldemichel.layer.aerial' },
],
overlays: [
{
id: '6074',
controllable: false,
visibility: false,
displayName: 'mcapi.meldemichel.layer.hamburgBorder',
},
],
attributions: {
453: 'mcapi.meldemichel.attribution.cityplan',
452: 'mcapi.meldemichel.attribution.aerial',
},
}
```

Wenn die `pinSpecification` (wie im Beispiel) fehlt, werden die Farben in Abhängigkeit vom Flag `editable` mit weißer Umrandung und Füllfarbe `editable ? '#ff0019' : '#0392cf'` hergestellt; ebenso wird das Flag `isMovable` auf den Wert von `editable` gesetzt. Die `pinSpecification` kann weiterhin auch selbst übergeben werden. Dann ist es erforderlich, das Flag `isMovable` auch selbst zu setzen. Von diesem abhängig ist, ob der Pin beweglich ist, es muss also den Wert von `editable` haben.

- `editable`: Wenn hier true gesetzt wird, erscheint der Marker rot und ist beweglich. Ansonsten ist er blau und unbeweglich. (Wie zuvor beschrieben überschreibbar.) Das Flag muss gesetzt werden. Beweglichkeit umfasst auch das Klicken an eine neue Stelle innerhalb der Karte.
- `pinCoordinate`: Die Karte bezieht keinen Meldungslayer mehr, sondern zeigt nur eine einzelne Meldung. Die initiale Position des Markers muss hiermit übergeben werden. Aktualisierungen lassen sich wie sonst auch beziehen.

Wenn der Pin verändert wird, wird wie bisher intern ein Reverse Geocoding angestoßen und das Ergebnis in den Store geschrieben.

Zur Adresssuche kann direkt die Suchfunktion der masterportalAPI verwendet werden, die unter http://141.91.163.211/mcapi/docs/module-core_masterportalAPI.html#.exports.search dokumentiert ist. Von den `searchX`-Flags sollten bei der Adresssuche `searchAddress`, `searchStreets`, und `searchHouseNumbers` auf `true` gesetzt werden.
Der URL werden folgende Query-Parameter (hier mit Beispielwerten) hinzugefügt:
Um eine Koordinate, die sich aus der Suche ergibt, in der Karte zu setzen und zu zentrieren, kann folgendes Snippet verwendet werden.
- `mapCenter=569029.708,5932888.959`
- `mapZoomLevel=9`
- `mapBaseLayer=452`
- Wert ist ID in der https://geoportal-hamburg.de/lgv-config/services-internet.json
- `vendor_maps_position=569029.708,5932888.959`
- `vendor_maps_address_str=Berlinertordamm`
- `vendor_maps_address_hnr=4`
- `vendor_maps_address_plz=12345`
- `vendor_maps_address_to=0` (Entfernung zum Hit im Falle von )
```js
window.mapInstance.plugins.pin.control.element.inputCoordinate([
567889.7183395522, 5934312.142969829,
])
window.mapInstance.getView().setCenter([567889.7183395522, 5934312.142969829])
window.mapInstance.getView().setZoom(8)
Analog liest der Klient im Modus `complete` beim Start auch alle bis auf die letzten zwei Query-Parameter wieder ein. Dabei wird die Adresse überschrieben, falls sie nicht zur `vendor_maps_position` passt.
```

## Localization

The map client is fully prepared for localization, and all visible text that does not come from external services can be overwritten. Please see the general documentation from the initial chapter for details.
18 changes: 8 additions & 10 deletions packages/clients/meldemichel/example/index.html
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<!DOCTYPE html>
<html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Meldemichel Example Hub (Build Test)</title>
Expand All @@ -22,10 +22,6 @@
<h1>Meldemichel Example Hub</h1>
<p>This is a minimal test page. Stage services are used.</p>
<dl>
<dt>
<a href="./complete.html">"COMPLETE" (Übersichtskarte)</a>
</dt>
<dd>Meldemichel Map Client rendered fullpage in mode COMPLETE.</dd>
<dt><a href="./report.html">"REPORT" (Meldungsansicht)</a></dt>
<dd>
Meldemichel Map Client as element in a larger page. Rendered in mode
Expand All @@ -36,8 +32,7 @@ <h1>Meldemichel Example Hub</h1>
</dt>
<dd>
Meldemichel Map Client as element in a larger page. Rendered in mode
'SINGLE' with parameter `movable` set to 'true'. TODO update description
when feature is implemented
'SINGLE' with parameter `movable` set to 'drag'.
</dd>
<dt>
<a href="./single.immovable.html"
Expand All @@ -46,13 +41,16 @@ <h1>Meldemichel Example Hub</h1>
</dt>
<dd>
Meldemichel Map Client as element in a larger page. Rendered in mode
'SINGLE' with parameter `movable` set to 'false'. TODO update
description when feature is implemented
'SINGLE' with parameter `movable` set to 'none'
</dd>
<dt>
<a href="./complete.html">"COMPLETE" (Übersichtskarte) (⚠️WORK-IN-PROGRESS)</a>
</dt>
<dd>Meldemichel Map Client rendered fullpage in mode COMPLETE.</dd>
<dt>
<a href="../dist/index.html"
>"COMPLETE" (Übersichtskarte) – Production Mode (as delivered via
NPM)</a
NPM) (⚠️WORK-IN-PROGRESS)</a
>
</dt>
<dd>
Expand Down
28 changes: 22 additions & 6 deletions packages/clients/meldemichel/example/report.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,12 +53,12 @@
<div class="mock-content">
<p>This is a minimal test page for the REPORT environment.</p>
<div id="polarstern"></div>
<p>Communicated data:</p>
<p>Coordinates: <span id="test-display-coordinate">null</span></p>
<p>Address: <span id="test-display-address">null</span></p>
<p>Address data: <span id="test-display-address-data">null</span></p>
<h2>Subscribed data</h2>
<ul id="subscribed-data-list"></ul>
<h2>Setting data</h2>
<p>This uses test data. See report.html contents.</p>
<button onclick="_polar.setMapState()">
Set parameters after rendering
Set test parameters after rendering (only works initially)
</button>
</div>
<script type="module">
Expand All @@ -67,7 +67,6 @@
const mapInstance = await meldemichelMapClient.createMap({
containerId: 'polarstern',
mode: 'REPORT',
// TODO incomplete API
})

window._polar = {
Expand All @@ -86,6 +85,23 @@

// NOTE: Uncomment to test immediate execution
// _polar.setMapState()

// subscribing to store values
const dataList = document.getElementById('subscribed-data-list')

mapInstance.$store.watch(
(_, getters) => getters["meldemichel/mapState"],
(mapState) => {
dataList.innerHTML = ''
const mapStateEntries = Object.entries(mapState)
mapStateEntries.forEach(([key, value]) => {
const li = document.createElement('li')
li.innerHTML = `${key}: ${JSON.stringify(value, null, 2)}`
dataList.appendChild(li)
})
},
{ immediate: true }
)
</script>
</body>
</html>
Loading

0 comments on commit de36368

Please sign in to comment.