Version 1.0 (2010-11-02)
Copyright © 2010, Alexey Burkov, www.exlab.net
This manual also available in Russian.
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.
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:
Dextep.class.php
on your server;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.
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');
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.
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:
$cacheEnabled = false
;getTemplate()
method with second parameter true
. It means you need to recache template.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.
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 are ignored and not displayed in output. You can comment any part of template using following syntax:
{* This is comment *}
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}
{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}
{foreach}
{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}
{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.
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.
$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 )
.
This class is licensed under the terms of the BSD License:
Copyright © 2010, Alexey Burkov, www.exlab.net
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
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.