Dextep Manual

This manual also available in Russian.

What it this?
Installation and Configuration
Using Dextep
Template Syntax
Appendix. Expressions and operators
Credits and License

What it this?

Dextep is pretty simple template engine for PHP. It provides an easy way to implement MVC architectural pattern. In other words, you can separate application logic from user interface.

Template engine supports some basic presentation logic like expressions, conditional operator (if), loops (for and foreach) and sub-template inclusion. Dextep syntax is quite similar to Smarty syntax, but much more simple considering it's smaller and has less features. Dextep also compiles template and caches it to achieve additional speed.

Installation and Configuration

Dextep requires a web server running PHP 4.4.9 or greater. Previous PHP versions seems to be supported down to PHP 4.0.6 but have not been tested. You can try it running test.php.

To install Dextep:

if you are using PHP 5 or greater just extract Dextep.class.php on your server;
if you are using PHP 4 then you should use Dextep-php4.class.php instead (you still can rename it to Dextep.class.php if you wish to).

You can enable/disable template caching, reconfigure path to cache and template folders and extension of template files by changing values defined in Dextep.class.php. Default values are:

$cacheEnabled = true;		// true = caching enabled, false = disabled
$cachePath = 'cache/';		// path to cache folder
$templatePath = 'templates/';	// path to templates folder
$templateExt = '.html';		// templates extension

Be sure $cachePath and $templatePath folders exist. Cache folder must be writable if caching is enabled.

Using Dextep

Basics

Firstly, you should create object of class Dextep:

require_once "Dextep.class.php";
$template = new Dextep();

Templates are basically files with extension .html (can be redefined in $templateExt variable) stored in templates folder (defined by $templatePath variable) or its subfolders. Method getTemplate($tpl) returns executed template code, where $tpl is template filename without extension. For example, following code outputs template stored in page.html file:

echo $template->getTemplate('page');

And this one will apply template blocks/header.html to variable $content:

$content = $template->getTemplate('blocks/header');

Variables

You can pass variable of any type (including associative or numeric array) to template by using method setVar($key, $value):

$template->setVar('title', 'Hello, world!');

$test = array('foo', 'sub' => array('bar', true, 3.5));
$template->setVar('test', $test);

A variable's value can changes during template execution, so method getVar($key) allows you to get it:

echo $template->getVar('title');

Use dot-separated syntax to get value of specific element of array:

echo $template->getVar('test.0'); // foo
echo $template->getVar('test.sub.2'); // 3.5

You can also use dot-separated syntax with setVar() to append new element to array or change value of existing one without overriding whole array:

$template->setVar('test.sub.0', 'New value'); // replaces "bar" with "New value"

NOTE: Associative keys are more priority than numeric ones. For example, if same array contains both elements with keys 2 and "2" then dot-separated syntax will apply the latter.

Caching

Template is being cached (if caching is enabled) on first getTemplate() method call. Further calls will use cached version. Cache has neither lifetime nor conformity checks. If cached file exists it should be used. It's that simple. So if you updated template (or sub-template used within) you have three options to get fresh output:

Disable caching by setting $cacheEnabled = false;
Delete cached file from cache folder;
Call getTemplate() method with second parameter true. It means you need to recache template.

Error handling

You can set which errors are to be reported by using PHP function error_reporting(). Howerer, there are two kind of errors which are to be processed by Dextep. These are "template not found" and "template self-inclusion" errors. Currently Dextep just stops script execution with die() function if any of these occurs. You can change behavior by overriding error() method depending on your needs.

Template Syntax

Dextep template tags are enclosed within delimiters { and }. Content outside of these delimiters is displayed unchanged. To use symbols { or } as part of content, you should use special tags {lb} and {rb} accordingly.

Comments

Comments are ignored and not displayed in output. You can comment any part of template using following syntax:

{* This is comment *}

Variables and Expressions

To output variable's value just type its name with prefix $ within delimiters. To output specific element of array use dot-syntax described above. Examples:

{$title}
{$test.sub.0}

Also you can use expressions and apply evaluated values to variables:


{$var = $array.key + 5}
{$a * (2 + $b)}

First expression will set evaluated value to $var and output it. Second one will just output evaluated value wihout changing any variable. If you need to set value to variable without it being outputted, then you should use prefix @ before expression:

{@$b = 5}

Dextep operators are pretty the same as PHP operators. See appendix for full list.

NOTE: Expressions with strings are not fully supported. You can concatenate string variables with operator . (dot), but you can not use strings directly in expression. Also you should type space before operator . (dot) to avoid mess with dot-syntax of array:

{$s = $test.0 . $test.sub.0}

Variables starting with prefix $ are basically used to pass values from script to template. But as you can see above it is possible to change variable's value or even define new variable within template. All of them can be accessed from the script using getVar method after template is being executed. If you need to define variable which should not be accessable from the script then use prefix % instead of $:

{%var = 2*$var}

Note that variables %var and $var are different. Variables with prefix % are also used with loop operators for and foreach (see below).

NOTE: You may want to use some variable as index of array, but you should know that it is only possible with %-variables (limitation of syntax). To bypass this restriction you may do following:

{%i = $i}
{$array.%i}

Conditions `{if}`

Dextep {if} statement is quite similar to PHP if statement. Every {if} tag must be paired with a closing {/if} tag. Any expression or variable can be used as condition:

{if $bool} This text should be outputted only if $bool is true {/if}

Also you can use {else} and/or {elseif} tags:

{if $a < 5} 
  Low
{elseif $a > 10}
  High
{else}
  Medium
{/if}

Loops `{foreach}`

Again, {foreach} corresponds to PHP's foreach. It is used to loop over an associative or numerically-indexed array. Every {foreach} tag must be paired with a closing {/foreach}:

{foreach $array as %item}
  Item = {%item},
{/foreach}

Row inside {foreach} above repeats as many times as many elements has $array. Note that second variable has prefix %. Each iteration %item changes it's value to proper element's value. So if it was defined before {foreach} it's value will be overrided. Dextep provides same way to access element's keys as PHP does:

{foreach $array as %key => %value}
  Note that {$array.%key} is the same as {%value}
{/foreach}

Loops `{for}`

Tag {for} is used to repeat some part of code defined number of times. It has four required attributes: var is for iteration variable, from and to define iteration limits and step measures how much var is to be changed per iteration. Tag {for} also must be paired with a closing {/for}:

{for var=%i from=9 to=0 step=-2}
  {%i}
{/for}

This example will output "9 7 5 3 1".

NOTE: from and to attributes can be variables and expressions, but step can only be a number.

Includes

Lastly, Dextep supports sub-template inclusion by providing {include} tag:

{include "subtemplate"}

Template name can be wrapped in single (') or double quotes ("), but it is not necessary. Scope of variables extends to sub-template.

Appendix. Expressions and operators

$a, $b and $c below are variables, but in some cases they can represent constant values or sub-expressions.

Arithmetic operators:
`$a = $b`	Sets `$a` equal to `$b`
`$a . $b`	Concatenates strings `$a` and `$b`
`$a + $b`	Adds `$b` to `$a`
`$a - $b`	Subtracts `$b` from `$a`
`$a * $b`	Multiplies `$a` and `$b`
`$a / $b`	Divides `$a` by `$b`
`$a % $b`	Divides `$a` by `$b` and returns only the remainder
`-$a`	Returns opposite of `$a`
`++$a`	Adds 1 to the `$a` before processing the whole expression
`--$a`	Subtracts 1 from `$a` before processing the whole expression
`$a++`	Adds 1 to `$a` after processing the whole expression
`$a--`	Subtracts 1 from `$a` after processing the whole expression
`$a += $b`	Same as `$a = $a + b`
`$a -= $b`	Same as `$a = $a - b`
`$a *= $b`	Same as `$a = $a * b`
`$a /= $b`	Same as `$a = $a / b`
Logical operators:
`$a ? $b : $c`	If `$a` is true then returns `$b`, otherwise returns `$c`
`$a && $b`	Checks if both `$a` and `$b` are true
`$a \|\| $b`	Checks if at least `$a` or `$b` is true
`!$a`	Checks if `$a` is not true
`$a == $b`	Checks for equal values
`$a === $b`	Checks for equal values and data types
`$a != $b`	Checks for values not equal
`$a !== $b`	Checks for values not equal or not the same data type
`$a < $b`	Checks for `$a` being less than `$b`
`$a > $b`	Checks for `$a` being greater than `$b`
`$a <= $b`	Checks for `$a` being less than or equal to `$b`
`$a >= $b`	Checks for `$a` being greater than or equal to `$b`

Also you can override the order of precedence by wrapping part of an expression in parentheses ( and ).

Credits and License

This class is licensed under the terms of the BSD License:

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the www.exlab.net nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.