Getting Comfortable with JavaScript API 4.0
1258
0
06-08-2016 01:30 AM
by
Noah-Sager
Now that the ArcGIS API for JavaScript 4.0 has been released for a couple of weeks, this is an excellent opportunity to take a walk through some of the new syntax and functionality. This blog will go through a sample 3D application focusing on the Search widget. You can follow along with the sample code from the Esri Developer Support GitHub repository, and run the hosted sample here: View it Live.
Functionality-wise, the app displays a 3D map with four widgets: Search, Zoom, Compass, and Attribution. By default, the View includes the latter three widgets, as described in the documentation. If you’re not familiar with the 4.x changes, all mapping apps contain a map and a view. The map holds the data, and the view contains the visualization information for that data. In other words, the map is the subject, and the view is the camera; complete with filters, modes, and settings. All 2D apps will have MapViews, and 3D apps will have SceneViews (note: the term ‘scene’ indicates three dimensions across ArcGIS). The same applies for maps from ArcGIS Online and Portal for ArcGIS: a WebMap is 2D, and a WebScene is 3D.
You can input a location in the Search widget and either select a result from the drop-down suggestions, or press Enter on the keyboard to go to the first place in the list. The view will zoom to that location and place a picture marker symbol on the map. If you open the Developer Tools in the web browser, you will see some helpful console log messages indicating the progress of the Search widget.
In the code, there are many helpful comments describing the functionality, with links to references to find more information. The Map and SceneView constructors might be new, but they are very straightforward. What I want to focus on here are two things: the SearchViewModel (beginning on line 88), and the view.ui (beginning on line 117).
One of the awesome features of 4.0 is the separation of the styling and the business logic. This means that widgets have a view and a ViewModel. The view is the widget itself and handles the display of the widget, while the ViewModel handles the properties and configurations. I should mention that we don’t have to use the ViewModel if we don’t want to since the ViewModel properties are also wired to the widget view. This was done for simplicity purposes. As an example, let’s look at the Search widget in the code:
The actual widget constructor was used for naming the widget and setting the visibility to true (default is true anyway). The SearchViewModel handles all the configurations that were set to customize the user experience and interface the way I needed (see the sample for comments). What’s interesting about this ViewModel system is because it's separated from the widget constructor, it’s now way easier to share business logic amongst widgets and code bases. Here is some more information about the SearchViewModel.
The second interesting aspect of 4.0 I will discuss here is how we add the Search widget to the app. Let’s look at the code snippet from 4.0 and from 3.x. Currently, we can add the widget directly to the view’s user interface without creating a separate div element. This is an efficient (and dare I say, elegant) workflow.
At the 3.x versions, we need to create a div element, reference the div when the widget is created, and reference it again inside the HTML body tag.
For more information about adding widgets to the view, you can reference this documentation.
In summary, the ArcGIS API for JavaScript is a powerful product that leverages the power of GIS directly on your web browser. If you’ve been working with earlier versions of the API, reading the Transition to 4.x help document can get you going. And if you’re brand new, you can start with the Discover 4.x Guide. There’s a lot more to come as we continue to add functionality and awesomeness to the JavaScript API 4.x. Happy coding!
Noah S. - SDK Readiness Lead
Functionality-wise, the app displays a 3D map with four widgets: Search, Zoom, Compass, and Attribution. By default, the View includes the latter three widgets, as described in the documentation. If you’re not familiar with the 4.x changes, all mapping apps contain a map and a view. The map holds the data, and the view contains the visualization information for that data. In other words, the map is the subject, and the view is the camera; complete with filters, modes, and settings. All 2D apps will have MapViews, and 3D apps will have SceneViews (note: the term ‘scene’ indicates three dimensions across ArcGIS). The same applies for maps from ArcGIS Online and Portal for ArcGIS: a WebMap is 2D, and a WebScene is 3D.
2D map + 3D scene
You can input a location in the Search widget and either select a result from the drop-down suggestions, or press Enter on the keyboard to go to the first place in the list. The view will zoom to that location and place a picture marker symbol on the map. If you open the Developer Tools in the web browser, you will see some helpful console log messages indicating the progress of the Search widget.
In the code, there are many helpful comments describing the functionality, with links to references to find more information. The Map and SceneView constructors might be new, but they are very straightforward. What I want to focus on here are two things: the SearchViewModel (beginning on line 88), and the view.ui (beginning on line 117).
One of the awesome features of 4.0 is the separation of the styling and the business logic. This means that widgets have a view and a ViewModel. The view is the widget itself and handles the display of the widget, while the ViewModel handles the properties and configurations. I should mention that we don’t have to use the ViewModel if we don’t want to since the ViewModel properties are also wired to the widget view. This was done for simplicity purposes. As an example, let’s look at the Search widget in the code:
Search Widget and SearchViewModel
The actual widget constructor was used for naming the widget and setting the visibility to true (default is true anyway). The SearchViewModel handles all the configurations that were set to customize the user experience and interface the way I needed (see the sample for comments). What’s interesting about this ViewModel system is because it's separated from the widget constructor, it’s now way easier to share business logic amongst widgets and code bases. Here is some more information about the SearchViewModel.
The second interesting aspect of 4.0 I will discuss here is how we add the Search widget to the app. Let’s look at the code snippet from 4.0 and from 3.x. Currently, we can add the widget directly to the view’s user interface without creating a separate div element. This is an efficient (and dare I say, elegant) workflow.
Add Search Widget 4.0
At the 3.x versions, we need to create a div element, reference the div when the widget is created, and reference it again inside the HTML body tag.
Add Search Widget 3.x
For more information about adding widgets to the view, you can reference this documentation.
In summary, the ArcGIS API for JavaScript is a powerful product that leverages the power of GIS directly on your web browser. If you’ve been working with earlier versions of the API, reading the Transition to 4.x help document can get you going. And if you’re brand new, you can start with the Discover 4.x Guide. There’s a lot more to come as we continue to add functionality and awesomeness to the JavaScript API 4.x. Happy coding!
Noah S. - SDK Readiness Lead
