Commands and Operations
Commands and operations are runnable, independent units of work within VertiGIS Studio Web. Commands and operations act as global functions which can be executed from any component or service.
Commands and operations have one key difference. Commands execute behavior that can have effects on the application, while operations produce outputs which can be passed to commands. Commands and operations can be run sequentially in what's called a "command chain" to enable complex behavior.
Commands and Operations are grouped by namespace, for example:
auth.sign-in
auth.sign-out
edit.add-feature
edit.delete-features
The full list of existing commands and operations available in VertiGIS Studio Web can be found in the API documentation.
Commands and operations are used to power much of VertiGIS Studio Web's built in behavior and interactions. They can be run through configuration, or through custom services or components.
One thing that makes commands and operations so powerful is that built in components have properties in the app config which take them as values. They power everything from basic components like the IWTM, to advanced functionality like the results list. This allows built-in component's internal behavior to be configured with different commands and operations.
{
"items": [
...
{
"id": "iwtm-config-1",
"items": [
{
"id": "return-to-initial-view",
"iconId": "zoom-initial",
"title": "Return to Initial View",
"action": "map.zoom-to-initial-viewpoint",
"$type": "menu-item"
},
],
"$type": "menu"
},
{
"id": "results-list-config",
"featureActions": {
"id": "results-context",
"items": [
{
"id": "zoom",
"iconId": "zoom-feature",
"title": "Zoom to Feature",
"action": "map.zoom-to-features",
"$type": "menu-item"
},
{
"id": "remove-feature",
"iconId": "trash",
"title": "Remove Feature",
"action": "results.remove",
"$type": "menu-item"
},
],
"$type": "menu"
},
"onFeatureClick": [
"results.display-details"
],
"$type": "results"
},
...
]
}
Workflow Command
VertiGIS Studio Workflow can allow for the creation of completely customized behavior without writing custom code. VertiGIS Studio Web has a special command, workflow.run, which allows you to run workflows anywhere you would run a command or operation. Using workflow, you can take custom behavior in VertiGIS Studio Web further without having to write custom code.
Check out this example of running a workflow from app config.
Configuring Commands and Operations
Commands and operations can be used through the app config to customize built in components.
{
"schemaVersion": "1.0",
"items": [
...
{
"id": "button-config",
"iconId": "zoom-in",
"title": "Zoom In",
"action": "map.zoom-in",
"$type": "menu-item"
}
...
]
}
App config properties like action can accept a singular command/operation or a command chain .
Command chains are arrays of commands and operations which are executed sequentially. The output of previous operations is passed along the chain to future operations and commands, allowing for complex input dependent behavior.
{
"id": "zoom",
"$type": "menu-item",
"title": "Zoom to Features",
"action": ["map.zoom-to-features", "highlights.pulse"]
}
Passing Explicit Arguments
Commands and operations can be configured with an arguments property that passes values to the function at execution time.
You can find out what arguments a command or operation takes in the commands and operations API reference.
{
"$type": "menu",
"id": "iwtm",
"items": [
{
"title": "Hello",
"isEnabled": true,
"iconId": "info",
"action": {
"name": "ui.display-notification",
"arguments": {
"message": "World"
}
}
}
]
}
Passing Implicit Arguments
If you do not pass explicit arguments, then implicit arguments will be passed to the command or operation. Implicit arguments come from the context that a command or operation is running in, or from a previous operation in the command chain
For example, let's look at the configuration for the onFeatureClick property of a <results-list> component model.
{
"schemaVersion": "1.0",
"items": [
...
{
"id": "results-list",
"$type": "results",
"onFeatureClick": "results.display-details"
},
...
]
}
In this example, the context is an item in the results list, so results.display-details will receive an argument with a Features property, which is the shape of argument it needs.
Arguments are also passed implicitly if you create a command chain, which runs operations one after the other.
Command Chains
App config properties that accept a command or operation can take a single operation or they can take a command chain. Command chains are arrays of commands and operations which are executed sequentially. The output of previous operations is passed along the chain to future operations, allowing for complex chains of behavior.
For example, here's configuration for the various behaviors of a <results-list> component.
{
"schemaVersion": "1.0",
"items": [
...
{
"id": "results-list",
"$type": "results",
"featureActions": [
"item://menu-item/zoom-to-features",
"item://menu-item/save-features-to-csv"
],
"onFeatureClick": "results.display-details"
},
{
"id": "zoom-to-features",
"$type": "menu-item",
"title": "Zoom to Features",
"action": ["map.zoom-to-features", "highlights.pulse"]
},
{
"id": "save-features-to-csv",
"$type": "menu-item",
"title": "Save Features to CSV",
"action": ["results.convert-to-csv", "system.download-file"]
},
...
]
}
Since these commands and operations are running from the context of a <results-list> component, the first command or operation will receive the relevant feature as its input. If the property is a command chain, the next step in line will receive one of two possible inputs.
- If the previous step was a command (which doesn't produce output), then the original input is passed on to the next step.
- If the previous step was an operation (which produces an output), then the output of that operation is passed onto the next step.
In this way, you can run multiple commands in a row that receive a feature as input, as seen in the action command chain of zoom-to-features in the example.
// Both of these commands will receive the Features argument passed into the
// command chain.
["map.zoom-to-features", "highlights.pulse"]
The action command chain of save-features-to-csv demonstrates how an operation can pass its output to the next command or operation in the list. In this case, it's passing the CSV content to system.download-file.
// `system.download-file` will receive the output of `results.convert-to-csv`.
["results.convert-to-csv", "system.download-file"]
Example: Configured Map and I Want to Menu
This example demonstrates two different types of argument passing behavior.
- App Config
- Layout
{
"schemaVersion": "1.0",
"items": [
{
"$type": "map-extension",
"id": "default",
"webMap": "https://www.arcgis.com/home/item.html?id=0ba877a4185448cb832af9a661031e31",
"onClick": [
"tasks.identify",
"highlights.add-focus",
"results.display"
]
},
{
"$type": "menu",
"id": "iwtm",
"items": [
{
"title": "Return to Default Map View",
"isEnabled": true,
"action": [
{
"name": "map.zoom-to-initial-viewpoint",
"arguments": [
"item://map-extension/default"
]
}
]
}
]
}
]
}
<?xml version="1.0" encoding="utf-8" ?>
<layout xmlns="https://geocortex.com/layout/v1">
<split resizable="true">
<panel show-close-button="false" width="26">
<results-list active="true"/>
<feature-details active="false"/>
</panel>
<map config="default">
<iwtm config="iwtm" slot="top-left"/>
</map>
</split>
</layout>
Let's first look at the command chain defined on the onClick property of a map. This chain consists of three operations and commands:
task.identify,highlights.add-focusresults.display
tasks.identify does not have any named arguments defined, so it will take arguments passed into it from its current context. Since this chain is run on a map click, the context argument passed in has the shape:
{
"geometry": "Esri.Point(<map-click-location>)",
... <other props>
}
tasks.identify receives this argument, and since it is an operation, produces an output. Looking at the Commands and Operations Documentation, tasks.identify has output of type Features.
highlights.add-focus and results.display both take a Features type input, so the output of tasks.identify will work nicely. highlights.add-focus is immediately after tasks.identify, so it receives the output of identify. Since highlights.add-focus is a command, it does not produce any output. Therefore, results.display will receive the output of the last operation, tasks.identify. In this way, you can pass the output of an operation to multiple commands.
The second behavior in this application is a map.zoom-to-initial-viewpoint command on the I Want To Menu. This command takes Maps type argument. The argument property in the app config supplies an array of maps by referencing the default map with an Item URI. Item URIs are a way of referencing other items within the app config.
Next Steps
VertiGIS Studio Web has a large array of built-in command and operations that you can chain to power custom behavior. Custom commands and operations can also be implemented with the SDK.
Commands, Operations, and Events API
Check out the available commands and operations
Run a Command or Operation with a Button
Learn how to configure a button to run a command or operation
Build your own Commands and Operations
Use the SDK to implement custom commands and operations
Learn about Events built into VertiGIS Studio Web
Learn about the global event infrastructure in VertiGIS Studio Web