Building a JavaScript application from an ArcGIS.com template

Building a JavaScript application from an ArcGIS.com template: "

With all the buzz about the ArcGIS Viewer for Flex, we're often asked if our team has built a similar viewer application using the ArcGIS API for JavaScript. The answer is no (although you may have spotted an unofficial 1.x-based sample in the user community code gallery). In this post we'll walk through the process of creating a professional-looking, versatile Web application with the ArcGIS API for JavaScript.

1. Create a map using the ArcGIS.com viewer and select a Web application template
   
2. Download the template and personalize the layout
3. Add widgets to customize the application

In this post, we'll walk you through the process.

1. Create a map using the ArcGIS.com viewer and select a Web application template

ArcGIS.com and the ArcGIS.com viewer make it easier than ever to create, edit and share maps. You can build a map using the viewer, then embed the map in an existing site or one of the provided templates. The templates are a new feature that allow you to make a basic Web application out of your map without writing any code. We plan on adding more color schemes and layouts in future templates.

To start this post, we'll assume that you've made a map in ArcGIS.com, you've saved the map, and you've picked out a template for your application. View this post on the ArcGIS Online Blog if you need steps for accessing the template gallery.

2. Download the template and personalize the layout

Once you've found a template that you like, click the download link and follow the instructions to install and configure the template. In this post we are going to customize the Chrome template, so choose that template from the gallery if you'd like to follow along.

Each template comes with a readme file that provides instructions on how to perform common customizations like adding a company logo and modifying the layout text. A critical step explained in the readme file is how to put your map ID in the template, so that your Web application 'knows' which map from ArcGIS.com that it needs to display. With the expectation that you've wired up the map ID to your template, we'll move on to personalizing the template by modifying the text color.

Update the text and background colors

The downloaded template includes all the images and style rules used to define the application look and feel. The style rules are included in a CSS file and define how elements in the Web page like links, borders, headers etc. appear.

Open the css/layout.css file in your favorite text editor and look for the title rule. The color property defines the text color for the application's title using a hex color value. Using a Web site like colorcombos.com find a new color for the title text. Here we've picked a dark green color:

#title {    

 color: #595F23;  

        font-size: 30px;

        text-align: left;

       font-weight: bolder;

}

If you like, modify some of the other properties such as font-size and font-weight, then save the file and view index.html in a browser to view the changes.

Another quick change we can make is to modify the background color of the left content panel. In the CSS file, replace the background-color for the leftPane section with a new color. Here we used a pale green:

#leftPane {  

  background-color: #a2b964;

}

W3 schools has a great tutorial on getting started with CSS if you'd like to learn more.

3. Add widgets to customize the application

The JavaScript API at 2.0 includes several new widgets for things that would otherwise require extensive coding and UI design. These include the OverviewMap, Editor, BasemapGallery, Legend and TimeSlider. You can add widgets to the sample layouts to really start adding to the functionality of your template. Take a look at the Seaside with legend template for an example.

Widgets simplify the process of adding advanced functionality to your application. Many of the API samples show how to work with the widgets to create time-aware applications, view and edit attributes, add attachments, create advanced editing applications, and more.

Add the BasemapGallery widget

The BasemapGallery widget displays a collection of basemaps—for example streets, topography, and imagery—that users can select from to provide context to their maps. To incorporate the BasemapGallery widget into the template, we'll have to modify the javascript and html files.

Open the javascript/layout.js file in your favorite text editor. At the top of the file, import the BasemapGallery by adding the following line of code.

  dojo.require('esri.dijit.BasemapGallery');

Next, paste the following function at the bottom of the layout.js file. This code creates a new BasemapGallery to display a set of basemaps from ArcGIS.com.

function createBasemapGallery() {

  var basemapGallery = new esri.dijit.BasemapGallery({

    showArcGISBasemaps: true,   

     map: map  

}, 'basemapGallery');

  basemapGallery.startup(); 

   dojo.connect(basemapGallery, 'onError', function(msg) {console.log(msg)});

}

Next, add this line of code createBasemapGallery(); to the application just below the addScalebar() line. Note that you'll need to add this twice. See the bold sections below.

if (map.loaded) { 

  addScalebar(); 

  createBasemapGallery();

} 

else {

 dojo.connect(map, 'onLoad', function() {  

 addScalebar(); 

  createBasemapGallery();

});

Now you're ready to position the BasemapGallery widget on the page. You can position the widget so that it sits on top of the map using a dijit TitlePane. The TitlePane is a panel that displays a title and allows you to open or collapse the pane's content.

Open the index.html file in a text editor and add a reference to the dijit.TitlePane to the dojo.require section.

  dojo.require('dijit.TitlePane');

Next add the bold content below to the 'Map Section' to position the TitlePane and BasemapGallery on the map.

<!-- Map Section -->

<div id="map" dojotype="dijit.layout.ContentPane" region="center">

<div style="position:absolute; right:30px; top:10px; z-Index:999;">

  <div dojoType="dijit.TitlePane" title="Switch Basemap" closable="false"  open="false">

  <div dojoType="dijit.layout.ContentPane" style="width:380px; height:280px; overflow:auto;">  

 <div id="basemapGallery"></div> </div></div></div> 

 </div>

Open the index.html file in a browser and view your customizations. Here's an example of how your application might look.
"