Module Configuration Files

The module configuration files, which contain XML, specify the configuration information at the module level for Commerce Server Business Desk. Each module configuration file is referenced by a moduleconfig element in the master configuration file, together making up the overall configuration of categories and modules for a particular instance of Business Desk. The module configuration files can be thought of as include files for the master configuration file.

This topic explains the contents of the module configuration files. Specifically, it shows the XML structure, where each element name is a link to a description of the contents of that element, and where the attributes of each element are shown in italic, without the equal sign and value that normally accompanies them. Required elements and attributes are shown in bold; optional elements and attributes are not bolded.

The XML schema for the master configuration file can be found in a file Bdmodule-schema.xml in the Business Desk Config folder.

Note

• The XML elements and attributes in the module configuration files must be expressed in lowercase letters.

XML Structure

<?xml version = '1.0' encoding='windows-1252' ?>
<config>
  <actions>
    <actionidhelptopic>
      <name>action name</name>
      <tooltip>action tooltip</tooltip>
      <tasks>
        <taskiconid type>
          <gotoaction>menu item name</goto>
          <posttoactionformname>menu item name</postto>
          <name>task name</name>
          <key>access key from above</key>
          <tooltip>task tooltip</tooltip>
        </task>
        ...
        <taskicon id type>
          ...
        </task>
      </tasks>
    </action>
    ...
    <actionidhelptopic>
      ...
    </action>
  </actions>
  <modules>
    <moduleid>
      <name>module name</name>
      <tooltip>module tooltip</tooltip>
    </module>
    ...
    <module id>
      ...
    </module>
  </modules>
</config>

config

This required element contains all configuration information in the module configuration files.

Parent Element

None (document root).

Required Child Elements

actions, modules

Optional Child Elements

None.

Data

None.

Attributes

None.

Return to XML Structure

actions

This required element contains one or more action elements specified for the modules defined in this module configuration file.

Parent Element

config

Required Child Elements

action (at least one)

Optional Child Elements

None.

Data

None.

Attributes

None.

Return to XML Structure

action

This required element specifies a particular action available within the module. This includes the URL of the ASP page associated with the action, and identifies the appropriate Help topic and the tasks available within the action.

Parent Element

actions

Required Child Elements

name, tooltip, tasks

Optional Child Elements

None.

Data

None.

Attributes

Attribute	Description
helptopic	Specifies the name of the Help file that corresponds to this action. Required. Legal values: The name of an existing HTML Help file, specified without a path or a file extension. Default value: None.
id	Specifies the URL of the entry point ASP page for this action. Required. Legal values: The URL of an existing entry point ASP page, specified relative to the Commerce Server Business Desk root. Default value: None.

Remarks

Every ASP page that is referenced as the target of a task or module must be identified with an action element. This is required for the Business Desk Framework to properly manage navigation between modules and between the action pages in a module.

Return to XML Structure

name

This required element provides a name for this action.

Parent Element

action

Required Child Elements

None.

Optional Child Elements

None.

Data

The name of the action.

Attributes

None.

Remarks

If the specific action name contains any HTML formatting directives, proper escaping must be used. For example, the string &lt; must be used for the "<" character, the string &gt; must be used for the ">" character, and the string &amp; must be used for the "&" character.

Return to XML Structure

tooltip

This required element provides text that is used as the title attribute for the action.

Parent Element

action

Required Child Elements

None.

Optional Child Elements

None.

Data

The tooltip string associated with the action, which is displayed when the cursor is over the task button.

Attributes

None.

Return to XML Structure

tasks

This required element contains zero or more task elements defined for this action.

Parent Element

action

Required Child Elements

None.

Optional Child Elements

task

Data

None.

Attributes

None.

Remarks

A tasks element does not typically contain zero elements. This corresponds to an action page with no tasks.

There cannot be more than 22 task elements specified within any given tasks element.

Return to XML Structure

task

This required element specifies a particular task available from this action. This includes a specification of one or more ASP pages that serve as entry points to the task, and provides the task name and tooltip information.

Parent Element

tasks

Required Child Elements

name, key, tooltip, goto, postto

(goto and postto are mutually exclusive)

Optional Child Elements

task

Data

None.

Attributes

Attribute	Description
icon	Specifies the (pathless) name of an icon file to display in the corresponding task button. Optional. Legal values: The name of an existing icon file, specified without a path. Default value: None. If no icon file is supplied, the value of the name element contained in the task element is used as button text.
id	Specifies an identifier for the task, which is typically set to the same value as the icon attribute, but without the "task" prefix. Required. Legal values: A unique string to distinguish the task from other tasks. Default value: None. The following id attribute values result in special framework behavior: "save", "saveback", "savenew", "back", and "find": find: stays on the same page and toggles the display of the find pane on the page. back: always re-enabled after a task is executed. save, saveback and savenew: enabled/disabled automatically by the framework if you have set the proper event handlers on the associated events in the master EditSheet HTC.
type	Specifies that a task menu should be used to distinguish between multiple sub-tasks. Optional. Legal values: The string "menu" is the only legal value Default value: None. This attribute should be set to the value "menu" when multiple goto or postto elements are provided and a task menu is to be used to choose between the available sub-tasks. Otherwise, this attribute should not be present.

Remarks

Each task appears as a task button at the top of the page when the action page is displayed.

Return to XML Structure

goto

This element specifies one of possibly several ASP pages that serve as entry points to this task. Every task must contain at least one goto or postto element, and may contain more than one. However, goto and postto elements cannot both appear in the same task.

Parent Element

task

Required Child Elements

None.

Optional Child Elements

None.

Data

When a task menu is being used, the element data is used as the task menu item name corresponding to this choice.

Attributes

Attribute	Description
action	Specifies the URL of one of possibly several entry point ASP pages for this task. Required. Legal values: The URL of an existing entry point ASP page, specified relative to the Commerce Server Business Desk root. Default value: None. This value must correspond to the value of the id attribute for one of the action elements specified in this module configuration file.

Remarks

When multiple goto elements are specified, the preferred method for allowing the user to decide between them is to use a task menu. The type attribute of the task element should be set to the value "menu", and the multiple goto elements should each contain data to be used as the name of that choice in the drop-down task menu.

When task menus are used, the icon specified by the icon attribute should specify that the task is a task menu. For more information about task icons, and task menu icons in particular, see Icons.

When task menus are used, there cannot be more than 30 task menu items (goto elements) specified.

Another method lets users choose in a selection dialog box provided by the module. At times, however, the choice is determined by other factors, such as the type of item selected in a ListSheet HTC.

Return to XML Structure

postto

This element specifies one of possibly several ASP pages that serve as entry points to this task. Every task must contain at least one postto or goto element, and may contain more than one. However, both postto and goto elements must not appear in the same task.

Parent Element

task

Required Child Elements

None.

Optional Child Elements

None.

Data

When a task menu is being used, the element data is used as the task menu item name corresponding to this choice.

Attributes

Attribute	Description
action	Specifies the URL of one of possibly several entry point ASP pages for this task. Required. Legal values: The URL of an existing entry point ASP page, specified relative to the Commerce Server Business Desk root. Default value: None. This value must correspond to the value of the id attribute for one of the action elements specified in this module configuration file.
formname	Specifies the name of the form that is posted to the URL specified by the action attribute. Required. Legal values: The name of an existing form element. Default value: None.

Remarks

When multiple postto elements are specified, the preferred method for allowing the user to decide between them is to use a task menu. The type attribute of the task element should be set to the value "menu", and the multiple postto elements should each contain data to be used as the name of that choice in the drop-down task menu.

When task menus are used, the icon specified by the icon attribute should be of the correct type to specify that the task is a task menu. For more information about task icons, and task menu icons in particular, see Icons.

When task menus are used, there cannot be more than 30 task menu items (postto elements) specified.

At times, however, the choice is determined by other factors, such as the type of item selected in a ListSheet HTC. At times, however, the choice is determined by other factors, such as the type of item selected in a ListSheet HTC.

Return to XML Structure

name

This required element specifies the name of this task.

Parent Element

task

Required Child Elements

None.

Optional Child Elements

None.

Data

The name of the task.

Attributes

None.

Remarks

This name is used as the button text if no icon file is specified for this task. Otherwise the name is not used.

If the specific task name contains any HTML formatting directives, proper escaping must be used. For example, the string &lt; must be used for the "<" character, the string &gt; must be used for the ">" character, and the string &amp; must be used for the "&" character.

Return to XML Structure

key

This required element specifies a character that serves as the accessibility key associated with the task.

Parent Element

task

Required Child Elements

None.

Optional Child Elements

None.

Data

The single character that serves as the accessibility key for this task, which should correspond to an underlined character in the task name.

Attributes

None.

Remarks

The accessibility key for the task should specify the same character identified with underlining in the task name. For example, if the task name is specified such that the user sees the string Delete, the character "d" must appear between the <key> and </key> tags.

Return to XML Structure

tooltip

This optional element provides a very brief description of the purpose of this task, and should be more descriptive than the task name itself. The provided text is set as the title attribute for the task button, and is visible when the cursor is over the task.

Parent Element

task

Required Child Elements

None.

Optional Child Elements

None.

Data

The task tooltip, as shown when the cursor is over the task button.

Attributes

None.

Return to XML Structure

modules

This required element contains one or more module elements.

Parent Element

config

Required Child Elements

module

Optional Child Elements

None.

Data

None.

Attributes

None.

Return to XML Structure

module

This required element provides information used in the display of a module entry below a category in the navigation pane. It also identifies a corresponding action. Together, this information defines the entry points into a module.

Parent Element

modules

Required Child Elements

name, tooltip

Optional Child Elements

None.

Data

None.

Attributes

Attribute	Description
id	Specifies the URL of the entry point ASP page for this module. Required. Legal values: The URL of an existing entry point ASP page, specified relative to the Commerce Server Business Desk root. Default value: None. This value must correspond to the value of the id attribute for one of the action elements specified in this module configuration file.

Remarks

A given (conceptual) module may have more than one entry point action associated with it.

Return to XML Structure

name

This required element specifies the name of the module as the Commerce Server Business Desk user sees it in the navigation pane.

Parent Element

module

Required Child Elements

None.

Optional Child Elements

None.

Data

The module name, as the user sees it.

Attributes

None.

Remarks

If the specific module name contains any HTML formatting directives, proper escaping must be used. For example, the string &lt; must be used for the "<" character, the string &gt; must be used for the ">" character, and the string &amp; must be used for the "&" character.

Return to XML Structure

tooltip

This optional element provides a very brief description of the purpose of this module, and should be more descriptive than the module name itself. The provided text is set as the title attribute for the module entry in the navigation pane.

Parent Element

module

Required Child Elements

None.

Optional Child Elements

None.

Data

The module tooltip, as shown when the cursor is over the module name.

Attributes

None.

Return to XML Structure

All rights reserved.