VALUEMAPLABELRENDERER

Used in

Servers

Image Feature

Parent elements

GROUPRENDERER LAYER LAYERDEF LAYERINFO SCALEDEPENDENTRENDERER

Syntax

<VALUEMAPLABELRENDERER	Attribute Description Table
*(r)labelfield="string"* *(r)lookupfield="string"* featureweight="no_weight \| med_weight \| high_weight" [no_weight] howmanylabels="one_label_per_name \| one_label_per_shape \| one_label_per_part" [one_label_per_name] labelbufferratio="double" [0.0] labelpriorities="0,0,0,0,0,0,0,0 - 8,8,8,8,8,8,8,8 \| LE_PlaceOnTopHorizontal" [2,2,1,4,5,3,2,4] labelweight="no_weight \| med_weight \| high_weight" [high_ weight] linelabelposition="See table below for values" [placeabove] rotationalangles="string" > (r)(m)<EXACT... /> [Or] (r)(m)<RANGE... /> [Or] <OTHER... /> </VALUEMAPLABELRENDERER >
(r): Attribute or child element is required. (m): Child element can be used multiple times.

Description

Labels features by category. A field is specified for labeling features based on criteria in EXACT or RANGE.

Restrictions

The attribute labelpriorities="LE_PlaceOnTopHorizontal" is limited to Image Services.
The attribute rotationalangles is valid only with point layers.
Only one VALUEMAPLABELRENDERER can be used per layer. Additional label renderers are not processed.
EXACT or RANGE is required. OTHER is optional.

Notes

When rotating symbols, the attribute labelpriorities always takes precedence over the attribute rotationalangles. If you find that your labels are not rotating as expected when using Image Services, remove the labelpriorities attribute if it is present.
If subfields is used in SPATIALQUERY or QUERY for a layer, any fields used for labeling must be included in the subfields list.
When joined tables or fully qualified ArcSDE names are used for the field name in labelfield or lookupfield in a map configuration file, this file cannot be read locally in ArcIMS Author or ArcExplorer-Java Edition.
For more information on using renderers, see Using ArcXML Renderers.

Attribute Descriptions for VALUEMAPLABELRENDERER

Attribute

Usage

featureweight

Prioritizes the importance of features. The feature weight 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. Giving importance to features increases the complexity of the labeling problem and also the processing time.

howmanylabels

Known limit: this attribute may not work as expected, particularly when labeling lines or points.

Determines how often a feature is labeled.

"One_label_per_part" labels all parts of a feature in the case of multipart features. For instance, the State of Hawaii consists of several islands, but they are grouped together as one polygon feature. Each island is labeled.

Known limit: Not all parts of a feature may be labeled.
"One_label_per_name" labels once per feature name. When several features share the same name, only one label is shown. For example, if there is more than one polygon with the name "Residential", only one "Residential" polygon is labeled.

Known limit: You may see duplicate labels for a feature name.
"One_label_per_shape" labels once per feature even if there are multiple segments. For example, the group of islands that make up Hawaii are only labeled once. If there are other features with the same name, they are also labeled.

Known limit: You may see duplicate labels for a shape.

labelbufferratio

Sets a buffer around the label. When this is set, no labels overlap within the buffer range. The ratio is the fraction of the height or the width of the label rectangle (whichever is smaller) compared to the width of the buffer. A ratio of "0.0" means no buffer. A ratio of "1.0" means that the buffer is twice the size of the label (the label width equals the buffer width). A negative ratio causes the buffer to be smaller than the label. This can be used to allow labels to overlap.

labelfield

Field containing text for labeling features. The field can be in the layer table or in a joined table. Performance is generally better if the field name is all upper case. When joined DBF table names or fully qualified ArcSDE names are used for the field name in a map configuration file, this file cannot be read locally in ArcIMS Author or ArcExplorer-Java Edition.

For shapefiles with no joined tables, the field can be referenced using the short format.
labelfield="AREA"
For shapefiles with joined tables, the name of the joined table must be included along with the field.
labelfield="JOINEDTABLE.AREA"
For ArcSDE layers without joined tables, the field can be referenced using the short format.
labelfield="AREA"
The fully qualified name can also be used.
labelfield="ARCSDENAME.TABLE.AREA"
For ArcSDE layers with joined tables, joined fields must be referenced using the fully qualified format.
labelfield="ARCSDENAME.TABLE.AREA"

Labels can include data concatenated from two or more fields. Each field name is separated by a space:

Using a shapefile with no joined tables. The short format can be used for field names.
labelfield="CITY STATE_NAME"
Using a shapefile with joined tables. The name of the joined table must be included along with the field names.
labelfield="JOINEDTABLE.CITY JOINEDTABLE.STATE_NAME"
Using an ArcSDE layer without joined tables. The short format can be used.
labelfield="CITY STATE_NAME"
The fully qualified name can also be used.
labelfield="ARCSDENAME.TABLE.CITY ARCSDENAME.JOINEDTABLE.STATE_NAME"
Using an ArcSDE layer with joined tables. The fully qualified format must be used.
labelfield="ARCSDENAME.TABLE.CITY ARCSDENAME.JOINEDTABLE.STATE_NAME"

labelpriorities

Determines where to place the label around the point. The attribute accepts different weights for each of eight positions around the point. Each position corresponds to the positions as shown below:

1	2	3
8	X	4
7	6	5

In each position, the user can prioritize the importance of that position from 0 upwards. 0 signifies that the label should not be placed in that position. 1 means that this is an acceptable position for the label, and all higher numbers represent lesser priorities for that position. For example, "1,0,1,0,0,0,0,0" means that only the first and third label positions will be taken into account when labeling. In another example, "1,2,3,0,1,0,0,0" means try to label at the first and fifth position; if not, then put the label at the second position; if not, then put it at the third position; if this is not possible, then don't label it.

When using an Image Service, another option is to place a label on top of points rather than around points. To do this, use "LE_PlaceOnTopHorizontal" for the label priority.

labelweight

Prioritizes the importance of labels. The label weight is usually set to "high_weight" since the labels are more important. This can be set lower if the labels are not as important as the feature.

linelabelposition

Determines where on the line to place the label. The following options are available:

placeabove - Place above the line.
placebelow - Place below the line.
placeontop - Place on the line.
placeleft - Place along the left side of the line (Label follows line and is not perpendicular to the line).
placeright - Place along the right side of the line (Label follows line and is not perpendicular to the line).
placeabovebelow - Place above or below the line.
placeleftright - Place at either side of the line.
placeinline - Place anywhere on the line.
placeparallel - Place parallel to the line.
placeontophorizontal - Place label on top of the line but always horizontal.
placeatstartabove - Place label at the start above the line.
placeatstartontop - Place label at the start on top of the line.
placeatstartbelow - Place label at the start below the line.
placeatendabove - Place label at the end above the line.
placeatendontop - Place label at the end on top of the line.
placeatendbelow - Place label at the end below the line.
placeeitherendabove - Place at either end above the line.
placeeitherendontop - Place at either end on top of the line.
placeeitherendbelow - Place at either end below the line.

lookupfield

Name of field used to specify ranges for RANGE or exact values for EXACT. The field can be in the layer table or in a joined table. Performance is generally better if the field name is all upper case. When joined DBF table names or fully qualified ArcSDE names are used for the field name in a map configuration file, this file cannot be read locally in ArcIMS Author or ArcExplorer-Java Edition.

For shapefiles with no joined tables, the field can be referenced using the short format.
lookupfield="AREA"
For shapefiles with joined tables, the name of the joined table must be included along with the field.
lookupfield="JOINEDTABLE.AREA"
For ArcSDE layers without joined tables, the field can be referenced using the short format.
lookupfield="AREA"
The fully qualified name can also be used.
lookupfield="ARCSDENAME.TABLE.AREA"
For ArcSDE layers with joined tables, joined fields must be referenced using the fully qualified format.
lookupfield="ARCSDENAME.TABLE.AREA"

rotationalangles

The rotational angles are possible angles that the label can be placed at, relative to the labeled point. By default, labels are always placed horizontally. To rotate a label, a comma-delimited list of up to eight rotational angles can be given and are prioritized from first to last. For example, if the first priority is to place labels at 45 degrees and the second priority is at 30 degrees, the rotational angles attribute would look like this:

Labelpriorities always take precedence over rotationalangles. If you find that your labels are not rotating as expected, remove the labelpriorities attribute if it is present. Alternatively, you can set all the labelpriorities to "0".

Examples for VALUEMAPLABELRENDERER

Example 1: Labels for a line layer using EXACT.

<?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>
      <PROPERTIES>
        <ENVELOPE minx="-178.215027" miny="18.924782" maxx="-66.969849" maxy="71.406647" name="Initial_Extent" />
        <MAPUNITS units="decimal_degrees" />
        <FILTERCOORDSYS id="4326" />
        <FEATURECOORDSYS id="4326"/>
      </PROPERTIES>
      <WORKSPACES>
         <SHAPEWORKSPACE name="shp_ws-0" directory="<path to USA ESRIDATA>"/>
      </WORKSPACES>
      <LAYER type="featureclass" name="ROADS" visible="true" id="1">
        <DATASET name="ROADS" type="line" workspace="shp_ws-0" />
        <GROUPRENDERER>
          <VALUEMAPLABELRENDERER lookupfield="ADMN_CLASS" labelfield="ROUTE" linelabelposition="placeontop" howmanylabels="one_label_per_shape">
          <EXACT value="US Highway" label="US Highway">
            <SHIELDSYMBOL font="Arial" fontstyle="regular" fontsize="10" type="usroad" />
          </EXACT>
          <EXACT value="Interstate" label="Interstate">
            <SHIELDSYMBOL antialiasing="true" font="Arial" fontstyle="regular" fontsize="10" type="interstate" />
          </EXACT>
          <OTHER>
            <TEXTSYMBOL font="Arial" fontstyle="regular" fontsize="10" />
          </OTHER>
        </VALUEMAPLABELRENDERER>
        <SIMPLERENDERER>
            <SIMPLELINESYMBOL type="solid" width="2" color="27,127,27" />
          </SIMPLERENDERER>
        </GROUPRENDERER>
      </LAYER>
    </MAP>
  </CONFIG>
</ARCXML>

Example 2: Labels for a point layer using different types of text symbols in RANGE.

<?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>
      <PROPERTIES>
        <ENVELOPE minx="-180" miny="-90" maxx="180" maxy="90" name="Initial_Extent" />
        <MAPUNITS units="decimal_degrees" />
        <FILTERCOORDSYS id="4326" />
        <FEATURECOORDSYS id="4326"/>
      </PROPERTIES>
      <WORKSPACES>
         <SHAPEWORKSPACE name="shp_ws-0" directory="<path to WORLD ESRIDATA>"/>
      </WORKSPACES>
      <LAYER type="featureclass" name="cities" visible="true" id="1">
        <DATASET name="cities" type="point" workspace="shp_ws-0" />
        <GROUPRENDERER>
          <VALUEMAPLABELRENDERER lookupfield="POPULATION" labelfield="NAME" labelpriorities="1,0,0,0,0,0,0,0">
          <RANGE lower="0.0" upper="150000.0" label="Smallest">
            <TEXTSYMBOL font="Tahoma" fontstyle="regular" fontsize="10" />
          </RANGE>
          <RANGE lower="150001.0" upper="750000.0" label="Medium">
            <TEXTSYMBOL font="Arial" fontstyle="italic" fontsize="12" glowing="125,125,125" />
          </RANGE>
          <RANGE lower="750001.0" upper="3427180.0" label="Largest">
            <TEXTSYMBOL font="Times New Roman" fontstyle="bolditalic" fontsize="14" glowing="255,255,0" shadow="0,0,0" />
          </RANGE>
          </VALUEMAPLABELRENDERER>
          <SIMPLERENDERER>
            <SIMPLEMARKERSYMBOL color="51,102,51" width="8" />
          </SIMPLERENDERER>
        </GROUPRENDERER>
      </LAYER>
    </MAP>
  </CONFIG>
</ARCXML>