By Julie Powell, Esri Product Management
This article as a PDF.
You can more easily create new widgets and repurpose existing widgets with any third-party framework such as Bootstrap, React, or jQuery. (React shown here.)
Its clean design and cutting-edge capabilities bring forward the most useful aspects of the 3.x API but also enables you to build compelling web apps with 3D visualization. Not all the 2D capabilities of the 3.x API will be available with the initial release. For example, time-enabled layers and Open Geospatial Consortium, Inc. (OGC), layers and editing will be available in later releases of the 4.0 API. Esri will be rapidly evolving the new API so that it not only achieves parity in terms of features with the 3.x API but introduces new capabilities.
1 Make a 3D map as easily as a 2D map.
With the introduction of map views, developers can render a map with a 2D view or a 3D view (or both) with just a few lines of code. Working with a 3D view is much like working with a 2D view. For example, both views have a unified approach for working layers, renderers, tasks, geometry, symbology, pop-ups, and navigation, but 3D adds 3D-specific concepts such as environment (atmosphere and lighting) and the camera. Compare the code for creating a 2D view and a 3D view shown in Listing 1.
Listing 1: Creating a 2D view and a 3D view
Many developers have adopted the pattern of authoring a web map in ArcGIS Online and Portal for ArcGIS and consuming it in an app. They create beautiful visualizations of their data, configure pop-ups, and set up bookmarks, then load the map into their app by simply referencing the web map's ID. This is a huge time saver.
Listing 2: Loading a web scene using its ID
With the 4.0 API, you can follow the same pattern with 3D maps using web scenes. This is accomplished by styling your map in ArcGIS Online or Portal for ArcGIS, saving it as a web scene, and then loading it in your app using the web scene's ID.
2 Author, manage, and mash up layers using layer items … all with minimal code.
Layer items are similar to web maps in that they allow developers to set up initial extent, rendering, filtering, pop-ups, and other settings. In contrast to web maps, which consist of the entire map, layer items represent individual map layers. This allows you to choose the individual layers needed for each application. If you are developing in a team environment, others can also consume your layers, which are represented in a meaningful and consistent way. The 4.0 API lets you load layers by referencing the layer item's ID. Listing 3 shows an example of how a layer can be loaded using the layer item.
Note: Not all 2D layer capabilities are supported in the initial 4.0 release.
Listing 3: Loading a layer item
With the 4.0 release, pop-ups are responsive and adapt to the screen size used. Pop-ups are also dockable and can have action buttons such as the mail button shown.
3 Build a great user experience.
The API was designed to give you the tools to build an app that has a polished user interface and responsive design. Widgets, flexible UI placement, and control over the map view are a few of the capabilities in this new API that will help you build a user-friendly app suitable for any device.
Widgets are the UI building blocks. API widgets have been built from the ground up with a clean user experience adaptable for any screen resolution. Widgets can be easily placed in one of the corners as shown in Listing 4 or offset from the edge. Relative placement of UI elements helps accommodate multiple screen resolutions.
Listing 4: Placing a widget
You can use API widgets as-is or style them using CSS to change specific aspects of the widget such as button color as shown in Listing 5.
Listing 5: Styling a widget button using CSS
Controlling the map view is important. If you need the map to fill only a portion of the screen so that a menu or other UI element occupies the rest of the space, you will want to keep a particular extent centered on the screen. Using view padding, you can make the map center or extent work off a subsection of the full view. As the screen size changes, your map will be centered relative to the location you specified.
4 Benefit from a simple and consistent API.
The 4.0 version of the API introduces an improved developer experience with a cleaner implementation. For example, working with properties is more straightforward. In the past, you often had to use methods to get or set property values. Only sometimes could you set property values directly. In the 4.0 version, you can consistently set all properties within the constructor or directly in the property itself. Because the API is more consistent in this way, the documentation can focus on describing the purpose of each property rather than on how to get and set it.
In the example in Listing 6, the SimpleMarkerSymbol's properties are simply set in the constructor. The 4.0 API also introduces a new concept called autocasting, which takes the values passed in these properties and instantiates the typed objects internally within the API. The example illustrates how you don't have to explicitly create a new SimpleLineSymbol for the SimpleMarkerSymbol's outline. Thanks to autocasting, the require statement for the esri/symbols/SimpleLineSymbol module is not needed.
Listing 6: Setting properties in the constructor
There is also a consistent approach for watching for property changes. In previous versions of the API, property changes were handled with events. Using the documentation, developers had to figure out which event to listen to determine when a particular property changed. With the 4.0 API, monitoring for property changes has become much easier because all properties can be watched via the .watch method (property, callback). The callback is called each time the property changes and allows you to work with the property's new value, old value, and name along with the watched object. You only have to learn and remember the essential classes and properties to work with the API.
With map views, developers can render a map with a 3D view using just a few lines of code, such as this map showing submarine cables.
5 Have it your way with tooling.
6 Don't do it all. Let configurable apps or Web AppBuilder for ArcGIS help.