ArcGIS Viewer for Flex - Main configuration file

This page describes an older version, please read about the latest version at:
http://resources.arcgis.com/en/help/flex-viewer/concepts/

The ArcGIS Viewer for Flex application has a main configuration file named config.xml, which is the default application configuration file. It controls the appearance, functionality, and data content in the Viewer application. It is located in the main flexviewer installation folder.

The contents of config.xml can be divided into the following main sections:

General properties, for example, application title, style colors, fonts
Application user interface (UI), for example, widgets that form part of the Viewer UI
Map content, for example, basemaps and operational layers
Widget container, for example, widgets in the widget tray

When the ArcGIS Viewer for Flex application is initially deployed, it loads with the config.xml file settings. By editing this file, the Viewer application can be easily configured to meet any specific business requirements. Additional sample Viewer configuration files are included in the main flexviewer folder to demonstrate different Viewer configuration examples.

The following graphic conceptually illustrates the main sections of the Viewer's application configuration file:

Graphic showing the main sections of the Viewer's application configuration file.

The file starts and ends with a <configuration> tag that identifies it as a configuration file for the Viewer application.

General Viewer properties

The following tags can be used to set the Viewer's general properties:

<title>

The Viewer application title text displayed in the upper left corner in the Viewer.

<subtitle>

The Viewer's subtitle text.

<logo>

Location path to the logo image displayed to the immediate left of the title on the Viewer's UI. The image should be no larger than 48 by 48 pixels or it resizes to that size. Portable Network Graphics (PNG) and Graphic Interchange Format (GIF) files are supported.

<httpproxy>

The uniform resource locator (URL) to the proxy server that will be used for <layer> tags that have their attribute useproxy="true", as well as widgets that support the useproxy tag in their configuration files (Data Extract, Geoprocessing, GeoRSS, Locate, Query, and Search widgets). For more information, see Using a proxy page.

<style>

Contains the following style related settings:

<colors>—The color set that defines the Viewer's appearance. This tag has five values (from left to right), text color, background color, rollover color, selection color, and title text color. Color values are based on red, green, and blue (RGB) in hexadecimal format. For example Viewer style colors, see Setting styles for the Viewer.
<alpha>—The transparency level for the Viewer UI components. Values range from 0.0 (transparent) to 1.0 (opaque).
<font>—The main font used in the application (including the subtitle), which has the following attributes:
- name—The font's name, for example, Comic Sans MS.
- size—The font's size, for example, 12.
  Tip:
  For fonts represented by characters, for example Japanese, a larger font size is helpful.
<titlefont>—The font used for the title in the Header Controller, which has the following attributes:
- name—The title font's name, for example, Comic Sans MS.
- size—The title font's size, for example, 28. If you remove the subtitle, there is space for a bigger font size, for example, 36.

<geometryservice>

General geometry service used by some widgets and when wraparound is set to true. It has the following attributes:

url—URL of your geometry service.
token—Token value used for accessing secured ArcGIS for Server services.
useproxy—Whether to use a proxy or not. If set to true, uses the proxy page specified with <httpproxy>. This is a Boolean value with the default set to false.

<splashpage>

This references a splash screen that appears when the Viewer application is opened. It has the following attributes:

label—The widget's name used for the splash page.
config—The location path of the splash page widget's configuration file.
url—The URL of the splash page widget's .swf file.

<bing>

If using Bing Maps for maps or geocoding, you need to provide your key, which has the following attribute:

key—Your bing key. Required.

The following is a subset of the config.xml file and its general properties:

<configuration>
    <title>ArcGIS Viewer for Flex</title>
    <subtitle>... using ArcGIS</subtitle>
    <logo>assets/images/logo.png</logo>
    <style>
        <colors>0xFFFFFF,0x333333,0x101010,0x000000,0xFFD700</colors>
        <alpha>0.8</alpha>
    </style>
    <bing key="your-bing-key"/>
    ...
</configuration>

UI elements

UI elements are independent widgets (that is, located outside of a widget container) and typically form part of the Viewer application layout's UI. These widgets comprise the Viewer application controls (four widgets form the default Viewer UI, Navigation widget, Overview Map widget, Map Switcher widget, and HeaderController widget).

<widget>—Independent <widget> tags are defined here for each widget that forms the Viewer UI. For information on its attributes, see Widget tag. For managed widgets, see <widgetcontainer> later in this topic .

The following is the config.xml file code sample of the Viewer UI elements:

...
<!-- UI elements -->
<widget left="10" top="50" config="widgets/Navigation/NavigationWidget.xml" url="widgets/Navigation/NavigationWidget.swf"/>
<widget right="-2" bottom="-2" config="widgets/OverviewMap/OverviewMapWidget.xml" url="widgets/OverviewMap/OverviewMapWidget.swf"/>
<widget right="20" top="55" config="widgets/MapSwitcher/MapSwitcherWidget.xml" url="widgets/MapSwitcher/MapSwitcherWidget.swf"/>
<widget left="0" top="0" config="widgets/HeaderController/HeaderControllerWidget.xml" url="widgets/HeaderController/HeaderControllerWidget.swf"/>
...

Map content

This section of the Viewer application configuration file defines the map content for the Viewer. It starts and ends with a <map> tag, which can have three child tags, that is, <basemaps>, <operationallayers>, and <lods>.

Map content can be defined in one of the following ways (but not both):

By explicitly defining data layers (for example, basemaps and operational layers) in the configuration file; or
By accessing a published web map from ArcGIS.com

Using a web map

Use the <map> tag itemid property. The itemid property refers to the item ID of a web map from ArcGIS.com. The Viewer can access and view published web maps from ArcGIS.com. For more information, see About ArcGIS.com Web Maps. Note that you cannot add basemaps and operational layers when using a web map.

<map itemid="2f1d4a31078d460aa4a7aa46f5b882e5">
</map>

Using basemaps and operational layers

<basemaps>—A list of map services used as a basemap in the Viewer. Only one basemap can be visible at a time, but a basemap can consist of more than one layer. To create hybrid basemaps, set the name property to be the same on the layers in the basemaps group that should make up the hybrid basemap. When multiple map services are listed in <basemaps>, the Map Switcher widget can be used to enable end users to switch between them. The <basemaps> tag has the following child tag that can be repeated multiple times:

<layer>—This is a map service displayed as a layer in the Viewer. For more information on its attributes, see Layer tag.

<operationallayers>—List of map services that overlay on top of the basemap data in the Viewer. Operational layers can be accessed from the Map Switcher widget, the More button, and the Layer List widget. The <operationallayers> tag has the following child tag that can be repeated multiple times:

<layer>—This is a map service displayed as a layer in the Viewer. For more information on its attributes, see Layer tag.

<map>
    <basemaps>
        <layer label="Streets" type="tiled" visible="true" alpha="1"
                  url="http://server.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer"/>
        <layer label="Aerial" type="tiled" visible="false" alpha="1"
                  url="http://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer"/>
        ...
    </basemaps>
    <operationallayers>
        <layer label="Boundaries and Places" type="tiled" visible="false"
                  url="http://server.arcgisonline.com/ArcGIS/rest/services/Reference/World_Boundaries_and_Places_Alternate/MapServer"/>
        ...
    </operationallayers>
</map>

<map>—Defines the map component in the Viewer. It has the following general attributes (none of which are required):

initialextent—The map's initial spatial extent. This is defined in minimum x,y and maximum x,y coordinates of your application's spatial reference. The spatial reference of your application is the spatial reference of your first base layer, or the wkid/wkt, if they are defined. For example, most of the ArcGIS Online tiled services are in the World Geodetic System 1984 (WGS84) Web Mercator Auxilary Sphere projection (wkid #102100). The coordinate values can be obtained using the Extent Helper application. If not specified, the initial extent defaults to the initial extent of the first basemap.
fullextent—This attribute is used by the Navigation widget to zoom to the map's "maximum spatial extent." The syntax is the same as for initalextent. If this property is not set, the full extent of the application is the initial extent.
center—The map's initial center point.
level—The initial level at which to open the map. The levels are dependant on your map's level of detail (LOD).
scale—The map's initial scale.
esrilogovisible—Determines whether to display the Esri logo in the application. This is a Boolean value, with the default set to true.
openhandcursorvisible—Determines whether to use the open hand cursor in the application. This is a Boolean value, with the default set to false as of version 2.3. Prevously, the default was set to true.
paneasingfactor—Adjusts the map's "easing" when panning. Valid values are between 0 and 1. A value of 1 turns off the easing. If not set, defaults to 0.2. For more information, see Map.panEasingFactor. (Added in version 2.3.)
scalebarvisible—Determines whether to display the scale bar in the application. This is a Boolean value, with the default set to true.
zoomslidervisible—Determines whether to display the map's zoom slider in the application. This is a Boolean value, with the default set to false because the Navigation widget displays in the Viewer by default.
wkid—The Well Known ID that refers to the map's spatial reference ID number. If both wkt and wkid are specified, the wkid is used. If wkid is not specified, the projection of the first <layer> sets the wkid (or wkt).
wkt—The Well Known Text that refers to the map's spatial reference text. Requires all ArcGIS Servers to be 10.0 or above. If wkid is not specified, the projection of the first <layer> sets the wkid (or wkt).
wraparound180—Determines whether to enable continous panning across the dateline. The default is false.

Attributes for positioning map component

top—The vertical distance in pixels from the top edge of the map to the top edge of the application. The default is 0 pixels, but 40 is a best practice when using the HeaderController widget, since it typically covers the top 40 pixels.
bottom—The vertical distance in pixels from the bottom edge of the map to the bottom edge of the application. The default is 0 pixels.
left—The horizontal distance in pixels from the left edge of the map to the left edge of the application. The default is 0 pixels.
right—The horizontal distance in pixels from the right edge of the map to the right edge of the application. The default is 0 pixels.

<map
        initialextent="-13046840 4036096 -13045400 4036867"
        fullextent="-16677000 2009000 -4819000 8330000"
        scale="1000000"
        wraparound180="true"
        top="40">

<lods>—The LODs, or set scales. By default, the available levels are determined from your basemap. To change this, specify your set of levels. For layers with pre-created tiles, these must exactly match your levels. The <lods> tag has one child tag <lod>, which in turn, has two properties (that is, resolution and scale).

<map>
    <lods><!-- only show a few levels -->
        <lod resolution="78271.5169639999" scale="295828763.795777"/>
        <lod resolution="9783.93962049996" scale="36978595.474472"/>
        <lod resolution="1222.99245256249" scale="4622324.434309"/>
        <lod resolution="152.874056570411" scale="577790.554289"/>
    </lods>
    ...
</map>

Widget container

A widget container is a conceptual construct, and is not something directly visible in the Viewer UI. It enables widgets to be grouped for management purposes in the Viewer. Widgets stored in a widget container are referenced in the widget tray. Widgets that end-users can easily turn on and off in the Viewer, are typically stored within a widget container. For information on its attributes, see Widgetcontainer tag.

<widgetcontainer>—Defines a widget container for the Viewer application. A Viewer can have multiple widget containers. When <widget> tags are child tags to <widgetcontainer>, the widgets are stored in the widget container and appear in the widget tray.

In the following config.xml file code sample, the "Bookmarks" and "Find an address" widgets are stored in a widget container:

...
<widgetcontainer layout="float">
    <widget label="Bookmarks"
                x="400" y="90" icon="assets/images/i_bookmark.png"
                config="widgets/Bookmark/BookmarkWidget.xml"
                url="widgets/Bookmark/BookmarkWidget.swf"/>
    <widget label="Find an address"
                x="100" y="90" preload="open"
                icon="assets/images/i_target.png"
                config="widgets/Locate/LocateWidget_US.xml"
                url="widgets/Locate/LocateWidget.swf"/>
    ...
</widgetcontainer>
...

2/15/2012