Hinzufügen konfigurierbarer Parameter zu Vorlagen

Mittels konfigurierbarer Web-Apps können Benutzer das Aussehen und Verhalten einer Anwendung anpassen. Apps werden in vier Schritten konfigurierbar gemacht:

1. Erstellen Sie eine Webanwendungsvorlage, falls dies nicht bereits erfolgt ist.
2. Erstellen Sie eine Konfigurationsdatei.
3. Richten Sie die Vorlage zum Lesen der Konfigurationseigenschaften ein, und wenden Sie sie auf die Anwendung an.
4. Verknüpfen Sie die Konfigurationsdatei mit dem Element für die App-Vorlage.

Die ersten Schritte sind in den folgenden Abschnitten beschrieben.

Erstellen einer Konfigurationsdatei

Die Konfigurationsdatei ist eine JSON-Datei, mit der die Konfigurationsoptionen für die App-Vorlage definiert werden. Diese Datei enthält einen oder mehrere Abschnitte, die die Optionen kategorisieren.

Die Eigenschaft fieldName muss innerhalb der Konfigurationseinstellung eindeutig sein.

Erstellen Sie die einzelnen Abschnitte, indem Sie eine Kategorie und eine Reihe von Feldern festlegen.

{
    "configurationSettings": [
        {
            "category": "",
            "fields": []
        }
    ]
}

Legen Sie die Konfigurationsoptionen anhand der in der folgenden Tabelle aufgelisteten Feldtypen fest.

Feldtyp	Beschreibung
Absatz	Zeigt einen erläuternden Text im Dialogfeld "Konfiguration" an. { "type": "paragraph", "value": "* These menu items will appear in the application when the web map has layers that require them." }
Zeichenfolge	Akzeptiert Texteingabe. Beinhaltet die Eigenschaft stringFieldOption, die den Typ des auf dem Bildschirm angezeigten Textfeldes festlegt. Die Werte lauten textbox, textarea und richtext. Die Option textbox ist der Standardwert und ein einzeiliges Textfeld. Die Option textarea zeigt ein größeres Textfeld für die Eingabe von Daten an. Die Option richtext zeigt einen Richtext-Editor an, der Benutzern die Anwendung einiger Formatierungsoptionen ermöglicht, z. B. Fett- oder Kursivformatierung des Textes. { "type": "string", "fieldName": "description", "label": "Description", "tooltip": "", "stringFieldOption": richtext || textarea || textbox, "placeHolder": "Text that appears in the text box to provide a hint to users on text to enter" }
Boolescher Wert	Erstellt ein Kontrollkästchen zum Festlegen von true- oder false-Werten. { "type": "boolean", "fieldName": "displaytitle", "label": "Show Title", "tooltip": "" }
Zahl	Erstellt ein Feld, das numerische Werte akzeptiert. Wenn das Feld nur einen bestimmten Wertebereich akzeptiert, können Sie mithilfe der Einstellung constraints die Eingabe auf einen bestimmten Wertebereich beschränken oder die Eingabewerte formatieren. { "type": "number", "fieldName": "range", "label": "Range:", "tooltip": "", "constraints" :{min:0,max:10,places:0} }
Optionen	Erstellt eine Dropdown-Liste mit einer Reihe von Optionen. { "type": "options", "fieldName": "theme", "tooltip": "Color theme to use", "label": "Color Scheme:", "options": [{ "label": "Blue", "value": "blue" }, { "label": "Green", "value": "green" }, { "label": "Orange", "value": "orange" }] }
Farbauswahl	Zeigt eine Farbauswahl an, über die Benutzer eine Farbe aus einer Palette auswählen oder HEX-, RGB- oder HSV-Werte angeben können. { "type": "color", "label": "Choose a selection color", "fieldName": "selectionColor" }
Das Dialogfeld "Webkarte"	Zeigt ein Dialogfeld an, um nach einer neuen Karte zu suchen, die in der App angezeigt werden soll. { "type": "webmap" }
Das Dialogfeld "Gruppe"	Zeigt ein Dialogfeld an, um nach einer neuen Gruppe zu suchen, die in der App angezeigt werden soll. { "type": "group" }
Auswahl mehrerer Layer und Felder	Stellt eine Strukturansicht der Layer und Felder in der Karte dar, die mit den unterstützten Typen und Geometrietypen übereinstimmen. Ermöglicht Endbenutzern von Apps die Auswahl mehrerer Layer und mehrerer Felder für jeden Layer. { "label":"Select search layers and fields", "fieldName":"searchLayers", "type":"multilayerandfieldselector", "tooltip":"Select layer and fields to search", "layerOptions":{ "supportedTypes":[ "FeatureLayer" ], "geometryTypes":[ "esriGeometryPoint", "esriGeometryLine", "esriGeometryPolyline", "esriGeometryPolygon" ] }, "fieldOptions":{ "supportedTypes":[ "esriFieldTypeString" ] } }
Layer- und Feldauswahl	Zeigt eine Dropdown-Liste mit Layern in der Karte an, die nach den aufgelisteten Typen und Geometrien gefiltert ist. Geben Sie optional mindestens eine Feldauswahl an, um Benutzern die Auswahl eines Layers und von Feldern zu ermöglichen. { "type":"layerAndFieldSelector", "fieldName":"tableLayer", "label":"Layer to display in table", "tooltip":"Layer to display in table", "fields":[ { "multipleSelection":true, "fieldName":"hiddenFields", "label":"Hide the selected fields", "tooltip":"Fields to hide in table", "supportedTypes":[ "esriFieldTypeSmallInteger", "esriFieldTypeInteger", "esriFieldTypeSingle", "esriFieldTypeDouble", "esriFieldTypeString" ] } ], "layerOptions":{ "supportedTypes":[ "FeatureLayer" ], "geometryTypes":[ "esriGeometryPoint", "esriGeometryLine", "esriGeometryPolygon" ] } }
Optionsfeld	Erstellt eine Optionsschaltfläche, mit der immer nur eine Option ausgewählt werden kann. Die ausgewählte Option wird auf "True" gesetzt. { "type": "radio", "fieldName": "layout", "tooltip": "Custom Layout", "label": "Custom Layout:", "items": [{ "label": "Sidebar", "value": "sidebarmenu" }, { "label": "FullWidth", "value": "fullwidth" }, { "label": "default", "value": "Default", "checked": true }] }
Grundkarten	Zeigt eine Dropdown-Liste aller benannten Esri Grundkarten an. { “type”: “basemaps”, “fieldname” :”my_basemap”, “label”: “Alternate Basemap” }
Bedingungsfunktionen	Zeigt Inhalte basierend auf einer TRUE- oder FALSE-Bedingung an bzw. blendet sie aus. Wenn das Kontrollkästchen Layer-Liste anzeigen beispielsweise deaktiviert ist, werden die Layer-Liste und alle zugehörigen Optionen (z. B. Sublayer in Layer-Liste einbeziehen) ausgeblendet. { "type":"conditional", "condition": false, "fieldName":"showtitle", "label":"Display Map Title", "items":[ { "placeHolder":"Defaults to web map title", "label":"Title:", "fieldName":"title", "type":"string", "tooltip":"Defaults to web map title" },{ "type":"paragraph", "value":"Enter a value to override the default title font size " }, { "type":"string", "label":"Title font size", "tooltip":"Specify title font size", "fieldName":"titlefontsize", "placeHolder":"20px" } ] } }

Beispiel für eine Konfigurationsdatei

Nachstehend ist ein Beispiel für eine vollständige Konfigurationsdatei aufgeführt.

{
    "configurationSettings": [        {
            "category": "General Settings",            "fields": [                {
                    "type": "options",                    "fieldName": "theme",                    "tooltip": "Color theme to use",                    "label": "Color Scheme:",                    "options": [                        {
                            "label": "Blue",                            "value": "blue"
                        },                        {
                            "label": "Green",                            "value": "green"
                        },                        {
                            "label": "Orange",                            "value": "orange"
                        }
                    ]                },                {
                    "type": "string",                    "fieldName": "layer",                    "label": "Analysis Layer",                    "tooltip": "Feature Layer with Facilities to search"
                },                {
                    "type": "string",                    "fieldName": "orgname",                    "label": "Organization Name:",                    "tooltip": "",                    "stringFieldOption": "richtext",                    "placeHolder": "Organization Name"
                },                {
                    "type": "number",                    "fieldName": "bufferdistance",                    "label": "Search Distance (miles)",                    "value": "1"
                }
            ]        }
    ],    "values": {
        "theme": "orange",        "bufferdistance": 1    }
}

Einrichten der Vorlage zum Lesen der Informationen der Konfigurationsdatei

Wenn die Vorlage konfigurierbar ist, muss die Anwendung die Element-ID für eine Web Mapping-Anwendung als Wert für den URL-Parameter appid akzeptieren. Diese ID wird verwendet, um eine asynchrone Anforderung zum Abrufen der Konfigurationseigenschaften für die Anwendung auszuführen. In ArcGIS API for JavaScript können Sie mit esri.request die Konfigurationsdetails der App abrufen.

In diesem Beispiel löst sich esri.arcgis.utils.arcgisUrl in www.arcgis.com/sharing/content/items auf.

var requestHandle = esri.request({
    url: esri.arcgis.utils.arcgisUrl + "/" + appid + "/data",
    content: {
        f: "json"
     },
    callbackParamName: "callback",
    load: function (response) {
     for (var key in response.values){
      if(response.values[key]!==undefined)configOptions[key]=response.values[key];
      }
    }, 
});

Die Antwort enthält die Änderungen, die der Benutzer über das Konfigurationsfenster an der Anwendung vorgenommen hat. Sie können die Änderungen abrufen und sie auf die Anwendung anwenden. Die Anwendung sollte Standardwerte für die Konfigurationsoptionen definieren, um Situationen zu handhaben, in denen die Vorlage nicht konfiguriert ist.

{
    "source": "15a34e2c161b4364860854fbc84262c5",    "folderId": "5705faa4594a4fd09edf01742c16e523",    "values": {
        "webmap": "32f1438789d34b5e8125f0f7c64b8d63",        "layer":"https://sampleserver6.arcgisonline.com/arcgis/rest/services/Water_Network/MapServer/2",        "theme": "green",        "orgname": "Water Points",        "bufferdistance": 3       }
 }

Verknüpfen der Informationen der Konfigurationsdatei mit dem Element für die App-Vorlage

Nachdem Sie die Konfigurationsdatei erstellt haben, können Sie sie mit Ihrer benutzerdefinierten App-Vorlage verknüpfen und die Anwendung konfigurierbar machen. Zunächst fügen Sie die Vorlage als neues Anwendungselement hinzu, sofern dies nicht bereits erfolgt ist, und legen als Zweck Konfigurierbar fest. Dann öffnen Sie die Elementseite Ihrer Anwendung, klicken Sie auf die Schaltfläche Einstellungen, kopieren Sie den JSON-Code aus Ihrer Konfigurationsdatei, und fügen Sie ihn in das Feld Konfigurationsparameter ein.

Hinweis:

Für das Feld Konfigurationsparameter ist ein gültiges JSON erforderlich. Sie sollten Ihr JSON mithilfe eines Validators wie JSONLint prüfen, um sicherzustellen, dass Sie über ein wohlgeformtes, fehlerfreies JSON verfügen.

Wenn Sie die konfigurierbare Vorlage in der Map Viewer- oder Gruppen-App-Galerie der Organisation verwenden möchten, geben Sie das Element für die Gruppe frei, die für diese App-Galerie verwendet wird. Anschließend kann der Administrator Ihrer Organisation den Map Viewer konfigurieren oder Gruppen konfigurieren, um die Gruppe zu verwenden, die Ihre Vorlage enthält.