Adding a task

This example provides details on how to implement a task. The query task is used, which shows tabular results but does not include a map. [Show me]

The following is the HTML page in its entirety:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <title>State Info</title>
    <link rel="stylesheet" type="text/css" href="http://serverapi.arcgisonline.com/jsapi/arcgis/1.6/js/dojo/dijit/themes/tundra/tundra.css">
    <script type="text/javascript" src="http://serverapi.arcgisonline.com/jsapi/arcgis/?v=1.6"></script>
    <script type="text/javascript">
      dojo.require("esri.tasks.query");

      var myQueryTask, myQuery;

      function init() {
        //build query
        myQueryTask = new
esri.tasks.QueryTask("http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Demographics/ESRI_Census_USA/MapServer/5");

        //build query filter
        myQuery = new esri.tasks.Query();
        myQuery.returnGeometry = false;
        myQuery.outFields = ["STATE_NAME","POP2007","MALES","FEMALES"];
      }

      function execute(stateName) {
        myQuery.text = stateName;
        //execute query
        myQueryTask.execute(myQuery,showResults);
      }

      function showResults(myFeatureSet) {
        var s = "";
        for (var i=0, il=myFeatureSet.features.length; i<il; i++) {
          var featureAttributes = myFeatureSet.features[i].attributes;
          for (att in featureAttributes) {
            s = s + "<strong>" + att + ": </strong>" +
			featureAttributes[att] + "<br />";
          }
        }
        dojo.byId("info").innerHTML = s;
      }

      dojo.addOnLoad(init);
    </script>
  </head>
  <body>
    <form action="">
      US state name :
      <input type="text" id="stateName" value="California" />
      <input type="button" value="Get Details"
onclick="execute(dojo.byId('stateName').value);" />
    </form>
    <br />
    <br />
    <div id="info" class="tundra" style="padding:5px; margin:5px; background-color:#eee;">
    </div>
  </body>
</html>

The following discussion assumes you are already familiar with the basic concepts of the JavaScript API and Dojo, and you understand the basic patterns of how the JavaScript API works within an HTML page. For more information, see Adding a map.

Scripts inside HTML HEAD

The scripts section inside HTML HEAD is where you write your functions that call the JavaScript API.

    <script type="text/javascript" language="Javascript">

Reference the packages.

Since you are implementing a task, you need to reference the tasks package using dojo.require(). In this example, the "esri.tasks.query" package is referenced. For more information on what packages can be referenced, see About Dojo.

      dojo.require("esri.tasks.query");

Create the init() function.

The init() function is where the query is built. First, a QueryTask named myQueryTask is initialized using the QueryTask constructor.

The value "esri.tasks.QueryTask" is the full reference to the QueryTask class. Class names are always capitalized.
The URL you see is the endpoint for a MapServer service named "USA". The query layer is layer "5", which references a states layer. This endpoint is a unique reference that you can generate using Services Directory.

      function init() {
        myQueryTask = new
esri.tasks.QueryTask("http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Demographics/ESRI_Census_USA/MapServer/5");

Next, you need to build the query filter.

A Query named myQuery is initialized using the Query constructor. This constructor does not include any parameters.
Depending on your application, you may want to have the geometry returned for each feature. If you do not want the geometry, you must set the property "returnGeometry" to false.
You need to include which fields you want displayed in the results using the property "outFields". This list must use the actual field names rather than the alias names. You can display the field aliases in the results.

        //build query filter
        myQuery = new esri.tasks.Query();
        myQuery.returnGeometry = false;
        myQuery.outFields = ["STATE_NAME","POP2007","MALES","FEMALES"];
      }

Create a callback function.

The callback function is the function referenced from the input in the HTML page. In this example, a function named "execute" is called after a user types in a state name and clicks the "Get Results" button.

The state name is used as input text for the search. The property Query.text is short hand for a where clause using "like". This search is done only on the display field associated with the layer. This display field can be set in ArcMap document. If no display field is set, the default display field is the first text field. You can determine what the display field is for a layer in Services Directory.
Execute the query. You do this through the QueryTask.execute method. The inputs to the method are the Query and a reference to a function named "showResults".

      function execute(stateName) {
        myQuery.text = stateName;
        //execute query
        myQueryTask.execute(myQuery,showResults);
      }

Create a function to show the results.

The showResults() function first parses the results based on the information received when the QueryTask was executed in the callback function. The results are passed into the showResults function in "myFeatureSet", which is a FeatureSet object. A FeatureSet contains an array of Graphic features.

      function showResults(myFeatureSet) {

In the next section of this function, the variable "s" is populated with the field names and the field values contained in "myFeatureSet".

The outer for loop is repeated for each feature in "myFeatureSet". In this example, since only one state is processed, "myFeatureSet" contains only one Graphic, and the for loop is repeated only once.
The variable "featureAttributes" is assigned the attributes for the Graphic in "myFeatureSet".
The inner for loop is repeated for each attribute in "featureAttributes". The field name and the field value are assigned to "s".

        var s = "";
        for (var i=0, il=myFeatureSet.features.length; i<il; i++) {
          var featureAttributes = myFeatureSet.features[i].attributes;
          for (att in featureAttributes) {
            s = s + "<strong>" + att + ": </strong>" +
			featureAttributes[att] + "<br />";
          }
        }

The next step in this function is to assign the value of "s" as innerHTML, which allows text on an HTML page to be replaced with new text. In this example, dojo.byId is used, which is similar to the document.getElementById(id) JavaScript function. This function searches and returns the first HTML element with the argument ID of "info". In this case, the text is written inside the HTML DIV with id="info".

        dojo.byId("info").innerHTML = s;
      }

Specify the addOnLoad event.

As with all HTML pages using the JavaScript API, you must specify the Dojo addOnLoad event. The parameter it takes is "init", which represents what takes place in the init() function. The final step is to include the closing script tag.

      dojo.addOnLoad(init);
    </script>

HTML BODY

The next section is the BODY section of the HTML page.

The first input provides a text box for a user to type in a state name. The default value is "California".
The second input is a button. When a user clicks the button, the onclick event is invoked and calls the execute() function. The "stateName" reference in dojo.byId is the same "stateName" referenced as the ID of the first input. The value is the state name typed in by the user.
The DIV id "info" references the same variable set in the showResults() function.

  <body>
    <form action="">
      US state name :
      <input type="text" id="stateName" value="California" />
      <input type="button" value="Get Details"
onclick="execute(dojo.byId('stateName').value);" />
    </form>
    <br />
    <br />
    <div id="info" class="tundra" style="padding:5px; margin:5px; background-color:#eee;">
    </div>
  </body>