ListSheet Configuration

  • Article

The XML data-island identified by the MetaXML container attribute contains the configuration information used by the ListSheet HTML component (HTC).

For more information about how an XML document can be included on a page (creating an XML data-island), see XML Data-Islands.

The structure of this data-island is shown below, with links to more detailed explanations of each element. Element attributes are shown in italic and without the values that are normally associated with them. Required elements and attributes are shown in bold; optional elements and attributes are not in bold.

Ee798776.note(en-US,CS.10).gif Note

  • The XML elements and attributes in the MetaXML data-island for the ListSheet HTC must be expressed in lowercase letters.

XML Structure

<listsheet>
  <globalcurpage headers pagecontrols pagesizerecordcount scroll selectall selectionselectionbuttons sort/>
  <columns>
    <columnformat hide id id2            id3 sortdir width>Column heading name</column>
    <subobjectdatawidth labelwidth type>
      <columnformat hide id width>Column heading name</column>
    </subobject>
  </columns>
  <operations>
    <pageformid/>
    <sortformid/>
    <sublistformid/>
    <custom_opformid/>
  </operations>
</listsheet>

listsheet

This required element contains the configuration information for a ListSheet HTML component (HTC).

Parent Element

None (document root).

Required Child Elements

columns, global

Optional Child Elements

operations

Data

None.

Attributes

None.

Return to XML Structure

global

This required element specifies global characteristics of a ListSheet HTC, allowing ListSheet HTCs to exhibit different behavior in different situations.

Parent Element

listsheet

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

Attribute Description
curpage Specifies the current page number.

Optional.

Legal values: Integers.

Default value: 1.
headers Specifies whether column headings are displayed.

Optional.

Legal values: "yes" and "no". If the value is "no", the display of column headings is suppressed.

Default value: "yes".
pagecontrols Specifies whether or not page controls are displayed.

Optional.

Legal values: "yes" and "no". If the value is "no", the display of page controls is suppressed.

Default value: "yes".
pagesize Specifies the number of records displayed per page.

Optional.

Legal values: Integers.

Default value: 20.

This value is used to calculate the number of pages available for display.
recordcount Specifies the total number of records in all pages.

Optional.

Legal values: Integers.

Default value: None.

This value is used to calculate the number of pages available for display. If it is set to -1 and page controls are displayed, then no last page display or validation is performed.
scroll Controls whether or not scroll bars are available to display the entire list.

Optional.

Legal values: "yes" and "no". If the value is "no", the display of scroll bars is suppressed, resulting in a ListSheet HTC that is the height of the entire list (scrolling in the browser might be required in this case).

Default value: "yes".
selectall Specifies whether the ListSheet HTC will show all items as selected.

Optional.

Legal values: "yes" and "no". If the value is "yes", all items are selected.

Default value: "no".
selection Specifies whether multiple selection is allowed in this instance of the ListSheet HTC.

Optional.

Legal values: "single" and "multi".

Default value: "single".

The Select All and Unselect All buttons are only displayed when the value is "multi".
selectionbuttons Specifies whether the Select All and Unselect All buttons are displayed.

Optional.

Legal values: "yes" and "no". If the value is "no", display of the Select All and Unselect All buttons is suppressed.

Default value: "yes".
sort Specifies whether clicking on a column heading sorts the records according to the values in that column.

Optional.

Legal values: "yes" and "no". If the value is "no", column sorting is disabled and the firing of the OnPage event is suppressed.

Default value: "yes".

Return to XML Structure

columns

This required element contains the descriptions of the various columns displayed by the ListSheet HTC.

Parent Element

listsheet

Required Child Elements

column (at least one)

Optional Child Elements

subobject

Data

None.

Attributes

None.

Return to XML Structure

column

This required element provides configuration information about a particular column in a ListSheet HTC.

Parent Element

columns

Required Child Elements

None.

Optional Child Elements

None.

Data

The name of the column as the user sees it.

Attributes

Attribute Description
format Specifies that special formatting should be used for this column.

Optional.

Legal values: "select", "password", "float". See below for additional details.

Default value: None.

The value "select" will look up the display value from a select list within the meta-data.

The value "password" will mask the display in the same manner as an HTML password input element.

The value "float" will display the data as a normalized decimal number.
hide Specifies whether the column is displayed.

Optional.

Legal values: "yes" and "no". If the value is "yes", display of this column is suppressed.

Default value: "no".
id Provides the identifier used to associate this column with its corresponding first-level data.

Required.

Legal values: A string that uniquely identifies the corresponding first-level data in the XML data island identified by the DataXML container attribute.

Default value: None.

The ListSheet HTC expects to find this identifier as an XML element in the first-level of the data to be displayed.
id2 Provides the identifier used to associate this column with its corresponding second-level data.

Optional.

Legal values: A string that uniquely identifies the corresponding second-level data in the XML data island identified by the DataXML container attribute.

Default value: None.

The ListSheet HTC expects to find this identifier as an XML element in the second-level of the data to be displayed.

This attribute must be present for each column to be displayed as the second-level of a two- or three-tiered list.
id3 Provides the identifier used to associate this column with its corresponding third-level data.

Optional.

Legal values: A string that uniquely identifies the corresponding third-level data in the XML data island identified by the DataXML container attribute.

Default value: None.

The ListSheet HTC expects to find this identifier as an XML element in the third-level of the data to be displayed.

This attribute must be present for each column to be displayed as the third-level of a two- or three-tiered list.
sortdir When present, specifies the initial sort column and the direction of the sort.

Optional.

Legal values: "asc" and "desc" (ascending or descending, respectively).

Default value: None.

If more than one column has this attribute set, only the first one has any effect.
width Specifies an initial width for the column.

Optional.

Legal values: An integer between 0 and 100, representing column width as a percentage of control width. The specified widths of all columns are normalized if they do not add up to 100.

Default value: None.

If a width is not specified, the width percentage is calculated as the total width divided by the number of displayed columns.

Remarks

At least one column element is required, though typically several column elements will be specified.

Return to XML Structure

subobject

This optional element specifies details about the data displayed in the detail rows of heterogeneous grouped lists. This data is always specified as the second-level data in the DataXML container attribute, and can be displayed in either the list-style or the properties-style, as specified by the type attribute.

Parent Element

columns

Required Child Elements

column

Optional Child Elements

None.

Data

None.

Attributes

Attribute Description
datawidth Specifies an initial width for the data column when the type attribute is set to "properties".

Optional.

Legal values: An integer between 0 and 100, representing data column width as a percentage of control width.

Default value: 50.

When the type attribute is set to "list", this attribute is irrelevant and is ignored if present.
labelwidth Specifies an initial width for the label column when the type attribute is set to "properties".

Optional.

Legal values: An integer between 0 and 100, representing label column width as a percentage of control width.

Default value: 30.

When the type attribute is set to "list", this attribute is irrelevant and is ignored if present.
type Specifies which type of heterogeneous grouped list will be displayed.

Required.

Legal values: "list" and "properties".

Default value: None.

Remarks

Typically, more than one column element will be specified.

The presence of the subobject element indicates that the ListSheet HTC will display as a heterogeneous grouped list. In this case, the id2 and id3 attributes of the top-level column elements are not used.

When the subobject element is absent, the ListSheet HTC will display as either a flat list, a two-level homogeneous grouped item list, or a three-level homogeneous grouped item list, depending on how many of the attributes id, id2, and id3 are specified.

Return to XML Structure

column

This required element provides configuration information about a particular row or column in a ListSheet displaying a heterogeneous grouped list. Whether it is a column or row depends on whether the type attribute of the subobject element is set to "list"****or "properties", respectively.

Parent Element

subobject

Required Child Elements

None.

Optional Child Elements

None.

Data

The name of the column or the label on the row as the user sees it.

Attributes

Attribute Description
format Specifies that special formatting should be used for this column or row.

Optional.

Legal values: "select", "password", "float". See below for additional details.

Default value: None.

The value "select" will look up the display value from a select list within the meta-data.

The value "password" will mask the display in the same manner as an HTML password input element.

The value "float" will display the data as a normalized decimal number.
hide Specifies whether the column or row is displayed.

Optional.

Legal values: "yes" and "no". If the value is "yes", display of this column or row is suppressed.

Default value: "no".
id Provides the identifier used to associate this column or row with its corresponding second-level data.

Required.

Legal values: A string that uniquely identifies the corresponding second-level data in the XML data island identified by the DataXML container attribute.

Default value: None.

The ListSheet HTC expects to find this identifier as an XML element in the second-level of the data to be displayed.
width Specifies an initial width for the data column when the type attribute of the subobject element is set to "list".

Optional.

Legal values: An integer between 0 and 100, representing data column width as a percentage of control width. The specified widths of all columns are normalized if they do not add up to 100.

Default value: Calculated by dividing the number of subobject columns by 80, resulting in uniform column width in the right-hand 80% of the overall width of the ListSheet HTC.

When the type attribute of the subobject control is set to "properties", this attribute is irrelevant and is ignored if present.

Remarks

If the subobject element is present, at least one column element is required, though in general, multiple column elements will be specified.

Return to XML Structure

operations

This optional element contains other elements that, when present, cause certain standard XMLHTTP operations to be performed when specific events are fired. This set of operations can also be extended with custom operations.

Parent Element

listsheet

Required Child Elements

None.

Optional Child Elements

page, sort, sublist, custom_op

Data

None.

Attributes

None.

Remarks

All child elements, including custom child elements, represent different operations that will be performed when different events occur.

If the operations element is present but contains no child elements, it will be ignored.

The operations corresponding to the child elements are known as XMLHTTP operations. For more information about XMLHTTP operations, see XMLHTTP Operations and Fetch Pages.

Return to XML Structure

page

This optional element corresponds to a standard XMLHTTP operation available with the ListSheet HTC. When this element is present, the entire list reloads with new data after the OnNewPage event fires. The new data is returned from a page on the server and must not contain anything except the data in the standard XML data format.

Parent Element

operations

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

Attribute Description
formid Specifies the identifier of the form that will be posted when the OnNewPage event fires.

Required.

Legal values: Valid id attribute of a form element.

Default value: None.

Remarks

For more information about XMLHTTP operations, see XMLHTTP Operations and Fetch Pages.

The identifier of the corresponding form is set as the formid attribute. The action attribute of the form must be set to the post page: the page that returns the new page of data.

The following table shows the arguments that are sent when the form is posted.

Argument Description
op The value of this attribute is set to "page". This argument, combined with the post page specified as an attribute of the form, allows specific server-side code to be executed in response to the OnNewPage event.

The op argument allows the same post page to process more than one operation, branching to perform different operations based on the value of this argument.
prevpage The value of this attribute is set to number of the page currently being displayed, soon to be the previous page displayed.
page The value of this attribute is set to the number of the new page to be displayed.
column The value of this attribute is set to the ID of the sort column for the new page of data. This ID is the name of the relevant child element of the record element.
direction The value of this attribute is set to either "asc" or "desc", depending on whether the new page of data should be sorted in the ascending direction or the descending direction, respectively.

For more information about how the posting of forms is used to perform operations on the server, including saving changes to data, see Saving Changes to Data.

Return to XML Structure

sort

This optional element corresponds to a standard XMLHTTP operation available with the ListSheet HTC. When this element is present, the entire list reloads with new data after the OnHeaderClick event fires. The new data is returned from a page on the server and must not contain anything except the data in the standard XML data format.

Parent Element

operations

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

Attribute Description
formid Specifies the identifier of the form that will be posted when the OnHeaderClick event fires.

Required.

Legal values: Valid id attribute of a form element.

Default value: None.

Remarks

For more information about XMLHTTP operations, see XMLHTTP Operations and Fetch Pages.

The identifier of the corresponding form is set as the formid attribute. The action attribute of the form should be set to the post page: the page that returns the first page of data, re-sorted as specified.

The following table shows the arguments that are sent when the form is posted.

Argument Description
op The value of this attribute is set to "sort". This argument, combined with the post page specified as an attribute of the form, allows specific server-side code to be executed in response to the OnHeaderClick event.

The op argument allows the same post page to process more than one operation, branching to perform different operations based on the value of this argument.
page The value of this attribute is always set to 1. This operation does not permit re-sorting the list without returning to the beginning of the list, where the "top" of the sort will be displayed.
column The value of this attribute is set to the ID of the sort column for the new page of data. This ID is the name of the relevant child element of the record element.
direction The value of this attribute is set to either "asc" or "desc", depending on whether the new page of data should be sorted in the ascending direction or the descending direction, respectively.

For more information about how the posting of forms is used to perform operations on the server, including saving changes to data, see Saving Changes to Data.

Return to XML Structure

sublist

This optional element corresponds to a standard XMLHTTP operation available with the ListSheet HTC. When this element is present, the list under the currently selected item loads with data when this operation is invoked using the reload method, which should be called in the OnGroupOpen event handling routine. This means that the retrieval of detail data can be deferred until it needs to be displayed.

Parent Element

operations

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

Attribute Description
formid Specifies the identifier of the form that will be posted when the OnGroupOpen event fires.

Required.

Legal values: Valid id attribute of a form element.

Default value: None.

Remarks

For more information about XMLHTTP operations, see XMLHTTP Operations and Fetch Pages.

The identifier of the corresponding form is set as the formid attribute. The action attribute of the form should be set to the post page, the page that returns the detail data.

The following table shows the arguments that are sent when the form is posted.

Argument Description
op The value of this argument is set to "sublist". This argument, combined with the post page specified as an attribute of the form, allows specific server-side code to be executed in response to the OnGroupOpen event.

The op argument allows the same post page to process more than one operation, branching to perform different operations based on the value of this argument.
xmllist The value of this argument is set to the XML of the list item that was clicked, so that the post page knows what sub-items to return.

In some situations it might be appropriate to include other parameters in the posted form as part of fetching the correct XML response. For example, suppose a response page is designed to be shared by several different pages, returning different results based on which page calls it. In this case, the form might have a hidden element containing the page name so the response page will know which page called it.

For more information about how the posting of forms is used to perform operations on the server, including saving changes to data, see Saving Changes to Data.

Return to XML Structure

custom_op

Custom operation elements, which are optional, correspond to custom XMLHTTP operations defined for a ListSheet HTC. When a custom operation element is present, the entire list reloads when the reload method is called with its sOp parameter set to the custom name for this element.

Parent Element

operations

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

Attribute Description
formid Specifies the identifier of the form that will be posted when the reload method is called with its sOp parameter set to the custom name for this element.

Required.

Legal values: Valid id attribute of a form element.

Default value: None.

Remarks

For example, if the element double_sort is included as a custom operation, and the reload method is called with its sOp parameter set to "double_sort", the form with the specified identifier will be posted. For example:

bRetVal = elListSheet.reload("double_sort")

The reload method returns False if no XML is returned or if any error elements are present, and True otherwise.

For more information about XMLHTTP operations, see XMLHTTP Operations and Fetch Pages.

The identifier of the corresponding form is set as the formid attribute. The action attribute of the form should be set to the post page, the page that returns the new data.

The following table shows the arguments that are sent when the form is posted.

Argument Description
op The value of this attribute is set to "custom_op". This argument, combined with the post page specified as an attribute of the form, allows specific server-side code to be executed in response to a particular invocation of the reload method.

The op argument allows the same post page to process more than one operation, branching to perform different operations based on the value of this argument.

In some situations it might be appropriate to include other parameters in the posted form as part of fetching the correct XML response. For example, suppose a response page is designed to be shared by several different pages, returning different results based on which page calls it. In this case, the form might have a hidden element containing the page name so the response page will know which page called it.

For more information about how the posting of forms is used to perform operations on the server, including saving changes to data, see Saving Changes to Data.

Return to XML Structure


All rights reserved.