@vertigis/viewer-spec 58.9.0 → 58.9.1

package/LICENSE

@@ -1,5 +1,5 @@
-VertiGIS North America Ltd. ("VERTIGIS NA") hereby grants You, free of charge, a personal, non-exclusive, nontransferable, license to access and use this software and associated documentation files (the "Software") for development purposes only. You shall not deploy the Software into production or use for revenue generating purposes. If You wish to deploy the Software into production, then the use of the Software shall be governed by VERTIGIS NA's Master License Agreement, which can be found at www.geocortex.com/legal and shall supersede all other terms of use.
-
-You shall include copyright and this permission notice in all copies or works involving the Software. 
-
+VertiGIS North America Ltd. ("VERTIGIS NA") hereby grants You, free of charge, a personal, non-exclusive, nontransferable, license to access and use this software and associated documentation files (the "Software") for development purposes only. You shall not deploy the Software into production or use for revenue generating purposes. If You wish to deploy the Software into production, then the use of the Software shall be governed by VERTIGIS NA's Master License Agreement, which can be found at www.geocortex.com/legal and shall supersede all other terms of use.
+
+You shall include copyright and this permission notice in all copies or works involving the Software. 
+
 You acknowledge and agree that Software is provided AS IS and that VERTIGIS NA makes no representations and expressly disclaims any and all warranties of any kind, express or implied, including, but not limited to, any warranties regarding merchantability, fitness for a particular purpose, and noninfringement of intellectual property. In no event shall VERTIGIS NA be liable for any claim, damages, or other liability, whether in contract, tort, or other causes of action, arising from, out of, or in connection with the Software or use or other dealings with the Software. You shall bear all risk and liability regarding Your use of the Software and expressly acknowledge and agree that Your use of the Software is at Your own risk. You shall comply with all applicable laws.

package/README.md

@@ -1,3 +1,3 @@
-# VertiGIS Viewer Specification
-
-This package contains specifications for app config JSON, layout XML, and a reference of all commands, operations, and events for VertiGIS Studio Web and Mobile. For more information on extending these products, visit our [Developer Center](https://developers.vertigisstudio.com).
+# VertiGIS Viewer Specification
+
+This package contains specifications for app config JSON, layout XML, and a reference of all commands, operations, and events for VertiGIS Studio Web and Mobile. For more information on extending these products, visit our [Developer Center](https://developers.vertigisstudio.com).

package/docs/Geocortex Apps.md

@@ -1,311 +1,311 @@
-# VertiGIS Studio Apps
-
-## Introduction
-
-A VertiGIS Studio App is a JSON document containing configuration for an application
-that is built on top of the ArcGIS Extensions API. Building on the Esri Web Map
-Specification, VertiGIS Studio Apps enable a declarative approach to working with the
-VertiGIS and Esri APIs. Rather than initializing the properties of API objects
-programmatically in code, you can define all of their settings externally in an
-App JSON document. Then, you can access the configured objects via the
-`AppContainer` class. Here is an example VertiGIS Studio App containing a map
-extension and a menu:
-
-```
-{
-    "schemaVersion": "1.0",
-    "items": [
-        {
-            "$type": "map-extension",
-            "id": "default",
-            "title": "LA County",
-            "webMap": "b6c7a4a9eb5a4954a0d284c6c53537d2"
-        },
-        {
-            "$type": "menu",
-            "id": "i-want-to",
-            "items": [
-                {
-                    "id": "zoom-in",
-                    "title": "Zoom In"
-                },
-                {
-                    "id": "zoom-out",
-                    "title": "Zoom Out"
-                }
-            ]
-        }
-    ]
-}
-```
-
-In code, you would then access the items defined in this App like so:
-
-```
-const appJson = ... // Load the JSON from somewhere.
-const container = new AppContainer(appJson);
-const mapX = await container.get("map-extension", "default");
-const iwtm = await container.get("menu", "i-want-to");
-```
-
-With the exception of a few special App properties like `$type`, the JSON for
-each item uses the same schema that is supported by the constructor for the
-corresponding API object. For example, this produces the same end result as the
-above code:
-
-```
-const mapX = new MapExtension({
-    "id": "default",
-    "title": "LA County",
-    "webMap": "b6c7a4a9eb5a4954a0d284c6c53537d2"
-});
-const iwtm = new Menu({
-    "id": "i-want-to",
-    "items": [
-        {
-            "id": "zoom-in",
-            "title": "Zoom In"
-        },
-        {
-            "id": "zoom-out",
-            "title": "Zoom Out"
-        }
-    ]
-});
-```
-
-## App Items
-
-The `items` property of an App contains the set of configured items for an
-application (order is irrelevant). At minimum, each item must have `id` and
-`$type` properties (see [ItemType](apidoc://ItemType/ItemType) for a list of
-default supported types). The combination of type and ID must be unique within
-an App. This means that you are permitted to have two items with an ID of
-`"default"`, but only if they are of different types. IDs must consist of only
-[unreserved URI characters](https://tools.ietf.org/html/rfc3986).
-
-Any remaining properties on an item that do not start with "\$" are its
-configured settings, and vary based on the type of item. For example, the map
-extension's `"title"` property in the previous example. These properties will
-get passed in to the appropriate [item factory](#Custom-Item-Types) for that
-item type.
-
-### Item URIs
-
-Items in an App can be uniquely identified via URIs that use a special `item://`
-scheme, like so:
-
-```
-item://<type>/<id>
-```
-
-The AppContainer class allows retrieving an item via its `item://` URI:
-
-```
-const mapX = await container.get("item://map-extension/default");
-```
-
-### Item References
-
-The property values for an item can reference other items, using `item://` URIs.
-For example:
-
-```
-items: [
-    {
-        "$type": "layer-extension",
-        "id": "incidents",
-        "layer": {
-            "layerType": "ArcGISFeatureLayer",
-            "url": "http://sampleserver6.arcgisonline.com/arcgis/rest/services/SF311/FeatureServer/0"
-        }
-    },
-    {
-        $type: "map-extension",
-        id: "default",
-        layerExtensions: [
-            "item://layer-extension/incidents"
-        ]
-    }
-]
-```
-
-When the `item://map-extension/default` item is requested from the AppContainer,
-it will first create the `item://layer-extension/incidents` object that it
-references, and then substitute it in place of the reference prior to creating
-the map extension.
-
-**NOTE**: Regardless of how many times an item is requested or referenced by
-other items, only a single object instance is ever created per unique item.
-
-### Custom Item Types
-
-By default, AppContainer is pre-configured to understand the various items types
-that are built in the ArcGIS Extensions API, e.g. MapExtension and Menu. However, you
-can work with custom item types in an App by registering custom item factories
-with AppContainer. An item factory is just a method that takes item
-configuration and produces an actual object. For more information, see
-[AppContainer.registerType()](apidoc://AppContainer.registerType).
-
-You can also override the built-in factories for ArcGIS Extensions API items with your
-own factories to customize how these items are created.
-
-## Settings
-
-An App may contain a `settings` block at the top level, which is a place to
-define custom, application-wide settings as a set of key/value pairs. The key is
-a unique name for the setting, and the value is a simple scalar value (string,
-boolean, or number).
-
-```
-{
-    "schemaVersion": "1.0",
-    "settings": {
-        "baseServiceUrl": "http://sampleserver6.arcgisonline.com/arcgis/rest/",
-        "defaultMaxResults": 300
-    }
-}
-```
-
-Settings can be accessed programmatically via the
-[AppContainer.settings](apidoc://AppContainer.settings) property. Setting values
-can also be referenced within an App by using a special URI syntax:
-
-```
-setting://<setting-name>.
-```
-
-Whenever an item’s property has a value like this, the configuration loader will
-substitute it for the actual setting value. This is useful when a setting is
-used by more than one item in an App, as it gives you a single place to change
-it. You can also insert a setting’s value into a string property or other
-settings, by surrounding the `setting://` URI with `{}` characters within a
-string. For example:
-
-```
-{
-    "schemaVersion": "1.0",
-    "settings": {
-        "baseServiceUrl": "http://sampleserver6.arcgisonline.com/arcgis/rest"
-    },
-    items: [
-        {
-            "$type": "layer-extension",
-            "id": "hurricanes",
-            "layer": {
-                "layerType": "ArcGISMapServiceLayer",
-                "url": "{setting://baseServiceUrl}/services/Hurricanes/MapServer"
-            }
-        }
-    ]
-}
-```
-
-## Failure Modes
-
-By default, when one item references another and the referenced item cannot be
-created, then the original item cannot be created either. In this case an error
-will occur when you attempt to get the original item from the App container. You
-can adjust this behavior by defining a custom failure mode for an item in the
-top-level `failureModes` property. This property maps an `item://` URI to the
-failure mode value for that item. Possible values are `"error"`, `"warn"`, and
-`"ignore"`, with `"error"` being the default. For example:
-
-```
-{
-    "schemaVersion": "1.0",
-    items: [
-        {
-            "$type": "layer-extension",
-            "id": "broken",
-            "layer": {
-                "url": "invalid URL"
-            }
-        },
-        {
-            $type: "map-extension",
-            id: "default",
-            layerExtensions: [
-                "item://layer-extension/broken"
-            ]
-        }
-    ],
-    "failureModes": [
-        "item://layer-extension/broken": "warn"
-    ]
-}
-```
-
-In this example, the item `item://layer-extension/broken` contains an invalid
-URL, and so it cannot be created. Normally this would mean that
-`item://map-extension/default` couldn't be created either, but because of the
-configured failure mode of `"warn"` for the layer extension, the map extension
-can still be created. The AppContainer will remove the invalid URI prior to
-creating the map extension, and will raise a special `configWarning` event
-containing details about the item that could not be created. In this case, the
-host application should handle this event by warning the end user about the
-missing layer.
-
-Failure modes are also passed on to the item factories. This means that objects
-that are created by the AppContainer can also respond to failure modes. For
-example, MapExtension will honor a layer extension's failure mode if the layer
-fails to load successfully (e.g. the map service is currently unavailable). The
-exact behavior depends on the type of object.
-
-## App Imports
-
-An App can import one or more other Apps via the top-level `import` block. This
-is a list of one or more URLs pointing to other Apps to import, like so:
-
-```
-{
-    "schemaVersion": "1.0",
-    "import": [
-        "http://some.company.com/apps/default-basemaps.app.json",
-        "default-layers.app.json"
-    ]
-}
-```
-
-When an App imports another one, the items, settings, failure modes, etc.
-defined in the referenced app become part of the current App, as though they had
-been defined inline.
-
-If the current App contains one or more items that also appear in the imported
-App, then the items' properties are merged, with locally defined property values
-overriding imported ones. Similarly, locally defined settings and failure modes
-override ones that are imported. If multiple Apps are imported, then content
-from Apps that appear later in the list of imports will override the content of
-earlier ones.
-
-An imported App can itself contain App imports. In that case, those inner imports
-are resolved first, and the resulting App is then imported into the outer one.
-
-## Importing Apps from Portal
-
-It is possible to import Apps from a portal instance by using one of the
-following URI patterns:
-
--   portal://<portal-id>/<item-id>
--   portal://<item-id>
-
-The first version (with _portal-id_) can be used when you want to specify the
-portal instance where the item is located. In order for this portal:// URI to
-successfully be resolved, you must associate _portal-id_ with an instance of
-@arcgis/core/portal/Portal. This can be done using the _portals_ map in
-@vertigis/arcgis-extensions/config.
-
-You can import App configuration from a portal instance like this:
-
-```
-{
-    "schemaVersion": "1.0",
-    "import": [
-        "portal://test-portal/abcdef0123456789abcdef0123456789,
-    ]
-}
-```
-
-If the imported configuration has any further imports in form
-portal://<item-id>, these will be changed to use the _portal-id_ of the parent
-App.
+# VertiGIS Studio Apps
+
+## Introduction
+
+A VertiGIS Studio App is a JSON document containing configuration for an application
+that is built on top of the ArcGIS Extensions API. Building on the Esri Web Map
+Specification, VertiGIS Studio Apps enable a declarative approach to working with the
+VertiGIS and Esri APIs. Rather than initializing the properties of API objects
+programmatically in code, you can define all of their settings externally in an
+App JSON document. Then, you can access the configured objects via the
+`AppContainer` class. Here is an example VertiGIS Studio App containing a map
+extension and a menu:
+
+```
+{
+    "schemaVersion": "1.0",
+    "items": [
+        {
+            "$type": "map-extension",
+            "id": "default",
+            "title": "LA County",
+            "webMap": "b6c7a4a9eb5a4954a0d284c6c53537d2"
+        },
+        {
+            "$type": "menu",
+            "id": "i-want-to",
+            "items": [
+                {
+                    "id": "zoom-in",
+                    "title": "Zoom In"
+                },
+                {
+                    "id": "zoom-out",
+                    "title": "Zoom Out"
+                }
+            ]
+        }
+    ]
+}
+```
+
+In code, you would then access the items defined in this App like so:
+
+```
+const appJson = ... // Load the JSON from somewhere.
+const container = new AppContainer(appJson);
+const mapX = await container.get("map-extension", "default");
+const iwtm = await container.get("menu", "i-want-to");
+```
+
+With the exception of a few special App properties like `$type`, the JSON for
+each item uses the same schema that is supported by the constructor for the
+corresponding API object. For example, this produces the same end result as the
+above code:
+
+```
+const mapX = new MapExtension({
+    "id": "default",
+    "title": "LA County",
+    "webMap": "b6c7a4a9eb5a4954a0d284c6c53537d2"
+});
+const iwtm = new Menu({
+    "id": "i-want-to",
+    "items": [
+        {
+            "id": "zoom-in",
+            "title": "Zoom In"
+        },
+        {
+            "id": "zoom-out",
+            "title": "Zoom Out"
+        }
+    ]
+});
+```
+
+## App Items
+
+The `items` property of an App contains the set of configured items for an
+application (order is irrelevant). At minimum, each item must have `id` and
+`$type` properties (see [ItemType](apidoc://ItemType/ItemType) for a list of
+default supported types). The combination of type and ID must be unique within
+an App. This means that you are permitted to have two items with an ID of
+`"default"`, but only if they are of different types. IDs must consist of only
+[unreserved URI characters](https://tools.ietf.org/html/rfc3986).
+
+Any remaining properties on an item that do not start with "\$" are its
+configured settings, and vary based on the type of item. For example, the map
+extension's `"title"` property in the previous example. These properties will
+get passed in to the appropriate [item factory](#Custom-Item-Types) for that
+item type.
+
+### Item URIs
+
+Items in an App can be uniquely identified via URIs that use a special `item://`
+scheme, like so:
+
+```
+item://<type>/<id>
+```
+
+The AppContainer class allows retrieving an item via its `item://` URI:
+
+```
+const mapX = await container.get("item://map-extension/default");
+```
+
+### Item References
+
+The property values for an item can reference other items, using `item://` URIs.
+For example:
+
+```
+items: [
+    {
+        "$type": "layer-extension",
+        "id": "incidents",
+        "layer": {
+            "layerType": "ArcGISFeatureLayer",
+            "url": "http://sampleserver6.arcgisonline.com/arcgis/rest/services/SF311/FeatureServer/0"
+        }
+    },
+    {
+        $type: "map-extension",
+        id: "default",
+        layerExtensions: [
+            "item://layer-extension/incidents"
+        ]
+    }
+]
+```
+
+When the `item://map-extension/default` item is requested from the AppContainer,
+it will first create the `item://layer-extension/incidents` object that it
+references, and then substitute it in place of the reference prior to creating
+the map extension.
+
+**NOTE**: Regardless of how many times an item is requested or referenced by
+other items, only a single object instance is ever created per unique item.
+
+### Custom Item Types
+
+By default, AppContainer is pre-configured to understand the various items types
+that are built in the ArcGIS Extensions API, e.g. MapExtension and Menu. However, you
+can work with custom item types in an App by registering custom item factories
+with AppContainer. An item factory is just a method that takes item
+configuration and produces an actual object. For more information, see
+[AppContainer.registerType()](apidoc://AppContainer.registerType).
+
+You can also override the built-in factories for ArcGIS Extensions API items with your
+own factories to customize how these items are created.
+
+## Settings
+
+An App may contain a `settings` block at the top level, which is a place to
+define custom, application-wide settings as a set of key/value pairs. The key is
+a unique name for the setting, and the value is a simple scalar value (string,
+boolean, or number).
+
+```
+{
+    "schemaVersion": "1.0",
+    "settings": {
+        "baseServiceUrl": "http://sampleserver6.arcgisonline.com/arcgis/rest/",
+        "defaultMaxResults": 300
+    }
+}
+```
+
+Settings can be accessed programmatically via the
+[AppContainer.settings](apidoc://AppContainer.settings) property. Setting values
+can also be referenced within an App by using a special URI syntax:
+
+```
+setting://<setting-name>.
+```
+
+Whenever an item’s property has a value like this, the configuration loader will
+substitute it for the actual setting value. This is useful when a setting is
+used by more than one item in an App, as it gives you a single place to change
+it. You can also insert a setting’s value into a string property or other
+settings, by surrounding the `setting://` URI with `{}` characters within a
+string. For example:
+
+```
+{
+    "schemaVersion": "1.0",
+    "settings": {
+        "baseServiceUrl": "http://sampleserver6.arcgisonline.com/arcgis/rest"
+    },
+    items: [
+        {
+            "$type": "layer-extension",
+            "id": "hurricanes",
+            "layer": {
+                "layerType": "ArcGISMapServiceLayer",
+                "url": "{setting://baseServiceUrl}/services/Hurricanes/MapServer"
+            }
+        }
+    ]
+}
+```
+
+## Failure Modes
+
+By default, when one item references another and the referenced item cannot be
+created, then the original item cannot be created either. In this case an error
+will occur when you attempt to get the original item from the App container. You
+can adjust this behavior by defining a custom failure mode for an item in the
+top-level `failureModes` property. This property maps an `item://` URI to the
+failure mode value for that item. Possible values are `"error"`, `"warn"`, and
+`"ignore"`, with `"error"` being the default. For example:
+
+```
+{
+    "schemaVersion": "1.0",
+    items: [
+        {
+            "$type": "layer-extension",
+            "id": "broken",
+            "layer": {
+                "url": "invalid URL"
+            }
+        },
+        {
+            $type: "map-extension",
+            id: "default",
+            layerExtensions: [
+                "item://layer-extension/broken"
+            ]
+        }
+    ],
+    "failureModes": [
+        "item://layer-extension/broken": "warn"
+    ]
+}
+```
+
+In this example, the item `item://layer-extension/broken` contains an invalid
+URL, and so it cannot be created. Normally this would mean that
+`item://map-extension/default` couldn't be created either, but because of the
+configured failure mode of `"warn"` for the layer extension, the map extension
+can still be created. The AppContainer will remove the invalid URI prior to
+creating the map extension, and will raise a special `configWarning` event
+containing details about the item that could not be created. In this case, the
+host application should handle this event by warning the end user about the
+missing layer.
+
+Failure modes are also passed on to the item factories. This means that objects
+that are created by the AppContainer can also respond to failure modes. For
+example, MapExtension will honor a layer extension's failure mode if the layer
+fails to load successfully (e.g. the map service is currently unavailable). The
+exact behavior depends on the type of object.
+
+## App Imports
+
+An App can import one or more other Apps via the top-level `import` block. This
+is a list of one or more URLs pointing to other Apps to import, like so:
+
+```
+{
+    "schemaVersion": "1.0",
+    "import": [
+        "http://some.company.com/apps/default-basemaps.app.json",
+        "default-layers.app.json"
+    ]
+}
+```
+
+When an App imports another one, the items, settings, failure modes, etc.
+defined in the referenced app become part of the current App, as though they had
+been defined inline.
+
+If the current App contains one or more items that also appear in the imported
+App, then the items' properties are merged, with locally defined property values
+overriding imported ones. Similarly, locally defined settings and failure modes
+override ones that are imported. If multiple Apps are imported, then content
+from Apps that appear later in the list of imports will override the content of
+earlier ones.
+
+An imported App can itself contain App imports. In that case, those inner imports
+are resolved first, and the resulting App is then imported into the outer one.
+
+## Importing Apps from Portal
+
+It is possible to import Apps from a portal instance by using one of the
+following URI patterns:
+
+-   portal://<portal-id>/<item-id>
+-   portal://<item-id>
+
+The first version (with _portal-id_) can be used when you want to specify the
+portal instance where the item is located. In order for this portal:// URI to
+successfully be resolved, you must associate _portal-id_ with an instance of
+@arcgis/core/portal/Portal. This can be done using the _portals_ map in
+@vertigis/arcgis-extensions/config.
+
+You can import App configuration from a portal instance like this:
+
+```
+{
+    "schemaVersion": "1.0",
+    "import": [
+        "portal://test-portal/abcdef0123456789abcdef0123456789,
+    ]
+}
+```
+
+If the imported configuration has any further imports in form
+portal://<item-id>, these will be changed to use the _portal-id_ of the parent
+App.