Lucas Stephanou

This is the first part of two

A few days ago Fabien Potencier, lead developer of Symfony project, published a new component  of the Symfony Components project.

As you may not know yet, Symfony components is a “lego way” that Fabien and symfony team found to publish piece by piece the parts that will compose the next big version of symfony framework, the very waited symfony 2 version.

This last component is a templating framework, but what is that?

A Templating Framework and some history

A big part of php developers around the world use day-by-day a templating engine, like smarty and phptal.

A group of devs have asked in symfony mailing lists to use symfony together with one of those engines.

But bundle a template engine together with Symfony was never in mind of core team, for some(and good) reasons.

Some time ago, the Symfony components project was released and putting all parts together we can understand everything, the answer is a templating framework(not a template engine) , giving us a flexibe way to implement whatever “engine” we want in a standard way.

Wich template engine?

Well, to test Symfony templating framework we need to choice a engine to reproduce.
Wich one?
Smarty? No, thanks. Too flat to me.
PHPTal? Maybe
Haml? Hum, far away from html and php syntax. A good example to see if the framework  is good

Implementing Haml Templating Engine with Symfony templating framework

Since Haml isn’t exactly a tiny language, I’ll implement just a few features.

The goal is parse this example:

!!!
%html
  %head
    %title= $title
  %body
    #header
      %h1 Symfony templating Haml example
    #content
      %img {:src => 'http://haml-lang.com/images/haml.gif'}
      %h2 Haml
      %p Haml is a markup language that’s used to cleanly and simply describe the HTML of any web document without the use of inline code. Haml functions as a replacement for inline page templating systems such as PHP, ASP, and ERB, the templating language used in most Ruby on Rails applications. However, Haml avoids the need for explicitly coding HTML into the template, because it itself is a description of the HTML, with some code to generate dynamic content.
    #footer
      %span.author Lucas Stephanou

The simple Symfony Haml Template Engine

Since phphaml is very easy to use, our template renderer class will be simple.

<?php

/**
 * sfTemplateRendererHaml is a renderer for Haml templates.
 *
 * @package    symfony
 * @subpackage templating
 * @author     Lucas Stephanou <lucas@lucas-ts.com>
 * @version    SVN: $Id$
 */
class sfTemplateRendererHaml extends sfTemplateRenderer
{
  private $hamlParser;

  public function __construct(HamlParser $hamlParser)
  {
    $this->hamlParser = $hamlParser;
  }    

  /**
   * Evaluates a template.
   *
   * @param mixed $template   The template to render
   * @param array $parameters An array of parameters to pass to the template
   *
   * @return string|false The evaluated template, or false if the renderer is unable to render the template
   */
  public function evaluate(sfTemplateStorage $template, array $parameters = array())
  {  

    // even if $template is a string representation, hamlParser will take care of this
    $this->hamlParser->setFile($template);

    foreach($parameters as $key => $val)
    {
      $this->hamlParser->assign($key,$val);
    }   

    return $this->hamlParser->render();
  }
}

The

<?php
__construct(HamlParser $hamlParser)

method receive a HamlParser class as argument, this will allow us to implement all this with  DI in the next article.

<?php
evaluate($template, array $parameters = array())

this method  is all we need to do for  a renderer class, we receive a $template instance(object or a string) and $parameters.

Them the symfony templating framework will expect to receive a string(in case of success ) or a boolean false if something goes wrong.

Testing

To test if we do all right, just create a single file:

<?php

require_once '../../symfony_templating/lib/sfTemplateAutoloader.php';
sfTemplateAutoloader::register();

$loader = new sfTemplateLoaderFilesystem(dirname(__FILE__).'/%name%.haml');

require_once dirname(__FILE__).'/../lib/phphaml/haml/HamlParser.class.php';
$parser = new HamlParser();

require_once dirname(__FILE__).'/../lib/sfTemplateRendererHaml.php';
$engine = new sfTemplateEngine($loader,array(
 'haml' => new sfTemplateRendererHaml($parser),
));

echo $engine->render('haml:example', array('title' => 'Haml Lucas Test'));

Al l code is pretty obvious

1. register symfony templating autoload
2. instantiate a template loader (in this case a filesystem loader)
3. include the HamlParser and instantiate it
4. include our haml renderer class
5. create a template engine indicating that our class will render haml files
6. render  the template passing a single parameter(title)

In the next article we will integrate the symfony dependency injection lib and create a more flexible way to load templates

All code are here for download:

http://dl.getdropbox.com/u/1417411/sfSimpleHaml.tar.bz2