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 denselben 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.

Mithilfe 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 Konfiguration in einer app.json Datei aufgebaut.

Aufbau und Möglichkeiten

Im einfachsten Fall besteht ein Domain-Bundle lediglich aus einer 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 Datei

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",
                "searchAttribute": "ADRESSE",
                "searchLabel": "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 Konfiguration in einer app.json Datei konfiguriert. Um die aktive Grundkarte zu definieren, verwenden Sie die Eigenschaft "selected":true. 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 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. Alle Themenkarten aus Domain-Bundles, die zum App-Start verfügbar sind, werden als Block zur Karte hinzugefügt. Dabei liegen die Themenkarten aus zuerst geladenen Domain-Bundles oben, zuletzt geladene am unteren Ende des Blocks. Themenkarten aus später geladenen Domain-Bundles werden separat oberhalb bzw. unterhalb vorhandener Themenkarten eingefügt. Ob die Themenkarten vor oder nach den bereits in der App vorhandenen Themenkarten eingefügt werden, kann per Konfiguration festgelegt werden.

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 nicht zusammengeführt.
Themenkartenkonfiguration in Apps überschreiben

Innerhalb einer App ist es möglich, die Konfiguration von Themenkarten, die in einem Domain-Bundle definiert sind, für die jeweilige App zu überschreiben. Die Eigenschaften, die überschrieben werden sollen, werden dabei im Parameter map-layers-override je Layer festgelegt. Beispielsweise kann auf diese Art und Weise die initiale Sichtbarkeit von Themenkarten aus einem Domain-Bundle in der jeweiligen App gesteuert werden:

Beispiel - Überschreiben von Eigenschaften von Themenkarten
"domains-system": {
    "Config": {
        "map-layers-override": {
            "trees": {
                "visible": false
            }
        }
    }
}

Die Id`s der Layer, die angepasst werden sollen, werden als Schlüssel innerhalb von map-layers-override verwendet. Im obigen Beispiel wird die initiale Sichtbarkeit des Layers trees auf false gesetzt.

Ebenso ist es möglich, Eigenschaften von Sublayern der Themenkarten zu überschreiben. Die Eigenschaften von Sublayern werden innerhalb des Elements sublayers-override wie folgt festgelegt:

Beispiel - Überschreiben von Eigenschaften von Sublayern
"domains-system": {
    "Config": {
        "map-layers-override": {
            "trees": {
                "sublayers-override": {
                    "1": {
                        "visible": false
                    }
                }
            }
        }
    }
}

Auch innerhalb von sublayers-override werden die Id`s der zu ändernden Sublayer als Schlüssel verwendet.

Themenkarten unterhalb oder oberhalb bereits vorhandener Themenkarten einfügen

Standardmäßig werden Themenkarten, die in Domain-Bundles konfiguriert sind, oberhalb der in der app.json Datei konfigurierten Themenkarten eingefügt. Um die Themenkarten aus den Domain-Bundles unterhalb derer aus der App-Konfiguration einzufügen, setzen Sie folgende Konfiguration:

Fragment aus der bundles-Sektion der app.json Datei
"domains-system": {
    "Config": {
        "domainLayersOnTop": false
    }
}

Quellen für Suche und räumliche Auswahl

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

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",
            "searchAttribute": "ADRESSE",
            "searchLabel": "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 Datei.

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 der Konfiguration einer app.json Datei zeigt, wie die Reihenfolge, in der Domain-Bundles geladen und angewandt werden, beeinflusst werden kann. Geben Sie die Bundlenamen in der Reihenfolge an, in der Sie geladen werden sollen. Es reicht aus, 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 der bundles-Sektion der app.json Datei
"domains-system": {
    "Config": {
        "domainBundleOrder": ["domain-domainBundleForBasmaps", "domain-domainBundleForMapLayers"]
    }
}
Die Reihenfolge, in der Domain-Bundles geladen werden, wird beim Starten der App ausgewertet. Beim dynamischen Starten oder Stoppen eines Domain-Bundles wird die Reihenfolge nicht berücksichtigt.