ClearSilver PHP Extension

	Warning
	This software is provided as-is; use at your own risk! Neither the author nor his employers can be held responsible for any damages resulting from its use. Having said that, patches are welcome!

	Note
	The latest version of this document can be found at http://www.geodata.soton.ac.uk/software/php_clearsilver/.

Clearsilver is a fast, powerful, and language-neutral template system. It is designed to make it easy to create template driven websites. This extension provides a procedural PHP interface to Clearsilver.

The general idea is that PHP is used to create a Hierarchical Data Format (HDF). The HDF represents the dynamic output of a PHP script. The HDF is then combined with static output in the form of a Clearsilver template to produce the final output. The template is composed of text (usually, but not limited to, HTML) interspersed with Clearsilver tags.

A useful page providing an overview of the Clearsilver software architecture can be found at http://www.clearsilver.net/docs/template_basics.hdf.

Most PHP interaction with Clearsilver involves the creation of the HDF. This can be populated dynamically, read from disk, etc. Many scripts do not output anything^[1] to the browser directly, save the output produced through feeding the resulting HDF to the template. However, the flexible design of Clearsilver, specifically its ability to easily work with templates stored as strings, means that this purist approach is not the only use for the technology. For instance, PHP objects which render to strings (e.g. implementing PHP5's __toString method) can internally create an HDF representing their current state. Their output can then be tailored by rendering this data with alternative templates. This provides an elegant solution to those seeking to create applications based on the Model View Controller (MVC) paradigm.

If you have comments, enhancements, bugs or you would like to help develop the extension please email geodata@soton.ac.uk.

Thanks go to the Neotonic Software Corporation for providing ClearSilver.

The latest version can downloaded from http://www.geodata.soton.ac.uk/software/php_clearsilver/downloads.php.

The following steps will enable PHP with support for Clearsilver. Use the first procedure unless you want the extension installed as a built-in module. Both procedures require that Clearsilver is installed^[2] and that you have downloaded the PHP Clearsilver distribution.

	Note
	This extension has been developed on Linux; there is no support yet for any other system.

In the following procedures PHP_CLEARSILVER refers to the version of PHP Clearsilver that you are using (e.g. PHP_CLEARSILVER=php-clearsilver-0.1).

Once installed you can view the output of the phpinfo function to check that PHP Clearsilver is available.

Ensure the extension is loaded, either by altering your PHP INI file or by calling the dl function at the beginning of your script. Then work along the following lines:

<?php

// initialise the Hierarchical Data Format (HDF)
$hdf = hdf_init();

// populate HDF
hdf_set_value($hdf, 'person.name.fore', 'Joseph');
hdf_set_value($hdf, 'person.name.middle', 'Frank');
hdf_set_value($hdf, 'person.name.nick', 'Buster');
hdf_set_value($hdf, 'person.name.sur', 'Keaton');
hdf_set_value($hdf, 'person.profession', 'Comedian');
hdf_set_value($hdf, 'person.age', 71);
hdf_set_value($hdf, 'person.alive', false);

// initialise a Clearsilver parse tree (CS) with the HDF
$cs = cs_init($hdf);

// create template (from a string in this case) 
$template = '<p>
  <b><?cs var person.name.fore ?> 
  "<i><?cs var person.name.nick ?></i>" 
  <?cs var person.name.sur ?></b>, the greatest
  <?cs var person.profession ?> of them all, 
  <?cs if:person.alive ?> 
    is <?cs var person.age ?> years old
  <?cs else ?>
    died at the age of <?cs var person.age ?>
  <?cs /if ?>.
</p>';

// parse the template
cs_parse_string($cs, $template);

// render the template
print cs_render($cs);

// destroy the resources
hdf_destroy($hdf);
cs_destroy($cs);

?>
			

			  
<p>
  <b>Joseph 
  "<i>Buster</i>" 
  Keaton</b>, the greatest
  Comedian of them all, 
  
    died at the age of 71
  .
</p>

			  
			

	Note
	Documentation of Clearsilver template syntax can be found at http://www.clearsilver.net/docs/man_templates.hdf. Note that some useful template functions are not documented but can be found in the test examples in the Clearsilver distribution (e.g. subcount).

The HDF is described in detail at http://www.clearsilver.net/docs/man_hdf.hdf, but it is useful to note that it can be derived directly from PHP's array type (see hdf_set_node and hdf_obj_next). Effectively an HDF's node name corresponds to an array's key. Unlike arrays, however, an HDF node can have child nodes as well as a value; in a multi-dimensional array a key's value is either a primitive type (or object) or an array. A PHP implementation of this mapping follows:

			  
<?php
// iterate over an array, mapping it to an HDF
function array2hdf(&$array, $hdf, $node_name = null) {
  foreach ($array as $key => $value) {
    if ($node_name !== null) {
      $key = sprintf("%s.%s", $node_name, $key);
    }

    if (!is_array($value)) {
      hdf_set_value($hdf, $key, $value);
    } else {
      array2hdf($value, $hdf, $key);
    }
  }
}

$arr = array('Name' => 'My Index',
             'URL' => '/myindex.html',
             'Menu' => array('Home',
                             'Preferences',
                             'Help',
                             'Support'));

$hdf = hdf_init();

// copy the array to the HDF
array2hdf($arr, $hdf, 'Page');

print hdf_write_string($hdf);
?>
			  
			

			  
Page {
Name = My Index
URL = /myindex.html
Menu {
0 = Home
1 = Preferences
2 = Help
3 = Support
}
}
			  
			

	Tip
	This can be accomplished more efficiently by passing an array as the value to hdf_set_node.