ArcGIS Web AppBuilder: Choosing a destination before app launch


In the prequel to this blog, we looked at the basic construction of URL schemes, important parameters and key/pair values within ArcGIS Web AppBuilder. As a result, we were able to use our existing Web AppBuilder template and swap out the default web map for another web map by utilizing the capabilities that lie within the URL.

This blog introduces additional concepts with regards to these available URL capabilities and explores different parameters surrounding the position, selection and extent of the map when displayed on app launch. As mission control, we are able to modify parameters that allow us to pre-define and articulate the placement of our app before blasting off.

The document, URL parameters for ArcGIS Web AppBuilder covers the URL parameters available for use in ArcGIS Web AppBuilder.

Of the parameters, there are some that allow us to control the extent and position of our web map. In this blog post, we are going to focus on the ‘center‘, ‘extent‘, ‘find‘ and the ‘query‘ parameters.

Center

Utilising the American spelling format, this parameter is used to centre our map at a predefined coordinate pair value (x,y) or coordinate pair value with well known ID (x,y,WKID). The basic structure of a URL using the ‘center’ parameter is shown below.

Geographic Coordinate System (GCS) format
https://<your app>?center=123,-456

Projected coordinate System (PCS) format (with WKID)
https://<your app>?center=123,-456,102100

An example of this in action could be centring a map around the Esri head office coordinates like this:

https://<your app>?appid=<AppID>&center=-117.19479001927878,34.057264995787875

You can additionally add the level parameter to the above so the zoom level is to your liking. For example,

 https://<your app>?appid=<AppID>&center=-117.19479001927878,34.057264995787875&level=<level number> 

The below graphic shows the JSON result returned when directly calling the Esri geocoding service. From this, we are able to see the various parameters it holds including the X and Y coordinates we used in the above example that references the center parameter.

Extent

Similar to the ‘center’ parameter, the ‘extent’ parameter is also used to centre our map in a predefined nature. However, the difference is that this parameter uses a bounding box to do so, instead of centring using a single coordinate pair. The extent parameter takes four values for geographic coordinate systems (GCS): MinX, MinY, MaxX, MaxY, and follows the same format for projected coordinate systems (PCS), with an optional well-known text value at the end. Unlike the ‘center’ parameter, ‘extent’ usually won’t need to be used in conjunction with parameters like ‘level’ because the desired bounding box is already specified.

The example below shows the extent parameter used in a URL to return the extent for Esri’s head office in Redlands, California in a WebAppBuilder application.

https://<your app>?appid=<AppID>&extent=-117.19579001927879,34.056264995787878,-117.19379001927878,34.058264995787873

Find

The ‘find’ parameter calls the Esri World Geocoding Service (EWGS), performing a findAddressCandidates operation using the SingleLine address type. This ‘find’ parameter works in the same way that an interactive location search function would. That is, instead of manually entering the address in the location search bar, the location is appended to the URL, and the web map is consequently panned and zoomed to the nominated address location.

For example.

https://<your app>?appid=<AppID>&find=80 new york street, redlands

The above URL statement will call a findAddressCandidates operation to the Esri geocoding service as captured below.

Query

The ‘query’ parameter is arguably the most versatile of the available parameters, having a number of uses. For example, it may be used to select and zoom to a particular feature/record,  identify a group of features via the popup window upon launch, or even query multiple features.

There are a few ways to format a query parameter into our URL but, in this section, we will be focusing on two of the aforementioned uses: 1. The standard three-argument [Layer Name, Field, Value] format, which selects, zooms and presents a popup window for a subject feature, and, 2. The more versatile two-argument [Layer Name; Where clause] format, may be used to return a single feature or multiple features.
(For more information on the Query parameter please click here.)

Format 1 – Standard:

query=<layer name>,<field name>,<field value>
https://<your app>?appid=<AppID>&query=BNE_Test_Cllips,Name,3

Below we can see an image of a URL with a standard query parameter applied to it, following the format above. This approach separates each of its three arguments using a comma in a top-down approach. e.g.[Layer Name, Layer Field, Field Value]

Upon launch, the web app should zoom into and select the queried feature. A pop-up window should also appear by default displaying the feature as configured.

Format 2 – Where clause:

Return single feature

query=<layer name>; <where clause>
https://<your app>?appid=<AppID>&query=BNE_Test_Cllips;Name=10

Note the use of the semi-colon to separate the layer name and the where clause. This varies from the usual approach of using a comma as the delimiter.

Return multiple features

https://<your app>?appid=<AppID>&query=BNE_Test_Cllips;Name in (10,8,4,7)
OR
https://<your app>?appid=<AppID>&query=BNE_Test_Cllips;Name%20in%20(10,8,4,7)

When querying multiple features via a URL, not all queried features are selected/highlighted in the map like the image above suggests. Rather, one item in our list of features is selected on the map screen and the rest of the queried features are added to the popup window, where we can step through the query result records using forward and back arrows. (Note: features in a query result popup will be in ascending order (e.g. 4,7,8,10) as opposed to the order provided in the URL where clause (e.g. 10,8,4,7). This will be dependent on the field/data type.  For the above example, numeric field values were queried.

Furthermore, the extent of the map should include at least some part of the queried features’ shared extent (see below image). This appears to be because the ‘level’ parameter is ineffective when used alongside the query parameter.

Note: Formatting our ‘query’ statement with URL encoded values is regarded as the best practice. Especially when using operators such as ‘in’ that require spaces on either side. Although the browser should populate these values automatically, this will act as a safety net and provide an extra level of control.

As mentioned above, the extent of the map should include all queried features but doesn’t necessarily encompass them entirely. The image above shows partial inclusion of features 8 and 10 although both are registered in the query string of the URL.

Conclusion

There are certain parameters we can utilise that allow the user to have more control over placement, position, and selections of our Web AppBuilder mapping applications. This is useful because we are able to pre-determine these parameters into our URL so our ‘rocket’ (Application) knows where to go before it leaves the launchpad. Use these parameters to enable functionality already built into the ArcGIS Platform, to more effectively work with Web Apps.

Good luck on your upcoming Web AppBuilder journey, shoot for the stars.

Resources

BLOG Part 1: Boost your Web AppBuilder Productivity with the URL Scheme

Use URL parameters

Esri Geocoding service – Find Address Candidates operation

Query a Feature (Anchor Point): from URL parameters

HTML URL Encoding Reference

Got something to say?

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s