From phpDrone

Templates in phpDrone are here to help designers and programmers work together. The syntax in phpDrone template engine was conceived to be as close as possible to plain English and to have a structure that a HTML designer knows to use when coding templates for a php programmer. Never the less, if the designer chooses, the templates can be coded directly in PHP language. Yes, that's right! phpDrone accepts templates written in phpDrone HTML-like syntax and also in PHP syntax.

Let's start with an example that will illustrate a basic Hello World use of the phpDrone template system.

include 'phpDrone/phpDrone.php';
$template = new DroneTemplate('template.html');
$template->set('someone',"world");
$template->render();

This code basically does the following:includes the phpDrone libraries, create an instance of the DroneTemplate class, assign value "world" to template variable "someone" and renders the templates. Now let's see how the template for this PHP code should look.

Hello <!-- someone --> !
<!-- REM this will be a HTML comment -->

As a drawback for using HTML comments syntax to represent phpDrone syntax, in case you now want to put a comment in you resulting HTML code, you'll have to put the case sensitive prefix 'REM' to your comments ('REM' as in 'reminder', not the music band :P). The template file extension is not important in case you want to use phpDrone syntax inside the template. But this template can be also written in PHP as following:

Hello <?php echo $someone ?> !
<!-- this will be a HTML comment -->

Note that the file extension has changed from html to php. In case you want your template to be written in PHP, then the extension must be ".php", otherwise phpDrone will consider a template using the phpDrone template syntax.

In the following documentation we will not discuss the templates written in PHP, because there is no limitation, other than PHP limitation, on what you can do in template code written in PHP. Refer to the PHP manual for more explanation on how to write PHP code.

Templates for HTML designers

Variables

Variables are used to represent data in the templates. To name a variable in phpDrone syntax, you don't have any limitation. You can use any character you want in any order. To reference a multidimensional variable, as an array, you have to use the '.' (dot) operator.

<!-- REM to display a simple variable name 'foo'-->
<!-- foo -->
 
<!-- REM to display a multi-dimensional variable-->
<!-- foo.bar.umm -->

Filters

Filters are used in the context of variables. Filters are used to modify the output of the that variable. To add a filter to a variable, just append the '|' (pipe) operator to the variable name, followed by the name of the filter. You can use as many filters as you want on a variable. Arguments are passed to the filters in a positional manner (not by naming the argument, but by it's position in the list of arguments). To pass arguments to a filter, just enumerate the arguments you want to pass to the filter inside '()' (parenthesis).

<!-- REM to change the case of a variable output to lower case-->
<!-- foo|toLower -->
 
<!-- REM to truncate the output of a variable to 100 characters-->
<!-- foo|trunc(100) -->

Here is a list of all the filters that come bundle with the phpDrone distribution

trunc(count)

truncates the output of a variable to count (default 220) characters

toLower

change the output case to lower case

capitalize

change the output case to first letter upper case

toUpper

change the output case to upper case

inc(num)

increments an integer variable by num (default 1)

dec(num)

decrements an integer variable by num (default 1)

obfuscate

scrambles the HTML result of a variable using Javascript.The text will be displayed correctly, but the code will be scrambled so that the automatic parsers won't see it correctly. Recommended for safely displaying email addresses.

formatTime(format)

format a UNIX timestamp, into human readable date. Uses PHP formatting options of the date() function

htmlSafe

replaces HTML special characters such as they can be displayed (<br /> will become <br />)

strip_tags(except)

will strip out any HTML tags from the output, excepting except (default is empty). A good example of an except argument could be: '<br>'

translate

used with the i18n module to translate the output of the variable

It is possible to use multiple filters on a single template variable. For example, the next template is a valid template:

<!-- foo|toLower|capitalize -->

Loops: FOR

To iterate over an multidimensional variable (array), you can use the FOR loop. The syntax of the FOR loop is:

<!-- for bar,umm in foo -->
<!-- REM do stuff with the key 'bar' and value 'umm'-->
<!-- /for -->

This will iterate over the 'foo' variable and will extract, one by one, the key of that array (stored into 'bar' variable) and the value of that array (stored into 'umm' variable).The variables 'bar' and 'umm' will be accessible only in the for body (ended by <!-- /for -->). The key variable is optional. If you omit it ( <!-- for umm in foo -->), only the values will be extracted.

Inside the body of the FOR, you also can use some special, reserved variables:

drone_for_step

the numeric step of the FOR loop, starting at 1

drone_for_index

the numeric step of the FOR loop, starting at 0

drone_for_total

the total number of items in the variable that is iterated

drone_for_first

this will return true, if the item that is being processed at this step is the first one in the variable that is iterated

drone_for_last

this will return true, if the item that is being processed at this step is the last one in the variable that is iterated

A small example based on the previous FOR example could be:

<!-- for bar,umm in foo -->
The current item (<!-- bar -->:<!-- umm -->) is the #<!-- drone_for_step --> element in 'foo'
<!-- /for -->

The output for this code, depending on what is passed from PHP code to 'foo' variable, might be:

The current item (First_Name:John) is the #1 element in 'foo'
The current item (Last_Name:Smith) is the #2 element in 'foo'
The current item (Address:Some address) is the #3 element in 'foo'
The current item (Gender:Male) is the #4 element in 'foo'

There is a special feature that you can use inside a FOR loop: cycle. The syntax for this is: <!-- cycle str1,str2,...,strx-->. What this does? As it's name states, it will cycle ,with any FOR step, through the enumerated strings (str) and output it. This is very useful, for example, to create tables with alternate row coloring. To illustrate this, we have the following example:

<!-- for bar,umm in foo -->
<table>
  <tr class="<!-- cycle oddRow,evenRow-->">
    <td>The curent item (<!-- bar -->:<!-- umm -->) is the #<!-- drone_for_step --> element in 'foo'</td>
  </tr>
</table>
<!-- /for -->

Based on the situation in the example above, the output will be:

<table>
  <tr class="oddRow">
    <td>The curent item (First_Name:John) is the #1 element in 'foo'</td>
  </tr>
  <tr class="evenRow">
    <td>The curent item (Last_Name:Smith) is the #2 element in 'foo'</td>
  </tr>
  <tr class="oddRow">
    <td>The curent item (Adress:Some address) is the #3 element in 'foo'</td>
  </tr>
  <tr class="evenRow">
    <td>The curent item (Gender:Male) is the #4 element in 'foo'</td>
  </tr>
</table>

Conditions: IF

The if statement is used to determine, based on a variable or an expression, if a part of the HTML should be displayed or which part of the HTML should be displayed. The syntax of the IF is the following:

<!-- if expression -->
<!-- REM display something (first block)-->
<!-- else -->
<!-- REM display something else (second block)-->
<!-- /if -->

The expression might be a variable or a PHP-like expression (see the PHP manual). If the expression is evaluated to true, then the IF block will be replaced with the first block, else will be replaced with the second block.

To give an example on the first part (if a part of HTML should be displayed):

<!-- for bar in foo -->
 
<!-- if drone_for_first -->
First
<!-- /if -->
 
<!-- drone_for_step -->
 
<!-- if drone_for_last -->
Last
<!-- /if -->
 
<!-- /for -->

One output of the previous code might be:

First
1
2
3
4
5
Last

You can also tell what will be displayed if the expression is evaluated to false. To illustrate this, we will also show you how to use a basic PHP expression. Considering that variables 'a' and 'b' are passed to the following templates:

<!-- if a>b -->
a is grater than b
<!-- else -->
a is lower than or equal to b
<!-- /if -->

Inheritance

One of the phpDrone approach on how to make template code reusable is inheritance. What this means is that phpDrone enables you to define a master template, marking blocks of HTML that are prone to change between different parts of the site, then inherit that master template in another template and redefine parts that are different, keeping the other parts that don't change from the master template.

To illustrate this, we will show you a small example of a dummy site, that has a constant header part, and a content and footer that can change:

<html>
<body>
 
<div id='header'>
This is the content of the header part
</div>
 
<div id='content'>
<!-- block the_content -->
This is the content of the main part
<!-- /block -->
</div>
 
<div id='footer'>
<!-- block the_footer -->
This is the content of the footer part
<!-- /block -->
</div>
 
</body>
</html>

Now, let's say that we want to have another template, that will have exactly the same content as base.html, except that we want to redefine the content block of this template. To do that, we have to use the 'extends' statement as the FIRST thing in our new template file. To specify which template the new template will extend, we will have to give to the 'extends', as argument, the relative path to the base template. If the base template is in the same directory, the argument will be simply the file name 'base.html'. If, for example, the base template is in a directory 'baseTemplates', than the argument would be 'baseTemplates/base.html'.

<!-- extends base.html-->
 
<!-- block the_content -->
NEW content of the main part NEW
<!-- /block -->

This will result in the following output:

<html>
<body>
 
<div id='header'>
This is the content of the header part
</div>
 
<div id='content'>
NEW content of the main part NEW
</div>
 
<div id='footer'>
This is the content of the footer part
</div>
 
</body>
</html>

Another approach is to use the inject method. The syntax for this method is: <!--inject part.html-->. This will be like writing all the content of the part.html in the place of the inject method. All the templates variables will be passed forward to the part template. For locating the part template, the same rules apply, as for extends:

<!-- inject header.html-->
 
<!-- block content -->
Contents of the main part
<!-- /block -->
<!-- inject footer.html-->

Note that templates in which you inject parts CAN be extended.

Templates for PHP coders

The following subsection is dedicated to the PHP programmers that will use the templates that designers made for them. Next, we will see how to use the Template class and what are the class methods.

Variables

You can assign basically any PHP variable to the phpDrone template, without any limitations. To learn how to set a template variable, please read bellow the set() method of the template class.

Filters

You can define your own filters that you can call inside the template. To do that, you must place a file called filters.php inside your droneEnv directory (read the Install section for more details on how to allow phpDrone create this directory). For example, let's say you want to make a filter, called 'splitter', that will split the output of a variable after a specific character. In this file, now you can define your own filters, which are basically PHP functions, that must have the following structure:

function filter_splitter($input,$splitAfter)
{
// it will split the string $input after each $splitAfter
return explode($splitAfter, $input);
}

As you can see, this function receives 2 arguments. Only the first one ($input) is mandatory, the rest are optional if your filter doesn't receive any parameters. If your filter takes more than one parameter, let's say 3, you filter function should receive 3 more arguments beside $input.

You must know the following things regarding a filter function:

• it always start with filter_ and is preceded by the name of the filter (of your choice)
• it always receives at least one argument, in which it will store the initial value of the template variable
• must return a value that will be used to replace the initial value of the template variable
• if your filter receives arguments, those will be enumerated (under any name) after the first (mandatory) argument

Template methods

In the beginning of this page (index.php example), you can see a valid example on how to use the Template class. Now, we will list the methods that are available, once you have an instance of the Template class (like in the top example).

constructor

The constructor of the template class has only one (optional) argument: the template file. If you don't pass a template file here, you are obligated to pass one to the render() method. The template constructor will look for this file in the following locations:

• if the setting 'Main.templateDir' is set, then it will look in that directory
• finally, it will look in a directory called 'templates' in the current working directory

set()

Set a value to a variable in the template file. This method receives two arguments:

varName

the name of the variable that you want to set in the template

varValue

the value of the variable that you want to set in the template

render()

Outputs the processed template. This receives one argument, if you passed none to the constructor. Note that this will override the template file name, if one was also passed to the constructor.

getBuffer()

Same as render, but instead of outputting the buffer, it will return it.