Location: PHPKode > scripts > Dextep Template Engine > manual-en.html
<!DOCTYPE html>
<html lang="en">
<head>
<title>Dextep Manual</title>
<meta charset="utf-8" />
<style type="text/css">
table{width:100%}
ol ul{list-style:none;padding-left:1em;margin-left:0;}
code{color:#000066}
.notice{color:#aaa}
</style>
</head>
<body>
<h1>Dextep Manual</h1>
<p>Version 1.0 (2010-11-02)<br />
Copyright &copy; 2010, Alexey Burkov, <a href="http://www.exlab.net/">www.exlab.net</a></p>
<p>This manual also available in <a href="manual-ru.html">Russian</a>.</p>

<a id="toc"><h2>Table of Contents</h2></a>
<ol>
<li><a href="#intro">What it this?</a></li>
<li><a href="#install">Installation and Configuration</a></li>
<li><a href="#using">Using Dextep</a><ul>
	<li><a href="#basics">Basics</a></li>
	<li><a href="#variables">Variables</a></li>
	<li><a href="#caching">Caching</a></li>
	<li><a href="#errors">Error handling</a></li>
	</ul></li>
<li><a href="#syntax">Template Syntax</a><ul>
	<li><a href="#comments">Comments</a></li>
	<li><a href="#expressions">Variables and Expressions</a></li>
	<li><a href="#if">Conditions <code>{if}</code></a></li>
	<li><a href="#foreach">Loops <code>{foreach}</code></a></li>
	<li><a href="#for">Loops <code>{for}</code></a></li>
	<li><a href="#include">Includes</a></li>
</ul></li>
<li><a href="#appendix">Appendix. Expressions and operators</a></li>
<li><a href="#credits">Credits and License</a></li>
</ol>
<hr />
<a id="intro"><h2>What it this?</h2></a>

<p>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.</p>
<p>Template engine supports some basic presentation logic like expressions, conditional operator (<code>if</code>), loops (<code>for</code> and <code>foreach</code>) 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.</p>

<a id="install"><h2>Installation and Configuration</h2></a>

<p>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 <code>test.php</code>.</p>
<p>To install Dextep:
<ol>
	<li>if you are using PHP 5 or greater just extract <code>Dextep.class.php</code> on your server;</li>
	<li>if you are using PHP 4 then you should use <code>Dextep-php4.class.php</code> instead (you still can rename it to <code>Dextep.class.php</code> if you wish to).</li>
</ol>
<p>You can enable/disable template caching, reconfigure path to cache and template folders and extension of template files by changing values defined in <code>Dextep.class.php</code>. Default values are:</p>
<pre><code>$cacheEnabled = true;		<span class="notice">// true = caching enabled, false = disabled</span>
$cachePath = 'cache/';		<span class="notice">// path to cache folder</span>
$templatePath = 'templates/';	<span class="notice">// path to templates folder</span>
$templateExt = '.html';		<span class="notice">// templates extension</span></code></pre>
<p>Be sure <code>$cachePath</code> and <code>$templatePath</code> folders exist. Cache folder must be writable if caching is enabled.</p>

<a id="using"><h2>Using Dextep</h2></a>

<a id="basics"><h3>Basics</h3></a>
<p>Firstly, you should create object of class <code>Dextep</code>:</p>
<pre><code>require_once "Dextep.class.php";
$template = new Dextep();
</code></pre>
<p>Templates are basically files with extension <code>.html</code> (can be redefined in <code>$templateExt</code> variable) stored in templates folder (defined by <code>$templatePath</code> variable) or its subfolders. Method <code>getTemplate($tpl)</code> returns executed template code, where <code>$tpl</code> is template filename without extension. For example, following code outputs template stored in <code>page.html</code> file:</p>
<pre><code>echo $template->getTemplate('page');</code></pre>
<p>And this one will apply template <code>blocks/header.html</code> to variable <code>$content</code>:</p>
<pre><code>$content = $template->getTemplate('blocks/header');</code></pre>

<a id="variables"><h3>Variables</h3></a>
<p>You can pass variable of any type (including associative or numeric array) to template by using method <code>setVar($key, $value)</code>:</p>
<pre><code>$template->setVar('title', 'Hello, world!');

$test = array('foo', 'sub' => array('bar', true, 3.5));
$template->setVar('test', $test);</code></pre>
<p>A variable's value can changes during template execution, so method <code>getVar($key)</code> allows you to get it:</p>
<pre><code>echo $template->getVar('title');</code></pre>
<p>Use dot-separated syntax to get value of specific element of array:</p>
<pre><code>echo $template->getVar('test.0'); <span class="notice">// foo</span>
echo $template->getVar('test.sub.2'); <span class="notice">// 3.5</span></code></pre>
<p>You can also use dot-separated syntax with <code>setVar()</code> to append new element to array or change value of existing one without overriding whole array:</p>
<pre><code>$template->setVar('test.sub.0', 'New value'); <span class="notice">// replaces "bar" with "New value"</span></code></pre>
<p><em>NOTE: Associative keys are more priority than numeric ones. For example, if same array contains both elements with keys <code>2</code> and <code>"2"</code> then dot-separated syntax will apply the latter.</em></p>

<a id="caching"><h3>Caching</h3></a>
<p>Template is being cached (if caching is enabled) on first <code>getTemplate()</code> 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:</p>
<ol>
<li>Disable caching by setting <code>$cacheEnabled = false</code>;</li>
<li>Delete cached file from cache folder;</li>
<li>Call <code>getTemplate()</code> method with second parameter <code>true</code>. It means you need to recache template.</li>
</ol>

<a id="errors"><h3>Error handling</h3></a>
<p>You can set which errors are to be reported by using PHP function <code><a href="http://php.net/manual/en/function.error-reporting.php">error_reporting()</a></code>. 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 <code>die()</code> function if any of these occurs. You can change behavior by overriding <code>error()</code> method depending on your needs.</p>


<a id="syntax"><h2>Template Syntax</h2></a>
<p>Dextep template tags are enclosed within delimiters <code>{</code> and <code>}</code>. Content outside of these delimiters is displayed unchanged. To use symbols <code>{</code> or <code>}</code> as part of content, you should use special tags <code>{lb}</code> and <code>{rb}</code> accordingly.</p>

<a id="comments"><h3>Comments</h3></a>
<p>Comments are ignored and not displayed in output. You can comment any part of template using following syntax:</p>
<pre><code>{* This is comment *}</code></pre>

<a id="expressions"><h3>Variables and Expressions</h3></a>
<p>To output variable's value just type its name with prefix <code>$</code> within delimiters. To output specific element of array use dot-syntax described above. Examples:</p>
<pre><code>{$title}
{$test.sub.0}</code></pre>
<p>Also you can use expressions and apply evaluated values to variables:</p>
<pre><code>
{$var = $array.key + 5}
{$a * (2 + $b)}</code></pre>
<p>First expression will set evaluated value to <code>$var</code> 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 <code>@</code> before expression:</p>
<pre><code>{@$b = 5}</code></pre>
<p>Dextep operators are pretty the same as PHP operators. See <a href="#appendix">appendix</a> for full list.</p>
<p><em>NOTE: Expressions with strings are not fully supported. You can concatenate string variables with operator <code>.</code> (dot), but you can not use strings directly in expression. Also you should type space before operator <code>.</code> (dot) to avoid mess with dot-syntax of array:</em></p>
<pre><code>{$s = $test.0 . $test.sub.0}</code></pre>
<p>Variables starting with prefix <code>$</code> 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 <code>getVar</code> method after template is being executed. If you need to define variable which should not be accessable from the script then use prefix <code>%</code> instead of <code>$</code>:</p>
<pre><code>{%var = 2*$var}</code></pre>
<p>Note that variables <code>%var</code> and <code>$var</code> are different. Variables with prefix <code>%</code> are also used with loop operators <code>for</code> and <code>foreach</code> (see below).</p>
<p><em>NOTE: You may want to use some variable as index of array, but you should know that it is only possible with <code>%</code>-variables (limitation of syntax). To bypass this restriction you may do following:</em></p>
<pre><code>{%i = $i}
{$array.%i}</code></pre>


<a id="if"><h3>Conditions <code>{if}</code></h3></a>
<p>Dextep <code>{if}</code> statement is quite similar to PHP <code>if</code> statement. Every <code>{if}</code> tag must be paired with a closing <code>{/if}</code> tag. Any expression or variable can be used as condition:
<pre><code>{if $bool} This text should be outputted only if $bool is true {/if}</code></pre>
<p>Also you can use <code>{else}</code> and/or <code>{elseif}</code> tags:</p>
<pre><code>{if $a &lt; 5} 
  Low
{elseif $a &gt; 10}
  High
{else}
  Medium
{/if}
</code></pre>

<a id="foreach"><h3>Loops <code>{foreach}</code></h3></a>
Again, <code>{foreach}</code> corresponds to PHP's <code>foreach</code>. It is used to loop over an associative or numerically-indexed array. Every <code>{foreach}</code> tag must be paired with a closing <code>{/foreach}</code>:
<pre><code>{foreach $array as %item}
  Item = {%item},
{/foreach}</code></pre>
<p>Row inside <code>{foreach}</code> above repeats as many times as many elements has <code>$array</code>. Note that second variable has prefix <code>%</code>. Each iteration <code>%item</code> changes it's value to proper element's value. So if it was defined before <code>{foreach}</code> it's value will be overrided. Dextep provides same way to access element's keys as PHP does:</p>
<pre><code>{foreach $array as %key => %value}
  Note that {$array.%key} is the same as {%value}
{/foreach}</code></pre>

<a id="for"><h3>Loops <code>{for}</code></h3></a>
<p>Tag <code>{for}</code> is used to repeat some part of code defined number of times. It has four required attributes: <code>var</code> is for iteration variable, <code>from</code> and <code>to</code> define iteration limits and <code>step</code> measures how much <code>var</code> is to be changed per iteration. Tag <code>{for}</code> also must be paired with a closing <code>{/for}</code>:</p>
<pre><code>{for var=%i from=9 to=0 step=-2}
  {%i}
{/for}</code></pre>
<p>This example will output "<samp>9 7 5 3 1</samp>".</p>
<p><em>NOTE: <code>from</code> and <code>to</code> attributes can be variables and expressions, but <code>step</code> can only be a number.</em></p>

<a id="include"><h3>Includes</h3></a>
<p>Lastly, Dextep supports sub-template inclusion by providing <code>{include}</code> tag:</p>
<pre><code>{include "subtemplate"}</code></pre>
<p>Template name can be wrapped in single (') or double quotes ("), but it is not necessary. Scope of variables extends to sub-template.</p>

<a id="appendix"><h2>Appendix. Expressions and operators</h2></a>
<p><code>$a</code>, <code>$b</code> and <code>$c</code> below are variables, but in some cases they can represent constant values or sub-expressions.</p>
<table>
	<tr><td colspan="2"><h4>Arithmetic operators:</h4></td></tr>
	<tr>
		<td><code>$a = $b</code></td>
		<td>Sets <code>$a</code> equal to <code>$b</code></td>
	</tr>
	<tr>
		<td><code>$a . $b</code></td>		
		<td>Concatenates strings <code>$a</code> and <code>$b</code></td>
	</tr>
	<tr>
		<td><code>$a + $b</code></td>		
		<td>Adds <code>$b</code> to <code>$a</code></td>
	</tr>
	<tr>
		<td><code>$a - $b</code></td>
		<td>Subtracts <code>$b</code> from <code>$a</code></td>
	</tr>
	<tr>
		<td><code>$a * $b</code></td>
		<td>Multiplies <code>$a</code> and <code>$b</code></td>
	</tr>
	<tr>
		<td><code>$a / $b</code></td>
		<td>Divides <code>$a</code> by <code>$b</code></td>
	</tr>
	<tr>
		<td><code>$a % $b</code></td>
		<td>Divides <code>$a</code> by <code>$b</code> and returns only the remainder</td>
	</tr>
	<tr>
		<td><code>-$a</code></td>
		<td>Returns opposite of <code>$a</code></td>
	</tr>
	<tr>
		<td><code>++$a</code></td>
		<td>Adds 1 to the <code>$a</code> before processing the whole expression</td>
	</tr>
	<tr>
		<td><code>--$a</code></td>
		<td>Subtracts 1 from <code>$a</code> before processing the whole expression</td>
	</tr>
	<tr>
		<td><code>$a++</code></td>
		<td>Adds 1 to <code>$a</code> after processing the whole expression</td>
	</tr>
	<tr>
		<td><code>$a--</code></td>
		<td>Subtracts 1 from <code>$a</code> after processing the whole expression</td>
	</tr>
	<tr>
		<td><code>$a += $b</code></td>
		<td>Same as <code>$a = $a + b</code></td>
	</tr>
	<tr>
		<td><code>$a -= $b</code></td>
		<td>Same as <code>$a = $a - b</code></td>
	</tr>
	<tr>
		<td><code>$a *= $b</code></td>
		<td>Same as <code>$a = $a * b</code></td>
	</tr>
	<tr>
		<td><code>$a /= $b</code></td>
		<td>Same as <code>$a = $a / b</code></td>
	</tr>
	<tr><td colspan="2"><h4>Logical operators:</h4></td></tr>
	<tr>
		<td><code>$a ? $b : $c</code></td>
		<td>If <code>$a</code> is true then returns <code>$b</code>, otherwise returns <code>$c</code></td>
	</tr>
	<tr>
		<td><code>$a &amp;&amp; $b</code></td>
		<td>Checks if both <code>$a</code> and <code>$b</code> are true</td>
	</tr>
	<tr>
		<td><code>$a || $b</code></td>
		<td>Checks if at least <code>$a</code> or <code>$b</code> is true</td>
	</tr>
	<tr>
		<td><code>!$a</code></td>
		<td>Checks if <code>$a</code> is not true</td>
	</tr>
	<tr>
		<td><code>$a == $b</code></td>		
		<td>Checks for equal values</td>
	</tr>
	<tr>
		<td><code>$a === $b</code></td>		
		<td>Checks for equal values and data types</td>
	</tr>
	<tr>
		<td><code>$a != $b</code></td>
		<td>Checks for values not equal</td>
	</tr>
	<tr>
		<td><code>$a !== $b</code></td>
		<td>Checks for values not equal or not the same data type</td>
	</tr>
	<tr>
		<td><code>$a &lt; $b</code></td>
		<td>Checks for <code>$a</code> being less than <code>$b</code></td>
	</tr>
	<tr>
		<td><code>$a &gt; $b</code></td>		
		<td>Checks for <code>$a</code> being greater than <code>$b</code></td>
	</tr>
	<tr>
		<td><code>$a &lt;= $b</code></td>		
		<td>Checks for <code>$a</code> being less than or equal to <code>$b</code></td>
	</tr>
	<tr>
		<td><code>$a &gt;= $b</code></td>
		<td>Checks for <code>$a</code> being greater than or equal to <code>$b</code></td>
	</tr>
</table>

<p>Also you can override the order of precedence by wrapping part of an expression in parentheses <code>(</code> and <code>)</code>.</p>

<a id="credits"><h2>Credits and License</h2></a>
<p>This class is licensed under the terms of the BSD License:</p>
<p>Copyright &copy; 2010, Alexey Burkov, <a href="http://www.exlab.net/">www.exlab.net</a><br />
All rights reserved.</p>
<p>Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:</p>
<ul>
	<li>Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.</li>
	<li>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.</li>
	<li>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.</li>
</ul>
<p>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.</p>
</body>
</html>
Return current item: Dextep Template Engine