End users interact with your GIS data, services and web maps through client applications… a rather mechanical statement, but one that states the obvious nonetheless! Re-phrasing this as “Users experience your GIS data and services using client applications”, places emphasis on the emotion associated with using apps and the important role they provide as the delivery vehicle for your content, maps and analysis tools.
In my first ‘We Talk Tech’ article we took a tour of Experience Builder, highlighting its capabilities and how it can be used to exert full design control over your web applications in both map centric and page centric design patterns. This follow-up takes a closer look at the process of creating your own widgets. We consider the when and how in relation to extending Experience Builder and take the Experience Building 'Developer Edition’ and SDK for a test drive.
Figure 1 - Creating new experience builder widgets
When to extend? - The assessment part
There is little doubt, that employing a ‘Configure First’ strategy is the best practice approach to meeting your app delivery requirements by using commercial off-the-shelf (COTS) apps such as Experience Builder.
Figure 2 - COTS, configuration & strategies to extend
Where functional gaps arise, it is prudent to evaluate if the requirement can be delivered using an alternative config-based workflow or assess where information products (i.e. data model, services, and web maps) can be updated and republished to squeeze more capability by means of configuration alone.
When functional gaps remain, there is a case for considering extending. Using modular frameworks like Experience Builder allows you to create custom widgets and ‘plug’ them into apps - meeting edge requirements that cannot be realised straight out-of-the-box. Extending existing apps lets you develop only the additional functionality you need, reducing the overall complexity of meeting the business need.
I posit that it is possible to create some really rich and innovative widgets using a low code approach, bridging functional gaps when they arise with a low code footprint. Let’s take a look at what’s involved.
Getting started – the set-up part
To get started you will first need to set up your environment by:
- Downloading and Installing Node.js (Developer Edition runs on top of node.js 12+)
- Downloading the Experience Builder SDK and following the steps here for set-up (or view the set up in this video)
- Registering the Experience Builder Client in ArcGIS (Online or Enterprise)
Once the set-up has completed, launch Experience Builder by browsing to https://localhost:3001. At this point you’ll be prompted to supply a credential to Experience Builder. Once signed into ArcGIS, you’ll be re-directed to your own local instance of Experience Builder.
Figure 3 - Experience Builder Developer Edition (Deploy a certificate)
Hint: Experience Builder is set up with a self-signed certificate. To avoid any browser security warnings or trust issues when accessing ArcGIS or external resources, follow the steps described in this post to replace the self-signed certificate with one from a trusted certificate authority.
What you need to be familiar with – the tech part
Figure 4 - Experience builder underlying technologies
To start creating your own widgets, a basic understanding of the following technologies and core concepts is recommended:
Figure 5 - Frameworks that power experience builder
- Is a syntax similar to html that allows you to describe what the widget's UI’s will look like through React
- Esri’s web API for building compelling web apps that unlock your data’s potential with interactive user experiences
- 3rd party libraries such as JQuery and Bootstrap
- Useful to integrate some existing widgets and components into your widget using some common JS libraries such as JQuery and bootstrap
The getting started area of the Experience Builder online documentation is another excellent resource which brings all of the core concepts of widget creation together in one place – and one that is recommended pre-reading before you get started.
Figure 6 - Widget Structure
The structure of an experience builder widget provides separation between the configuration (Settings.tsx), runtime logic and front-end UI for the widget (Widget.tsx). The creation of your widget will primarily involve updates and modifications to these two files.
Finally, for your code editor or IDE, I’d recommend using Visual Studio Code, as it understands the TypeScript environment out-of-the-box. With your environment set up complete, you are ready to create your first widget.
Creating widgets – the fun part
Most map centric apps allow you to access your GIS data using the traditional pattern of map navigation, feature selection followed by attribute display in a pop-up or table row. I am always interested in exploring new ways to interact with GIS data from the ‘inside out’, in other words presenting the geodatabase contents and media in an engaging and interactive web page context before the need to interact with data via the map itself.
I decided to set myself the challenge of creating a widget that provides a gallery view of media & file attachments in a feature layer while maintaining the link between the attachment and display on a map.
Figure 7 - Access image attachment through pop-up link
Figure 8 - Access image attachments through an ‘experience’ widget
I defined the following requirements to form the scope for the widget:
- Must display all media attachments for a configured feature layer in a single page load.
- Must allow users to browse images on desktop and touch screen devices.
- Must allow users to select an image and view attributes for the feature it is associated with.
- Must allow users to select an image and zoom to the associated feature with a paired map widget.
With must have requirements laid down, the next stage involved sketching out the user interface and design concept for the widget behaviour and identifying dependencies.
Figure 9 - Creating a conceptual wireframe for your custom widget
To keep coding to a minimum I sought to use existing libraries where possible. The JQuery library – ‘flipster’ met my needs for the image carousel control. External or 3rd party JS libraries are referenced in the dependency section of your widget’s manifest.json file as below.
Figure 10 - View inside the widget manifest.json
I then needed to figure out how to bind the JQuery control to images stored as attachments in a feature service. Configuring a widget is tactfully handled through the use of the Settings.tsx file, through which you can deliver a convenient front-end for site admins.
The <DataSourceSelector/> component allows users to browse for and select a data source in accordance with the SupportedTypes property set for your widget. I limited the SupportedTypes to feature layers, prompting the user to browse for a Feature Service (or a web map that contains one).
Runtime logic and display rendering is handled in the main entry file – Widget.tsx. The REACT render() method contains the code to query attachments for the selected layer and hydrate the carousel control with any images returned by the query.
Additional configuration was added to set the display style variable for carousel and a <FieldSelector/> prompts the admin to select a field (from the feature layer’s schema) to display some descriptive text about the selected feature.
Finally, map display was achieved by adding a <JimuMapViewSelector/> element to the setting page to facilitate connection with a map widget (if available on the same page). Inter widget communication is event driven using jimu message types including DataRecordsSelectionChange. A message/action facilitated communicate between my widget and a paired map control, with navigation driven by querying the geometry property for the selected feature on the carousel control.
Figure 11 - Widget configuration & ‘buddying’ with a map widget
Figure 12 - Testing preview in widget ‘coverflow’ mode
Figure 12.1 - Testing preview in widget ‘wheel’ mode
Figure 13 - Access core JS API widgets including print
In the following example I reference the print widget base class and build a print widget within minutes! See the widget in action below.
Hosting your app – the deployment part
Deployment of Experience Builder apps is described here – it’s essentially download and host. For sites with private content ensure to register you site and add the applications clientid to the app’s config.json.
Figure 15 - Download your app for deployment
Web apps that use widgets created using the SDK do require hosting. Platform-as-a-service (PaaS) providers such as AWS and Azure’s app service offer rapid deployment of app hosting as a service, without the need for traditional server infrastructure. I’ve deployed the widgets created for this article on Azure’s app service here. With App Service you can also automate your deployment using continuous integration with DevOps tools or simple file sync using cloud storage including a OneDrive folder.
Figure 16 - Hosting on Azure App service
Wrapping up – the summary part
It was a really creative and fun process to work with the SDK to create my first widget. I am impressed with agility the SDK and developer edition provide – the scaffolding for widget creation with a well-documented API. Integrating existing JS libraries and code samples supports a low-code approach to implementation. While the array of widgets available in experience builder out-of-the-box will no doubt continue to evolve, it is re-assuring to know that there is a modular framework available for extending and creating new workflows when it’s needed.
“Imagination is everything. It is the preview of life's coming attractions” : A. Einstein
Nigel McGuirk is a solution architect with over 20 years’ experience designing and implementing Web GIS architectures, applications & workflows. He has a passion for location based technology and helping customers achieve their goals through well designed solutions on the ArcGIS platform. In his spare time he enjoys music, running and photography.