Widgets Configuration File XML Structure

The widgets configuration file contains the list of widgets that are available for display in Flash mode.

Widgets are generally provided in the widgets.xml file, but they can also be included within pageConfig.xml. The recommended practice is to use a separate configuration file to ensure that your customizations are correctly propagated in future upgrades. You use the same XML structure whether you make the settings in widgets.xml or in pageConfig.xml.

A sample of the XML structure for widgets.xml is shown below, followed by a description of the elements and attributes that make up the file.

XML structure

</widgets>

Description

The table below describes the XML structure of the widgets configuration file. The four columns in the table include the following descriptive information:

Parent Element - Child Element 1 - Child Element 2	Indicates the name of the element described in the next three columns. If this is a parent element, the names of all possible child elements are listed below the parent element.
Number of Nodes	Specifies the number of nodes that are required or allowed for the corresponding element in the Parent Element column. For example, if the value is "1", there must be only one node— no more, no less. If the value is "0 or more", the node is not required ("0"), but there is no restriction on the number of nodes that can be added ("or more"). If the value is "1 or more", the node is required ("1"), but there is no restriction on the number of nodes that can be added ("or more").
Parent Element Attributes	Lists the separate attributes that can be used with the corresponding element in the Parent Element column. Included in parentheses beneath each attribute name are the attribute type and an indication of whether the attribute is required or implied. For example, the version attribute for the <widgets> element has an attribute type of "nmtoken" (name token) and is implied. The scope attribute for the <widget> element has an attribute type of "cdata" (character data) and is required.
Description	Describes either a parent element in the Parent Element column or an attribute in the Parent Element Attributescolumn.

Parent Element - Child Element 1 - Child Element 2	Number of Nodes	Parent Element Attributes	Description
<widgets> - <widget>	0 or 1		The <widgets> element groups a list of widgets available for display in Flash mode. These <widgets> elements are used to define the properties of the different widgets displayed in MicroStrategy products..
		config-src (cdata / implied)	If the widgets are defined in a separate file, the config-src attribute tells the page configuration file the location of the widgets configuration file.
		version (nmtoken / implied)	If the widgets are defined in a separate file, the version attribute indicates the release number of the widgets configuration file. This attribute is useful for backwards compatibility because it lets the application know what features are available.
<widget>	1 or more		The <widget> element defines the properties of a single widget that can be displayed in Flash mode.
		id (id / required)	The id attribute is the unique id for the widget.
		scope (cdata / implied)	The scope attribute represents the field unit type value for the underlying document object. For a list of possible values, refer to com.microstrategy.web.objects.rw.EnumRWUnitTypes.
		fqcn (cdata / implied)	The fqcn attribute is the fully-qualified class name for the widget. It is important to specify the class name correctly since it is persisted in the metadata the first time the widget is used. On subsequent uses, this class name is retrieved from the metadata, rather than from widgets.xml. The value of this attribute is blank if the widget was built using the Visualization Framework.
		rslPath (cdata / implied)	The rslPath attribute provides the path to the custom visualization file for the widget from the MicroStrategy Web installation folder.
		title (cdata / implied)	The title attribute specifies the name to be displayed in the widget drop-down list if no descriptor ID is specified in titleId.
		titleId (cdata / implied)	The titleId attribute provides a descriptor ID, which can be used for localization. This is the key of the string from the MessageBundles.properties file with the localized description of the widget. For example, desc-id="scenario1.1". The localized description of the widget is displayed in the widget drop-down list if it exists.
		titleDESCId (cdata / implied)	The titleDescId attribute is reserved for future use. Use the default value, "-1".
		tbImage (cdata / implied)	The tbImage attribute is reserved for future use. Use the default value, "" (blank).
		tbClass (cdata / implied)	The tbClass attribute indicates the CSS class name that will be specified in a CSS file for displaying an icon for the widget.
		previewImage (cdata / implied)	The previewImage attribute provides the relative path to the icon that will be displayed at the bottom right of the template container in Design mode and to the right of the widget name in the drop-down list of widgets. The value of title or titleId is displayed when the cursor hovers over this icon.
		minSecondaryProviders	The minSecondaryProviders attribute indicates the minimum number of additional data providers that must furnish data to a widget. If a value other than "0" (zero) is entered here, when this widget is used in a document, the user must specify the secondary data providers on the Flash tab of the widget Properties dialog.
		maxSecondaryProviders	The maxSecondaryProviders attribute indicates the maximum number of additional data providers that must furnish data to a widget. This value should be greater than or equal to the value of the minSecondaryProviders attribute.
		isAPP	The isAPP attribute indicates the method used for creating the widget. A value of "true" indicates that the widget was built using the Visualization Framework. If the widget was built using any other method, the value should be " " (blank) or "false".