Archive for August, 2009
Toolbars Made Easy with ArcGIS Server JavaScript API
As a GIS web application developer you want to focus on building functionality specific to the application you are constructing. Spending valuable time and effort adding basic GIS functions such as zooming and panning to your application detract from what should be your primary focus. Luckily, ESRI has made the addition of navigation and drawing toolbars to your application a snap with the ArcGIS Server JavaScript API. In this post I’ll show you just how easy it is.
Let’s start by examining a navigation sample that ESRI has placed on their resource center website. At first glance you’d think that the navigation toolbar is simply a user interface component that you drop into your application. Not exactly. The JavaScript API provides a toolbar helper class called esri.toolbars.Navigation to assist with accomplishing this task. In addition, the API also provides a class to handle drawing tasks such as lines and polygons. What these helper classes do is save you the work of drawing zoom boxes, capturing mouse clicks and other user initiated events. This is no small feat as I’m sure any experienced GIS web developer can attest.
We’ll start with the construction of the user interface components of the toolbar and then we’ll move on to discussing how to hook the tools into your map.
Using Dijits To Create the Toolbar and Buttons
The toolbar you see in the example is created using the Toolbar and Button user interface controls provided by Dijit (a sub-project of Dojo). Each control is enclosed within a <div> tag inside the <body> of the web page with all buttons being enclosed by the surrounding <div> that contains the Toolbar dijit.
Each button can be assigned both an icon and text. Notice in the figure above that the ‘Zoom Out’ Button assigns a value of ‘zoomoutIcon’ to the ‘iconClass’ attribute. This simply points to a CSS style that has been defined at the top of the file. Notice in the figure below that we have a style called ‘zoomoutIcon’ which defines an image to use for our button.
With a Button dijit you can also include text along with the icon. For this button we include the text ‘Zoom Out’ inside the <div> tag that creates the button.
The resulting button with icon and text is seen below.
So, that about sums it up for the user interface portion of the toolbar. Next we need to add in the code that creates an instance of esri.toolbars.Navigation and hook it into our map and toolbar.
esri.toolbars.Navigation
Creating an instance of the Navigation class is as easy as calling the constructor and passing in a reference to esri.map as seen in the code example below. However, you’ll first want to make sure that you add a reference to esri.toolbars.navigation.
Finally, we use dojo.connect to wire up an event to an event handler. In this case we are connecting the ‘onExtentHistoryChange’ event to the ‘extentHistoryChangeHandler’ function will run when the extent history changes.
How it Works
Now I’ll draw your attention back to the <div> tags where we created our toolbar and buttons. The Navigation class contains a number of constants and methods as seen below.
Each of the buttons that we defined within <div> tags has an ‘onClick’ attribute which refers to an event that fires when the button is clicked. In the case of the ‘Zoom In’ button seen in the code example below, a click of the button calls the ‘activate’ method on Navigation. A navigation type is passed into the ‘activate’ method. The navigation type can be one of three constants: PAN, ZOOM_IN, ZOOM_OUT. In each case these buttons are really tools that will require an additional map action by the user. For example, in the case of ‘ZOOM_IN’ the user would then draw a rectangle on the map which would trigger the generation of a new map displayed to the user.
In addition to zooming in and out and panning the Navigation class also supports full extent, next extent, and previous extent functions as defined through their corresponding methods (zoomToFullExtent(), zoomToNextExtent(), zoomToPrevExtent()). These methods are invoked through the ‘onClick’ event as seen below.
Hopefully this example has illustrated how easy it is to add a navigation toolbar to your ArcGIS Server application through the JavaScript API. You no longer have to be concerned with adding in JavaScript code to draw and handle the extent rectangle or capture mouse coordinates for a pan operation. In addition, the user interface components of the toolbar can be created easily through various user interface controls supplied by the Dijit library. I didn’t cover the Drawing toolbar in this post, but the esri.toolbars.Draw class makes it equally easy to support the drawing of geometries such as points, lines, and polygons within a similar toolbar.
More Information
For more information on the ArcGIS Server JavaScript API you may wish to consider our “Mastering the ArcGIS Server JavaScript API” course which covers this topic among many others. Our August 3rd – September 11th session is SOLD OUT. However, our next session begins October 5th and ends November 13th. Register before August 31st to save 15%.
Article List: ArcGIS JavaScript API and Dojo
Spent a little time over the weekend finding articles on the web related to ArcGIS Server JavaScript API and Dojo. I know this list is certainly not all-inclusive, but it should be a good start for those of you looking for some good how-to articles on this subject. Please feel free to pass on any additional articles and we’ll post them here.
Dojo, Dijit, DojoX
- An Easier Way to Zoom: A Dojo Dijit that Zooms to States and Counties (ESRI Blog)
- Creating a Reusable Task-Oriented Dijit (ESRI Blog)
- Using the Dojo BorderContainer to Design Application Layouts (ESRI Blog)
- Creating a Simple Map Dijit with the ArcGIS JavaScript API (ESRI Blog)
- Using Dojo Dijits with the ArcGIS JavaScript API (ESRI Blog)
- What is Dojo and Why Is It Important to ArcGIS Users (ESRI Blog)
- Custom Objects in Dojo.ItemFileReadStore: Using a Type Map (ESRI Blog)
- Fundamentals of Using Dojo with the ArcGIS Server JavaScript API (GeoChalkboard)
- Using Dojo to Enhance Web Mapping Applications (GeoChalkboard)
- Reading JSON Data with Dojo (GeoChalkboard)
- Accessing Multiple Data Formats with the Dojo Data API (GeoChalkboard)
Basic Concepts – ArcGIS Server JavaScript API
- The ArcGIS JavaScript API is Now Available to the Public (ESRI Blog)
- An Introduction to the ArcGIS Server JavaScript API (GeoChalkboard)
- ArcGIS JavaScript API: Basics for Developers (ArcGIS Resource Center)
- An Overview of the ArcGIS JavaScript APIs (ArcGIS Resource Center)
- Using the ArcGIS Server REST API (ArcGIS Resource Center)
- ArcGIS Server JavaScript API Example (James Fee Blog)
- ArcGIS Server REST API 101: Part 1 (Spatial Bytes)
- 2009 ESRI Developer Summit: Using the ArcGIS Server REST API (ESRI Developer Summit)
- ArcGIS Server JavaScript APIs (Dave Bouwman Blog)
Integration with Google, OpenLayers, Virtual Earth (Bing)
- Creating a Google Gadget with the ArcGIS JavaScript API in 5 Minutes (ESRI Blog)
- Integrating the Google Maps API Geocoder with ArcGIS Server (GeoChalkboard)
- Using OpenLayers with ArcGIS Server Rest API (James Fee Blog)
Specific Techniques
- Creating Graphics Using the ArcGIS Server JavaScript API (GeoChalkboard)
- Using Events in the ArcGIS Server JavaScript API (GeoChalkboard)
- Working with the Map Extent – ArcGIS Server JavaScript API (GeoChalkboard)
- Attaching an InfoWindow to Graphics with the ArcGIS Server JavaScript API (GeoChalkboard)
- Patterns and Best Practices for Building Applications with ArcGIS API for JavaScript (ArcGIS Resource Center)
- Developing Advanced Applications with the ArcGIS JavaScript API (ArcGIS Resource Center)
- ArcGIS JavaScript API Printing through PDF (ESRI Blog)
- Displaying an Image Service with the ArcGIS JavaScript API (ESRI Blog)
- Geoprocessing Parameter Types in the ArcGIS JavaScript API (ESRI Blog)
- A Quick Look at the Versatile Spatial Filters in the ArcGIS JavaScript APIs (ESRI Blog)
- Build Your JSAPI Applications for Performance (Geocortex Blog)
- Perform Buffer in ArcGIS JavaScript API Using ArcGIS Server 9.3 Geometry Service (GIS World Online)
- Installing and Using Your Own Data with the Sample ArcGIS Server 9.3 JavaScript API Viewer (mandown, geo.geek.nz)
- ArcGIS Server JavaScript API – Searchwith Apostrophes (ROK Technologies)
- Querying Points and Lines on Click with the ArcGIS JavaScript API (ESRI Blog)
Learn by Example
- Video Explains “Parcel Notification List” JavaScript Example (ESRI Blog)
- ArcGIS JavaScript and REST APIs: “Super Tuesday” Results (ESRI Blog)
- Building a Wildfire Mashup with ArcGIS Server and Google Maps – Post 1 of 5 (GeoChalkboard)
- Building a Wildfire Mashup with ArcGIS Server and Google Maps – Post 2 of 5 (GeoChalkboard)
- Building a Wildfire Mashup with ArcGIS Server and Google Maps – Post 3 of 5 (GeoChalkboard)
- Building a Wildfire Mashup with ArcGIS Server and Google Maps – Post 4 of 5 (GeoChalkboard)
- Building a Wildfire Mashup with ArcGIS Server and Google Maps – Post 5 of 5 (GeoChalkboard)
Other
More Information
We still have seats remaining for our October 5th – November 13th session of “Mastering the ArcGIS Server JavaScript API“. In this course we cover many of the topics listed above and more. Register before August 31st to take advantage of a 15% discount.
Upcoming Instructor Guided, Internet Based Courses
Geospatial Training Services has a number of instructor guided, Internet based courses that will be delivered in the near future.
Mastering the ArcGIS Server JavaScript API
- Course fills up very quickly so register early to reserve your seat
- October 5th – November 13th
- $675 if you register before August 31st. Regular price is $715 for government/educational and $795 for commercial
Building Web 2.0 Mapping Applications with ArcGIS Server and Google Maps
- This will be our 5th session of this course and each has sold out quickly so register early
- View Survey Results from Recent Class
- September 14th – October 16th
- $500 if you register before August 15th. Price goes up to $667 after.
Student Comments
“Overall, it was a great experience!”
“These courses are great. I am so pressed for time this is the only way I can acquire extra skills these days.”
“Very informative and knowledgeable course. It help determine which direction I should take my further GIS and web programming skills.”
“Really good course material. Very relevant subject matter.”
Read Full Post | Make a Comment ( None so far )“I thought the course was very organized. The style of presentation and the lesson format worked well together. It made the information easy to understand.”
Reading JSON Data with Dojo
Last time we discussed the high level details of the Read, Identity, Write, and Notification APIs that together comprise what the Dojo Data API. These abstract APIs are implemented by various core implementations called stores that read specific dataset types including JSON, XML, CSV and web services from Google, Flickr, and others. Today we’re going to discuss ItemFileReadStore which is Dojo’s core implementation for JSON format data.
What is JSON?
JSON or JavaScript Object Notation is a text based, lightweight data-interchange format that is easy for a human to read. In addition, from an application development standpoint it’s easy to write and parse. JSON is typically preferable to XML if you have a choice. Since the format of JSON is close to what you find with JavaScript objects it requires less translation than XML and has been clocked at as much as 100 times faster than XML in a browser environment (Dojo: The Definitive Guide). To see an example JSON file please click here.
ItemFileReadStore
Dojo uses the ItemFileReadStore and ItemFileWriteStore data stores to work with JSON format data. ItemFileReadStore implements the Read and Identity APIs and is used to read JSON data while ItemFileWriteStore is used to write JSON format data and implements all four of the Data APIs. We’ll be discussing ItemFileReadStore in this post.
ItemFileReadStore is the specific data store implementation for reading JSON data. In addition to implementing the Read and Identity APIs, ItemFileReadStore also contains additional implementation features including a specific data format, query syntax, means for deserializing attribute values, identifiers for items, and others. Now let’s look at an example of the data format expected by ItemFileReadStore.
ItemFileReadStore requires that JSON data follow a specific structure which is outlined via a code example shown in the figure below.
The identifier property points to the identifier attribute in items. An optional label property points to the label attribute. Finally, the data itself comes in items, which is an array of attribute/value pairs. The test data shown in the example was taken from a JSON file containing wildfire information. Ultimately each of these wildfires is plotted to our sample Google Maps application as a marker. Each wildfire is given a unique numeric identifier and the label is simply the latitude and longitude coordinates combined. The items are a collection of attribute/value pairs listing information about the specific fire including the coordinates, date, time, satellite that identified the fire, and the confidence value.
Creating ItemFileReadStore
Instances of ItemFileReadStore can be created in your code either declaratively or programmatically. In either case, the end result is the same in terms of what the user sees. Declarative creation is easily accomplished through the use of dojoType as seen in the code below. The ‘url’ attribute is used to point to the location of your JSON format file. Here it is assumed that the file is located in the same folder as your application, but this could also be a fully qualified url. You will also want to assign an ID to the instance so that it can be referred to later in your application.
Programmatic creation of ItemFileReadStore is accomplished using a constructor as seen below. Here we are passing in the url to our file. The end result is a new instance of ItemFileReadStore which is referenced by the variable itmFileReadStore.
Applying a Query
You can apply a query to an instance of ItemFileReadStore to create a subset of the data returned by ItemFileReadStore. The Fetch() method can be used to execute a query against the data store. The query should take the format you see in the figure below where the word ‘query’ is followed by a colon and then the query attributes inside curly brackets.
You can also specify additional queryOptions of ignoreCase and deep. In addition to providing the ability to query a data store, the Fetch method also provides a number of callback for handling the return events.
ItemFileReadStore.Fetch provides the ability to query the data store similar to a SELECT statement in SQL. To apply an ‘AND’ condition to the query you simply separate the items with a comma which serves as an implied ‘AND’. In the code example below we are querying for all items with a satellite value of ‘T’ AND a date of ‘03312009’.
As I mentioned earlier this is only a semi-standard version of SQL so you can’t use OR, NOT, set operations, numerical comparison operators, or joins. You are pretty much limited to ‘AND’ conditions supported by wildcard operators. The wildcard operators include an asterisk for matching multiple characters and a question mark for matching a single character. Furthermore, you can also use the ‘ignoreCase’ and ‘deep’ queryOptions. By default both options are set to ‘false’. Ignore case is self descriptive so I won’t go into detail on this other than to say that setting this value to ‘true’ will ignore upper and lower case characters that match the query. The ‘deep’ option triggers a query of all items and child items instead of only items at the root level.
Callback Functions
Fetch also provides the ability to call a handful of callback functions in response to various events. The syntax for each event handler is the name of the handler followed by a colon and then the name of the function that should execute in response to the event. The four event handlers include onBegin, onComplete, onError, and onItem. Most of these handlers are self descriptive, but the onItem event requires further explanation. The onItem handler is fired once for each item returned by the query. This is typically specified when you need to explicitly perform some type of operation on each item that is returned. Perhaps you’d like to do some additional filtering or attach a custom attribute to the item depending upon the value. Each event handler is just a specific JavaScript function run in response to the event. The code examples below provide more details on the callback function that are available.
Search by Identifier
As you’ll recall from earlier in the discussion an ItemFileReadStore object implements the Identity API as well as the Read API. The Identity API provides for the implementation of a fetch by an identifier through the fetchItemByIdentity method. The identifier is a unique value and the fetchItemByIdentity method can search through your JSON file or stream for a specific value. There are two event handlers that can be used to process the item or handle any errors. onItem is used to process the returned item while onError is used to process errors. This process is described in the figure below.
More Information
For more information on the Dojo Data API you may wish to consider our “Mastering the ArcGIS Server JavaScript API” course which covers this topic among many others. Our August 3rd – September 11th session is SOLD OUT. However, our next session begins October 5th and ends November 13th.