NodeEdit and ElementList

Even if you don't care about the internals of x:template, these two parts of the engine are important for you to know.

NodeEdit

The interface XTemplate\Interfaces\NodeEdit defines everything you can do to modify the templates to your needs. This interface is implemented by the ElementList-class and the DOMElement-class which means: It doesn't matter how you access the nodes of the DOM tree. Even if you don't use selectors, you have all the features you already know.

This is a list of the supported operations:

Signature Explanation
[NodeEdit] setContent([string] $content) Sets the content of the current node as string. If the node contains any child nodes, they will be droped. If you pass HTML code to the method, it will be converted to a normal textnode.
[string] getContent() Returns the content of the first matched node as string.
[void] remove() Removes the node from its DOM tree. All childnodes are removed, too.
[NodeEdit] setAttribute([string] $name, [string] $value) Sets the value of the attribute with the name $name to $value. If the attribute doesn't exist, it will be created.
[string] getAttribute([string] $name); Returns the value of the attribute with the name $name. If the attribute doesn't exist, a XTemplate\Exceptions\NodeEditException-exception will be thrown.
[NodeEdit] addClass([string) $class) Adds a class to the current list of classes in the class-attribute. The classes are saved as whitespace separated list. If there is no class-attribute, it will be created. If the node already has the class which shall be added, it won't be added a second time.
[NodeEdit] removeClass([string) $class) Removes a class from the current list of classes in the class-attribute. If there is no class-attribute or the class is not in the list of classes, nothing is done.
[NodeEdit] appendHTML([string] $html) The html string $html is added to the matching node. It is not parsed as HTML! So basicly you can add anything you want to your template without breaking it. If you want to append HTML to your template and access it with CSS selectors afterwards, use appendXML.
[void] append([DOMNode] $element) Appends a DOMNode to the matched nodes. You can also pass an instance of XTemplate\SubView. In this case the subview is appended to the element.
[void] appendBefore([DOMNode] $element, [DOMNode] $position) Appends a DOMNode or a subview before the $position node. If you don't pass a position node, the current element is used to create the reference.
[string] __toString() Converts the current node into a HTML string.
[NodeEdit] callback([XTemplate\FuncWrapper] $callback) This method allows you to perform a some operations on every node which matches. You can use it like this:
$this["div"]->callback(new FuncWrapper(function($objNode, $arg1, $argn) {
    if ($objNode->getContent() == "test")
    {
        $objNode->addClass($arg1);
    }
    else
    {
        $objNode->addClass($argn);
    }
}, $arg1, $argn));
                
[NodeEdit] appendBefore([DOMNode] $element, [DOMNode] $ref) Inserts $element before $ref.
[NodeEdit] appendXML([string] $xml) Parses $xml and appends it to the current node. Afterwards you can access the appended node with CSS selector. This is not possible if you use appendHTML.

As you can see, some methods return an instance of NodeEdit. These method calls can be stacked. Example:

scripts/4_nodeedit_elementlist/nodeedit.php
<?php
    /**
     * x:template - PHP based template engine
     * Copyright (c) 2011 - 2012 by Tobias Pohlen <tobias.pohlen@xtemplate.net>
     * 
     * Released under the GPL License.
     * 
     * @author Tobias Pohlen
     * @ignore
     */
 
    // Load the x:template engine
    require_once "../../../Engine.php";
 
    /**
     * A simple class to demonstrate how the NodeEdit calls can be stacked.
     * 
     * @author      Tobias Pohlen
     * @version     $Id$ 
     * @package     xtemplate
     * @ignore
     */
    class Example1 extends XTemplate\ComfortView
    {
        /**
         * Path to the template file relative to this class file.
         */
        const TEMPLATE = "template.html";
 
        protected function _render()
        {
            $this[".foo"]
                    ->setContent("bar")
                    ->setAttribute("id", "foo")
                    ->setAttribute("style", "width: 400px;")
                    ->addClass("bar");
        }
    }
?>

ElementList

The class XTemplate\ElementList is the return type of the select-method which is used every time you use a CSS selector (No matter which way to select you choose). Since this class implements the NodeEdit-interface, too, you are able to treat the result which a selector returns just like you treat a single node.

Additionally this class gives you some more safety when accessing node, because even if your selector doesn't match any node, you still can call these methods and won't ever get a NullPointerException.