Element - Ariadne CMS

ar/xmlElement

This describes the ar_xmlElement object, as created by the ar_xml::node() method.

You can use this object as if it was a string. Some methods in PHP only accept real strings, so you must force the typecast yourself, e.g.:

<pinp>
  echo htmlspecialchars( (string) $node );
</pinp>

The ar_xmlElement class extends the ar_xmlNode class. It difers in that an element can have children and attributes, a node cannot. An ar_xmlNode has only the cloneNode() method and the properties: nodeValue, cdata, parentNode, nextSibling and previousSibling.

All of the methods below can also be applied to an ar_xmlNodes list of nodes and will affect all of nodes in that list..

methods

`(object)`	`appendChild`	Appends a child node or an array of childNodes.
`(object)`	`cloneNode`	Creates a copy of the current node.
`(object)`	`getElementById`	Searches the child nodes recursively for a node with the given id.
`(object)`	`getElementsByTagName`	Searches the child nodes for nodes with the given tag name.
`(object)`	`insertBefore`	Inserts a node or array of nodes before a given child node.
`(object)`	`removeChild`	Removes a node or an array of nodes from the childNodes.
`(object)`	`replaceChild`	Replaces a node or an array of nodes with another node or array of nodes.
`(void)`	`setAttribute`	Sets an attribute to a specific value.
`(void)`	`setAttributes`	Sets a list of attributes to specific values.

properties

`(array)`	`attributes`	List of attributes for this element.
`(object)`	`childNodes`	ar_xmlNodes list of childNodes of this element.
`(object)`	`firstChild`	Readonly. The first child node of this element.
`(object)`	`lastChild`	Readonly. The last child node of this element.
`(object)`	`nextSibling`	Readonly. The next sibling of this element, if it exists. Works only if the element has a parentNode.
`(mixed)`	`nodeValue`	The text value of this node, or an array of nodeValues of its childNodes.
`(object)`	`parentNode`	(Readonly). The parent element of this element. Can be changed, but results will be unpredictable.
`(object)`	`previousSibling`	Readonly. The previous sibling of this element, if it exists. Works only if the element has a parentNode.
`(string)`	`tagName`	The tag name of this element.

appendChild

(object) ar_xmlElement::appendChild( $node )

(mixed) $node The child node to append.

Appends a node or list of nodes to the childNodes of the current element. Returns a reference to $node.

If $node is an array, it will append all the values of the array, in order. If it is a string, it will append an ar_xmlNode with the nodeValue set to the string value. If any node already has a parentNode, the node will be removed from the childNodes list of that parent.

Since this DOM implementation has no concept of ownerDocument, this means that two completely different sets of dom elements can affect each other. If you append a child element from one set of dom elements to another set of dom elements, the child element will have moved. You do not get a copy unless you specifically call cloneNode first. e.g.:

<pinp>
  $x   = ar('xml');
  $ul  = $x->el('ul', $x->el( 'li', 'item' ) );
  $ul2 = $x->el('ul');
  $li  = $ul->li[0];
  $ul2->appendChild( $li );
  echo $ul; 
</pinp>

Will output:

<ul></ul>

... because the call to appendChild moved the child node 'li' from $ul to $ul2. This works exactly the same for arrays of nodes.

cloneNode

(object) ar_xmlElement::cloneNode( $recurse )

(bool) $recurse Whether or not to clone all the children as wel. If false only this element will be cloned, without childNodes.

Creates a copy of the current element and returns it. If $recurse is true, all the childNodes will be copied as well. Otherwise the childNodes of the copy will be empty.

getElementById

(object) ar_xmlElement::getElementById( $id )

(string) $id The id of the element to search for.

Searches the childNodes of this element recursively for an element with the given id and returns it or null. The search is performed on a special cache which keeps track of all id's of all child elements. You can add more than one element with the same id, but then the result of this function is unpredictable. It will always return an element with the given id, you cannot predict which one it will be. So just make sure you only use unique id's.

getElementsByTagName

(object) ar_xmlElement::getElementsByTagName( $tagName, $recurse = true )

`(string)`	`$tagName`	The name of the tags to search for or '*' for all elements.
`(bool)`	`$recurse`	Whether or not to search through the childNodes recursively.

This method searches the childNodes list for elements with the given tag name and returns them in an ar_xmlNodes list. An alternative way to do this is to use the following shorthand:

<pinp>
  $listItems = $ul->li;
</pinp>

Which is the same as:

<pinp>
  $listItems = $ul->getElementsByTagName('li', false);
</pinp>

insertBefore

(object) ar_xmlElement::insertBefore( $node, $referenceNode )

`(mixed)`	`$node`	The node or list of nodes to insert.
`(mixed)`	`$referenceNode`	The node or list of nodes to insert before.

Searches the childNodes for $referenceNode (or the first node in $referenceNode if it is an array) and inserts $node before it. If $node is a list of nodes, all nodes in $node will be inserted there, in order. Any node that is inserted that has an existing parentNode is removed there. If you want to copy a node, use the cloneNode() method.

removeChild

(object) ar_xmlElement::removeChild( $node )

(mixed) $node The node or list of nodes to remove.

Removes the specified node or list of nodes from the childNodes of this element. Returns $node.

replaceChild

(object) ar_xmlElement::replaceChild( $node, $referenceNode )

`(mixed)`	`$node`	The node or list of nodes to insert.
`(mixed)`	`$referenceNode`	The node or list of nodes to remove.

Searches the childNodes for $referenceNode and inserts $node before it. It removes $referenceNode from the childNodes.

If $referenceNode is a list of nodes, it removes all of them and $node is inserted before the first node in the list.

If $node is a list of nodes, all nodes in $node will be inserted before $referenceNode in order.

Any node that is inserted that has an existing parentNode is removed from its original parentNode. If you want to copy a node, use the cloneNode() method.

setAttribute

(void) ar_xmlElement::setAttribute( $name, $value )

`(string)`	`$name`	The name of the attribute.
`(mixed)`	`$value`	The value of the attribute.

Adds an attribute value to an element. If the value is a string, it overwrites any previous value set for the attribute. If it is an array with numerical keys, the values are joined with a space (' ') and this overwrites the previous value. If it is an associative array, the values only overwrite attribute values which have previously been set with the same key name.

So it is possible to do something like this:

<pinp>
  $x = ar('xml');
  $ul = $x->el('ul',
    $x->el('li', array('class' => 'foo'), 'item 1' ),
    $x->el('li', 'item 2' )
  );
  $ul->li->setAttribute('class', array( 'oddEven' => 'bar' ) );
  echo $ul;
</pinp>

This will result in:

<ul>
  <li class="foo bar">item 1</li>
  <li class="bar">item 2</li>
</ul>

As you can see the class 'bar' has been appended to the class attribute of item 1. If you leave out the 'oddEven' key, it will instead overwrite the existing 'foo' class. Ofcourse, with a name like 'oddEven' you might expect a bit more, e.g:

<pinp>
  $ul->childNodes->setAttribute('class', array(
    'oddEven' => ar::listPattern( '(odd even?)*' ) );
  echo $ul;
</pinp>

This will magically output:

<ul>
  <li class="foo odd">item 1</li>
  <li class="even">item 2</li>
</ul>

And even better, the following code works too:

<pinp>
  $ul->childNodes->setAttribute('class', array(
    'oddEven' => ar::listPattern( '(odd even?)*' ) );
  $ul->appendChild( $x->el( 'li', 'item 3' ) );
  echo $ul;
</pinp>

This will result in:

<ul>
  <li class="foo odd">item 1</li>
  <li class="even">item 2</li>
  <li class="odd">item 3</li>
</ul>

Because the attribute is defined on the childNodes of $ul, the value is regenerated every time $ul is converted to a string. The ar::listPattern call generates a helper object which returns a different string for each position in the childNodes list, based on the given expression.

setAttributes

(void) ar_xmlElement::setAttributes( $attributes )

(array) $attributes A list of attributes, as $name => $value pairs.

Adds a list off attribute values to a tag. See ar_xmlElement::setAttribute for details.

More than a CMS