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?
Web components are a set of technologies introduced by the W3C that allow the construction of custom reusable and framework-agnostic HTML elements. They provide strong encapsulation, custom functionality, and full compatibility with HTML and DOM APIs. 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 release of ArcGIS Maps SDK for JavaScript (v4.28) introduced a beta version of our standards-based web components. The initial offering of JavaScript Maps SDK components consists of three packages that extend parts of the JavaScript Maps SDK into reusable HTML elements:
- 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.
- Common components can be used alongside other JavaScript Maps SDK component packages to provide additional functionality.
<arcgis-map item-id="05e015c5f0314db9a487a9b46cb37eca"/>
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). 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.
How do components impact your apps?
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("viewReady", async (event) => {
const { view } = event.detail;
const { map } = view;
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 widgets with a map or scene
JavaScript Maps SDK components can further improve the readability and simplicity of your apps. For instance, widgets can access a map by setting their reference-element (see the Properties tab for more) to the id of the <arcgis-map/>. This is useful when widgets 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: