<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Class MXMLNode - Class MXMLNode</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./modules.html"><span>Modules</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./enum.html"><span>Enumerations</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Class MXMLNode<span class="faldoc_belong"><a href="./module_feather_mxml.html">[in MXLM]</a></p></h1>
<p class="faldoc_brief">Minimal entity of the XML document. </p>
<p class="faldoc_funcdecl">
<b>class</b> MXMLNode( type, [name], [data] )
</p>
<p class="faldoc_brief"><a href="#more">more...</a></p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#addBelow">addBelow()</a></td><td>Adds a node below this one. </td></tr>
<tr><td><a href="#clone">clone()</a></td><td>Clones a whole XML hierarcy starting from this node. </td></tr>
<tr><td><a href="#data">data()</a></td><td>Set and/or return the content of this node. </td></tr>
<tr><td><a href="#depth">depth()</a></td><td>Calculates the depth of this node. </td></tr>
<tr><td><a href="#deserialize">deserialize()</a></td><td>Stores an XML node on a stream. </td></tr>
<tr><td><a href="#firstChild">firstChild()</a></td><td>Return the first child of a node. </td></tr>
<tr><td><a href="#getAttribs">getAttribs()</a></td><td>Gets the all the XML attributes of this node. </td></tr>
<tr><td><a href="#getAttribute">getAttribute()</a></td><td>Gets the value of an XML attribute of this node. </td></tr>
<tr><td><a href="#getChildren">getChildren()</a></td><td>Gets the all the children nodes of this node. </td></tr>
<tr><td><a href="#insertAfter">insertAfter()</a></td><td>Inserts a node after this one. </td></tr>
<tr><td><a href="#insertBefore">insertBefore()</a></td><td>Inserts a node before this one. </td></tr>
<tr><td><a href="#insertBelow">insertBelow()</a></td><td>Inserts a node below this one. </td></tr>
<tr><td><a href="#lastChild">lastChild()</a></td><td>Return the last child of a node. </td></tr>
<tr><td><a href="#name">name()</a></td><td>Set and/or return the name of this node. </td></tr>
<tr><td><a href="#nextSibling">nextSibling()</a></td><td>Return the next node child of the same parent. </td></tr>
<tr><td><a href="#nodeType">nodeType()</a></td><td>Returns the type of this node. </td></tr>
<tr><td><a href="#parent">parent()</a></td><td>Return the parent node of this node. </td></tr>
<tr><td><a href="#path">path()</a></td><td>Returns the path from the root to this node. </td></tr>
<tr><td><a href="#prevSibling">prevSibling()</a></td><td>Return the previous node child of the same parent. </td></tr>
<tr><td><a href="#removeChild">removeChild()</a></td><td>Removes a child from its parent tree. </td></tr>
<tr><td><a href="#serialize">serialize()</a></td><td>Stores an XML node on a stream. </td></tr>
<tr><td><a href="#setAttribute">setAttribute()</a></td><td>Sets an XML attribute of this node to a given value. </td></tr>
<tr><td><a href="#unlink">unlink()</a></td><td>Removes a node from its parent tree. </td></tr>
</table>
<a name="more"><h2 class="faldoc_title">Detailed description</h2></a>
<p class="faldoc_funcdecl">
<b>class</b> MXMLNode( type, [name], [data] )
</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">type</td><td class="faldoc_paramdesc"> One of the node type defined by the <a href="./enum_MXMLType.html">MXMLType</a> enumeration. </td></tr>
<tr><td class="faldoc_optparam">name</td><td class="faldoc_optparamdesc">Name of the node, if this is a tag node. </td></tr><tr><td class="faldoc_optparam">data</td><td class="faldoc_optparamdesc">Optional data content attached to this node.. </td></tr>
</table>
<br/>
<p class="item_brief">Minimal entity of the XML document. </p>
<p class="faldoc_text">This class encapsulates a minimal adressable entity in an XML document. Nodes can be of different types, some of which, like CDATA, tag and comment nodes can have a simple textual data attached to them (equivalent to a single data node being their only child). </p>
<p class="faldoc_text">Nodes can be attached and detached from trees or serialized on their own. The subtrees of child nodes stays attached to its parent also when the MXMLDocument they are attached to is changed. Also, serializing a node directly allows to write mini xml valid fragments which may be used for network transmissions, database storage, template filling etc., without the need to build a whole XML document and writing the ?xml heading declarator. </p>
<p class="faldoc_text"> The <b>type</b> must be one of the <a href="./enum_MXMLType.html">MXMLType</a> enumeration elements. The <b>name</b> of the node is relevant only for Processing Instruction nodes and tag node, while data can be specified for comment, tag and data nodes. </p>
<p class="faldoc_text">If the node is created just to be de-serialized, create it as an empty comment and then deserialize the node from a stream. </p>
<h2 class="faldoc_title">Methods</h2>
<h3 class="faldoc_funcname"><a name="addBelow">addBelow()</a></h3>
<p class="item_brief">Adds a node below this one. </p>
<p class="faldoc_funcdecl">MXMLNode.addBelow( node )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">node</td><td class="faldoc_paramdesc">The node to be added below this one. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method appends the given <b>node</b> as the last child of this node, eventually removing it from a prevuious tree structure to which it was linked if needed. </p>
<p class="faldoc_text"> After this method returns, <b>node</b> can be retreived calling the <a href="./class_MXMLNode.html#lastChild">MXMLNode.lastChild</a> on this node, until another <b>addBelow</b> adds another node at the end of the children list. </p>
</p>
<h3 class="faldoc_funcname"><a name="clone">clone()</a></h3>
<p class="item_brief">Clones a whole XML hierarcy starting from this node. </p>
<p class="faldoc_funcdecl">MXMLNode.clone( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A copy of this node, with all its children copied. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="data">data()</a></h3>
<p class="item_brief">Set and/or return the content of this node. </p>
<p class="faldoc_funcdecl">MXMLNode.data( [data] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">data</td><td class="faldoc_optparamdesc">If provided, the new data of this node. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> If a new <b>data</b> is not given, the current node data. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">A data can be assigned to any node, but it will be meaningful only for data, tag, comment and CDATA nodes. Moreover, tag nodes can have also other children; in this case, the data set with this method will be serialized as if it was a first child data node. </p>
</p>
<h3 class="faldoc_funcname"><a name="depth">depth()</a></h3>
<p class="item_brief">Calculates the depth of this node. </p>
<p class="faldoc_funcdecl">MXMLNode.depth( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The depth of this node. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method returns the number of steps needed to find a node without parents in the parent hierarchy of this node. </p>
<p class="faldoc_text">The dept for a topmost tree node is 0, for a root node in a tree is 1 and for its direct child is 2. </p>
</p>
<h3 class="faldoc_funcname"><a name="deserialize">deserialize()</a></h3>
<p class="item_brief">Stores an XML node on a stream. </p>
<p class="faldoc_funcdecl">MXMLNode.deserialize( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_MXMLError.html">MXMLError</a></td><td class="faldoc_raisedesc">If the serialization failed. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method allows the storage of a single node and all its children in an XML compliant format. The resulting data is an valid XML fragment that may be included verbatim in an XML document. </p>
</p>
<h3 class="faldoc_funcname"><a name="firstChild">firstChild()</a></h3>
<p class="item_brief">Return the first child of a node. </p>
<p class="faldoc_funcdecl">MXMLNode.firstChild( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The first child of this node or nil if the node hasn't any child. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method returns the first child of a node; it's the node that will be delivered for first in the rendering of the final XML document, and that will appare on the topmost postition between the nodes below the current one. </p>
<p class="faldoc_text"> To iterate through all the child nodes of a node, it is possible to get the first child and the iteratively <a href="./class_MXMLNode.html#nextSibling">MXMLNode.nextSibling</a> until it returns nil. In example: </p>
<pre class="faldoc_code">
// node is an MXMLNode...
child = node.firstChild()
while child != nil
> "Child of ", node.name(), ": ", child.name()
child = child.nextSibling()
end
</pre>
</p>
<h3 class="faldoc_funcname"><a name="getAttribs">getAttribs()</a></h3>
<p class="item_brief">Gets the all the XML attributes of this node. </p>
<p class="faldoc_funcdecl">MXMLNode.getAttribs( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A dictionary containing all the XML attributes and their values. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method retreives all the attributes of the node, and stores them in a dictionary as a pair of key => value strings. </p>
<p class="faldoc_text">Attributes can be assigned to PI, Tag and DOCTYPE nodes. </p>
<p class="faldoc_text">If the node doesn't have any XML attribute, an empty dictionary is returned. </p>
<p class="faldoc_text">The dictionary is read-only; values in the dictionary can be changed, but this won't change the values of the original XML attributes in the source node. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> Don't confuse XML attributes with Falcon attributes. </p>
</p>
<h3 class="faldoc_funcname"><a name="getAttribute">getAttribute()</a></h3>
<p class="item_brief">Gets the value of an XML attribute of this node. </p>
<p class="faldoc_funcdecl">MXMLNode.getAttribute( attribute )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">attribute</td><td class="faldoc_paramdesc">The XML attribute to be read. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The value for this XML attribute (as a string). </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method retreives the value for an XML attribute of the node. Attributes can be assigned to PI, Tag and DOCTYPE nodes. </p>
<p class="faldoc_text">If the attribute doesn't exist, nil is returned. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> Don't confuse XML attributes with Falcon attributes. </p>
</p>
<h3 class="faldoc_funcname"><a name="getChildren">getChildren()</a></h3>
<p class="item_brief">Gets the all the children nodes of this node. </p>
<p class="faldoc_funcdecl">MXMLNode.getChildren( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An array containing all the children node. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method stores all the children of an XML node in an array. </p>
<p class="faldoc_text">If the node doesn't have any child, an empty array is returned. </p>
<p class="faldoc_text">The array is read-only; it is possible to change it but inserting or removing nodes from it won't change the children list of the source node. </p>
</p>
<h3 class="faldoc_funcname"><a name="insertAfter">insertAfter()</a></h3>
<p class="item_brief">Inserts a node after this one. </p>
<p class="faldoc_funcdecl">MXMLNode.insertAfter( node )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">node</td><td class="faldoc_paramdesc">The node to be added after this one. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method prepends the given <b>node</b> after of this one in the list of sibling nodes, eventually removing it from a prevuious tree structure to which it was linked if needed. This is equivalent to inserting the node exactly after this one, at the same level, in the final XML document. </p>
<p class="faldoc_text">If this node was the last child of its parent, the inserted node becomes the new last child. </p>
</p>
<h3 class="faldoc_funcname"><a name="insertBefore">insertBefore()</a></h3>
<p class="item_brief">Inserts a node before this one. </p>
<p class="faldoc_funcdecl">MXMLNode.insertBefore( node )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">node</td><td class="faldoc_paramdesc">The node to be added before this one. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method prepends the given <b>node</b> in front of this one in the list of sibling nodes, eventually removing it from a prevuious tree structure to which it was linked if needed. This is equivalent to inserting the node exactly before this one, at the same level, in the final XML document. </p>
<p class="faldoc_text">If this node was the first child of its parent, the inserted node becomes the new first child. </p>
</p>
<h3 class="faldoc_funcname"><a name="insertBelow">insertBelow()</a></h3>
<p class="item_brief">Inserts a node below this one. </p>
<p class="faldoc_funcdecl">MXMLNode.insertBelow( node )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">node</td><td class="faldoc_paramdesc">The node to be added below this one. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method prepends the given <b>node</b> as the first child of this node, eventually removing it from a prevuious tree structure to which it was linked if needed. </p>
<p class="faldoc_text"> After this method returns, <b>node</b> can be retreived calling the <a href="./class_MXMLNode.html#firstChild">MXMLNode.firstChild</a> on this node, until another <b>insertBelow</b> adds another node at the beginning of the children list. </p>
</p>
<h3 class="faldoc_funcname"><a name="lastChild">lastChild()</a></h3>
<p class="item_brief">Return the last child of a node. </p>
<p class="faldoc_funcdecl">MXMLNode.lastChild( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The last child of this node or nil if the node hasn't any child. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method returns the last child of a node; it's the node that will be delivered for last in the rendering of the final XML document, and that will appare on the lowermost postition between the nodes below the current one. </p>
<p class="faldoc_text"> To iterate through all the child nodes of a node in reverse order, it is possible to get the last child and the iteratively <a href="./class_MXMLNode.html#prevSibling">MXMLNode.prevSibling</a> until it returns nil. In example: </p>
<pre class="faldoc_code">
// node is an MXMLNode...
child = node.lastChild()
while child != nil
> "Child of ", node.name(), " reverse: ", child.name()
child = child.prevSibling()
end
</pre>
</p>
<h3 class="faldoc_funcname"><a name="name">name()</a></h3>
<p class="item_brief">Set and/or return the name of this node. </p>
<p class="faldoc_funcdecl">MXMLNode.name( [name] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">name</td><td class="faldoc_optparamdesc">If provided, the new name of this node. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> If a new <b>name</b> is not given, the current node name. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">A name can be assigned to any node, but it will be meaningful only for tag and PI nodes. </p>
</p>
<h3 class="faldoc_funcname"><a name="nextSibling">nextSibling()</a></h3>
<p class="item_brief">Return the next node child of the same parent. </p>
<p class="faldoc_funcdecl">MXMLNode.nextSibling( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The next node at the same level, or nil. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method returns the next node that would be found in the rendered XML document right after this one, at the same level. If such node doesn't exist, it returns nil. </p>
</p>
<h3 class="faldoc_funcname"><a name="nodeType">nodeType()</a></h3>
<p class="item_brief">Returns the type of this node. </p>
<p class="faldoc_funcdecl">MXMLNode.nodeType( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A value in <a href="./enum_MXMLType.html">MXMLType</a> enumeration. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="parent">parent()</a></h3>
<p class="item_brief">Return the parent node of this node. </p>
<p class="faldoc_funcdecl">MXMLNode.parent( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The parent node or nil if this node has no parents. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method returns the node that is currently parent of this node in the XML tree. </p>
<p class="faldoc_text"> The method returns nil if the node hasn't a parent; this may mean that this node is the topmost node in an XMLDocument (the node returned by <a href="./class_MXMLDocument.html#top">MXMLDocument.top</a>) or if it has not still been added to a tree, or if it has been removed with <a href="./class_MXMLNode.html#removeChild">MXMLNode.removeChild</a> or <a href="./class_MXMLNode.html#unlink">MXMLNode.unlink</a>. </p>
</p>
<h3 class="faldoc_funcname"><a name="path">path()</a></h3>
<p class="item_brief">Returns the path from the root to this node. </p>
<p class="faldoc_funcdecl">MXMLNode.path( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The path of this node in its XML document tree. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The path of a node is the list of parent node names separated by a slash "/", starting from the root node (or from the first node of a separate tree) and terminating with the node itself. </p>
<p class="faldoc_text">In example, the path of the node "item" in the following XML document: </p>
<pre class="faldoc_code">
<root>
<content>
<item/>
</content>
</root>
</pre>
<p class="faldoc_text">would be "/root/content/item" </p>
</p>
<h3 class="faldoc_funcname"><a name="prevSibling">prevSibling()</a></h3>
<p class="item_brief">Return the previous node child of the same parent. </p>
<p class="faldoc_funcdecl">MXMLNode.prevSibling( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The previous node at the same level, or nil. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method returns the previous node that would be found in the rendered XML document right after this one, at the same level. If such node doesn't exist, it returns nil. </p>
</p>
<h3 class="faldoc_funcname"><a name="removeChild">removeChild()</a></h3>
<p class="item_brief">Removes a child from its parent tree. </p>
<p class="faldoc_funcdecl">MXMLNode.removeChild( child )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">child</td><td class="faldoc_paramdesc">The child node to be removed. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> True if the <b>child</b> node is actually a child of this node, false otherwise. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method is equivalent to <b>MXMLNode.unlink</b> applied to the child node, but it checks if the removed node is really a child of this node before actually removing it. </p>
<p class="faldoc_text"> If the <b>child</b> parameter is really a child of this node it is unlinked and the method returns true, otherwise the node is untouched and the method returns false. </p>
</p>
<h3 class="faldoc_funcname"><a name="serialize">serialize()</a></h3>
<p class="item_brief">Stores an XML node on a stream. </p>
<p class="faldoc_funcdecl">MXMLNode.serialize( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_MXMLError.html">MXMLError</a></td><td class="faldoc_raisedesc">If the serialization failed. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method allows the storage of a single node and all its children in an XML compliant format. The resulting data is an valid XML fragment that may be included verbatim in an XML document. </p>
</p>
<h3 class="faldoc_funcname"><a name="setAttribute">setAttribute()</a></h3>
<p class="item_brief">Sets an XML attribute of this node to a given value. </p>
<p class="faldoc_funcdecl">MXMLNode.setAttribute( attribute, value )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">attribute</td><td class="faldoc_paramdesc">The XML attribute to be set. </td></tr><tr><td class="faldoc_param">value</td><td class="faldoc_paramdesc">The value for this XML attribute. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method sets the value for an XML attribute of the node. Attributes can be assigned to PI, Tag and DOCTYPE nodes. </p>
<p class="faldoc_text"> The <b>value</b> parameter can be any Falcon type; if it's not a string, the <b>FBOM.toString</b> method will be applied to transform it into a string. </p>
<p class="faldoc_text">If the attribute doesn't exist, it is added, otherwise it's value is changed. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> Don't confuse XML attributes with Falcon attributes. </p>
</p>
<h3 class="faldoc_funcname"><a name="unlink">unlink()</a></h3>
<p class="item_brief">Removes a node from its parent tree. </p>
<p class="faldoc_funcdecl">MXMLNode.unlink( )</p>
<p class="faldoc_text"><p class="faldoc_text">This method removes a node from the list of node of its parent node. The node is removed together with all its children and their whole subtree. </p>
<p class="faldoc_text">After an unlink, it is possible to insert the node into another place of the same tree or of another tree. </p>
<p class="faldoc_text"> Actually, all the insertion routines perform an <b>unlink</b> on the node that is going to be inserted, so it is not necessary to call <b>unlink</b> from the falcon script before adding it elsewhere. However, explicitly unlinked node may be kept elsewhere (i.e. in a script maintained dictionary) for later usage. </p>
</p>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./modules.html">Modules</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./enum.html">Enumerations</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
