[cvs] [Wiki] created: Doc/Dev/TemplatePackageH4

Tue Feb 2 19:14:09 UTC 2010

slusarz  Tue, 02 Feb 2010 14:14:09 -0500

Created page: http://wiki.horde.org/Doc/Dev/TemplatePackageH4

[[toc]]

++ Documentation for Horde_Template:: (H4)

This package may be deprecated in the future, but as of now large  
pieces of H4 are rendered with Horde_Template.

+++ Setup

Within a Horde environment, no specific setup is necessary.

To set up the template object:
<code type="php">$template =  
$GLOBALS['injector']->getInstance('Horde_Template');
</code>

You can proceed with feeding variables into the object (see below for  
examples).

Once you're done feeding in variables, you need to get your PHP code  
to output the resulting HTML, which you can do in either of the  
following ways.

If your template is in a local string, you can do the following:

<code type="php">echo $template->parse($template_code);
</code>

If your template is in a separate file, you should run this command:

<code type="php">echo $template->fetch($template_file);
</code>

**Note:** If you make the PHP script do any output of its own, outside  
of the Horde_Template:: system, it will appear in the output  
positioned relative to the position of the above {{fetch()}} call in  
the code.

+++ Simple Variables

PHP:
<code type="php">// If in php-land you have a variable like:
//   $foo = 'bar';

// Set it into your template using:
$template->set('foo', $foo);
</code>

Template:
<code><html><body>
foo value of <tag:foo />
</body></html>
</code>

** Note:** The {{<tag:... />}} has to be exactly like above, with one  
space between the foo and />. Any other variation and the value will  
not be parsed. Unparsed tags are silently removed from the output  
string.

+++ Arrays

PHP:
<code type="php">// In php, build an array to pass to the templates
//   $foo = array('apples', 'pears', 'peaches');

// To set in the template object
$template->set('foo', $foo);
</code>

Template:
<code><html><body>
many foo values:
<loop:foo>
  <li><tag:foo />
</loop:foo>
</body></html>
</code>

** Note:** Use a loop tag to go through all foo array elements to pull  
out all the values of foo. Again the syntax has to be precise or the  
tags will not be parsed correctly.

+++ Arrays With Keys

PHP:
<code type="php">// We now have an array with keys to pass
//   $foo = array(
//       'city'     => 'paris',
//       'country'  => 'france',
//       'language' => 'french'
//   );

// To set in the template object
$template->set('foo', $foo);
</code>

Template:
<code><html><body>
many foo values:
<loop:foo>
  <li><tag:foo.city />, located in <tag:foo.country /> where  
<tag:foo.language /> is spoken.
</loop:foo>
</body></html>
</code>

** Note:** You must have a loop array to parse through variables with  
keys. Using the tags {{<tag:foo.somekey />}} on their own without the  
loop tag will not work properly.

+++ If Conditions

PHP:
<code type="php">// Set up the php variable, this checks if a user has  
been authorized
// with the checkUserAuth() function returning a true or false
//   $is_auth = checkUserAuth();

// Set the 'if' variable into the template object.
// **** Note that the third parameter is required to tell the template  
engine that
// the variable will be used in an 'if' test, otherwise the 'if' will  
_always_ return 'true'.
$template->set('is_auth', $is_auth, true);

// And we set up another variable for inclusion inside the if statement
$template->set('visitors', countvisits());
</code>

Template:
<code><html><body>
Welcome to our site...<br />
<if:is_auth>
Today's site statistics are: <tag:visitors /> visitors!
</if:is_auth>
</body></html>
</code>

** Note:** as always the syntax has to be precise, and the part within  
the {{<if>...</if>}} block will be shown only if {{$is_auth}} is true.

+++ If-Else Conditions

PHP:
<code type="php">$template->set('somename', true);
</code>

Template:
<code><html><body>
Welcome to our site...<br />
<if:somename>
somename is true

<else:somename>
somename is false
</else:somename>

</if:somename>
</body></html>
</code>

** Note:** The {{<else>}} statement must be enclosed in the {{<if>}} block.

+++ If Conditions and Arrays

PHP:
<code type="php">$users = array('john', 'peter', 'mary');
$template->set('users', $users);
</code>

Template:
<code><html><body>
Welcome to our site...<br />
<if:users>
Current users:<br/>
<loop:users>
  <tag:users /><br/>
</loop:users>

<else:users>
There are no users at the moment
</else:users>

</if:users>
</body></html>
</code>

** Note:** The {{<else>}} statement must be enclosed in the {{<if>}} block.

+++ Nested Loops and Nested Tags

PHP:
<code type="php">$categories= array(
     array('type' => 'fruit', 'items' => array('apple', 'pear')),
     array('type' => 'veggie', 'items' => array('tomato', 'potato',  
'carrot', 'onion')),
     array('type' => 'thing', 'items' => array('spoon', 'paperbag', 'tool'))
);
$template->set('categories', $categories);
</code>

Template:
<code><table>
<loop:categories>
  <tr>
   <td>
    I have a <tag:categories.type />. What could it be?
   </td>
   <td>
    <ul>
<loop:categories.items>
     <li><tag:categories.items /></li>
</loop:categories.items>
    </ul>
   </td>
  </tr>
</loop:categories>
</table>
</code>

Output:
<code>I have a fruit. What could it be?
* apple
* pear

I have a veggie. What could it be?
* tomato
* potato
* carrot
* onion

I have a thing. What could it be?
* spoon
* paperbag
* tool
</code>