URL query parameters in Web AppBuilder
/URL parameters are dynamic values within the URL of a web map or app that perform pre-defined functionality, such as zooming to fixed scales/locations or querying within layers.
As an example of how they could be used, an existing enterprise system could be extended with web mapping applications or extra capabilities through the use of URL parameters. A hyperlink could be dynamically generated within the system so that when a user clicks on the URL/hyperlink it automatically launches a Web AppBuilder application and zooms to a feature, based on a unique identifier within the data. Using URL parameters means that a single page is capable of rendering any number of bespoke dynamic views, and so they can simplify and streamline systems.
This blog will focus on query based URL parameters in Web AppBuilder, and is applicable whether you are using ArcGIS Online, Portal for ArcGIS, or Web AppBuilder (Developer Edition). It is important to be familiar with the information defined in the “Fields” section of the service definition, particularly the field type, as this can affect how the query is built. Note that URL parameters are not available in 3D Web AppBuilder apps.
The following REST service, containing the location of polling stations in Edinburgh, will be the basis of this blog so viewing its definition in advance is recommended:
http://services2.arcgis.com/1qjjJoUN1p26Md36/arcgis/rest/services/EdinPollingPlaces/FeatureServer/0
Below is a sample Web AppBuilder application which uses the above REST service:
http://esriuk-aulg.maps.arcgis.com/apps/webappviewer/index.html?id=1b0b4147a1da446eaf2a041c422e4ab7
Constructing the URL
When constructing a query it is best practice to use the layer ID rather than name as the layer ID is a non-editable constant. The layer ID is retrieved by querying the webmap that is used in the Web AppBuilder application.
If the webmap ID is unknown, it can be retrieved from the "map": - "itemId": parameter in the output JSON generated by performing the following query on the application ID (in this example: 1b0b4147a1da446eaf2a041c422e4ab7) :
Substitute the webmap ID (in this example: 1ccf8d40064d42e89b633b0e9d3151fe) into the following URL:
This query will return JSON that will contain a parameter called “id”: within the “operationalLayers”: parameter.
The syntax for constructing the URL query parameter is :
query=<layer id>, <where clause>
Text Query
On the sample layer the AREA_CODE is a unique identifier of String type. Using the following example, the layer could be queried in the Web AppBuilder application based on the AREA_CODE field for the unique value 'NC11A':
Note, in this sample URL the layer ID is EdinPollingPlaces_7427 (as per the returned JSON). AREA_CODE is the name of the field as defined in the “Fields” section of the REST service definition. As this field is of String type, the value should be enclosed within single quotes or %27 (the encoding reference for a single quote).
Numeric Query
When querying on a numeric field it is not required to enclose the query value in single quotes. Using the following example, the layer could be queried in the Web AppBuilder application based on the VotingBooths numeric field, for the value of 2.
This query will return all the voting booths with a value of 2. In the case of multiple incidences of the same value, the popup can be utilised to scroll through each record that meets the condition.
As the VotingBooths field is a numeric type, it is also possible to use relational operators such as < for less than in place of "=".
Further Reading
This blog is a brief synopsis of using the query URL parameter and should be enough to get you started. There is further detail on the help pages regarding other parameter URL functions such as centre map, define scale or add point:
https://doc.arcgis.com/en/web-appbuilder/manage-apps/app-url-parameters.htm
For more information on URL encoding references please see the following: