Using CSS selectors

Now you're able to set up your view classes and know how to render them correctly. In this chapter I'm going to show you how to access certain parts of the template to fill the datas into the template. This happens in the _render()-method of your view class. The method's interface is defined in XTemplate\ViewBase. It doesn't receive any argument nor does it return anything. If you need to throw an exception, you can use XTemplate\Exceptions\RenderException.

The _render()-method is automatically called once you render the view. In this method you're free to do any modifications to the template, you wish to do. To express these modifications easily x:template implements CSS selectors which allow you to access certain parts of the template. The selectors work exactly the way they work in your browser.

To select nodes, have to call the select([selector])-method of your view instance. This method returns an instance of XTemplate\ElementList which contains all matched nodes.

Here is a basic example:

scripts/3_css_selectors/example1.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 view class demonstrating some selector features.
     * 
     * @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()
        {
            // The used methods of XTemplate\ElementList are explained later
            $this->select(".news.headline h1")->setContent("Headline");
            $this->select(".news.headline span")->setContent("01.01.1970");
 
            $this->select(".content div")->setContent("Lorem ipsum dolor sit amet..");
 
            $this->select(".content div:first-child")->addClass("first");
            $this->select(".content div:last-child")->addClass("last");
        }
    }
?>

Supported selectors

Sadly not all W3C selectors are implemented yet. Here is a list of the ones x:template supports at the moment:

Selector Meaning Examples
tagname Selects all elements of a certain tagname div
.classname Selects all elements of a certain class name .content
#id Selects all elements with the id-attribute equal to the argument.
This selector changed from version 0.4 to 0.5. The selector for the xid is now %. 		#id
%xid Selects all elements with the xid-attribute equal to the argument.
Important:In Version 0.5 this selector changed. Now the #- selector selects the ID and the %-selector selects the xid.		 foo%bar, %foobar
[(attr_name)(opreator)'(value)'] Selects all elements which match the given condition. You can only use one condition and the value must always be wrapped in '.
The following operators are supported:
Operator Meaning Example
= Selects all element which have an attribute with exactly this value *[name='test']
!= Selects all elements which don't have an attribute with this value *[name!='test']
~= Selects all elements which have this value in an attribute which is consists of a whitespace separated list of values. *[class~='test']
*= Selects all elements which have this value in a substring of the attribute *[name*='tes']
^= Selects all elements which have an attribute which starts with this value. *[name^='foob']
$= Selects all elements which hvae an attribute which ends with this value. *[name$='ar']
:[pseudo] These selectors work just like the W3C pseudo selectors. The following varieties are implemented, yet:
  • :first-child
  • :last-child
  • :nth-child(n)
  • :nth-last-child(n)
  • :nth-of-type(n)
  • :nth-last-of-type(n)
  • :only-child
  • :empty
  • :disabled
  • :checked
 :first-child
:last-child
element1 element2 Selects all element2-nodes which are descendants of an element1-node div span
element1 + element2 Selects all element2s which are directly preceeded by an element1-element. div + span
element1 ~ element2 Selects all element2s which are preceeded by an element1-element. div ~ span
element1 > element2 Selects all element2s which are direct childnodes of an element1-element. div ~ span

Of course you can combine these selectors just like regular CSS selectors.

Comfortable use

Since typing $this->select("[selector]")->furtherOperation() can become quite annoying, there is a nice short syntax to select nodes. Look at the following example to see how you can shorten your code:

scripts/3_css_selectors/short_syntax.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 view class demonstrating some selector features.
     * This is the class from the first example with a shortened syntax.
     * 
     * @author      Tobias Pohlen
     * @version     $Id$ 
     * @package     xtemplate
     * @ignore
     */
    class Example2 extends XTemplate\ComfortView
    {
        /**
         * Path to the template file relative to this class file.
         */
        const TEMPLATE = "template.html";
 
        protected function _render()
        {
            // The used methods of XTemplate\ElementList are explained later
            // Old: $this->select(".news.headline h1")->setContent("Headline");
            // New: 
            $this[".news.headline h1"] = "Headline";
 
            // Old: $this->select(".news.headline span")->setContent("01.01.1970");
            // New:
            $this[".news.headline span"] = "01.01.1970";
 
            // Old: $this->select(".content div")->setContent("Lorem ipsum dolor sit amet..");
            // New:
            $this[".content div"] = "Lorem ipsum dolor sit amet..";
 
            // Old: $this->select(".content div:first-child")->addClass("first");
            // New:
            $this[".content div:first-child"]->addClass("first");
 
            // Old: $this->select(".content div:last-child")->addClass("last");
            $this[".content div:last-child"]->addClass("last");
        }
    }
?>

As you can see, you won't use the select([selector])-method a lot. The same and even more can be achieved by using the array operator. This operator provides even some more service to you:

Syntax Meaning
$this["bar"]; $this->select("bar");
$this["bar"] = "foo"; $this->select("bar")->setContent("bar");
unset($this["bar"]); $this->select("bar")->remove();
echo $this["bar"]; echo $this->select("bar");

You learn more about the XTemplate\ElementList-class (the result of $this->select(...)) in the next chapter.