EXTENDING AN AXL FILE

(Slightly adapted from Exercise 2B in "Customizing ArcIMS using ArcXML - ESRI Training Manual)

Step 1 - Set up a website

Copy the n:\int_gis_map\labs\Exercise02\NA_Exer2B.axl into your workspace.  Create an image service called NA_Exer2B using ArcIMS Administrator that references this AXL file.  Then create a basic website - call the folder NA_Exer2B and give the website a title of "Interactive Map of North America."  Let me know if you have problems.

Cooktop 2.5, an XML editor is installed on all machines. If it is not, go to C:\Student\CAXL\Software and double click on the Cooktop Windows installer package to install the software.

Open Cooktop 2.5  First, you want to register .axl as a recognized file extension for ArcIMS.

• in Cooktop click All Options.

• From the left panel of the Global Options dialog, click Extensions.

• Under Extensions click xml files.
  
  On the right panel, under Extensions, you will see the list of extensions recognized by the XML Editor. If .axl is already there, close it down.

• If .axl is not in the list, under New Extension, type .axl and click Add.

• Click OK to close the Global Options dialog.

• Browse to the AXL file you just copied into your workspace and open it in Cooktop.
  
  When the file is opened a default text coloring scheme is applied to the document for easy identification.  Blue represents the ArcXML element and attributes, green symbolizes the attribute values and gray indicates text comments.

• Explore Cooktop and become familiar with its menus and tools.
  
  Before you edit your map configuration file, you will first apply a Document Type Definition (DTD) to the XML Editor.  The ArcXML DTD defines the structure and rules of ArcXML and attributes.  By applying the DTD, the XML editor recognizes the ArcXML rules so it can help located errors and validate the document.  The DTD can be used with many XML editor but because ArcIMS requires UTF-8 encoding, editors that support this encoding are recommended.  Cooktop is freeware.
  
  To apply the DTD to your opened AXL file, a DOCTYPE statement pointing to the location of the DTD needs to be present.  In most XML editors the DOCTYPE statement is added to the top of the document.

• In your copy of NA_Exer2b.axl the DOCTYPE line is already there; it points to a DTD on the C drive of your machine.  Often, these pointers are to URI's on the web.
  
  Every time you make a manual edit to your map configuration file you can ask the editor to validate it against the DTD.

• Click the Validate button (looks like a check mark)
  
  There should be no errors reported.
  
  Another useful button is the Format button which helps you tidy up your lines of code after editing.  It indents all elements in hierarchical order to make it more readable.

• Click the Format button (one arrow going up and one going down)
  
  You can use the validate and format button many times during editing as a check on your work.  I saves a lot of time.

Open your cfd312xxx\website\NA_Exer2B viewer with Internet Explorer.

Step 2 - Change the Labels of the County Layer - You will change all the labels to uppercase; you cannot do this in ArcIMS Author.

• Open another instance of Internet Explorer, access and maximize the ArcXML Programmer's Reference Guide (at C:\Program Files\ArcGIS\ArcIMS\Documentation\ArcXML_Guide\ArcXML_reference.htm)
• Search for the TEXTSYMBOL element.  What attribute needs to be used to display all label characters as uppercase? Question 1_________________________________________-
• Bring the AXL file from your workspace with the XML editor and find the Counties layer comment line:
  <!--.****COUNTIES****-->
• Find the TEXTSYMBOL element inside the Counties layer block of code.
• Add the attribute from the answer to Question 1
• Maximize ArcIMS Administrator and refresh the NA_Exer2B service.
• Maximize Internet Explorer and refresh the website (Ctrl F5 + F5)
• Zoom in until you see the Counties layer.  All the labels should be uppercase.  Note:  Any time you alter the AXL file related to a service you must refresh the service.

Step 3 - Add Another Renderer to State Highway Roads.  Currently the Roads layers are displayed using unique symbols based on the highway types (State Highway, Interstate and US Highway).  You will manually add another symbol for State Highways.  ArcIMS Author has the capability to add multiple symbols but it will apply to all the features in a layer.  If you want to create multiple symbols for only a certain type/category you need to do it manually.

First, look at the existing symbol:

• In the NA_Exer2B viewer zoom to the state of Kentucky where you can see the three different highway symbols together.  Interstate Highways are a sandy brown with a blue and red symbol, the US federal highways are olive with a Federal highway symbol and state roads are dark brown with a white oval.  You are going to add white dashed lines on top of the existing brown solid color for the State Highway symbol.
• In the XML editor find the Roads layer comment line:
  <!----******************ADD ANOTHER RENDERER TO THE STATE HIGHWAY*****************-->
• From the ArcXML Programmer Reference Guide find VALUEMAPRENDERER.  It has one mandatory attributet, lookupstring.  Set that to "admn_class.
• Place an EXACT element as a child to the VALURMAPRENDERER element with value = "State Highway" and label = "State Highway".
• Place a SIMPLELINESYMBOL child element to EXACT with attributes type = "dash"  width = "2" and color = "255,255,255" to create a white dash symbol.
• Close the necessary elements
  
  Because there are two VALUEMAPRENDERER elements applied to the State Highway layer they cannot be displayed unless you group them using a GROUPRENDERER element.  Notice that there is already a GROUPRENDERER element but it is perfectly OK to have GROUPRENDERERs nesting inside each other.
• Add an opening GROUPRENDERER element right above the opening of the first VALURMAPRENDER element.
• Add a closing GROUPRENDERER element right after the closing of the second VALUEMAPRENDERER element.
  
  The position of the new GROUPRENDERER element should appear as follows:
  
  <GROUPRENDERER>
  <GROUPRENDERER>
  <VALUEMAPRENDERER lookupfield="ADMN_CLASS">
  <EXACT value="Interstate" label="Interstate">
  <SIMPLELINESYMBOL width="3" captype="round" color="247,150,90" />
  </EXACT>
  <EXACT value="State Highway" label="State Highway">
  <SIMPLELINESYMBOL width="3" captype="round" color="106,57,10" />
  </EXACT>
  <EXACT value="US Highway" label="US Highway">
  <SIMPLELINESYMBOL width="3" captype="round" color="123,123,9" />
  </EXACT>
  </VALUEMAPRENDERER>
  <!--***** ADD ANOTHER RENDERER TO THE STATE HIGHWAY ******-->
  <VALUEMAPRENDERER lookupfield = "admn_class">
  <EXACT value = "State Highway" label = "State Highway">
  <SIMPLELINESYMBOL width = "2" type = "dash" color = "255,255,255" />
  </EXACT>
  </VALUEMAPRENDERER>
  </GROUPRENDERER>
  <VALUEMAPLABELRENDERER lookupfield="ADMN_CLASS" labelfield="RTE_NUM1" linelabelposition="PlaceOnTop">
  <EXACT value="State Highway" label="State Highway">
  <SHIELDSYMBOL antialiasing="true" font="Arial" fontstyle="regular" fontsize="8" type="oval" minsize="2" />
  </EXACT>
  <EXACT value="Interstate" label="Interstate">
  <SHIELDSYMBOL antialiasing="true" font="Arial" fontstyle="regular" fontsize="8" fontcolor="255,255,255" type="interstate" minsize="2" />
  </EXACT>
  <EXACT value="US Highway" label="US Highway">
  <SHIELDSYMBOL antialiasing="true" font="Arial" fontstyle="regular" fontsize="8" type="usroad" minsize="2" />
  </EXACT>
  </VALUEMAPLABELRENDERER>
  </GROUPRENDERER>
• Save the changes to your AXL file.
• To see the changes, refresh your service and the NA_Exer2B viewer. 
• Zoom into the same area of Kentucky and you should see the State Highways displayed in a dark brown solid color and white dashed lines on the top.  If everything is correct, minimize Internet Explorer. If you see no changes, trace back your steps and fix your errors.

Step 4 - Change the Rendering of the Cities Layer

In this step you will symbolize the cities using a TrueType marker symbol inside the TRUETYPEMARKERSYMBOL element.  You will also label the cities using two different sets of labels, and their display will be controled by the scale of the map display.  You will use the SCALEDEPENDENTRENDERER element for this purpose.

• Maximize the ArcXML Programmer's Reference Guide and go to the TRUETYPEMARKERSYMBOL element.  Answer these questions:
  Question 2:  What is the required attribute of TRUETYPEMARKERSYMBOL?
  __________________________________________________________
  Question 3: What does this value of the required attribute correspond to?
  _________________________________________________________
  
  First, take a look at two JPEG images showing the results of the rendering changes your are about to make to the Cities Layer.
• Start Internet Explorer and from the File menu open FullExtentCities.jpg from C:\Student\CAXL\Exercise02.
  
  The image shows the Cities layer and labeling in a full extent display.  The city points are symbolized using a red donut TrueType marker symbol and all the cities are labeled using the same font and size.
• Start another Internet Explorer.
• From the File menu, open ZoomInCities.jpg from C:\Student\CAXL\Exercise02.
  
  This image shows the Cities symbol and labels after the map is zoomed in past the scale of 1:10,000,000.  Notice how the Cities symbol has changed, and the label size for each city is proportional to the population value of that city.
• Minimize both Internet Explorers.
• Maximize the XML editor  and the AXL file.
• Find the Cities layer comment line:
  <!---*******  CITIES *****-->
  Right now the Cities layer is rendered using the default solid circle marker symbol; you will change it to a TrueType markersymbol.
• Find the SIMPLERENDERER element
  
  <SIMPLERENDERER>
  <SIMPLEMARKERSYMBOL color="227,127,127" width="6" />
  </SIMPLERENDERER>
   
• Delete the line shown in bold above.
• Replace that line with the TRUETYPEMARKERSYMBOL element using the following attributes:
  font = "ESRI Cartography"
  character = "104"
  fontsize = "12"
  fontcolor = "255,0,0"
  
  Now you will add labels to the cities.  However, you will add labels only for those cities within the initial map extent (cities in the USA, Canada, Mexico and Cuba).  Displaying labels only on the current map display can help the performance of your service.  You will use the VALUEMAPRENDERER and EXACT elements for this purpose.
• Maximize th4e ArcXML Programmer's Reference Guide and answer the following questions:
  
  Question 4:  What is the difference between the labelfield and lookupfield attributes of the VALUEMAPLABELRENDERER element? ________________________________________________________
• Add the VALUEMAPRENDERER element directly under the closing of the </SIMPLERENDERER> element.  The value from the field NAME field will be used for labeling and the value from the COUNTRY field will be used to select the cities that will get labels.  Set the labelpriorities = "0,1,2,3,4,0,0,0" and featureweight = "high_weight" attributes.
  
  The labelpriorities attribute is used to set preferences for the location of labels that are located in relation to the feature.  There are eight positions around a point feature starting from the upper left and going clockwise.  You can assign the number 1 to the positions with the highest priority, 2 for the next most important position, and so on.  A value of 0 says a label cannot be placed at that location.
  
  1 2 3
  8 X 4
  7 6 5
  
  
  The featureweight attribute prioritizes the importance of features.  It determines how important the feature labeled is for the label placement algorithm. If "no_weight" is specified then the feature has no importance and can be labeled over.  If "high_weight" is specified, then the feature has high importance and cannot be labeled over.
  
  Question 5: For a labelpriorities attribute, what does the value of 0,2,1,3,4,0,0,0 represent? _____________________________________________________________________
• Add the EXACT child element to the VALUEMAPLABELRENDERER element with the attribute: value = "US;Mexico;Canada;Cuba"
• For defining the label characteristics, use the TEXTSYMBOL child element with the following attributes:
  
  font = "Arial"
  fontstyle = "Bold"
  fontsize = "9"
  glowing = "240,255,255"
  antialiasing = "true"
  interval = "12"
  
  Because you added both symbol and label renderers to the Cities layer, remember that they can only viewed together if you group them using the GROUPRENDERER element.
• Add the opening of the GROUPRENDERER element right above the opening of the SIMPLERENDERER element.
• Add the closing of the GROUPRENDERER element right after the closing of the VALUEMAPRENDERER element.
• Validate the document against the DTD and fix any errors
• Format the document
• Save the changes and minimize the XML editor
• To view the changes in the map display, refresh the NA_Exer2B service and the NA_Exer2B viewer.
  
  At the initial extent you should see the city points are symbolized using a red donut marker symbol and labeled using the city's name in black with a white background glowing color.  The display should be similar to the FullExtentCities.jpg image you opened earlier.
  
  Now you are going to apply the SCALEDEPENDENTRENDERER element to the Cities layer.  SCALEDEPENDENTRENDERER allows you to use more than one set of renderers for the same features at different scales.  You will add two SCALEDEPENDENTRENDERER elements, the first one for the Adobe TrueType marker symbol and label and the second the the Cities' new set of symbols and labels.
• Minimize Internet Explorer.
• Maximize the XML editor and make sure you are still in the Cities layer section.
• Right after the <DATASET> element and before the opening GROUPRENDERER element add the SCALEDEPENDENTRENDERER element with the lower attribute equal to "1:10000000" (10 million)
  
  Question 6:  What is the purpose of the lower attribute? ____________________________________________________________________
• Add the closing </SCALEDEPENDENTRENDERER> element after the closing element of the GROUPRENDERER.  The structure should look like this:
  
  <DATASET name="cities" type="point" workspace="shp_ws-0" />
  <SCALEDEPENDENTRENDERER lower = "1:10000000" >
      <GROUPRENDERER>
              <SIMPLERENDERER>
                  <TRUETYPEMARKERSYMBOL font="ESRI Cartography" character="104" fontsize="12"     fontcolor="255,0,0" />
              </SIMPLERENDERER>
              <VALUEMAPLABELRENDERER labelfield = "NAME" lookupfield = "Country" labelpriorities = "0,2,1,3,4,0,0,0" featureweight = "high_weight">
                  <EXACT value = "US;Mexico;Canada;Cuba" >
  <TEXTSYMBOL font = "Arial" fontstyle = "bold" fontcolor = "0,0,0" fontsize = "9" glowing = "240,255,255" interval = "12" />
                  </EXACT>
              </VALUEMAPLABELRENDERER>
          </GROUPRENDERER>
  </SCALEDEPENDENTRENDERER>
  
  Now you will create another set of renderers for the Cities layer.  This new renderer set will be used when a user zoom in the map below the scale of 1:10,000,000.  The cities will be symbolized using the default circle marker symbol with the salmon color and labeled using the city name, followed by state name (for those cities in the USA).  The size of the label is proportion to the size of the city's population.
  
  The code for the SCALEDEPENDENTRENDERER is already written for you but commented out.
  
  <!--
  <SCALEDEPENDENTRENDERER upper="">
  <GROUPRENDERER>
  <SIMPLERENDERER>
  <SIMPLEMARKERSYMBOL type="circle" width="10" color="255,128,128" outline="0,0,0"/>
  </SIMPLERENDERER>
  <VALUEMAPLABELRENDERER labelfield="NAME STATE" lookupfield="Population" labelpriorities="0,2,1,3,4,0,0,0" labelbufferratio="1.0" featureweight="high_weight">
  <RANGE lower="1" upper="100000">
  <TEXTSYMBOL font="Arial" fontcolor="0,0,0" fontstyle="bold" glowing="255,255,255" antialiasing="true" interval="12" fontsize=""/>
  </RANGE>
  <RANGE lower="100000" upper="500000">
  <TEXTSYMBOL font="Arial" fontcolor="0,0,0" fontstyle="bold" glowing="255,255,255" antialiasing="true" interval="12" fontsize=""/>
  </RANGE>
  <RANGE lower="500000" upper="1000000">
  <TEXTSYMBOL font="Arial" fontcolor="0,0,0" fontstyle="bold" glowing="255,255,255" antialiasing="true" interval="12" fontsize=""/>
  </RANGE>
  <RANGE lower="1000000" upper="5000000">
  <TEXTSYMBOL font="Arial" fontcolor="0,0,0" fontstyle="bold" glowing="255,255,255" antialiasing="true" interval="12" fontsize=""/>
  </RANGE>
  <RANGE lower="5000000" upper="10000000">
  <TEXTSYMBOL font="Arial" fontcolor="0,0,0" fontstyle="bold" glowing="255,255,255" antialiasing="true" interval="12" fontsize="24"/>
  </RANGE>
  <RANGE lower="10000000" upper="100000000">
  <TEXTSYMBOL font="Arial" fontcolor="0,0,0" fontstyle="bold" glowing="255,255,255" antialiasing="true" interval="12" fontsize="28"/>
  </RANGE>
  </VALUEMAPLABELRENDERER>
  </GROUPRENDERER>
  </SCALEDEPENDENTRENDERER>
• Delete the comment elements (<!--- and -->) from the above block of code.
• Read the block of code and notice that the code uses the VALUEMAPRENDERER element followed by six RANGE child elements, each will represent a range of population values from the Population field.
  
  There are several missing pieces of attribute values from the block of code and you are going to insert those values.
• For the SCALEDPENDENTRENDERER element set the upper attribute to "1:10000000" (10 million)
  
  Question 7: What is the purpose of the upper attribute of the SCALEDEPENDENTRENDERER element? __________________________________________________________________________
  
  Question 8:  What do the lower and upper attributes of the RANGE element represent? __________________________________________________________________________
  
  The style of the text symbol for all the labels are the same except for the font size which gets larger as the city population increases.
• Assign the value of the fontsize attribute in each TEXTSYMBOL element following the Population range values.  Below are the fontsize values:
   

  Population Range	fontsize
  1 - 100000	10
  100000 - 500000	12
  500000 - 1000000	16
  1000000 - 5000000	20
  5000000 - 10000000	24
  10000000 - 100000000	28

• Add a set of GROUPRENDERER elements to group all renderers for the two sets of SCALEDEPENDENTRENDERER elements.  The position of this last GROUPRENDERER element is show in the following bold lines:
  
  
   <DATASET name="cities" type="point" workspace="shp_ws-0" />
  <GROUPRENDERER>
  <SCALEDEPENDENTRENDERER lower="1:10000000">
  ..
  ..
  ..
  </GROUPRENDERER>
  </SCALEDEPENDENTRENDERER>
  <SCALEDEPENDENTRENDERER upper="1:10000000">
  <GROUPRENDERER>
  ..
  ..
  ..
  </GROUPRENDERER>
  </SCALEDEPENDENTRENDERER>
  </GROUPRENDERER>
  </LAYER>
• Validate the document against the DTD, fix any errors and format the document
• To view the changes on the map display, refresh the service and viewer.
  
  At the initial extent you should see the cities at the full extent are symbolized using the red donute TrueType marker symbol and labeled using the city's name in black with a white glowing background color.  The display should be similar to the image FullExtentCities.jpg you opened earlier.
• Zoom in until the symbols and labels of the Cities layer change.
  
  When you zoomed past 1:10,000,000 you should see the cities points are symbolized using simple salmon pink circle default symbols. and labeled using the city and state names (in the USA).  The size of the labels are varied based on the size of each city's population.  The display should be similar to the ZoomInCities.jpg image you opened earlier.
  
  Step 5 - Add an ArcInfo GRID image
  
  In this last step you will add a shaded relief image as a background to your map.  The image is in ArcInfo GRID format.  Unlike most image types, you cannot add an ArcInfo GRID using ArcIMS Author. 
• Maximize the XML editor.
• Find the WORKSPACES element near the beginning of the file.
• Because you have been working with vector (feature) data only so far, you will need to add an IMAGEWORKSPACE element to identify the location of the ArcInfo GRID. image.
• Add the bolded code for the IMAGEWORKSPACE element below the current SHAPEWORKSPACE element
  
  <WORKSPACES>
  <SHAPEWORKSPACE name="shp_ws-0" directory="C:\Student\CAXL\Database\World" />
  <IMAGEWORKSPACE name = "img_ws-0" directory = "C:\Student\CAXL\Database\World" />
  </WORKSPACES>
  
  Now you will add the image to your map.  As with all other layers, you will need a LAYER element to identify how the layer will be displayed.  The name attribute within the DATASET element must match the folder name for the ArcInfo GRID image.
• Find the image layer comment line:
  
  <!--***** USA Shaded Relief***** -->
• Position the cursor at the end of the comment line and press Enter.
  Make sure your cursor is now positioned at the blank line.
• In the XML editor, press Ctrl+1
  
  A window appears that contains all the unique ArcXML element and attributes used in the current document.  If you need to add a same line of elements and attributes, you can double-click this line from the list and it will be inserted at the cursor position.
• From the dropdown list, double-click with the LAYER element to add it to your document.
  
  A new opening and closing LAYER element and its (empty) attributes are added to the blank line.
• Complete the attribute/value pairs for this new LAYER element as below:
  
  type = "image"
  name = "USA Shaded Relief"
  visible = "true"
  id = "Shaded_Relief"
  maxscale = "1:4000000"
• Using the same method, add the DATASET element as a child to the LAYER element with the following attribute/value pairs:
  
  name = "usa_relief"
  type = "image"
  workspace = "img_ws-0"
  
  Note:  The WORKSPACE attribute value for the DATASET element must match name attribute value for the IMAGEWORKSPACE element.
• Make sure the new lines of code look like this:
  
  <LAYER type="image" name="USA Shaded Relief" visible="true" id="Shaded_Relief" maxscale="1:40000000" >
  <DATASET name="usa_relief" type="image" workspace="img_ws-0">
  </DATASET>
  </LAYER>
• Validate the map configuration file against the DTD and save the document if there are no errors.
• Refresh the service and viewer. Refreshing the service will take longer because it has to read through the GRID. Because the shaded relief image is at the bottom you will have to turn off the polygon layers above it and refresh the map to see it.  You will see it only zoomed in to 1:40,000,000 or closer.