Dodawanie konfigurowalnych parametrów do szablonów

Po utworzeniu szablonu aplikacji internetowej można ustawić go jako konfigurowalny. 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, aby zdefiniować właściwości konfiguracyjne.
3. Skonfiguruj szablon w taki sposób, aby odczytywał właściwości konfiguracyjne i stosował je w aplikacji.
4. Powiąż plik konfiguracyjny z wybranym elementem dla szablonu aplikacji.

Tworzenie pliku konfiguracyjnego

Plik konfiguracyjny jest plikiem JSON, który definiuje opcje konfiguracji szablonu aplikacji. Zapoznaj się z pełnym przykładem pliku konfiguracyjnego.

Notatka:

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.

Plik konfiguracyjny zawiera co najmniej jedną sekcję, która określa kategorie opcji.

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. Podczas tworzenia pliku konfiguracyjnego i upewnij się, że właściwość fieldName jest unikatowa w obrębie ustawienia konfiguracji.

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" } Przykładowe dane wynikowe description:"Bike Accidents"
Wartość logiczna	Tworzy pole wyboru pozwalające wybrać wartość true lub false. condition umożliwia sprawdzenie, czy mapa zawiera określoną funkcjonalność. Jeśli mapa nie spełnia warunku, pole wyboru i etykieta nie są wyświetlane w panelu konfiguracji. { "type": "boolean", "fieldName": "tool_bookmarks", "condition": "bookmark", "label": "Bookmarks", "tooltip": "" } Przykładowe dane wynikowe tool_bookmarks:false
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} } Przykładowe dane wynikowe range:0.5
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" }] } Przykładowe dane wynikowe theme:"blue"
Okno wyboru kolorów	Otwiera okno wyboru kolorów umożliwiające wybranie danej barwy z palety kolorów albo określenie wartości szesnastkowych, RGB lub HSV. { "type": "color", "label": "Choose a selection color", "fieldName": "selectionColor" } Przykładowe dane wynikowe selectionColor:"#829254"
Okno dialogowe Mapa internetowa	Wyświetla okno dialogowe służące do przeglądania lub wyszukiwania nowych map w celu wyświetlenia w aplikacji. Opcjonalnie podaj warunek na potrzeby przetestowania mapy. Jeśli podany warunek nie będzie spełniony, w panelu konfiguracji zostanie wyświetlony komunikat weryfikacji potwierdzający, że mapa nie spełnia wymagań. Prawidłowe ciągi znakowe warunków są następujące: time — mapa zawiera dane czasowe edit — aplikacja ma co najmniej jedną edytowalną warstwę featurelayer — mapa ma co najmniej jedną warstwę obiektową filter — mapa ma zdefiniowany filtr interaktywny 4x — mapa zawiera zasoby, które nie są jeszcze obsługiwane w wersji 4x oprogramowania ArcGIS API for JavaScript { “type”: “webmap”, “conditions”: [“time”, “edit”, “featurelayer”, “filter”, “4x”] } Przykładowe dane wynikowe webmap:"739ef0cf75de432995c77dd44ec8f652"
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" } Przykładowe dane wynikowe group:"449d00a4478d4849bbb65612355d6cd1"
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" ] } } Przykładowe dane wynikowe searchLayers: [{ "id":"Whittier_Hazards_821", "fields":[], "type":"FeatureLayer" }]
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" ] } } Przykładowe dane wynikowe tableLayer: { id: "2014CyclingAccidents_All_874", fields: [{ id: "urlField", fields: ["Casualty_Severity"] }] }
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 }] } Przykładowe dane wynikowe customLayout:"fullmap"
Mapy bazowe	Wyświetla listę rozwijaną wszystkich nazwanych map bazowych Esri. { “type”: “basemaps”, “fieldname” :”my_basemap”, “label”: “Alternate Basemap” } Przykładowe dane wynikowe my_basemap:"satellite"
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" } ] } }
Wyszukaj	Konfiguruje panel wyszukiwania służący do znajdowania obiektów w obrębie pola warstwy obiektów albo adresów przy użyciu lokalizatora. Jeśli zostanie skonfigurowane wyszukiwanie obiektów, użytkownicy będą mogli wybierać warstwę obiektów i pola wyszukiwania. { “type”: “Search”, “fieldName”: “searchConfig”, “label”: “Configure Search Options” } Przykładowe dane wynikowe searchConfig: { sources: [{ locator: { url: "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer", _url: { path: "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer", query: null }, normalization: true }, url: "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer", name: "ArcGIS World Geocoding Service", enableSuggestions: true, singleLineFieldName: "SingleLine", enable: true, id: "dojoUnique3" }], activeSourceIndex: 0, enableSearchingAll: false }
Lista skal	Wyświetla listę wstępnie zdefiniowanych poziomów skal, spośród których użytkownik może dokonywać wyboru. Przykłady: Kraje, Województwa/Stany, Województwo/Stan, Powiaty, Powiat, Okręg administracyjny, Miasto, Miejscowość, Dzielnica. { “type”: “scaleList”, “fieldName”: “customUrlLayerZoomScale”, “label”: “Choose zoom level” } Przykładowe dane wynikowe “customUrlLayerZoomScale”: 12000

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

Aby ustawić szablon jako konfigurowalny, aplikacja musi akceptować 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.

1. O ile nie zostało to jeszcze zrobione, dodaj ten szablon aplikacji jako nowy element aplikacji.
2. Na stronie elementu szablonu aplikacji kliknij kartę Ustawienia i znajdź sekcję Aplikacja map internetowych.
3. Z menu rozwijanego Cel wybierz opcję Konfigurowalne.
4. W polu Parametry konfiguracji wklej kod JSON z pliku konfiguracyjnego.

   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.

5. Kliknij przycisk Zapisz, aby zapisać ustawienia.

Jeśli chcesz używać konfigurowalnego szablonu w galerii aplikacji przeglądarki Map Viewer swojej instytucji lub galerii aplikacji grupowych, udostępnij ten element grupie zastosowanej do tej galerii aplikacji. Wówczas administrator instytucji może skonfigurować mapę lub skonfigurować grupy, aby użyć danej grupy zawierającej Twój szablon.