ArcGIS Viewer for Flex - Widget framework

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

In Flex terms, a viewer widget is a Flex module. The BaseWidget class that is used for all viewer widgets extends Module.

Framework Reference

Definition of a Flex module

Modules are Flash (SWF) files that can be loaded by an application. They cannot run independently of an application, but any number of applications can share the modules. Modules let you split your application into several pieces, or modules. The main application (the Flex Viewer) can dynamically load other modules that it requires when it needs them. It does not have to load all modules when it starts, nor does it have to load any modules if the user does not interact with them.

Modular applications have the following benefits:

Smaller initial download size of the SWF file.
Shorter load time due to smaller SWF file size.
Better encapsulation of related aspects of an application.

In short, modules are a great way to split your application into smaller downloadable parts. Rather than compiling your code into one huge file, you can split the application into parts where each part only downloads when it is needed. The main point of modules is to make the main application SWF smaller, and thus faster to load.

Compiling widgets

Any widget you want to use must be compiled. To compile a widget, make sure it is listed among the Flex modules to build for your project (see Project > Properties > Flex modules).

While not necessary for working with widgets in the Flex Viewer, the Adobe documentation does provide a Modular applications overview topic for learning more about Flex modules.

BaseWidget class

The BaseWidget class is the foundation for all widgets. All widgets should derive from the BaseWidget class.

Note:

Once a new widget class is created by extending the BaseWidget class, the developer is responsible for adding the new widget class to Flash Builder's project properties module table. This allows the new widget to compile into a separate SWF file.

configData

The BaseWidget class makes the "main configuration file" settings available with the configData property, which is an instance of the ConfigData class as described later in this topic. This makes it easy to access and share information from the main configuration file.

// Example: Locate widget

bingKey = configData.bingKey;

configXML

The BaseWidget class takes care of loading the "widget configuration file" into configXML. Make sure you wait for the widgetConfigLoaded event before trying to access the configXML property. The WidgetManager passes the widget configuration file URL to the BaseWidget. The BaseWidget loads and parses the configuration XML file and makes the configuration parameters available as the configXML public property.

// Example: Query widget

if (configXML)
{
    ...
    queryTitleField = configXML.titlefield;
    queryLinkField = configXML.linkfield;
    queryRefreshRate = configXML.refreshrate;

map

The BaseWidget class also sets up the map property for easy access to the main map. This is available once the widget configuration file loads. The following are some examples of using the map property:

// Example 1: Query widget

map.extent = queryResult.geometry.extent;

// Example 2: Search widget

query.outSpatialReference = map.spatialReference;

ConfigData class

The ConfigData class is used to store configuration information from the main configuration file (default file is config.xml).

AppEvent class

AppEvent is used within the application to send messages among components through the EventBus. All event driven messaging in the Flex Viewer is using the AppEvent.

The following is the typical way of sending a message via the AppEvent:

ViewerContainer.dispatchEvent(new AppEvent(AppEvent.DATA_OPT_LAYERS, null, getOplayers));

The following is the typical way of receiving a message via the AppEvent:

ViewerContainer.addEventListener(AppEvent.DATA_PUBLISH, sharedDataUpdated);

AppEvent Constants	Description
BASEMAP_SWITCH	Indicates a change in the current base map. Dispatched by MapSwitcherWidget.
CHANGE_LAYOUT	Not currently used.
DATA_CREATE_INFOWIDGET	Indicates a pop-up window has been created. Dispatched by MapManager.
DATA_FETCH	Part of interwidget communication. Dispatched by a custom widget. DataManager listens for this event, then dispatches DATA_SENT with the data.
DATA_FETCH_ALL	Part of interwidget communication. Dispatched by the BaseWidget. DataManager listens for this event, then dispatches DATA_SENT with all data.
DATA_NEW_PUBLISHED	Part of interwidget communication. Dispatched by the DataManager. The event.data contains a hash table with multiple array collections.
DATA_OPT_LAYERS	Array of operational layers.
DATA_PUBLISH	Part of interwidget communication. Dispatched by the BaseWidget. DataManager listens for this event, adds the key and object to the dataTable, then dispatches AppEvent.DATA_NEW_PUBLISHED. The event.data contains an array collection.
DATA_SENT	Part of interwidget communication. Dispatched by the DataManager after it receives a DATA_FETCH or DATA_FETCH_ALL event.
INFOWIDGET_READY	Not currently used.
INFOWIDGET_REQUEST	Not currently used.
LAYER_LOADED	Dispatched by MapManager.
MAP_LAYER_VISIBLE	Indicates that layer visibility has changed. MapManager listens for this event.
MAP_LOADED	Indicates that main map has loaded. Dispatched by MapManager.
MAP_RESIZE	Not currently dispatched.
SET_MAP_ACTION	Used to set current map action. Used by Data Extract, Draw, and Search widgets.
SET_MAP_NAVIGATION	Used to set current map navigation mode. Used by Data Extract and Search widgets and supports the following: pan (Navigation.PAN) zoom in (Navigation.ZOOM_IN) zoom out (Navigation.ZOOM_OUT) zoom to full extent (ViewerContainer.NAVIGATION_ZOOM_FULL) zoom to previous extent (ViewerContainer.NAVIGATION_ZOOM_PREVIOUS) zoom to next extent (ViewerContainer.NAVIGATION_ZOOM_NEXT)
SET_STATUS	Dispatched by MapManager. Not currently used.
SHOW_INFOWINDOW	Used to show the info windows on the map through the AppEvent via EventBus.
WIDGET_ADD	Deprecated. Use WIDGET_ADDED instead.
WIDGET_ADDED	Indicates widget has been added.
WIDGET_CHAIN_NEXT	Not currently used.
WIDGET_CHAIN_START	Not currently used.
WIDGET_CHANGE_STATE	Deprecated. Use WIDGET_STATE_CHANGED instead.
WIDGET_FOCUS	?
WIDGET_MGR_RESIZE	Not currently used.
WIDGET_RUN	Indicates a widget is about to be opened. Dispatched by WidgetManager and HeaderControllerWidget. WidgetManager listens for this event. If the widget hasn't loaded, it will load now. If the widget has closed, it will re-open.
WIDGET_STATE_CHANGED	Indicates the widget state is changing. Dispatched by BaseWidget and WidgetTemplate.

2/15/2012