System Picker Configuration File XML Structure

In MicroStrategy Web, system pickers represent the objects that allow you to choose such settings as the fonts, colors, styles, borders, lines, and date and time formats that are used by the application. There can be multiple system picker configuration files, each of which defines the choices available for a specific type of setting. System pickers appear as drop-down lists in a toolbar or in certain editors. Each system picker configuration file groups a list of shortcut objects, which define the choices in the drop-down list.

System picker configuration settings are generally set in a separate file, but they can also be made 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 a separate file or in pageConfig.xml.

A sample of the XML structure for one of the system picker configuration files, advancedColorPicker.xml, is shown below, followed by a description of the elements and attributes that make up the file.

XML structure for advancedColorPicker.xml (one of several system-picker configuration files)

<shortcut-listcolumns="5" name="basicColors" version="1.0">

</attributes>

<attributename="style" value="background-color: #ffffff;" />

</attributes>

</shortcut>

...

</shortcut-list>

Description

The table below describes the XML structure of a system picker 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 <shortcut-list> element has an attribute type of "nmtoken" (name token) and is implied. The name attribute for the <shortcut> 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
<shortcut-list> - <attributes> - <shortcut>	1 or more		The <shortcut-list> element represents a specific system picker and groups a list of shortcut objects, each of which defines a single system picker item. (When you use a separate system pickers configuration file, the <shortcut-list> element represents the root element of the file.)
		config-src (cdata / implied)	If the system picker is defined in a separate file, the config-src attribute tells the page configuration file the location of the system picker configuration file.
		version (nmtoken / implied)	If the system picker is defined in a separate file, the version attribute indicates the release number of the system picker configuration file. This attribute is useful for backwards compatibility because it lets the application know what features are available.
		base-bean (cdata / implied)	The base-bean attribute indicates the bean from the page’s bean hierarchy associated with the list of system pickers. If an individual system picker item does not define a base bean attribute, this bean is used in tasks such as resolving features.
		desc (cdata / implied)	The desc attribute provides a descriptor that the application uses to display the system picker if the desc-id attribute is missing.
		desc-id (cdata / implied)	The desc-id attribute provides the Resource Bundle item id that the application uses to display the system picker in the language of the user's locale.
		enable-feature-id (cdata / implied)	The enable-feature-id attribute represents a feature that is evaluated to determine whether the system picker should appear enabled or disabled when it is displayed.
		feature-id (cdata / implied)	The feature-id attribute represents a feature that is evaluated to determine whether the system picker should be displayed.
		name (nmtoken / implied)	The name attribute provides a unique identifier for the system picker.
		columns (cdata / implied)	The columns attribute indicates the number of columns in which the system picker items are displayed.
		css-class (cdata / implied)	The css-class attribute defines the css class to associate with the object’s container when it is rendered.
		types (styles / implied)	The types attribute has only one value - 'styles'. When its value is set to 'styles', this attribute indicates that the list of system pickers to be rendered is associated with a list of metadata styles.
		use-container (false \| true / implied)	The use-container attribute indicates whether the list of system pickers is contained in an independent html container.
		use-default (false \| true / implied)	The use-default attribute indicates whether the definition of the system picker list should be inherited from a system picker list defined in the default page that shares the same name.
<shortcut> - <attributes> - <shortcut-list> - <shortcut>	0 or more		The <shortcut> element is used to define a single system picker item.
		append-state (cdata / implied)	The append-state attribute indicates whether the system picker item (shortcut) will include the page’s state when rendered.
		base-bean (cdata / implied)	The base-bean attribute indicates the bean from the page’s bean hierarchy associated with the system picker item (shortcut). This bean is used in tasks such as resolving features. (If this attribute is not set, the application tries to use the base-bean attribute for the parent <shortcut-list> element.)
		base-bone (cdata / implied)	The base-bone attribute defines the name of a JavaScript bone with which the system picker item (shortcut) is associated. If present, this bone is used to find the DHTML methods defined in other attributes of the system picker item.
		desc (cdata / implied)	The desc attribute provides a descriptor that the application uses to display the system picker item if the desc-id attribute is missing.
		desc-id (cdata / implied)	The desc-id attribute provides the Resource Bundle item id that the application uses to display the system picker item in the language of the user's locale.
		feature-id (cdata / implied)	The feature-id attribute represents a feature that is evaluated to determine whether the system picker item should be displayed. (This evaluation takes place when the HTML is created and can be overridden by the DHTML evaluation - specified by the dhtml-show attribute - that takes place when the user interacts with the system picker item.)
		enable-feature-id (cdata / implied)	The enable-feature-id attribute represents a feature that is evaluated to determine whether the system picker item should appear enabled or disabled when it is displayed. (This evaluation takes place when the HTML is created and can be overridden by the DHTML evaluation - specified by the dhtml-enabled attribute - that takes place when the user interacts with the system picker item.)
		check-feature-id (cdata / implied)	The check-feature-id attribute represents a feature that is evaluated to determine whether the system picker item should appear checked or cleared when rendered. (This evaluation takes place when the HTML is created and can be overridden by the DHTML evaluation - specified by the dhtml-checked attribute - that takes place when the user interacts with the system picker item.)
		dhtml-show (cdata / implied)	The dhtml-show attribute represents a DHTML code segment that is evaluated to determine whether the system picker item should be displayed. (This evaluation takes place when the user interacts with the system picker item and overrides the results of the evaluation that takes place when the HTML is created - specified by the feature-id attribute.)
		dhtml-enabled (cdata / implied)	The dhtml-enabled attribute represents a DHTML code segment that is evaluated to determine whether the system picker item should appear enabled or disabled when it is displayed. (This evaluation takes place when the user interacts with the system picker item and overrides the results of the evaluation that takes place when the HTML is created - specified by the enable-feature-id attribute.)
		dhtml-checked (cdata / implied)	The dhtml-checked attribute represents a DHTML code segment that is evaluated to determine whether the system picker item should appear checked or cleared when it is displayed. (This evaluation takes place when the user interacts with the system picker item and overrides the results of the evaluation that takes place when the HTML is created - specified by the check-feature-id attribute.)
		extra-url (cdata / implied)	The extra-url attribute defines a URL segment that will be appended to the link’s URL.
		href (cdata / implied)	The href attribute indicates the HTTP resource to which the application is redirected when the system picker item is clicked.
		iframe (false \| true / implied)	When the iframe attribute’s value is set to 'true', the system picker item uses the application’s iframe infrastructure to submit the user’s request to the Web server.
		img-height (cdata / implied)	If the system picker item is represented as an image, the img-height attribute indicates the height of the image.
		img-src (cdata / implied)	If the system picker item is represented as an image, the img-src attribute indicates the source path of the image.
		img-width (cdata / implied)	If the system picker item is represented as an image, the img-width attribute indicates the width of the image.
		location (prefix \| suffix / implied)	When rendering multi-column system pickers, the location attribute indicates whether this shortcut is rendered before or after the rest of the shortcuts, outside the columns block. For example, when possible colors are displayed in a grid with rows and columns of color choices, you can use the location attribute to specify that this shortcut should be displayed either above (value = 'prefix') or below (value = 'suffix') the grid.
		name (nmtoken / required)	The name attribute provides a unique identifier for the system picker item.
		onclick (cdata / implied)	The onclick attribute represents a DHTML code segment that is evaluated when the system picker item is clicked.
		selected (false \| true / implied)	The selected attribute indicates whether the system picker item is rendered as the selected item among the other links in the group.
<attributes> - <attribute>	0 or 1		The <attributes> element groups a list of attribute objects. These <attribute> elements define name-value pairs of html attributes that are added to the system picker object’s container when it is rendered.
		config-src (cdata / implied)	If the attributes are defined in a separate file, the config-src attribute tells the page configuration file the location of the attribute definition file.
		version (nmtoken / implied)	If the attributes are defined in a separate file, the version attribute indicates the release number of the attribute definition file. This attribute is useful for backwards compatibility because it lets the application know what features are available.
<attribute>	1 or more		The <attribute> element defines an html attribute name-value pair that is added to the system picker object’s container when it is rendered.
		name (cdata / required)	The name attribute defines the name of the html attribute to be added to the system picker object’s container.
		value (cdata / required)	The value attribute defines the value of the html attribute to be added to the system picker object’s container.