Skip to content

Quick start

Jump to bottom Edit New page
buchin edited this page Nov 22, 2010 · 10 revisions

Requirements

  • PHP 5.1 +

Getting started

Getting H2o

Download

With Git

git clone http://github.com/speedmax/h2o-php.git

With SVN

svn checkout http://h2o-template.googlecode.com/svn/trunk/ h2o

Installation

  1. Download and extract h2o into your project path or your php include path

    Sample file structure setup 

    myawesome_app/
    index.php
    templates/
    index.html
    h2o/

  2. use require 'h2o/h2o.php' in your php statement to include h2o library

  3. Below is a quick start code example to get you started.
  4. Checkout the example and specs if you are in the mood for exploring.

templates/index.html


    <body>
        <head><title>Hello world</title></head>
        <body>
            Greetings {{ name }}
        </body>
    </body>

index.php


    <?php
        require 'h2o/h2o.php';
        $h2o = new h2o('templates/index.html');
        echo $h2o->render(array('name'=>'Peter Jackson'));
    ?>

Syntax explanation

variable

{{ variable }}

Use dot (.) to access attribute of a variable

variable lookup order

When h2o context object encounters a dot (.), this will be the lookup order.


  1. key of associative array

  2. array-index

  3. array virtual attributes

  4. object attribute

  5. object method call

Virtual attributes are syntactic sugar for arrays


{{ items.length }}     // number of items
{{ items.size }}        // number of items
{{ items.first }}         // access first item in array
{{ items.last }}         // access last item in array

Example

in your template

{{ person.name }}

in php


    <?php 
        $h2o = new H2o('template.tpl');
        $person =array(
                'name' => 'Peter Jackson', 'age' => 25
        );
        $h2o->render(compact('person'));
    ?>

Let’s say you have assigned a person variable in your php script, the following
variable tag will print out Peter Jackson

Filters

Filters are variable modifiers to manipulate or format the value of a variable.
A filter usually look like this {{ person.name|capitalize }}, a pipe ( | )
character after a variable will apply a filter.

Filter chaining

filter chaining
(Image borrowed from liquid template)

You can chain multiple filters together and use a pipe ( | ) character to separate
them. {{ document.body|escape|nl2br }}

Filter arguments
Filters can accept arguments, for example {{ document.description|truncate 20 }}
will display first 20 character of
document description. Moreover, there are cases you want to pass multiple arguments
and you can use comma( , ) to separate them
{{ person.bio|truncate 20, "..." }}

Filter named arguments
h2o uses colon ( : ) to for named arguments to build optional arguments array.

{{ '/images/logo.png' | image_tag width:450, height:250, alt:"company logo" }}

and this translate to php will be this and that is pretty much what happen internally


    <?php
        echo image_tag("/image/logo.png", array(
            'width' => 450, 
            'height' => 250, 
            'alt'=>'company logo'
        ));
    ?>

Note: Difference with Django, Smarty
H2o does not use the colon ( : ) character to separate arguments for readability reasons,
h2o uses a comma ( , ) which is more logical.

Tag

{% tag %}

Tags are usually very powerful, they controls the logical flow or structure,
iteration. There are inline tags {% inline_tag %} or tags that requires a
closing tag. For example: {% if condition %} ... {% endif %}

if tag

if tags evaluate a variable or a simple expression. When results are true the if tag
body will be render or else part will be rendered.


{% if person.is_adult %}
    You are old enough.
{% else %}
    sorry, you are too young for that.
{% endif %}

for tag

For tag will iterate over a array of items. 

{% for task in tasks %}
    {{ task }}
{% endfor %}

Above will print all the tasks.

Template inheritance

H2o supports template inheritance, it is very powerful and the concept is easy
to understand.

Template inheritance is implemented using block, extends tag. This is easy for programmers
familiar with object oriented principles.

Quote from Django doc

… a base skeleton template that contains all the common elements of your
site and defines blocks that child templates can override.

Example:

base.html – defining the base structure of the page.


    <html>
     <head><title>{%block title %}This is a page title {% endblock %}</title></head>
     <body>
     <div id="content">
       {% block content%}
           <h1> Page title </h1>
           <p> H2O template inheritance is a powerful tool </p> 
       {% endblock %}
     </div>

     <div id="sidebar">
       {% block sidebar %}{% endblock %}
     </div>
     </body>
    </html>

As you can see, the base template is a typical web page using a two column layout,
we defined two blocks (content, sidebar) and HTML code common across all your page.

page.html – defining a template specific to a page.


    {% extends 'base.html' %}

    {% block content %}
        <h1> extended page </h1>
        <p> Body of extended page</p>
    {% endblock %}

    {% block sidebar %}
        Sidebar contains use links.
    {% endblock %}

The page.html extends base.html, now you will be able to override any block
previously defined.

There is a very good article about template inheritance in Django, in this area of
template inheritance h2o works exactly the same.

Power of inheritance is a very good blog post explaining inheritance

Tips

  • If you find you have a lot of common elements inside the template, it may be a
    good idea to put that portion of template inside a block in a base template.
  • Blocks give you a hook, this is especially useful when used for javascript and css
    too
  • When defining a block try and use a short and distinctive name

Configuration

There are a range of options to set up the template system the way you want it.


    <?php
        $h2o = new H2o('template.tpl', array(
            [option_name] => [option_value]
        ));
    ?>

loader

name of loader or a instance of H2o_Loader

Use file loader [default]

$template = new H2o('index.html', array('loader'=>'file');

Advance setup
<?php
$loader = new H2o_File_Loader($custom_searchpath);
$template = new H2o(‘index.html’, array(‘loader’=> $loader );
?>

Use dictionary loader

You may want to load templates from resources other than files, in which case
then this will be your friend. H2o uses hash_loader() for testing.


<?php
    $loader = hash_loader(array(
        "index.html" => 'Hello {{ person }}'
    ));
    $template = new H2o('index.html', array('loader' => $loader'));
?>

searchpath

Default: this will be the base path of your template.

H2o uses this path to load additional templates and extensions.

You can either explicity set the search path:

$template = new H2o('index.html', array('searchpath' => '/sites/common_templates'));

or, It will try to find the searchpath for you:

$template = new H2o('/sites/common_templates/index.html');

Cache

Define the type of caching engine H2o needs to use, set to false to disable
caching, you can read more about performance and caching in following sections

use file cache [default]

$template = new H2o('index.html', array('cache'=>'file'));

Use apc cache:

$template = new H2o('index.html', array('cache'=>'apc'));

The memcache module is not implemented yet.

Disable caching

$template = new H2o('index.html', array('cache'=>false));

Cache_dir

When a file cache is used, you can define where you want templates to be cached.

It will put the cached template in same location as that template

$template = new H2o('index.html', array('cache_dir'=>'/tmp/cached_templates'));

Cache_ttl

How long template cache will live (defaults: 1 hour), template fragment cache that is bundled
in cache extension will use this as default ttl value.

$template = new H2o('index.html', array('cache_ttl' => 3600));

Add a custom footer
Add a custom sidebar
Clone this wiki locally