LEGEND

LEGEND

Used in: CONFIG   REQUEST   RESPONSE
Servers: Image   ArcMap
Parent elements: IMAGE   PROPERTIES

<LEGEND	Attribute Description Table
When parent element is IMAGE: *file ="string"* *url ="string"* type ="gif \| jpg \| png \| png8" When parent element is PROPERTIES when using ArcMap Server: autoextend ="true \| false" [false] backgroundcolor ="0,0,0 - 255,255,255" display ="true \| false" [true] font ="Any system font" [Arial] layerfontsize ="integer" [10] swatchheight ="integer" [14] swatchwidth ="integer" [18] title ="string" titlefontsize ="integer" [12] valuefontsize ="integer" [8] When parent element is PROPERTIES when using Image Server: anitaliasing ="true \| false" [true] autoextend ="true \| false" [false] backgroundcolor ="0,0,0 - 255,255,255" cansplit ="true \| false" [false] cellspacing ="integer" [2] columns ="integer" [1] display ="true \| false" [true] font ="Any system font" [Arial] height ="1 - NNN" [300] layerfontsize ="integer" [10] reverseorder ="true \| false" [false] splittext ="string" [(cont)] swatchheight ="integer" [14] swatchwidth ="integer" [18] title ="string" titlefontsize ="integer" [12] transcolor ="0,0,0 - 255,255,255" valuefontsize ="integer" [8] width ="1 - NNN" [125] > When parent element is IMAGE: No Child Elements When parent element is PROPERTIES when using ArcMap Server: No Child Elements When parent element is PROPERTIES when using Image Server: (m) <LAYERS... /> </LEGEND >
Bold: Attribute or child element is required. (m): Child element can be used multiple times.

Description:

Defines the map's legend when using Image or ArcMap Image Services.

Restrictions:

When using an ArcIMS HTML Viewer, ArcIMS Java Viewer, ArcExplorer 4, or any other client using the ArcIMS Servlet Connector, the LEGEND element is restricted in an IMAGE response. The attribute file is not returned.

This restriction can be lifted by setting the property spatialServer.AllowResponsePath to true in esrimap_prop. This property file is found in the same directory as the ArcIMS Servlet Connector. For more information on the location of esrimap_prop and its properties, see the ArcIMS Help.

This restriction applies only when the ArcIMS Servlet Connector is used. It does not apply to the ActiveX, ColdFusion, or Java Connectors.
Valid only with Image or ArcMap Image Services in an ArcIMS HTML Viewer or other HTML implementation.
Legend image output can be streamed in Base64 encoded format and returned as part of the IMAGE response. This is an alternative to generating images in an output directory. The following restrictions apply:
- Valid only with Image Services. Streaming is not valid with ArcMap Image Services.
- Valid only when using the Java Connector. Streamed images are not supported with the ActiveX, ColdFusion, or Servlet Connectors.
- In the map configuration file, the following line must be included in the PROPERTIES section: <OUTPUT method="stream">.
- When creating an Image Service in ArcIMS Administrator, the Directory Location and HTTP Location must both be filled out. A dummy location can be used rather than pointing to an actual directory.
In an IMAGE response, if a legend image is streamed, the attributes file and url are not included and are not required.

Notes:

If LEGEND is defined in a map configuration file, then a legend is always generated during a GET_IMAGE request even if no legend is defined in the request.
To remove layers from the legend list, use LAYERS.

The following table shows which attributes are available for setting the size and font for the title and individual layers. The usage of attributes differs between Image and ArcMap Image Services.

	Attributes available when using an Image Service and no layers contain a value map.
	Attributes available when using an Image Service and at least one layer contains a value map.
	Attributes available when using an ArcMap Image Service and no layers contain a value map.
	Attributes available when using an ArcMap Image Service and at least one layer contains a value map.

For a comprehensive overview of using LEGEND, including more examples, see Using GET_IMAGE and IMAGE with Image Services or Using GET_IMAGE and IMAGE with ArcMap Image Services.

Attribute Descriptions for LEGEND:

When parent element is IMAGE:

Attribute	Usage	Back to Top
file	Full pathname and filename for location of legend image generated by the ArcIMS Spatial Server. Image is written to the ArcIMS Spatial Server's output directory by default. UNC pathnames are valid (\\myComputer\arcims\output).
type	Returned when OUTPUT method="stream" in a map configuration file for Image Services. The image is returned in the response in Base64 encoded format. Valid only when the Java Connector is used.
url	URL used by client to retrieve legend image.

When parent element is PROPERTIES when using ArcMap Server:

Attribute	Usage	Back to Top
autoextend	Extends the legend to accommodate information for all layers. Should always be set to "true" with ArcMap Server.
backgroundcolor	Legend’s background color using RGB values.
display	Turns legend on or off.
font	Font for title. The name is case sensitive. If font name uses "&", use "&" instead. For example, ESRI Transportation & Civic should be written as ESRI Transportation & Civic.
layerfontsize	Sets the font size of the childheading for layers that include a value map.
swatchheight	Height of the symbol swatch in pixels.
swatchwidth	Width of the symbol swatch in pixels.
title	Title of legend.
titlefontsize	Font size for title.
valuefontsize	For layers that include a value map, it sets the font size for value map labels. For layers with no value map, it sets the font size for the layer name.

When parent element is PROPERTIES when using Image Server:

Attribute	Usage	Back to Top
anitaliasing	Used to make edges of labels and symbols smoother. When set to "true", antialiasing is active. Note that the time to generate a map may significantly increase when antialiasing is turned on.
autoextend	If "true", automatically extends legend vertically past size specified in height, if needed.
backgroundcolor	Legend’s background color using RGB values.
cansplit	Allows splitting of valuemap layers between columns.
cellspacing	Defines number of pixels to pad between entries.
columns	Defines number of columns in legend.
display	Turns legend on or off.
font	Font for title. The name is case sensitive. If font name uses "&", use "&" instead. For example, ESRI Transportation & Civic should be written as ESRI Transportation & Civic. For Feature Services, the font must reside on the client machine or else the system default font is used.
height	Legend height in pixels.
layerfontsize	Font size for layer labels.
reverseorder	Reverse order of layers.
splittext	Text that displays in bottom of a column if a valuemap is carried over into the next column.
swatchheight	Height of the symbol swatch in pixels.
swatchwidth	Width of the symbol swatch in pixels.
title	Title of legend.
titlefontsize	Font size for title.
transcolor	Transparency color using RGB values. White is 255,255,255.
valuefontsize	Font size for value map labels.
width	Legend width in pixels.

Examples for LEGEND:

Example 1: When in an IMAGE response and LEGEND is restricted.	Back to Top
<?xml version="1.0" encoding="UTF8"?> <ARCXML version="1.1"> <RESPONSE> <IMAGE> <LEGEND url="http://mymachine.domain.com/output/Iextensions_MYMACHINE4094163.jpg" /> </IMAGE> </RESPONSE> </ARCXML>

Example 2: When in an IMAGE response with no restrictions on LEGEND.	Back to Top
<?xml version="1.0" encoding="UTF8"?> <ARCXML version="1.1"> <RESPONSE> <IMAGE> <LEGEND file="D:\ArcIMS\output\Iextensions_MYMACHINE4094163.jpg" url="http://mymachine.domain.com/output/Iextensions_MYMACHINE4094163.jpg" /> </IMAGE> </RESPONSE> </ARCXML>

Example 3: GET_IMAGE request where layers with ID of "0" and "1" are removed from the legend list.

Back to Top

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_IMAGE>
      <PROPERTIES>
        <LEGEND title="Legend" font="Arial" autoextend="true" columns="1" width="170" height="300" backgroundcolor="255,255,0" >
          <LAYERS>
            <LAYER id="0"/>
            <LAYER id="1"/>
          </LAYERS>
        </LEGEND>
        <DRAW map="false"/>
      </PROPERTIES>
    </GET_IMAGE>
  </REQUEST>
</ARCXML>

Example 4: Map configuration file where layers with ID of "0" and "1" are removed from the legend list.

Back to Top

<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <CONFIG>
    <ENVIRONMENT>
      <LOCALE country="US" language="en" variant="" />
      <UIFONT color="0,0,0" name="Arial" size="12" style="regular" />
      <SCREEN dpi="96" />
    </ENVIRONMENT>
    <MAP dynamic="true" >
      <PROPERTIES>
      <ENVELOPE minx="-180.0" miny="-90.0" maxx="180.0" maxy="90.0" name="Initial_Extent" />
      <MAPUNITS units="decimal_degrees" />
      <LEGEND title="Legend" font="Arial" autoextend="true" columns="1" width="170" height="300" backgroundcolor="255,255,0" >
        <LAYERS>
          <LAYER id="0"/>
          <LAYER id="1"/>
        </LAYERS>
      </LEGEND>
      </PROPERTIES>
      <WORKSPACES>
        <SHAPEWORKSPACE name="shp_ws-0" directory="<path to WORLD ESRIDATA>" />
        <SHAPEWORKSPACE name="shp_ws-2" directory="<path to USA ESRIDATA>" />
        <SHAPEWORKSPACE name="shp_ws-3" directory="<path to CANADA ESRIDATA>" />
      </WORKSPACES>
      <LAYER type="featureclass" name="WORLD30" visible="true" id="0">
        <DATASET name="WORLD30" type="polygon" workspace="shp_ws-0" />
        <SIMPLERENDERER>
          <SIMPLEPOLYGONSYMBOL filltype="solid" fillcolor="0,153,255" />
        </SIMPLERENDERER>
      </LAYER>
      <LAYER type="featureclass" name="CNTRY94" visible="true" id="1">
        <DATASET name="CNTRY94" type="polygon" workspace="shp_ws-0" />
        <SIMPLERENDERER>
          <SIMPLEPOLYGONSYMBOL filltype="solid" fillcolor="255,255,153" />
        </SIMPLERENDERER>
      </LAYER>
      <LAYER type="featureclass" name="United States" visible="true" id="2">
        <DATASET name="STATES" type="polygon" workspace="shp_ws-2" />
        <SIMPLERENDERER>
          <SIMPLEPOLYGONSYMBOL filltype="solid" fillcolor="255,0,0" />
        </SIMPLERENDERER>
      </LAYER>
      <LAYER type="featureclass" name="Canada" visible="true" id="3">
        <DATASET name="province" type="polygon" workspace="shp_ws-3" />
        <SIMPLERENDERER>
          <SIMPLEPOLYGONSYMBOL filltype="solid" fillcolor="0,153,0" />
        </SIMPLERENDERER>
      </LAYER>
      <LAYER type="featureclass" name="World Cities" visible="true" id="4">
        <DATASET name="CITIES" type="point" workspace="shp_ws-0" />
        <SIMPLERENDERER>
          <SIMPLEMARKERSYMBOL color="102,0,102" width="8.0" />
        </SIMPLERENDERER>
      </LAYER>
    </MAP>
  </CONFIG>
</ARCXML>

Example 5: When used in an IMAGE response and image is streamed using Base64 encoding.	Back to Top
<?xml version="1.0" encoding="UTF-8"?> <ARCXML version="1.1"> <RESPONSE> <IMAGE> <ENVELOPE minx="-180" miny="-135" maxx="180" maxy="135" /> <OUTPUT type="jpg">/9j/4AAQSk ... ZJRgABZ</OUTPUT> <LEGEND type="jpg" >/9j/4AAQSkZJRgABAQA ... UDBAQEAZ</LEGEND> </IMAGE> </RESPONSE> </ARCXML>