What is the ArcGIS Maps SDK for JavaScript?
The ArcGIS Maps SDK for JavaScript is a powerful mapping and spatial analysis technology that enables developers to build compelling web GIS experiences. At Esri, we use this foundational SDK to develop geospatial applications. These applications enable users to create, analyze, collaborate on, and share their maps.
What are web components?
Introduced by the W3C, web components are a set of technologies native to the browser that allow the construction of custom reusable and framework-agnostic HTML elements. They provide strong encapsulation, custom functionality, and full compatibility with HTML and the DOM API. There are three main technologies provided by web components that we use in the SDK:
- Custom Elements – Allow developers to define their own HTML elements with custom behavior.
- Shadow DOM – Provide encapsulation for the SDK’s JavaScript and CSS within a custom element so it doesn’t affect the rest of the DOM.
- And HTML Templates – Permit the definition of markup chunks that can be used in instances of custom elements, including templates.
In summary, web components are great for simplifying complex HTML, along with its associated CSS and JavaScript. Next, we’ll go over the JavaScript Maps SDK and how web components are available as a new feature of the SDK.
ArcGIS Maps SDK for JavaScript components
The October 2023 release of ArcGIS Maps SDK for JavaScript (v4.28) introduced a beta version of our standards-based web components. JavaScript Maps SDK components are a component library extending parts of the JavaScript Maps SDK to provide reusable custom HTML elements that can be easily brought into your own GIS web applications. As of v4.30 of the JavaScript Maps SDK, three component packages are offered:
- Map components contain the map, scene, and all the JavaScript Maps SDK widgets wrapped as web components.
- Coding components are intended to support the general act of coding. The Arcade editor component is currently the main offering.
- Charts components (beta) contain a series of components that can be used to build charts in JavaScript Maps SDK applications. When used alongside maps, they can provide a complete data visualization story of your data.
With Map components, you can showcase a web map with one line of HTML:
<arcgis-map item-id="05e015c5f0314db9a487a9b46cb37eca></arcgis-map>
Why our developers use web components from the SDK
Web components have a rich history at Esri. By adopting web components as fundamental building blocks in our development process, we have been able to create a wide range of reusable HTML elements that are not tied to any specific application framework (e.g., React, Angular, Vue) or module bundler (e.g., Vite, Webpack). We also heavily utilize components from Calcite Design System. This adoption of web components unifies our developers and ensures consistent user experiences across different ArcGIS products.
In terms of programming paradigms, JavaScript Maps SDK components offer a declarative-first approach, while the JavaScript Maps SDK has traditionally followed a mostly imperative/procedural approach. With the components, developers can rely on prebuilt ArcGIS experiences that reduce the need for boilerplate code and instead focus on using HTML markup to accomplish most—if not all—of the required tasks. This simplifies the process of integrating ArcGIS capabilities into your app. On the other hand, the JavaScript Maps SDK provides extensive control over the application’s state and flow of execution by allowing developers to write detailed instructions.
A new way to build JS Maps SDK apps: Use components
To gain a better understanding of how you might create a basic web map using the imperative approach, check out the example below. JavaScript is used to manipulate the <div id="viewDiv"></div> container element which is responsible for displaying the map and its widgets.
Web map built with the JavaScript Maps SDK
To illustrate the difference between the two paradigms, let’s consider the previous example and demonstrate how it may be rewritten using the @arcgis/map-components package.
Web map built with JavaScript Maps SDK components
As you have seen with map components, JavaScript is not necessary to achieve the same solution, which eliminates the need for the viewDiv container element. It also simplifies needing to separately initialize the WebMap and MapView. It is important to note that while the example was written purely with web components, the underlying API is still available, creating a balance between the imperative and declarative programming paradigms. This flexibility allows you to reap the benefits of both approaches.
<body>
<arcgis-map item-id="05e015c5f0314db9a487a9b46cb37eca">
<arcgis-search position="top-right" />
<arcgis-legend position="bottom-left" />
</arcgis-map>
<script>
// Access the underlying API to get the thumbnail url of the map
const mapElm = document.querySelector("arcgis-map");
mapElm.addEventListener("arcgisViewReadyChange", (event) => {
const { map } = event.target;
console.log(map.thumbnailUrl);
});
</script>
</body>Integrate your apps with the Calcite Design System
You can integrate the Calcite Design System with JavaScript Maps SDK apps to build comprehensive and engaging GIS experiences. Observe that again with the imperative approach, there is boilerplate code and <div/> HTML elements needed to be created and manipulated with JavaScript.
Web map built with the JavaScript Maps SDK and Calcite
Web map built with JavaScript Maps SDK components and Calcite
Easily associate components with a Map or Scene
The Map and Scene components are parent containers for building interactive 2D and 3D visualization experiences. Other components from the @arcgis/map-components package can be associated with a Map or Scene component to provide additional functionality, such as adding a legend, layer list, search, and more. The legend component can access a map by setting its reference-element (see the Properties tab for more) to the id of the <arcgis-map/>. This is useful when components live outside of the <arcgis-map/> component.
Legend associated with a map
Get started today!
Explore component tutorials, where you can discover components to build web mapping applications with minimal code. Also, stay tuned – additional components will be available in upcoming releases.
For more information, refer to the component documentation. If you encounter an issue, visit the troubleshooting guide and to collaborate with others, ask questions, or report issues visit Esri Community.
Article Discussion: