JSViewerDevelopersGuide

Updated: 1/13/2009 Page 1 Developer’s Guide Create GeoWeb Application with the Sample JavaScript Viewer Author Simon Biickert, Moxie Zhang Group Corporate Sales, ESRI, Inc File JSViewerDevelopersGuide.pdf Last Revised January 13, 2009 Status Public Release Updated: 1/13/2009 Page 2 Table of Contents 1 Introduction ..........................................................................................................................4 1.1 Prerequisites .................................................................................................................4 1.1.1 Skill and Software......................................................................................................4 1.1.2 Obtain Source Code and Libraries ............................................................................5 2 Sample JavaScript Viewer Architecture.............................................................................5 2.1 Overview .......................................................................................................................5 2.2 Sample JavaScript Viewer Lifecycle .............................................................................6 2.3 Sample JavaScript Viewer Application..........................................................................7 2.3.1 Understand Widget and Widget Programming Model ...............................................8 2.4 Widget Naming Convention.........................................................................................11 3 JavaScript Viewer Setup for Development ......................................................................12 3.1 Unzip the source distribution .......................................................................................12 3.2 Edit config.xml .............................................................................................................13 3.3 Configure Widgets.......................................................................................................13 3.4 Configure Proxy Support .............................................................................................14 4 Develop a Widget for Sample JavaScript Viewer ............................................................17 4.1 Create the Dojo Module ..............................................................................................17 4.2 Create the files for the Widget.....................................................................................19 4.3 Extend the _BaseWidget class....................................................................................20 4.4 Define the Widget’s template (user interface) .............................................................21 4.5 Make it configurable ....................................................................................................23 4.6 Add i18n support .........................................................................................................25 4.7 Access a Map..............................................................................................................28 4.8 Display Widget Graphic Data on Map .........................................................................31 4.9 Receive Data from Map (draw tool).............................................................................32 4.10 Control Navigation from a Widget ...............................................................................34 4.11 Retrieve information via a proxy..................................................................................35 5 The Sample JavaScript Viewer Core Code ......................................................................37 5.1 Dojo Publish and Subscribe ........................................................................................37 5.1.1 JavaScript Viewer Subscription List ........................................................................38 5.2 Dependency Injection..................................................................................................40 Updated: 1/13/2009 Page 3 5.3 Logging and Error Handling ........................................................................................42 5.3.1 djConfig.isDebug .....................................................................................................42 5.3.2 Console ...................................................................................................................43 Updated: 1/13/2009 Page 4 1 Introduction This document is for developers who intend to utilize the Sample JavaScript Viewer to develop ArcGIS JavaScript API based applications. 1.1 Prerequisites 1.1.1 Skill and Software The developers who develop Sample JavaScript Viewer based application should have sufficient knowledge and experience using HTML and JavaScript to develop Rich Internet Applications. The base platform for the ArcGIS JavaScript API and by extension the JavaScript Viewer is Dojo (http://www.dojotoolkit.org). At the time of this writing, the current version of Dojo used by the ArcGIS JavaScript API is 1.1. The JavaScript Viewer has an object-oriented JavaScript programming model which takes advantage of the strengths of JavaScript and Dojo, and avoids poor practices. To get the best head start in Widget development, we recommend the following programming texts: • Dojo: The Definitive Guide, 2008. Russell, O’Reilly Books. ISBN 978-0596516482. • JavaScript: The Good Parts, 2008. Crockford, O’Reilly Books. ISBN 978-0596517748. In addition, to develop a Widget with geo spatial features, a level of familiarity with using the ArcGIS JavaScript API is recommended, or at least familiarity with the samples provided by ESRI. The only required software is a programmer’s text editor, a standards-compliant web browser and an Internet connection. However, the JavaScript Viewer development team recommends: † Aptana Studio IDE (Free version), Visual Studio 2008 or TextMate † Firefox 3 with the Firebug plugin † Tortoise SVN (for source code control, optional) Updated: 1/13/2009 Page 5 1.1.2 Obtain Source Code and Libraries The source code release package will be distributed in a zip file and posted in the Code Gallery of ArcGIS JavaScript API. The release package is named by the Code Gallery as AS15905.zip, for example. The zip file contains a folder, JSViewer, where all the source files, images and documents will be included. The ArcGIS JavaScript API is dynamically downloaded from http://serverapi.arcgisonline.com at runtime. As HTML and JavaScript is a dynamically interpreted environment, there is no “compiled” version of the JavaScript Viewer1. For a local installation of the ArcGIS JavaScript API, the URLs in index.html would need to be adjusted to point to the internal server which is hosting the API. URLs which include “http://serverapi.arcgisonline.com/jsapi” would need to be changed to point to the local server. 2 Sample JavaScript Viewer Architecture 2.1 Overview The Sample JavaScript Viewer is architected to help develop and deploy GeoWeb focused applications that can fully leverage the power of the server side spatial services such as those provided by ArcGIS Server and ArcGIS Online. A Sample JavaScript Viewer application provides users a simple way to access geospatial services. As illustrated below, a geospatial service could come from the hosted SaaS type of provider such as ArcGIS Online, ArcGIS Server or web data sources such as GeoRSS feeds, KML files, JSON/REST data, etc. The data consumed within the Sample JavaScript Viewer application could be the data set at servers or could be generated from mobile devices such as field engineers’ laptops or smart phones. 1 The Dojo Toolkit has a build system which allows the application developer to create a compact, efficient version of the application. These tools are available at http://dojotoolkit.org and are recommended when putting applications into production. Updated: 1/13/2009 Page 6 The Sample JavaScript Viewer is designed to be able to participate into the full spectrum of the geospatial service implementation architecture with the focus on simplicity and flexibility. ArcGIS Online ArcGIS Servers Menu Control Sample Viewer Laptop Mobile Handheld Mobile Other Services and Feeds 2.2 Sample JavaScript Viewer Lifecycle A JavaScript Viewer application goes through a simple lifecycle from starting the application to the user interacting with Widgets. The five major events during the lifecycle are: 1. ArcGIS JavaScript API (Dojo) is loaded in the HTML page and the page is parsed and the onLoad event fires. 2. The JavaScript Viewer application loads the configuration XML file and applies it. 3. Based on the configuration file, the application loads the map layers from map servers such as ArcGIS Online or ArcGIS 9.3 servers. The application also constructs and displays the menu controller with branding information from the config XML file. 4. The Widget manager loads the Widget class files which are specified in the config XML file. Updated: 1/13/2009 Page 7 5. The users interact with the Widgets that conduct business logic. Menu ControlMenu Control Services and Data Feeds 1 2 4 5 Map Services Config.xml JS JSJSJSJS Widget Class JS Files ArcGIS API (Dojo) Viewer HTML 3 2.3 Sample JavaScript Viewer Application The Sample JavaScript Viewer application takes the programming complexity of managing maps, map navigation, application configuration, inter-component communication, data management, etc. out of developers’ hands. It allows the Web developers, especially the developers who are working with ESRI ArcGIS technologies, focus their time and efforts on implementing the core business functions. In addition, the result of the business focused rapid Updated: 1/13/2009 Page 8 development, which is in the form of widgets, can be quickly deployed to existing JavaScript Viewer applications by simply adding configuration entry into the JavaScript Viewer application’s configuration file. The following screenshot demonstrates a typical JavaScript Viewer application container. 2.3.1 Understand Widget and Widget Programming Model A Widget of the ArcGIS JavaScript Viewer for JavaScript is a set of text files that can be shared, moved and deployed to a JavaScript Viewer application. Generally, a developer might plan to Updated: 1/13/2009 Page 9 develop one or more Widgets and would package them in a Dojo module. A Widget can be as simple as a single JavaScript file. The above structure represents a fully- fleshed Widget that has its own icon, template, configuration file and internationalization support. It will be explained in more detail in later sections during the walkthrough of developing a Widget. Typically, a Widget encapsulates a set of isolate and focused business logic that allows users conduct a task with it. In a service oriented environment, a Widget represents a service or an orchestration of services that users can clearly execute a business function. A Widget is not only visually interactive with user, but also could connect to server side resources such as Map Services from ArcGIS server or ArcGIS online. A set of correlated Widgets plus a clearly define business workflow applicable to these Widgets can form a business solution. The solution, furthermore, can be deployed to participate in an enterprise-wide business process. Updated: 1/13/2009 Page 10 The lightweight Widget programming model that comes with the JavaScript Viewer allows developers easily develop their Widgets without handling low level detail mechanism of coding to integrate the Widgets into the JavaScript Viewer application. The Widget programming model contains four JavaScript classes. They are all in the com.esri.solutions.jsviewer module, but for brevity will be referred to only by their class name. Here are the short descriptions. The later sections will cover the details of how they are used. _Widget2 Class (_Widget.js) This interface defines the communicational methods that will be used by the WidgetManager to manage the Widgets. Extends the dijit._Widget, dijit._Templated, dijit._Container and dijit._Contained classes. _BaseWidget Dijit (_BaseWidget.js) This is the base Widget class that all Widgets should be derived from. By extending the _BaseWidget class, a new JavaScript class will be recognized by the JavaScript Viewer’s WidgetManager as a deployable Widget. In addition, extending the base Widget provides the prospective subclass with various low-level functions such as: • Managing multiple panels and icons for those panels • Interacting with the WidgetFrame • Loading config data (XML, JSON or plain text) • Querying child dijits The _BaseWidget can be instantiated for demonstration purposes, but it is not intended to be used in that fashion. A JavaScript Viewer Widget must extend the _BaseWidget class. _MapGraphicsMaintainer Class (_MapGraphicsMaintainer.js) This class is a mixin3 class for Widgets which need to add graphics to the map. It defines the common operations of adding graphics to and clearing those graphics from the map. 2 The underscore character “_” at the beginning of a Dojo classname indicates an abstract class which should be subclassed, not instantiated directly. Updated: 1/13/2009 Page 11 WidgetFrame Dijit (WidgetFrame.js) This is the UI class which represents the frames in which Widgets reside in the container application. The WidgetFrame is a container dijit, and performs the dynamic resizing, minimizing and other window management code. As a Widget developer, the exact functioning of the WidgetFrame is not important, beyond an understanding of how the developer’s Widget will arrive in the page and how the HTML template for the Widget will be nested in the page DOM. 2.4 Widget Naming Convention Widget class: Recommend that a widget class has suffix “Widget”, for example, SomethingWidget.js. Widget Configuration File: Recommend that use the same name as Widget class except with an xml or json extension, for example, SomethingWidget.json. Widget I18N File(s): Recommend that use the same name as Widget class except with “Strings” appended, for example, SomethingWidgetStrings.js. Widget template: Recommend that it use the same name as the Widget class except with an html extension, for example, SomethingWidget.html. 3 Dojo classes are multiple-inheritance. Mixin classes add functionality to their subclasses, but are not meant to be sole parent classes. Updated: 1/13/2009 Page 12 3 JavaScript Viewer Setup for Development This chapter covers much of the same information as in the README.txt file which can be found in the JSViewer directory you extracted from the JavaScript Viewer ZIP file. This chapter will go into more detail and show how to correctly establish a new module to contain the new Widget. Note: Since there is no “compile” step with HTML and JavaScript, there is no discussion of “building” the JavaScript Viewer for deployment. As with any JavaScript, the source can be “minified” to reduce download and parsing time. The JavaScript Viewer is delivered non- minimized. 3.1 Unzip the source distribution The zip file, AS15095.zip (named by Code Gallery, the number will be different), contains the root folder JSViewer. The name of this folder is not important; it can be renamed at will. For clarity, this document will refer to this folder as JSViewer. Copy this folder to the documents directory of your web server. As shown on the screenshot, the JavaScript Viewer was unzipped to d:\www. On this particular system, that translates to a URL of http://server/JSViewer. The path and URL will depend on your server. Updated: 1/13/2009 Page 13 The JavaScript Viewer can be deployed to Apache, IIS, or a Java application server such as Tomcat. This document assumes that one of these platforms is available and that it is configured correctly. At this point, the JavaScript Viewer is capable of being accessed. It is not fully configured, but it can be tested. Access the URL of the JavaScript Viewer in a web browser to check. 3.2 Edit config.xml In the JSViewer directory, there is an XML file named config.xml. This is the primary configuration point for the JavaScript Viewer. Open it in a plain text editor and modify it as per the information in README.txt. Many URLs in config.xml are relative to the Dojo module. Opening config.xml, you will note many attributes such as: • icon=”assets/images/icons/i_about.png” • config=”widgets/config/AboutWidget.xml” These are partial URLs which allow the JavaScript Viewer to find a file within a Dojo module. In the case of the config file above, on the sample test server the full URL to that file is: http://server/JSViewer/js/com/esri/solutions/jsviewer/widgets/config/AboutWidget.xml • The black part of the URL is where the JavaScript Viewer is installed. • The blue part of the URL is where the JavaScript Viewer Dojo package is located. • The red part of the URL is the part of the URL which is relative to the package. This allows the JavaScript Viewer to be relocated without having to reconfigure it, as well as saving a lot of typing out the module location. 3.3 Configure Widgets As provided, the JavaScript Viewer has several configured Widgets. These Widgets are all configured with general purpose, publicly available services. Refer to README.txt for a discussion of the configuration options for all of the provided Widgets. Updated: 1/13/2009 Page 14 The format of the configuration file for individual Widgets is up to the developer. For the Sample Flex Viewer, the best practice is to use XML configuration. Widgets built for the JavaScript Viewer may use either XML or JSON formatted config files. JSON formatted text is very efficiently and simply interpreted in JavaScript. It is recommended that 3rd party Widgets use JSON for Widget configuration. For a brief description of JSON: http://en.wikipedia.org/wiki/JSON. 3.4 Configure Proxy Support As part of setting up the config.xml file, the element needed to have its value set to one of “apache”, “php”, “asp” or “jsp”. Some information on which to choose is in README.txt, but what follows is a more technical discussion of what this setting means. As new types of AJAX-model web applications are being developed, there is a balance to be struck between security and functionality. The browser is an inherently insecure platform, and the browser developers attempt to fix this in different ways. One of the risks of the web platform is called a Cross Site Scripting (XSS) attack. XSS involves malicious JavaScript code being downloaded from a supposedly safe site, which when executed downloads additional code from a separate, malicious site. To guard against this type of a security breach, web browsers do not allow JavaScript to download any additional scripts or data from a server other than the one it was downloaded from itself. Updated: 1/13/2009 Page 15 Nevertheless, there are