Dodawanie konfigurowalnych parametrów do szablonów

Konfigurowalne aplikacje internetowe pozwalają użytkownikom personalizować wygląd i działanie aplikacji. Tworzenie konfigurowalnego szablonu aplikacji przebiega w czterech etapach:

1. Utwórz szablon aplikacji internetowej, jeśli wcześniej nie zostało to zrobione.
2. Utwórz plik konfiguracyjny.
3. Skonfiguruj szablon, aby wczytać właściwości konfiguracji i zastosować je w aplikacji.
4. Powiąż plik konfiguracyjny z wybranym elementem dla szablonu aplikacji.

Aby rozpocząć pracę, zapoznaj się z poniższymi sekcjami.

Tworzenie pliku konfiguracyjnego

Plik konfiguracyjny jest plikiem JSON, który definiuje opcje konfiguracji szablonu aplikacji. Plik ten zawiera co najmniej jedną sekcję, która określa kategorie opcji.

Właściwość fieldName musi być unikalna w ramach ustawień konfiguracji.

Utwórz kolejne sekcje, określając kategorię i zestaw pól.

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

Określ opcje konfiguracji za pomocą typów pola wyszczególnionych w tabeli poniżej.

Typ pola	Opis
Akapit	Pozwala wyświetlić objaśnienie w oknie dialogowym konfiguracji. { "type": "paragraph", "value": "* These menu items will appear in the application when the web map has layers that require them." }
Ciąg znakowy	Obsługuje dane w postaci tekstu. Zawiera właściwość stringFieldOption, która określa typ pola tekstowego wyświetlanego na ekranie. Wartości to textbox, textarea i richtext. Opcja textbox jest wybrana domyślnie i oznacza pole tekstowe z pojedynczym wierszem. Opcja textarea reprezentuje większe pole tekstowe do wprowadzania danych. Opcja richtext reprezentuje edytor tekstu formatowanego, który pozwala użytkownikom stosować formatowanie, takie jak ustawienia czcionki (pogrubiona, kursywa itp.). { "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" }
Wartość logiczna	Tworzy pole wyboru pozwalające wybrać wartość true lub false. { "type": "boolean", "fieldName": "displaytitle", "label": "Show Title", "tooltip": "" }
Liczba	Tworzy pole, które przyjmuje wartości liczbowe. Jeśli pole ma przyjmować wartości tylko z określonego zakresu, można użyć ustawienia constraints, aby ograniczyć dane wejściowe do przedziału wartości lub sformatować wprowadzane wartości. { "type": "number", "fieldName": "range", "label": "Range:", "tooltip": "", "constraints" :{min:0,max:10,places:0} }
Opcje	Tworzy rozwijaną listę z szeregiem opcji wyboru. { "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" }] }
Okno wyboru kolorów	Otwiera okno wyboru kolorów umożliwiające użytkownikom dokonanie wyboru danej barwy z palety kolorów albo określenie wartości szesnastkowych, RGB lub HSV. { "type": "color", "label": "Choose a selection color", "fieldName": "selectionColor" }
Okno dialogowe Mapa internetowa	Wyświetla okno dialogowe służące do przeglądania lub wyszukiwania nowych map w celu wyświetlenia w aplikacji. { "type": "webmap" }
Okno dialogowe Grupa	Wyświetla okno dialogowe służące do przeglądania lub wyszukiwania nowych grup w celu wyświetlenia w aplikacji. { "type": "group" }
Selektor wielu warstw i pól	Przedstawia widok drzewa warstw i pól w mapie, które są zgodne z obsługiwanymi typami i typami geometrii. Pozwala użytkownikom końcowym aplikacji na wybieranie wielu warstw i wielu pól dla każdej warstwy. { "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" ] } }
Selektor warstw i pól	Wyświetla listę rozwijaną warstw na mapie z filtrem według wymienionych typów i geometrii. Opcjonalnie podaj co najmniej jeden selektor pól, aby umożliwić użytkownikom wybór warstwy i pól. { "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" ] } }
Opcja jednokrotnego wyboru	Tworzy przycisk radiowy umożliwiający jednoczesny wybór tylko jednej opcji. Wybrana opcja zostanie ustawiona na wartość prawda (true). { "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 }] }
Mapy bazowe	Wyświetla listę rozwijaną wszystkich nazwanych map bazowych Esri. { “type”: “basemaps”, “fieldname” :”my_basemap”, “label”: “Alternate Basemap” }
Warunkowe	Wyświetla lub ukrywa zasoby w zależności od tego, czy warunek jest prawdziwy, czy też fałszywy. Jeśli na przykład pole wyboru Wyświetl listę warstw nie jest zaznaczone, lista warstw i wszystkie powiązane opcje (na przykład Uwzględnij warstwy podrzędne na liście warstw) są ukryte. { "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" } ] } }

Przykładowy plik konfiguracyjny

Poniżej znajduje się przykład kompletnego pliku konfiguracyjnego.

{
    "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    }
}

Konfiguracja szablonu w celu wczytania informacji z pliku konfiguracyjnego

Jeśli szablon ma być konfigurowalny, aplikacja musi przyjmować identyfikator elementu dla aplikacji do tworzenia map internetowych jako wartość parametru URL appid. Ten identyfikator jest używany do przesłania asynchronicznego żądania w celu pobrania właściwości konfiguracji aplikacji. W interfejsie ArcGIS API for JavaScript można użyć elementu esri.request, aby pobrać szczegółowe informacje o konfiguracji aplikacji.

W tym przykładzie element esri.arcgis.utils.arcgisUrl jest rozwiązywany na www.arcgis.com/sharing/content/items.

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];
      }
    }, 
});

W odpowiedzi uwzględnione będą zmiany wprowadzone przez użytkownika do aplikacji za pomocą panelu konfiguracyjnego. Można przywrócić zmiany i zastosować je w aplikacji. Aplikacja powinna definiować wartości domyślne opcji konfiguracji, które są używane, gdy szablony nie są skonfigurowane.

{
    "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       }
 }

Tworzenie powiązania pliku konfiguracyjnego z elementem dla własnego szablonu aplikacji

Po utworzeniu pliku konfiguracyjnego można powiązać go z własnym, spersonalizowanym szablonem aplikacji, dzięki czemu aplikacja staje się konfigurowalna. O ile nie zostało to jeszcze zrobione, najpierw dodaj ten szablon jako nowy element aplikacji do sekcji Konfigurowalne. Następnie otwórz stronę elementu swojej aplikacji, kliknij kartę Ustawienia, skopiuj kod JSON z pliku konfiguracyjnego i wklej go w polu Parametry konfiguracji.

Notatka:

Pole Parametry konfiguracji wymaga prawidłowego kodu JSON. Dobrą praktyką jest uruchamianie kodu JSON za pośrednictwem modułu sprawdzania poprawności, jakim jest np. JSONLint, aby upewnić się, że kod JSON został prawidłowo napisany i nie zawiera błędów.

Jeśli chcesz używać konfigurowalnego szablonu w galerii aplikacji przeglądarki map swojej instytucji lub galerii aplikacji grupowych, udostępnij ten element grupie zastosowanej do tej galerii aplikacji. Then the administrator of your organization can configure the map viewer or configure groups to use the group that includes your template.