Although the main handle to the xml document is the XML::Mini::Document object, much of the functionality
and manipulation involves interaction with Element objects.
A Element has:
- a name
- a list of 0 or more attributes (which have a name and a value)
- a list of 0 or more children (Element or XML::MiniNode objects)
- a parent (optional, only if MINIXML_AUTOSETPARENT > 0)
newNAME
Creates a new instance of XML::Mini::Element, with name NAME
name[NEWNAME]
If a NEWNAME string is passed, the Element's name is set to NEWNAME.
Returns the element's name.
attributeNAME[SETTO[SETTOALT]]
The attribute() method is used to get and set the Element's attributes (ie the name/value pairs contained
within the tag, <tagname attrib1="value1" attrib2="value2">)
If SETTO is passed, the attribute's value is set to SETTO.
If the optional SETTOALT is passed and SETTO is false, the attribute's value is set to SETTOALT. This is
useful in cases when you wish to set the attribute to a default value if no SETTO is present, eg
$myelement->attribute('href', $theHref, 'http://psychogenic.com') will default to
'http://psychogenic.com'.
Returns the value associated with attribute NAME.
text[SETTO[SETTOALT]]
The text() method is used to get or append text data to this element (it is appended to the child list as
a new XML::MiniNode object).
If SETTO is passed, a new node is created, filled with SETTO and appended to the list of this element's
children.
If the optional SETTOALT is passed and SETTO is false, the new node's value is set to SETTOALT. See the
attribute() method for an example use.
Returns a string composed of all child XML::MiniNodes' contents.
Note: all the children XML::MiniNodes' contents - including numeric nodes are included in the return
string.
numeric[SETTO[SETTOALT]]
The numeric() method is used to get or append numeric data to this element (it is appended to the child
list as a XML::MiniNode object).
If SETTO is passed, a new node is created, filled with SETTO and appended to the list of this element's
children.
If the optional SETTOALT is passed and SETTO is false, the new node's value is set to SETTOALT. See the
attribute() method for an example use.
Returns a space separated string composed all child XML::MiniNodes' numeric contents.
Note: ONLY numerical contents are included from the list of child XML::MiniNodes.
headerNAME
The header() method allows you to add a new XML::Mini::Element::Header to this element's list of
children.
Headers return a <? NAME ?> string for the element's toString() method. Attributes may be set using
attribute(), to create headers like <?xml-stylesheet href="doc.xsl" type="text/xsl"?>
Valid XML documents must have at least an 'xml' header, like: <?xml version="1.0" ?>
Here's how you could begin creating an XML document:
my $miniXMLDoc = XML::Mini::Document->new();
my $xmlRootNode = $miniXMLDoc->getRoot();
my $xmlHeader = $xmlRootNode->header('xml');
$xmlHeader->attribute('version', '1.0');
This method was added in version 1.25.
commentCONTENTS
The comment() method allows you to add a new XML::Mini::Element::Comment to this element's list of
children.
Comments will return a <!-- CONTENTS --> string when the element's toString() method is called.
Returns a reference to the newly appended XML::Mini::Element::Comment
docTypeDEFINITION
Append a new <!DOCTYPE DEFINITION [ ...]> element as a child of this element.
Returns the appended DOCTYPE element. You will normally use the returned element to add ENTITY elements,
like
my $newDocType = $xmlRoot->docType('spec SYSTEM "spec.dtd"');
$newDocType->entity('doc.audience', 'public review and discussion');
entityNAMEVALUE
Append a new <!ENTITY NAME "VALUE"> element as a child of this element.
Returns the appended ENTITY element.
cdataCONTENTS
Append a new <![CDATA[ CONTENTS ]]> element as a child of this element. Returns the appended CDATA
element.
getValue
Returns a string containing the value of all the element's child XML::MiniNodes (and all the
XML::MiniNodes contained within it's child Elements, recursively).
getElementNAME[POSITION]
Searches the element and it's children for an element with name NAME.
Returns a reference to the first Element with name NAME, if found, NULL otherwise.
NOTE: The search is performed like this, returning the first element that matches:
- Check this element's immediate children (in order) for a match.
- Ask each immediate child (in order) to Element::getElement()
(each child will then proceed similarly, checking all it's immediate
children in order and then asking them to getElement())
If a numeric POSITION parameter is passed, getElement() will return the POSITIONth element of name NAME
(starting at 1). Thus, on document
<?xml version="1.0"?>
<people>
<person>
bob
</person>
<person>
jane
</person>
<person>
ralph
</person>
</people>
$people->getElement('person') will return the element containing the text node 'bob', while
$people->getElement('person', 3) will return the element containing the text 'ralph'.
getElementByPathPATH[POSITIONSARRAY]
Attempts to return a reference to the (first) element at PATH where PATH is the path in the structure
(relative to this element) to the requested element.
For example, in the document represented by:
<partRateRequest>
<vendor>
<accessid user="myusername" password="mypassword" />
</vendor>
<partList>
<partNum>
DA42
</partNum>
<partNum>
D99983FFF
</partNum>
<partNum>
ss-839uent
</partNum>
</partList>
</partRateRequest>
$partRate = $xmlDocument->getElement('partRateRequest');
$accessid = $partRate->getElementByPath('vendor/accessid');
Will return what you expect (the accessid element with attributes user = "myusername" and password =
"mypassword").
BUT be careful: $accessid = $partRate->getElementByPath('partList/partNum');
will return the partNum element with the value "DA42". To access other partNum elements you must either
use the POSITIONSARRAY or the getAllChildren() method on the partRateRequest element.
POSITIONSARRAY functions like the POSITION parameter to getElement(), but instead of specifying the
position of a single element, you must indicate the position of all elements in the path. Therefore, to
get the third part number element, you would use
my $thirdPart = $xmlDocument->getElementByPath('partRateRequest/partList/partNum', 1, 1, 3);
The additional 1,1,3 parameters indicate that you wish to retrieve the 1st partRateRequest element in the
document, the 1st partList child of partRateRequest and the 3rd partNum child of the partList element (in
this instance, the partNum element that contains 'ss-839uent').
Returns the Element reference if found, NULL otherwise.
getAllChildren[NAME]
Returns a reference to an array of all this element's Element children
Note: although the Element may contain XML::MiniNodes as children, these are not part of the returned
list.
createChildELEMENTNAME[VALUE]
Creates a new Element instance and appends it to the list of this element's children. The new child
element's name is set to ELEMENTNAME.
If the optional VALUE (string or numeric) parameter is passed, the new element's text/numeric content
will be set using VALUE.
Returns a reference to the new child element
appendChildCHILDELEMENT
appendChild is used to append an existing Element object to this element's list.
Returns a reference to the appended child element.
NOTE: Be careful not to create loops in the hierarchy, eg
$parent->appendChild($child);
$child->appendChild($subChild);
$subChild->appendChild($parent);
If you want to be sure to avoid loops, set the MINIXML_AVOIDLOOPS define to 1 or use the avoidLoops()
method (will apply to all children added with createChild())
prependChildCHILDELEMENT
prependChild is used to add an existing Element object to this element's list. The added CHILDELEMENT
will be prepended to the list, thus it will appear first in the XML output.
Returns a reference to the prepended child element.
See the note about creating loops in the above appendChild() description.
insertChildCHILDELEMENTINDEX
Inserts the child element at a specific location in this elements list of children.
If INDEX is larger than numChildren(), the CHILDELEMENT will be added to the end of the list (same as
appendChild() ).
Returns the inserted child element.
removeChildCHILDELEMENT
Removes the element CHILDELEMENT from the list of this element's children, if it is found within this
list.
Returns the child element that was removed, else undef.
removeAllChildren
Clears the element's list of child elements. Returns an array ref of child elements that were removed.
remove
Removes this element from it's parent's list of children. The parent must be set for the element for
this method to work - this can be done manually using the parent() method or automatically if
$XML::Mini::AutoSetParent is true (set to false by default).
parentNEWPARENT
The parent() method is used to get/set the element's parent.
If the NEWPARENT parameter is passed, sets the parent to NEWPARENT (NEWPARENT must be an instance of
Element)
Returns a reference to the parent Element if set, NULL otherwise.
Note: This method is mainly used internally and you wouldn't normally need to use it. It get's called on
element appends when $XML::Mini::AutoSetParent or $XML::Mini::AvoidLoops or avoidLoops() > 0
avoidLoopsSETTO
The avoidLoops() method is used to get or set the avoidLoops flag for this element.
When avoidLoops is true, children with parents already set can NOT be appended to any other elements.
This is overkill but it is a quick and easy way to avoid infinite loops in the heirarchy.
The avoidLoops default behavior is configured with the $XML::Mini::AvoidLoops variable but can be set on
individual elements (and automagically all the element's children) with the avoidLoops() method.
Returns the current value of the avoidLoops flag for the element.
toString[SPACEOFFSET]
toString returns an XML string based on the element's attributes, and content (recursively doing the same
for all children)
The optional SPACEOFFSET parameter sets the number of spaces to use after newlines for elements at this
level (adding 1 space per level in depth). SPACEOFFSET defaults to 0.
If SPACEOFFSET is passed as $XML::Mini::NoWhiteSpaces no \n or whitespaces will be inserted in the xml
string (ie it will all be on a single line with no spaces between the tags.
Returns the XML string.
createNodeNODEVALUE
Private (?)
Creates a new XML::MiniNode instance and appends it to the list of this element's children. The new
child node's value is set to NODEVALUE.
Returns a reference to the new child node.
Note: You don't need to use this method normally - it is used internally when appending text() and such
data.
appendNodeCHILDNODE
appendNode is used to append an existing XML::MiniNode object to this element's list.
Returns a reference to the appended child node.
Note: You don't need to use this method normally - it is used internally when appending text() and such
data.
Install Now
PNG Icons
Emojis
