Konfiguration mit Domain-Bundles

Motivation

Die vorausgehenden Abschnitte stellen dar, auf welche Weise verschiedene Aspekte einzelner Apps - wie z.B. die Grundkarte(n), Themenkarten oder die Suche - angepasst werden können.

Es gibt jedoch Situationen, in denen zahlreiche Apps mit den selben Konfigurationsoptionen bedient werden sollen. Zum Beispiel, wenn sich mehrere Apps dieselben Dienste für Hintergrund- oder Themenkarten teilen. Dabei kann es vorkommen, dass sich zwar viele Apps einen Teil der Konfigurationsoptionen teilen, jedoch nicht alle dieselben.

Mit Hilfe von Domain-Bundles ist es möglich, diese Konfigurationsoptionen in einem eigenen Bundle zu verpacken. Dieses kann dann in vielen Apps wiederverwendet werden. Darüber hinaus können Konfigurationsoptionen für verschiedene Funktionen einer App in einem Domain-Bundle zusammengefasst werden. So lassen sich alle Aspekte einer Fachdomäne gebündelt konfigurieren.

Die Bereitstellung als Bundle unterstützt dabei, die enthaltenen Konfigurationsoptionen in zahlreichen Apps auf verschiedene Weise beliebig zu kombinieren. Außerdem bieten Bundles von Hause aus die Möglichkeit der Versionierung. So können Updates an der Konfiguration einer oder mehrerer Apps gezielt verteilt und angewandt werden.

Domain-Bundles erstellen

Die Konfiguration in einem Domain-Bundle ist analog zur app.json aufgebaut.

Aufbau und Möglichkeiten

Im einfachsten Fall besteht ein Domain-Bundle lediglich aus einer JSON-Datei (manifest.json), in der ein oder mehrere Konfigurationsfragmente abgelegt sind. Alle Konfigurationsfragmente werden in JSON innerhalb des Schlüsselworts domain-config beschrieben. Es ist möglich ein oder mehrere dieser Fragmente gleichzeitig in einem Domain-Bundle zu konfigurieren. Die folgende manifest.json zeigt beispielhaft eine leere Konfiguration aller möglichen Fragmente:

{
    "name": "domain-yourCustomDomainBundleName",
    "version": "1.0.0",
    "dependencies": {
        "domains-system": "^4.4.0"
    },
    "main": "",
    "layer": "",
    "i18n": [],
    "domain-config": {
        "map-basemaps": [],
        "map-layers": [],
        "ags-stores": [],
        "report-mappings": []
    }
}

Jedes Fragment hat sein eigenes Schlüsselwort und eine Konfiguration, die einem Teil der App-Konfigurationsdatei (app.json) entspricht. Die folgende Tabelle listet die möglichen Fragmente der Domain-Bundle-Konfiguration auf:

Fragment Schlüsselwort in domain-config Entsprechung in der app.json

Grundkarten

map-basemaps

 
"map-init": {
    "Config": {
        "basemaps": []
    }
}

Themenkarten

map-layers

 
"map-init": {
    "Config": {
        "map": {
            "layers": []
        }
    }
}

Quellen für Suche und räumliche Auswahl

ags-stores

 
"agssearch": {
  "AGSStore": []
}

Berichte (Reports)

report-mappings

 
"reporttool": {
  "ReportTask": {
    "mappings": []
  }
}

Vollständiges Beispiel

Das folgende Beispiel zeigt eine Domain-Bundle-Konfiguration, die alle verfügbaren Konfigurationsfragmente verwendet:

{
    "name": "domain-yourCustomDomainBundleName",
    "version": "1.0.0",
    "dependencies": {
        "domains-system": "^4.4.0"
    },
    "main": "",
    "layer": "",
    "i18n": [],
    "domain-config": {
        "map-basemaps": [
            {
                "id": "esri_street",
                "title": "Streets",
                "thumbnailUrl": "resource('images/thumbnailImage.png')",
                "basemap": "gray-vector"
            }
        ],
        "map-layers": [
            {
                "id": "koeln3",
                "title": "Koeln",
                "url": "https://services.conterra.de/arcgis/rest/services/common/koeln/MapServer",
                "coverImage": "resource('images/coverImage.png')",
                "type": "AGS_DYNAMIC",
                "visible": true
            }
        ],
        "ags-stores": [
            {
                "id": "store01",
                "title": "Adressen",
                "url": "https://services.conterra.de/arcgis/rest/services/common/koeln_adressen/MapServer/0",
                "omniSearchSearchAttr": "ADRESSE",
                "omniSearchDefaultLabel": "Adressen"
            }
        ],
        "report-mappings": [
            {
                "storeId": "store01",
                "reportId": "report01",
                "fileName": "Report.pdf"
            }
        ]
    }
}

Domain-Bundles verwenden

Die Installation und Nutzung von Domain-Bundles erfolgt analog zu anderen Bundles (siehe Verwalten von Funktionen (Bundles)).

Dabei können Domain-Bundles in einer oder mehreren Apps verwendet und beliebig kombiniert werden. Die Konfigurations-Fragmente der Domain-Bundles werden neben der bestehenden App-Konfiguration angewandt, wofür je nach Aspekt die im Folgenden beschriebenen Rahmenbedingungen gelten.

Auswirkungen auf die App

Jeder Aspekt, der mit einem Domain-Bundle konfiguriert wird (z.B. Karte oder Suche), wirkt sich auf die App und ihre Konfiguration aus. Im folgenden ist je nach Aspekt beschrieben, wie sich Domain-Bundle-Konfigurationen auf eine App auswirken.

Grundkarten

Grundkarten werden innerhalb des Schlüsselwortes "map-basemaps" analog zur app.json konfiguriert. Die aktive Grundkarte wird über die Eigenschaft "selected":true festgelegt. Hier ein Beispiel:

{
    "map-basemaps": [
        {
            "id": "esri_street",
            "title": "Streets",
            "thumbnailUrl": "resource('images/thumbnailImage.png')",
            "basemap": "gray-vector",
            "selected": true
        }
    ]
}

Aus der folgenden Tabelle kann entnommen werden wie sich über Domain-Bundles bereitgestellte Grundkarten auf die App bwz. App-Konfiguration auswirken:

Verhalten bei …​ Beschreibung Beispiele

…​ Anwendung der Konfiguration

Grundkarten aus Domain-Bundles werden der App hinzugefügt und stehen nach dem Laden des Bundles zur Auswahl zur Verfügung.

Grundkarten mit eindeutigen IDs werden der Karte hinzugefügt. Da nur eine Grundkarte selektiert sein kann, wird die Grundkarte aus einem Domain-Bundle nur dann selektiert, wenn es keine selektierte Grundkarte in der App gibt und nicht zuvor ein anderes Domain-Bundle eine Grundkarte selektiert hat.

…​ festgelegter Reihenfolge

Grundkarten werden in der Reihenfolge der geladenen Domain-Bundles hinzugefügt.

In der Karte ist nur eine Grundkarte gleichzeitig aktiv. Allerdings hat die Reihenfolge z.B. Einfluss auf die Darstellung im Basemap-Toggler.

…​ Duplikaten

Bereits geladene Grundkarten werden nicht überschrieben. Dabei gilt: App-Konfiguration geht vor Domain-Bundle-Konfiguration.

Die zu ladende Grundkarte wird nicht übernommen, wenn bereits eine in der App konfigurierte oder eine zuvor über ein anderes Domain-Bundle geladene Grundkarte über dieselbe ID verfügt.

Themenkarten

Die Konfiguration von Themenkarten mit dem "map-layers" Schlüsselwort in Domain-Bundles entspricht der Konfiguration der map.layers Eigenschaft in der map-init Bundle-Konfiguration.

{
    "map-layers": [
        {
            "id": "koeln3",
            "title": "Koeln",
            "url": "https://services.conterra.de/arcgis/rest/services/common/koeln/MapServer",
            "coverImage": "resource('images/coverImage.png')",
            "type": "AGS_DYNAMIC",
            "visible": true
        }
    ]
}

Themenkarten aus Domain-Bundles werden auf ähnliche Weise in die Karte übernommen, als wären sie direkt in der App konfiguriert. Die folgende Tabelle stellt situationsbezogene Besonderheiten dar:

Verhalten bei …​ Beschreibung Beispiele

…​ Anwendung der Konfiguration

Themenkarten, Sublayer, popupTemplates und andere Konfigurationen werden in die Karte übernommen, sobald das Domain-Bundle geladen wird.

…​ festgelegter Reihenfolge

Themenkarten werden in festgelegter Reihenfolge der Karte hinzugefügt. Die Layer von zuerst geladenen Domain-Bundles werden der Karte in gleicher Reihenfolge von unten nach oben zugefügt.

Die Reihenfolge beeinflusst nicht nur die Anordnung der Themen-Kacheln im TOC sondern auch die Darstellungsreihenfolge - und Überlagerung - von Layern in der Karte.

…​ Duplikaten

Themenkarten aus einem Domain-Bundle mit IDs, die bereits der Karte hinzugefügt wurden, werden nicht übernommen.

Es werden keine Konfigurationsoptionen eines Layers übernommen, dessen ID bereits in der Karte vorhanden ist - dementsprechend werden Einstellungen auch nicht zusammengeführt.

Quellen für Suche und räumliche Auswahl

Quellen für Suche und räumliche Auswahl werden unterhalb des Schlüsselworts "ags-stores" konfigureiert - analog zur Konfiguration von AGSStore für das agssearch Bundle in der app.json.

Um diese Funktion zu nutzen, muss das Domain-Bundle eine Abhängigkeit auf das Bundle agssearch haben. Alternativ kann das Bundle über die App geladen werden.

{
    "ags-stores": [
        {
            "id": "store01",
            "title": "Adressen",
            "url": "https://services.conterra.de/arcgis/rest/services/common/koeln_adressen/MapServer/0",
            "omniSearchSearchAttr": "ADRESSE",
            "omniSearchDefaultLabel": "Adressen"
        }
    ]
}
Verhalten bei …​ Beschreibung Beispiele

…​ Anwendung der Konfiguration

Quellen aus Domain-Bundles werden im System registriert und stehen wie gewohnt ihrer Konfiguration der "useIn" Eigenschaft für verschiedene Funktionen zur Verfügung.

So kann über ein Domain-Bundle die Räumliche Auswahl und die Suche um Quellen erweitert werden.

…​ festgelegter Reihenfolge

Auf die Funktionalität hat die Reihenfolge keine Auswirkung.

Allerdings hat die Lade-Reihenfolge Auswirkungen auf die in der Quellen-Liste der räumlichen Auswahl.

…​ Duplikaten

Es gibt keine Prüfung auf Duplikate bzw. bereits vorhandene StoreQuellen.

Quellen aus einem Domain-Bundle mit ID oder URL, die bereits bei registrierten Quellen vorkommen, werden der App hinzugefügt.

Report Mappings

Report Mapping werden unterhalb des Schlüsselworts "report-mappings" konfiguriert - analog zur Konfiguration der Mappings des ReportTask für das Bundle reporttool in der app.json.

Um diese Funktion zu nutzen, muss das Domain-Bundle eine Abhängigkeit auf das Bundle reporttool haben. Alternativ kann das Bundle über die App geladen werden.

{
    "report-mappings": [
        {
            "storeId": "store01",
            "reportId": "report01",
            "fileName": "Report.pdf"
        }
    ]
}
Verhalten bei …​ Beschreibung Beispiele

…​ Anwendung der Konfiguration

Mappings aus Domain-Bundles ergänzen die bereits bestehenden Mappings.

Ein Domain-Bundle kann hierüber eigene Report Mappings definieren.

…​ festgelegter Reihenfolge

Auf die Funktionalität hat die Reihenfolge keine Auswirkung.

Bei Duplikaten wird das zuerst registrierte Mapping verwendet.

…​ Duplikaten

Die Prüfung auf Duplikate erfolgt über die "storeId" innerhalb des Mappings. Ist bereits ein Mapping für den definierten Store hinterlegt, wird das zuletzt hinzugefügte ignoriert.

Ein Mapping aus einem Domain-Bundle mit einer StoreId, die bereits in registrierten Mappings vorkommt, wird der App nicht hinzugefügt.

Reihenfolge der Auswertung

Wie den voran gegangenen Beschreibungen der Auswirkungen von Domain-Bundles auf das App-Verhalten entnommen werden kann, ist die Reihenfolge, in der Domain-Bundles geladen werden, in vielen Fällen ausschlaggebend. Daher besteht die Möglichkeit, diese Reihenfolge anzupassen. Auf diese Weise kann z.B. die Darstellungsreihenfolge von Themenkarten beeinflusst werden. Außerdem lässt sich so sicherstellen, dass im Falle von uneindeutigen IDs die wichtigeren Domain-Bundles zuerst geladen werden.

Der folgende Auszug aus einer app.json Konfiguration zeigt, wie die Reihenfolge, in der Domain-Bundles geladen und angewandt werden, beeinflusst werden kann. Die Bundlenamen werden in der gewünschten Reihenfolge angegeben. Es reicht aus, nur diejenigen Bundlenamen anzugeben, für die eine Reihenfolge wichtig ist. Nicht aufgeführte Bundles werden nach den aufgeführten in zufälliger Reihenfolge geladen und angewandt.

Fragment aus 'bundles' Sektion der app.json
"domains-system": {
    "Config": {
        "domainBundleOrder": ["domain-domainBundleForBasmaps", "domain-domainBundleForMapLayers"]
    }
}
Die Reihenfolge, in der Domain-Bundles geladen werden, wird nur beim Starten der App ausgewertet. Beim dynamischen Starten oder Stoppen eines Domain-Bundles wird die Reihenfolge nicht berücksichtigt.