Creating a simple map dijit with the ArcGIS JavaScript API

Dojo Widgets or dijits are a great way to build web application UI components that either combine other components or bind data with business logic. Dijits are designed to be easy for users embed within their web applications.

In this post we’ll create a dijit that could allow a large city to share its mapping data with its citizens and allow businesses to integrate other functionality.

The Basics

When creating a dijit or a collection of dijits, it’s recommended that you use a specific folder structure. Each dijit requires a template, some cascading style sheets (CSS) and some images. Correspondingly, there are the templates, css and images folders. It is up to you whether to create these folders for each dijit or share these among several dijits.

The Template

All dijits start off with a layout that puts together the visual components. This dijit will contain a <div> for the map, a <span> with 2 buttons for toggling data layers and finally an <img> with the city seal. Clicking on the image opens a new window and navigates to the city’s home page.

You can optionally use CSS to style the visual components. In this case, since the toggle buttons and image are map overlays, we’ll apply CSS styling appropriately.

templates/MyFirstMapDijit.html

<div class="mapdijit">
  <span class="layerbuttons">
    <button dojoType="dijit.form.ToggleButton" dojoAttachEvent="onXXX:callback" ID="Button1">Neighborhoods</button>
    <button ... checked ID="Button2">Landbase</button>
  </span>
  <img src="..." class="seal" dojoattachevent="onclick:gotoCityOfPortland" />
</div>

It’s important to note the dojoType, dojoAttachEvent, and dojoattacheevent attributes:

• You will need to specify the dojoType attribute in order to allow the Dojo parser system to parse and apply rendering for appropriate dijits. This attribute value matches the name of a dijit class.
• The dojoAttachEvent attribute connects a specific event onXXX on the dijit and calls the specified callback function.
• The dojoattachevent attribute connects a specific event, say onclick on the HTML element and calls the specified function gotoCityOfPortland.

The Stylesheet

A CSS file is used to style the look and feel of the dijit. A user can potentially change the CSS to change the look and feel of this dijit.

css/MyFirstMapDijit.css

.mapdijit { position:relative; }
.mapdijit .layerbuttons { ...; z-index:100; ... }
.mapdijit .seal { ...; z-index:100; }

The CSS classes are referenced in the class attribute in the template markup. One thing to note is the z-index attribute on all map overlays. It is recommended that you use a z-index of 100 or higher when an element needs to display on top of a map.

The Dijit Class

Each dijit is backed by a JavaScript class which defines the behavior of the dijit. We’ll add the ability to add/toggle data layers and the additional behavior of opening the city's home page when a user clicks on the seal.

As part of the lifecycle of the dijit, at the last step at startup, we will initialize the map once all the HTML elements have been laid down and presented to the client.

MyFirstMapDijit.js

dojo.provide(...);

//include all dijit dependecies
dojo.require(...);

//declare new dijit class
dojo.declare("mydijits.MyFirstMapDijit", [dijit._Widget, dijit._Templated], {
    //dijit template contains other dijits
    widgetsInTemplate: true,

    //path to template
    templatePath: ...,

    //dijit startup method to initialize map
    startup: function() { ... },

    //behavioral functions
    toggleLandbase: function(visibility) { ... },
    toggleNeighborhoods: function(visibility) { ... },
    _toggleLayer: function(layer, visibility) { ... },
    gotoCityOfPortland: function() { ... }
  }
);

The toggle* and gotoCityOfPortland functions provide the desired custom functionality. The esri.Map is instantiated within the startup function. The widgetsInTemplate property specifies that the template contains other dijits. The templatePath specifies the path to the template file for the dijit. If the template is very simple, you can alternatively use the templateString property and provide the markup in this string and not create a template file.

Note: Specifying a template string reduces the number of server calls to fetch a template from a running application if a web page contains several different dijits.

Testing the Dijit

That's it! You are now ready to share this dijit with your users. To test it out, we’ll add the dijit to a blank page and verify that it works.

MyFirstMapDijitTest.html

 
  <head>
    ...
    <title>MyFirstMapDijit Test</title> 
    <!-- include dojo theme -->
    <link href=".../tundra.css">

    <!-- include dijit css -->
    <link href=".../MyFirstMapDijit.css">
    <!-- specify dojo configuration -->
    <script ...>djConfig = { ... }</script>
    <!-- reference ArcGIS JavaScript API -->
    <script ...></script>

    <!-- reference newly created dijit -->
    <script ...></script>

  </head>
  <body class="tundra">
    <!-- create markup -->
    <div dojoType="mydijits.MyFirstMapDijit" ...></div>
  </body>

Wrapup

You’ve just put together your first mapping dijit using the ArcGIS JavaScript API. In subsequent posts, we’ll show how to add other dijits, that analyze data on the map and others which encapsulate data and behavior that you can easily add to a website.

Download the example from the Code Gallery

Try the live example

Related links

• ArcGIS JavaScript API
• Dojo
• Dojo book: Writing Your Own Widget Class
• The Mojo of Dojo (Creating Your Own Widgets)
• Dissecting Dijit

Contributed by Jayant Sai of the ArcGIS JavaScript API development team.