Share this page
Description
An object representing a collection of XML elements. This object can be accessed using one of the following methods or properties:
- XMLData.ChildElementsByPath
- XMLElement.ChildElements
- XMLElement.ChildElementsByPath
- XMLElementsColl.AllItemsByName
Properties
 AllItemsByName | Returns a collection of elements with the specified name. |
| Count | Returns the number of elements in the collection. |
| Item | Returns the specified element from the collection. |
| ItemByName | Returns the element with the specified tag name. If more than one item has the same tag name, you can specify which occurrence of the tag name you want to retrieve. |
AllItemsByName Property
Description
Returns a collection of elements with the specified name.
Syntax
XMLElementsColl.AllItemsByName ( Name )
Argument | Type | Description |
|---|---|---|
Name | String | The element name you want to find. |
Return Value
IMPORTANT
The returned item collection is a copy of the specified items. Therefore, any changes you make to the original element collection after retrieving this collection (such as adding or removing an item with the specified name) are not included. For example, if you use the Count property on the returned item collection, the returned value is the same before and after adding or removing elements to or from the original collection. To ensure that the collection is up-to-date after changes are made, use the AllItemsByName property again to retrieve the updated collection.
ExampleThe following function loads an XML file and then uses the AllItemsByName property to find the quantity of children under the root that have the same name as the first child of the root.
Set doc = XMLUtil.CreateXML()
doc.LoadFile "c:\example.xml"
Set root = doc.GetRootElement()
Set children = root.ChildElements()
if children.Count() <> 0 then
Set firstChild = children.Item(1)
firstChildName = firstChild.ElementName()
Set sameNameChildren = children.AllItemsByName(firstChildName)
msg = "My first child name is " + firstChildName + " and I have " + FormatNumber(sameNameChildren.Count(),0) + " of them."
End If
msgbox msg
Count Property
Description
Returns the number of elements in the collection.
Syntax
XMLElementsColl.Count
Return Value
Number
ExampleSet doc = XMLUtil.CreateXML()
doc.LoadFile "c:\example.xml"
Set root = doc.GetRootElement()
Set children = root.ChildElements()
if children.Count() <> 0 then
Set firstChild = children.Item(1)
firstChildName = firstChild.ElementName()
Set sameNameChildren = children.AllItemsByName(firstChildName)
msg = "My first child name is " + firstChildName + " and I have " + FormatNumber(sameNameChildren.Count(),0) + " of them."
End If
msgbox msg
Item Property
Description
Returns the specified element from the collection.
Syntax
XMLElementsColl.Item (ID, [Index] )
Argument | Type | Description |
|---|---|---|
ID | Variant | The name (with quotes) of the element to return, or a numeric index (with or without quotes) that denotes the position of the item in the collection. The first item in a collection is numbered 1. |
Index | String | Optional. If you specify an element name for the ID argument, you can specify which occurrence of the name you want to find and return. If no index value is specified with an element name, the first occurrence of the element with the specified name is returned. |
Return Value
ExampleThe following function loads an XML file and then uses the Item property to find the quantity of children under the root that have the same name as the first child of the root.
Set doc = XMLUtil.CreateXML()
doc.LoadFile "c:\example.xml"
Set root = doc.GetRootElement()
Set children = root.ChildElements()
if children.Count() <> 0 then
Set firstChild = children.Item(1)
firstChildName = firstChild.ElementName()
Set sameNameChildren = children.AllItemsByName(firstChildName)
msg = "My first child name is " + firstChildName + " and I have " + FormatNumber(sameNameChildren.Count(),0) + " of them."
End If
msgbox msg
ItemByName Property
Description
Returns the element with the specified tag name. If more than one item has the same tag name, you can specify which occurrence of the tag name you want to retrieve. If not specified, the first occurrence is retrieved.
Syntax
XMLElementsColl.ItemByName (Tag, [Index])
Argument | Type | Description |
|---|---|---|
Tag | String | The tag name of the element to return. |
Index | Number | Optional. The occurrence of the tag name to use. |
Return Value
ExampleThe following example uses the ItemByName property to print the number of children of the root element named Cartman. This example shows the use of ItemByName with and without the optional index argument.
Set doc = XMLUtil.CreateXML()
doc.LoadFile "c:\example.xml"
Set root = doc.GetRootElement()
Set children = root.ChildElements()
Set child = children.ItemByName("Cartman")
numOfChildren = 0
While Not child Is nothing
numOfChildren = numOfChildren+1
Set child = children.ItemByName("Cartman",numOfChildren+1)
Wend
msgbox "The number of children named Cartman is " & numOfChildren
.
