Embed with URL parameters (1/3) - Obtain URL info (available URL parameters) from the ExB app and pass it down onto the Embed widget

1017
8
05-21-2021 04:46 AM
Labels (2)
TonghuiMing
Esri Contributor
2 8 1,017

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
WAB:
?extent=
?center=
?scale=
?query=
Ops Dashboard:
?state=

Note: Be aware of the differences between URL parameter usage rules for each app.

  1. After all the above information is ready, create an ExB app, drag an Embed widget to the canvas, save the app;
  2. 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:InkedFinalExBURL_LI.jpgNote: there should only be one '?' in the URL parameters. The following ones should be changed to '&'.
  3. 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}.
    AppURLconfiguration.pngDashboard.png
  4. 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.

  5. 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.

  6. 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 appRuntime_to use the URL parameters.png

 

Examples

1. Embed Case1_How to use the app URL1_WAB

End-user cases:

https://experience.arcgis.com/experience/b9a131b292c74a13ae7f3655c620d97f/?query=USA%20Major%20Citie...

https://experience.arcgis.com/experience/b9a131b292c74a13ae7f3655c620d97f/?query=USA%20Major%20Citie... 

...(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

 

 

8 Comments
cnw_ivesleung
New Contributor II

Will this be available for Dashboards where hash # is used?

GIS_utahDEM
New Contributor III

Is it possible to use URL parameters on an embedded dashboard to either allow a selection (within the dashboard) as a trigger for a data action (in an ExB table), or as a data action triggered by another ExB widget? Essentially I want a selection on a dashboard list to filter an ExB table, or a selection on an the ExB Table to highlight, flash or center on the related item in the embedded dashboard. The fact that certain URL parameters can take user input makes me think this would be possible, but I'm just not sure how to work it. 

Jianxia
Esri Regular Contributor

@GIS_utahDEM, the drawback for embedded apps is that they can't interact with other widgets from ExB as embedded apps live in sandboxes, isolated from others. The only way to communicate with them is to pass URL parameters down currently.

Jianxia
Esri Regular Contributor

@cnw_ivesleung, could you provide more information on what you are trying to do?

EmilyMcLeanACTGOV
New Contributor III

Hi @GIS_utahDEM ,

For your example of "selection on a dashboard list to filter an ExB table" you'll need URL parameters to be supported within Experience Builder Widgets. I've submitted an idea for this functionality here: Experience Builder Widgets to Support URL Parameters 

Hope this helps!

Thanks, 

Emily

MattHuser
New Contributor II

So if an Experience Builder references a simple Web Map, parameters do not work?  The only way to honor parameters within EB for situations like zooming to an address or extent is to create a WAB solution that references the Web Map and use the Embed Widget to reference the WAB solution instead of the Web Map inside of the EB?  If I'm reading this correctly, that would be problematic because I would lose out on functionality offered by the other widgets in EB since they would not be able to connect/interact with the embed widget content. 

Maybe I'm missing something...I have an EB that references a WebMap, how can I add a parameter to get to an address or extent?

Thanks!

Jianxia
Esri Regular Contributor

@MattHuser, the Embed widget with URL parameter in this blog, designed for the communication between embedded apps and an experience, is different from a general URL parameters. Unlike Web AppBuilder or Dashboards, Experience Builder has not had support for URL parameters described here, for example. Some of them will be supported eventually but there is no timeline currently. Hopefully this helps clarify a bit.

Matt-Huser
New Contributor

@Jianxia Thank you for the follow up and clarification.

About the Author
Product Engineer for Experience Builder and Web AppBuilder. Into sports like kayaking, canoeing, and swimming. Big fan of aquariums. U of M alumni.