TreeView Configuration
The TreeView control requires that the tree to be displayed be passed to it in the form of an XML data-island. The container attribute DataXML is set to the ID of this data-island.
For more information about the ways in which an XML document can be included on a page (creating an XML data-island), see XML Data-Islands.
It is important to note that the TreeView HTC is the only Commerce Server Business Desk HTC that does not have any configuration data. In other words, there is no MetaXML container attribute that must be specified for the TreeView HTC. Only data is provided, using the DataXML container attribute. The nested nature of the elements provides the nesting shown in the displayed tree.
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 bolded.
Note
- The XML elements and attributes, not including the arbitrarily named elements, in the MetaXML data-island for the TreeView HTC must be expressed in lowercase letters.
XML Structure
<documentselection>
<level_1_elementcaption closed enabled hidden queryid selected skip>data that might be displayed
<level_2_elementcaption closed enabled hidden queryid selected skip>data that might be displayed
<level_3_elementcaption closed enabled hidden queryid selected skip>data that might be displayed
Note that levels can go to an arbitrary depth...
</level_3_element>
</level_2_element>
</level_1_element>
<another_level_1_elementcaption closed enabled hidden queryid selected skip>data that might be displayed
<another_level_2_elementcaption closed enabled hidden queryid selected skip>data that might be displayed
<expand />
</another_level_2_element>
</another_level_1_element>
<operations>
<expandformid/>
<custom_opformid/>
</operations>
</document>
document
This required element contains the configuration information for a TreeView HTML Component (HTC).
Parent Elements
None (document root)
Required Child Elements
None.
Optional Child Elements
operations, arbitrary_tree_nodes
Data
None.
Attributes
Attribute | Description |
selection | Specifies whether multiple selection will be allowed.
Optional. Legal values: "single" and "multi", allowing single and multiple selection, respectively. Default value: "single". |
Remarks
To be meaningful, the document element must contain one or more elements besides the operations element. The names of these other elements is arbitrary, and in certain circumstances these names are used as the display string for the corresponding tree node shown to the user.
Return to XML Structure
level_N_element
Other than the document element, the two types of expand elements, and the operations element, the names of all elements in the data-island for the TreeView HTC are arbitrary. There are circumstances where the element name itself is displayed in the control; in such cases extra care must be taken with regard to the element names. Otherwise, they can be truly arbitrary with no effect on the functioning of the TreeView HTC. The arbitrary elements may contain data and may contain the caption attribute, but need not.
Parent Element
document, arbitrary_tree_element
Required Child Elements
None.
Optional Child Elements
arbitrary_tree_element
Data
Optionally, a string that will be displayed to the user as the name of the tree node, if no caption attribute value is provided for this element.
Attributes
Attribute | Description |
caption | Provides the highest precedence choice for text to be displayed to the user.
Optional. If present, it overrides both data supplied with the element and the element name itself. |
closed | When set to "yes", the tree item corresponding to this element will initially be displayed as closed.
Optional. If not present, or set to any other value, and assuming that the element has child elements, the corresponding item is initially displayed as open. |
enabled | When set to "no", the tree item corresponding to this element will be disabled.
Optional. Disabled items are dimmed, and their events are suppressed. Further, even if they have child items, they cannot to be opened and closed. If this attribute is not present, or set to any other value, the item is enabled, resulting in normal display and operation. |
hidden | When set to "yes", the tree item corresponding to this element will be hidden.
Optional. Any child items are hidden as well. If this attribute is not present, or set to any other value, the item is visible. |
queryid | This attribute is reserved for use by the TreeView HTC itself and should not be set prior to invoking the TreeView HTC. |
selected | When set to "yes", the tree item corresponding to this element will be initially displayed as selected.
Optional. Legal values are "yes" and "no". After initial loading, this attribute continues to be maintained. In other words, it is set to either "yes" or "no" as the corresponding tree item is selected and deselected, respectively. |
skip | When set to "yes", the corresponding element will be skipped when building the tree structure.
Optional. If this attribute is not present, or set to any other value, the element is not skipped and results in an item in the tree being displayed (subject to other effects of other attributes). Unlike the hidden attribute, setting the skip attribute for an element to "yes" does not prevent its child elements from being displayed. |
Remarks
The text that is displayed to the user for a particular item in the tree can come from one of three places, with a specific order of precedence, as follows:
If the element has a caption attribute, the value of that attribute is displayed.
Otherwise, if the element contains data, that data is displayed.
Otherwise, the element name itself is displayed.
For example, consider the following XML tree structure, which shows the actual text to be displayed in bold font. Note the presence of the expand element, which allows deferred loading of portions of the tree.
<Item1A>
<LevelTwo caption=Item2A>Data that will not be displayed
<LevelThree>Item3A</LevelThree>
<LevelThree>Item3B</LevelThree>
</LevelTwo>
</Item1A>
<Item1B>
<LevelTwo caption=Item2B>More text that will not be displayed
<LevelThree>Item3C</LevelThree>
<LevelThree>Item3D</LevelThree>
</LevelTwo>
<LevelTwo>Item2C
<expand />
</LevelTwo>
</Item1B>
<Item1C>
<LevelTwo caption=Item2D />
</Item1B>
Given the XML tree structure above, the TreeView HTC displays the following tree when fully expanded, and assuming that the one expand element resulted in a single item named "Item3E (retrieved using expand operation)" being returned.
[-] Item1A
[-] Item2A
Item3A
Item3B
[-] Item1B
[-] Item2B
Item3C
Item3D
[-] Item2C
Item3E (retrieved using expand operation)
[-] Item1C
Item2D
Return to XML Structure
expand
This optional element marks a place in the tree structure where the loading of subordinate tree elements is deferred until the element in question is actually expanded by the user.
Parent Elements
arbitrary_element
Required Child Elements
None.
Optional Child Elements
None.
Data
None.
Attributes
None.
Remarks
There are two distinct types of expand elements that can occur in the DataXML data-island. This is the first type, which can occur within the arbitrarily named tree elements, and which serves as a placeholder for where the loading of a section of the tree has been deferred, and thus where expansion can occur.
Together, the two types of expand elements are used to perform a special type of XMLHTTP Operation available with the TreeView HTC. This operation allows the loading of the subordinate tree items to be deferred until the containing tree item is opened. In circumstances involving large numbers of items, such deferral can drastically improve the performance of the initial loading and display of the tree.
This element, when present as the sole child element of another element, causes that element to be displayed as a containing item. In other words, with a plus sign indicating the (potential) presence of one or more subordinate items that are not currently being shown. The containing item must be initially closed because the subordinate items have not yet been retrieved. Indeed, the presence of the expand element implies that the closed attribute of its containing element is set to "yes".
When a tree item is opened by a user, the OnItemOpen event fires. If the data for the item being opened is already loaded, no event handler need be assigned to this event. On the other hand, if this event fires and the TreeView HTC finds an expand element rather than the requisite data, an event handling routine needs to be in place. This routine is responsible for adding arguments to the form so that the response page knows which node is being expanded. If no event handling routine has been assigned to the OnItemOpen event and an expand element is encountered, no arguments will be added to the form, and the operation is not likely to return the proper data.
Arguments are added to the form in the standard fashion: hidden input elements are embedded in the form, and the event handling routine simply assigns the appropriate values to those input elements. For example, suppose there is a form element with its id attribute set to "tvform" and it contains a hidden input element with its id attribute set to "category". The event handling routine can assign the value "chocolate" to that input element with the following line of code:
tvform.category.value = 'chocolate'
Once the event handling routine, if any, has executed, and if the TreeView HTC has found an expand element where it needs to show a newly expanded section of the tree, the TreeView HTC will call the reload method with the sOp parameter set to "expand".
For more information about XMLHTTP Operations, see XMLHTTP Operations and Fetch Pages.
The identifier of the corresponding form is set as the formid attribute of the other expand element, the one that is subordinate to the operations element. Unless you were to change the value of this attribute dynamically, all expansion must be handled by the same form. On the response page at the server, the passed arguments must be used to determine the item being expanded, so that the correct data can be returned.
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
operations
This optional element contains other elements that, when present, cause certain custom XMLHTTP Operations to be performed when the reload method is invoked with certain parameter values.
Parent Elements
document
Required Child Elements
None.
Optional Child Elements
expand, arbitrary_operations_elements
Data
None.
Attributes
None.
Remarks
If the operations element is present but contains no child elements, it is ignored.
Return to XML Structure
expand
This optional element identifies the form element that will be used to post the expansion request to the server.
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 OnItemOpen event fires and its handler calls the reload method with the sOp parameter set to "expand".
Required. Legal values: Valid id attribute of a form element. Default value: None. |
Remarks
There are two distinct types of expand elements that can occur in the DataXML data-island. This is the second type, which can occur within the operations element, and which serves to identify the form element that will be used to post the expansion request to the server.
Together, the two types of expand elements are used to perform a special type of XMLHTTP Operation available with the TreeView HTC. This operation allows the loading of the subordinate tree items to be deferred until the containing tree item is opened. In circumstances involving large numbers of items, such deferral can drastically improve the performance of the initial loading and display of the tree.
If any of the other type of expand elements exist in the DataXML data-island, then this expand element must be present, providing the ID of the form used to handle deferred item loading. The action attribute of this form must be set to the post page, the page that returns the new, expand section of the tree.
Like other HTTP/XML Operations, the new data returned from the post page on the server must not contain anything except the data in the standard XML data format.
The returned set of subordinate items actually replaces the expand element in the tree. This means that a particular expand operation will normally only occur once for each instantiation of the TreeView HTC.
For more information about XMLHTTP Operations, see XMLHTTP Operations and Fetch Pages.
This type of expand element is optional, but must be present if any of the other type of expand elements are present.
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 correspond to custom XMLHTTP Operations defined for a TreeView HTC. When a custom operation element is present, the entire tree reloads when the reload method is called with its sOp parameter set to the custom name for the element.
For example, if the element alpha_sort is included as a custom operation, and the reload method is called with its sOp parameter set to "alpha_sort", the form with the specified identifier will be posted. For example,
elTreeView.reload("alpha_sort")
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 more information about XMLHTTP Operations, see XMLHTTP Operations and Fetch Pages.
The identifier of the corresponding form is set as an attribute. The action attribute of the form should be set to the post page, the page that returns the new tree data.
The following table shows the arguments that are automatically 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. |
Additional arguments can be added to the form in the standard fashion: hidden input elements are embedded in the form, and the appropriate argument values are assigned to those input elements prior to the form being posted.
Custom operation elements are optional.
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