@vertigis/viewer-spec
Version:
VertiGIS Viewer Specification
312 lines (263 loc) • 10.3 kB
Markdown
# 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
/core/portal/Portal. This can be done using the _portals_ map in
/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.