Widgets in the ArcGIS Viewer for Flex
http://resources.arcgis.com/en/help/flex-viewer/concepts/
Conceptually, a widget is a chunk of code that provides functionality in the ArcGIS Viewer for Flex application. The Viewer application has an extensible widget programming model and supports modular functionality. For example, one widget enables Viewer application end-users to switch between base maps in the map display; a different widget provides functionality to find a location in the map; while another widget provides an overview map for the Viewer. Widgets can be added to and/or removed from the Viewer application to customize its appearance (i.e., user interface - UI) and functionality.
All functionality in the Viewer application is based on widgets, which are based on the ArcGIS API for Flex. Widgets can be thought of as "building blocks" that enable users to quickly and easily create custom GIS enabled Web mapping applications using the core Viewer as a starting point.
The recommended design strategy for creating custom GIS Web mapping applications with the ArcGIS Viewer for Flex is to select a specific group of widgets that supports a specific business workflow. The objective is to build a focused Web mapping application, NOT a generic GIS application.
Widget Basics:
The ArcGIS Viewer for Flex has the following directory structure:
Note:The graphic above does not show all the contents of the flexviewer folder.
Config.xml is the Viewer application's default primary configuration file. This file controls the appearance, functionality, and data content in the Viewer. (See Main Configuration File help topic). Widgets that are used by the Viewer application must be explicitly referenced in this file. Widgets are referenced in one of two ways:
- As an independent widget - stand alone <widget> tag
- Within a widget container - as a child tag to a <widgetcontainer> tag
How a widget is referenced in the config.xml file will affect its behavior in the Viewer UI. An independent widget usually forms part of the Viewer UI, while a widget stored in a widget container will appear in the widget tray (see below). A widget container collects widgets together for the purposes of ensuring that they have a similar look and feel in the Viewer application.
In the ArcGIS Viewer for Flex installation directory, the widgets folder contains the support files for all the Viewer application widgets. Each widget will have its own subfolder within the widgets folder, and each widget subfolder contains all the associated files needed for the individual widget to work. Every widget has a minimum of 2 files: a widget configuration file (.xml file) that controls the widget's properties, and a compiled Flash file (.swf file). In the graphic below, the widgets folder has 3 widgets: Bookmark, Coordinate, and DataExtract.
When a new widget is added to the Viewer application, it requires the 2 minimum files (XML configuration file and compiled Flash file), contained in its own subfolder in the widgets folder.
Widgets in the Viewer UI:
As noted earlier, how and where widgets are located within the context of the Viewer's UI is determined by how the widget is referenced in the Viewer application's configuration file (usually config.xml).
When a widget is referenced in the Viewer configuration file as an independent widget, it becomes part of the Viewer UI. In the config.xml file code sample below: the Navigation, Overview Map, and Map Switcher widgets are defined as unique components of the Viewer UI.
<!-- 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"/>
The 3 widgets form part of the default Viewer UI:
When a widget is referenced in the Viewer configuration file within a widget container, it will appear in the Viewer application widget tray. In the config.xml file code sample below, 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>
Conceptually, the widget tray is like a toolbar - containing icons that activate widgets in the Viewer. The widget tray is located at the top of the Viewer UI (default configuration). Widgets in the widget tray are typically closed (i.e., inactive) by default.
In the widget tray, clicking an icon for one of the widgets will change its status to open and display its dialog window. Open widgets will have a line appear underneath their icon. Widget dialogs can also be minimized.
Widgets can also be grouped in the widget tray; it may be beneficial to group widgets that perform similar functionality together for organizational purposes in the Viewer. Widgets can be grouped in the widget tray using the <widgetgroup> tag. In the XML configuration file code sample below, the Find U.S. address and Find European addresses widgets are grouped in the Locators widget group, within a widget container:
<widgetcontainer layout="float">
<widgetgroup label="Locators">
<widget label="Find U.S. address"
icon="assets/images/i_target.png"
config="widgets/Locate/LocateWidget_US.xml"
url="widgets/Locate/LocateWidget.swf"/>
<widget label="Find European addresses"
icon="assets/images/i_pin2.png"
config="widgets/Locate/LocateWidget_EU.xml"
url="widgets/Locate/LocateWidget.swf"/>
...
</widgetgroup>
</widgetcontainer>
Groups are represented with a folder icon, and clicking the arrow underneath the folder will display the widgets that participate within that particular group. Hovering the cursor over the folder icon will show the name of the group. The graphic below illustrates the example Locators widget group containing several locator widgets.
If multiple widgets from the widget tray are opened, the Viewer application display may become cluttered. A Toggle and Scroll keys control is available (when the <widgetcontainer>'s layout attribute is set to horizontal or vertical) to help manage the widget dialog windows. Toggle hides the widget dialog windows from the display and the scroll keys enable end-users to scroll through the various widget dialogs. The Toggle and Scroll keys control is only available for widgets contained within a widget container.
Where widgets are placed in the Viewer application UI depends on the widget's purpose and how it supports business workflows. Frequently used widgets are more likely to be defined as part of the Viewer UI, while widgets that support specific business tasks would belong in a widget container that is referenced by the widget tray.