Use URL parameters

Apps created with Web AppBuilder can be modified directly with URL parameters. The URL always begins with <your app>/? and includes one or more of the parameters listed below. Your app could be deployed in your web server or launched inside the Builder. To include more than one parameter, use an ampersand (&) to separate the parameters. The following is an example:

Deployed app

http://<your hosted app>/?find=380 new york street, redlands, ca&locale=fr

App launched in the Builder

http://<your machine name>:3344/webappbuilder/apps/4/?find=380 new york street, redlands, ca&locale=fr
Tip:

Now there is an easier way to construct URL parameters. Add the Share widget in the app and click Link Options. Link preview displays the parameters you selected and a short cut link including the url parameters is automatically generated for you. Be aware that the Search widget must be enabled in the app to use the find parameter.

Note:

Currently 3D apps do not support URL parameters.

Encode the query parameters

All query parameters must be encoded. Encoding replaces invalid characters with % followed by their hex equivalent.

For example, the following is an unencoded URL parameter:

http://<your app>/?find=380 new york street, redlands, ca

Here is the same parameter encoded:

http://<your app>/?find=380%20new%20york%20street,%20redlands,%20ca

The web has many free sites and tools for generating encoded URLs. For example, Albion Research Ltd. has a URLEncode and URLDecode Page. For readability, the rest of the examples in this topic are not encoded.

Center map

To center the map at a particular location, set center= using geographic coordinates (x,y) or projected coordinates (x,y,WKID).

Caution:

You can use commas or semicolons as separators. Use semicolons if your numbers use colons as their decimals

The following is a geographic coordinates example:

http://<your app>/?center=34,-50

The following is a projected coordinates example:

http://<your app>/?center=500000,5500000,102100

Define scale level

To define the scale level of the map, use the center= and level= parameters. The level parameter accepts the level ID of the cache scale as listed in the map service's REST endpoint. The following is an example:

http://<your app>/??center=20,45&level=4

Define scale

To define the scale of the map, use the center= and scale= parameters. The scale parameter accepts the cache scale as listed in the map service's REST endpoint. The following is an example:

http://<your app>/?center=20,45&scale=4622324

Define extent

To define the extent of the map, use extent= to define the extent of the map. The extent parameter accepts geographic coordinates (GCS) as MinX,MinY,MaxX,MaxY or projected coordinates (PCS) as MinX,MinY,MaxX,MaxY,WKID. You can use commas or semicolons as separators. Use semicolons if your numbers use colons as their decimals.

The following is a geographic coordinates example:

http://<your app>/?extent=-117.20,34.055,-117.19,34.06

The following is a projected coordinates example:

http://<your app>/?extent=-13079253.954115,3959110.38566837,-12918205.318785,4086639.70193162,102113

Find location of feature to open map

To find a location or feature that is used to open the map, use find=. The map is automatically zoomed to the closest match and a callout marker is added to the map. The find parameter accepts single-line addresses, partial addresses (such as city only or country only), place-names, longitude-latitude coordinates, and features in searchable layers (such as 1916352001 for a Parcel Identification Number (PIN)). The following is an example:

http://<your app>/?find=380 new york street, redlands, ca
Caution:

All query parameters must be encoded, and the Search widget must be enabled in the app to use this parameter.

Add point

To add a point to the map, use marker=<x>,<y>. The point is added to the map at the specified x and y location. You can also include the following optional properties:

  • <wkid>—Spatial reference of the x,y coordinates added to the map. If you do not include a WKID, GCS coordinates are used.
  • <encoded title>—Title of the point pop-up. If you do not include a title, the pop-up will be empty.
  • <encoded icon URL>—Symbol for the point. If you do not include a symbol, a blue marker symbol is used.
  • <encoded label>—Label next to the point symbol.

Considerations

  • <x>,<y> are required.
  • Be sure to encode the title, icon, and label parameters.
  • You must add properties in this order: marker=<x>,<y>,<wkid>,<encoded title>,<encoded icon URL>,<encoded label>.
  • You can use commas or semicolons as separators. Use semicolons if your numbers use colons as their decimals.
  • Use empty values. Do not use spaces. For example, if you want to specify a label and none of the other optional properties, add the label as the sixth parameter with empty values for the others (x;y;;;;label).
  • If you want the map to zoom in (in addition to centering on the point), include the level= parameter.

The following is an example:

http://<your app>/?marker=-79.234826;38.147884;;Race start and finish;;Grindstone 100 Ultra Marathon&level=7

Query feature

To query a feature and zoom to it, you can use one fo the following options:

  • query=<layer name>,<field name>,<field value>
  • query=<layer name>, <where clause>
  • query=<layer id>,<field name>,<field value>
  • query=<layer id>, <where clause>
Tip:

Now there is a way to construct URL parameters interactively. Add the Share widget in the app and click Link Options. Choose the Query a feature and zoom to it option and select the layer, field, and field value you want to query against. Copy the URL in Link preview that contains the URL parameters you specified. Remove the Share widget from the app if it's not needed.

Caution:

All of the query parameters are case sensitive and must be encoded.

Since the layer name can be changed, it is strongly recommended using the layer id in the query. You can retrieve the layer id from web map id as shown below.http://<your portal url>/sharing/rest/content/items/32a83775654249dcae6b8f2eff5d4072/data/?f=pjson.

Caution:

Make sure the web map is shared publicly when you retrieve the layer id.

For example, a layer is added in the map individually as shown below in the json format. It has layer id as Census_8491, field name as POP2000, and field value as 1211537. You can perform the following queries:

id: "Census_8491",
layerType: "ArcGISFeatureLayer",
url: "http://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3",
visibility: true,
opacity: 1,
mode: 1,
title: "Census - states",

http://<your app>/?query=Census_8491,POP2000,1211537
http://<your app>/?query=Census_8491,POP2000=1211537

You can also do queries against the string or OBJECTID.

http://<your app>/?query=Census_8491,STATE_NAME,California
http://<your app>/?query=Census_8491,STATE_NAME='California'
http://<your app>/?query=Census_8491,OBJECTID,1

Often a layer is added as a group of map service. To query a sublayer in a group, use <layer id_sublayer id> as the layer id instead. Taking the following layer as an example, it has layer id as Census_3217 and sublayer id as index of 3. The layer id for the sublayer should be Census_3217_3. You can perform the following queries:

id: "Census_3217",
layerType: "ArcGISMapServiceLayer",
url: "http://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer",
visibility: true,
opacity: 1,
title: "Census"

http://<your app>/?query=Census_3217_3,POP2000,1211537
http://<your app>/?query=Census_3217_3,POP2000=1211537

Switch locale

To switch app language, use locale=<language code>. These language codes are supported: ar,cs,da,de,en,el,es,et,fi,fr,he,it,ja,ko,lt,lv,nb,nl,pl,pt-br,pt-pt,ro,ru,sv,th,tr,zh-cn,vi,zh-hk,zh-tw.

The following is an example:

http://<your app>/?locale=fr

Authenticate user

To automatically authenticate a user in non-public app, use token=<token>. In this way users do not need to enter their user name and password. The following is an example:

http://<your app>/?token=utmVcabc_LNyEQ7OuuHD73em0MErLR_cudJTeSIdMFTnL0poF3shVBeng5ieWHyZn0kAA8nhUg7jseQxz3bi5crnFMMpldDiJLrtzmO3jEM-ZNVIUEh5_qMms-YgXUwGgFbeQlM9WaI3jwraUqwah0yCceBAxEkEIAEWvlBEDfVsYs3LZydORRcs2QIcdLas

Control when to turn on mobile layout

The app supports two styles of layout based on the screen size. One is for desktop and one is for mobile devices. When either the height or width of a screen display is less than 600 pixels, the mobile layout applies automatically. However this may result in unexpected behavior when the app is embedded in a website. For example, the pop up in the website becomes mobile layout style. To control the layout style, use mobileBreakPoint=<pixel number>. For example, you can remain in desktop style until the screen size is less than 300 pixels as shown below:

http://<your app>/?mobileBreakPoint=300

Run apps in different config file

By default, the app runs upon the config.json file in the stemapp or stemapp3d folder. If you want to apply different config file to the app, such as myConfig.json in the stemapp\sample-configs folder, use config=<file name>.

The following is an example:

http://[your app]/?config=sample-configs/myConfig.json