Embed with URL parameters (1/3) - Obtain URL info (available URL parameters) from the ExB app and pass it down onto the Embed widget
In the AGOL April update, a new feature was added:
A web experience can now communicate with an embedded app by passing URL parameters to control what appears in the embedded app at runtime. Use a single URL editor to form dynamic URLs from connected data attributes or app URL parameters, or add static URLs directly.
This series contains three articles, which will work you through three different cases on how the new feature works, allowing you to further utilize the Embed widget to accommodate different scenarios.
URL parameters are commonly used in web applications. If you embed some content inside an ExB app, how can I pass the parameter inside this embedded content to achieve the communication from the ExB app to embedded content?
How to configure the app
To prepare:
- ExB account access
- Apps that utilize URL parameters and can be embedded into ExB apps (e.g. Web AppBuilder, Ops Dashboard, etc.). Here are two examples used to demonstrate the following test case:
https://esridevbeijing.maps.arcgis.com/apps/webappviewer/index.html?id=b66a1c2f8d5a49ecacbf0b8fb6371df2 https://lcpsfhs.maps.arcgis.com/apps/opsdashboard/index.html#/0ef4d2226513499a8254b1f2d3102317
- The supported URL parameters of these apps (e.g. Web AppBuilder URL parameter doc, Ops Dashboard parameter doc, etc.). For example, the following URL parameters will be used to demonstrate this case:
WAB: ?extent= ?center= ?scale= ?query=
Ops Dashboard: ?state=
Note: Be aware of the differences between URL parameter usage rules for each app.
- After all the above information is ready, create an ExB app, drag an Embed widget to the canvas, save the app;
- Now, add the desired URL parameters that your embedded content is going to use to the ExB builder URL, in the browser tab, then click Enter to refresh the builder page to take effect, like this:
Note: there should only be one '?' in the URL parameters. The following ones should be changed to '&'.
- Inside your Embed widget, type your URL and the &query= part, for example, and then you will be able to open the URL info panel and add the app URL info as the value of this parameter at runtime. Note that the URL info generated by user selection will be in the format of {appURL.search.xxx}.
After all the content being configured, save the app, and run preview mode. Note that preview will not inherit your builder URL parameter for now so you would need to add them on later.
In the previewed app, all URLs will be removed now, so the added URL parameters for the embedded content shall be not affected, instead, it will show the content as it is without any URL parameters.
- Now, add any of the corresponding URL parameters added previously, and refresh the page, you can see the one that used the corresponding URL parameters will take effect and pass it to the embedded app
Examples
1. Embed Case1_How to use the app URL1_WAB
End-user cases:
...(can change per user's request and then show the different cities here)
2. Embed Case1_How to use the app URL2_embedDashboard
End-user cases:
https://experience.arcgis.com/experience/9b69e6e7a6984952944d0410ac9b1872/?state=Michigan
https://experience.arcgis.com/experience/9b69e6e7a6984952944d0410ac9b1872/?state=California
Key Point
- Type in the URL parameters you want for the ExB builder site, then save the app, so that the Embed widget can use them. You can even ignore the value of the parameter in the builder interface - try it out 🙂
- You are able to change the values of these URL parameters for ExB apps at runtime as long as they are valid for the embedded content.
What's coming next
- A new filter URL parameter (?data_filter=?dsId1:filter, dsId2:filter)
- How to use it in the Embed widget