Location: PHPKode > projects > SithTemplate > SithTemplate-1.1/docs/html/tutorial.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>SithTemplate: SithTemplate tutorial</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.7.2 -->
<div class="navigation" id="top">
  <div class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li class="current"><a href="pages.html"><span>Related&#160;Pages</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li><a href="examples.html"><span>Examples</span></a></li>
    </ul>
  </div>
</div>
<div class="header">
  <div class="headertitle">
<h1>SithTemplate tutorial </h1>  </div>
</div>
<div class="contents">
<h2><a class="anchor" id="tut-overview"></a>
Overview</h2>
<p>SithTemplate doesn't require any special installation or initialisation procedure. It uses an single entry point - <a class="el" href="_sith_template_8php.html">SithTemplate.php</a> file.</p>
<p>Library distinguishes between compilation time, and runtime - some parts may be used only in one of them (e.g. plugins - they run only during template compilation).</p>
<p>Your application will typically interact with <a class="el" href="class_template_environ.html">TemplateEnviron</a> class, and its members. This is "public API" or "client API" of the library, which is designed to be as simple as possible (I think nobody likes to dig through hundreds of pages of documentation, just to find right function to do something). Through this API you can create template instances, and retrieve template metadata. It also contains internal object cache, if you're lazy and repeatedly rendering same templates.</p>
<p>To create (and compile, if neccessary) the template object, you need to call either <a class="el" href="class_template_environ.html#a83a8ca46797584a7a175198532b220e7">TemplateEnviron::get</a> or <a class="el" href="class_template_environ.html#a5387aedb93a098eb199e94fdab8bc92f">TemplateEnviron::cachedGet</a>. It constructs and return an template instance, which is always a subclass of the <a class="el" href="class_template.html">Template</a> class.</p>
<p><a class="el" href="class_template.html" title="Abstract base class for templates.">Template</a> objects are independent of the <a class="el" href="class_template_environ.html">TemplateEnviron</a> and context. Thus, you can create object once, and render it using different runtime environments and variables. To actually render the template, you need to call <a class="el" href="class_template.html#a42044ff0ff501881954eaabce3da54ac">Template::render</a> method on previously constructed object, passing context array (containing all variables that template uses) and <a class="el" href="class_template_environ.html">TemplateEnviron</a> object.</p>
<p>You can also render the template using <a class="el" href="class_template_environ.html#a564c04dff7b3d6d026ae07adf64dc8b2">TemplateEnviron::render</a>, in case you don't use different environment objects.</p>
<div class="fragment"><pre class="fragment">&lt;?php
require_once <span class="stringliteral">&#39;SithTemplate.php&#39;</span>;

<span class="comment">// 1. We create environment</span>
$environ  = <span class="keyword">new</span> <a class="code" href="class_template_environ.html" title="Template environment - library&amp;#39;s end-user API.">TemplateEnviron</a>;
<span class="comment">// 2. Next, we create template object</span>
<span class="comment">// Library will take care of the (re)compilation.</span>
<span class="comment">// SithTemplate 1.1 introduced unified I/O system,</span>
<span class="comment">// which allows you to easily inline small templates in your PHP code.</span>
$template = $environ-&gt;<a class="code" href="class_template_environ.html#a83a8ca46797584a7a175198532b220e7" title="Returns template instance.">get</a>(<span class="stringliteral">&#39;string://Hello world&#39;</span>);
<span class="comment">// 3. Finally, we render and display previously created template</span>
<span class="comment">// You may notice that display/fetch APIs are gone, replaced by</span>
<span class="comment">// generic ones - you need to display template output by yourself.</span>
<span class="comment">//</span>
<span class="comment">// You can also see that environment object is passed back to the template -</span>
<span class="comment">// it is used in several places, like {% include %}-generated code, but passing</span>
<span class="comment">// it here, and not during construction, keeps template object more lightweight</span>
<span class="comment">// and independent, as it doesn&#39;t carry reference to original environment.</span>
<span class="comment">// It also eliminates possibility of circular reference, when template object</span>
<span class="comment">// is stored in environ&#39;s internal cache.</span>
echo $template-&gt;render(array(), $environ);

<span class="comment">// If you don&#39;t want to cache the template object on your own, you can use</span>
<span class="comment">// chained calls to cachedGet and render:</span>
$environ-&gt;cachedGet(<span class="stringliteral">&#39;string://Other&#39;</span>)-&gt;render(array(), $environ);

<span class="comment">// If you don&#39;t need the object at all, you can call TemplateEnviron::render instead.</span>
<span class="comment">// This call is the same as the chained call above, just shorter and less explicit.</span>
$environ-&gt;render(<span class="stringliteral">&#39;string://Other&#39;</span>, array());
</pre></div><h2><a class="anchor" id="tut-io"></a>
I/O system</h2>
<p>SithTemplate has its own extensible I/O system built-in.</p>
<p>All input and output is handled by so-called "I/O drivers". Library itself doesn't know, whether template is loaded/saved to filesystem, database or maybe across network. All I/O drivers follow <a class="el" href="interface_i_template_i_o_driver.html">ITemplateIODriver</a> interface.</p>
<p>I/O system is transparent - to use non-default driver, all you have to do is to use URI-like DSN as template name, wherever it is supported (e.g. as <a class="el" href="class_template_environ.html#a83a8ca46797584a7a175198532b220e7">TemplateEnviron::get</a> argument). Library may refer to the DSNs as "template IDs". If you don't specify the driver (e.g. the part before <code></code>://), a default one will be used (<code>defaultIODriver</code> setting, see <a class="el" href="tutorial.html#tut-settings">Environment settings</a>).</p>
<div class="fragment"><pre class="fragment">&lt;?php
require_once <span class="stringliteral">&#39;SithTemplate.php&#39;</span>;

$environ = <span class="keyword">new</span> <a class="code" href="class_template_environ.html" title="Template environment - library&amp;#39;s end-user API.">TemplateEnviron</a>;

<span class="comment">// SithTemplate 1.1 comes with two I/O drivers bundled:</span>
<span class="comment">//</span>
<span class="comment">// - &quot;file&quot; I/O - a traditional template-from-file driver.</span>
<span class="comment">//   This driver uses &quot;inputPrefix&quot; as source directory with templates,</span>
<span class="comment">//   and &quot;outputPrefix&quot; as cache directory, to store metadata and</span>
<span class="comment">//   compiled templates&#39; code.</span>
echo $environ-&gt;<a class="code" href="class_template_environ.html#a83a8ca46797584a7a175198532b220e7" title="Returns template instance.">get</a>(<span class="stringliteral">&#39;template.html&#39;</span>)-&gt;render(array(), $environ);
<span class="comment">// - &quot;string&quot; I/O, which allows you to inline templates in code.</span>
<span class="comment">//   This driver uses only &quot;outputPrefix&quot; setting.</span>
echo $environ-&gt;get(<span class="stringliteral">&#39;string://Hai&#39;</span>)-&gt;render(array(), $environ);
<span class="comment">//</span>
<span class="comment">// inputPrefix defaults to ./templates/</span>
<span class="comment">// outputPrefix defaults to ./templates_c/</span>
</pre></div><p>If you are interested in creating your own, see <a class="el" href="extending-st.html">Extending SithTemplate</a>.</p>
<h2><a class="anchor" id="tut-settings"></a>
Environment settings</h2>
<p>Every environment has a settings array associated with it. It determines library's behaviour during both runtime and compilation time.</p>
<p>The settings array is stored as <a class="el" href="class_template_environ.html#a1a6916c9094781e70523b3ed7ba20b68">TemplateEnviron::$settings</a> (and, as reference, in <a class="el" href="class_template_compiler_ex.html#a7436ce4d99eb25b14012d0fea3329545">TemplateCompilerEx::$settings</a>).</p>
<div class="fragment"><pre class="fragment">&lt;?php
require_once <span class="stringliteral">&#39;SithTemplate.php&#39;</span>;

<span class="comment">// You can change default settings during TemplateEnviron construction,</span>
<span class="comment">// by passing associative array to the constructor.</span>
$environ = <span class="keyword">new</span> <a class="code" href="class_template_environ.html" title="Template environment - library&amp;#39;s end-user API.">TemplateEnviron</a>(array(
 <span class="stringliteral">&#39;inputPrefix&#39;</span>  =&gt; <span class="stringliteral">&#39;./templates/&#39;</span>,
 <span class="stringliteral">&#39;outputPrefix&#39;</span> =&gt; <span class="stringliteral">&#39;./templates_c/&#39;</span>,
));

<span class="comment">// You can also load settings from INI file, using static named constructor</span>
<span class="comment">// See sample-configuration.ini for syntax.</span>
$environ = <a class="code" href="class_template_environ.html#a9b30f6017bfdf15e9c0234d52ecf5a8d" title="Named constructor.">TemplateEnviron::createFromINI</a>(<span class="stringliteral">&#39;settings.ini&#39;</span>);

<span class="comment">// Finally, you can change settings in runtime, by modifying settings</span>
<span class="comment">// array directly. Note that some settings won&#39;t take effect if changed</span>
<span class="comment">// in that way. Refer to documentation for more information.</span>
$environ-&gt;settings[<span class="stringliteral">&#39;recompilationMode&#39;</span>] = <a class="code" href="class_template_environ.html#a5b9029c41ea8dec7765f56b762a349d5" title="One of recompilation modes - always recompile.">TemplateEnviron::RECOMPILE_ALWAYS</a>;
</pre></div><h2><a class="anchor" id="tut-context"></a>
Variables and context</h2>
<p>A context is an associative array, that contains arbitarily nested scalars, objects, and other arrays. Context indexes (i.e. variable names) can be any Unicode string that doesn't contain any whitespace, except for "internal", "forloop" and "block" which are special variables used by the standard library (see <a class="el" href="stdlib.html#stdlib-variables">Special variables</a>).</p>
<p>Template variables are placeholders, that get replaced by appropriate values from the context array at runtime. They are the most basic template construct - without them templates would be quite useless.</p>
<p>This section documents simplest use of template variables - in the standalone <code>{{ variable expression }}</code> construct. Final result of that expression <b>MUST</b> evaluate to a scalar value (i.e. can be neither array [PHP would convert it to "Array" string] nor object [unless it can be converted to string - see PHP documentation for that]). Since this includes filters, it's important that the <b>last</b> filter in the chain produces scalar.</p>
<p>As mentioned above, variables can be filtered before displaying. This is done by appending <b>filter chain</b> to the entire expression. Filters can have their own arguments, and are separated in the chain by | (also known as pipe). Chain is executed in defined order (i.e. left to right), and have no length limit (but keep in mind that function calls in PHP are slowish, and filter chains are executed at runtime).</p>
<div class="fragment"><pre class="fragment">&lt;?php
require_once <span class="stringliteral">&#39;SithTemplate.php&#39;</span>;

$environ = <span class="keyword">new</span> <a class="code" href="class_template_environ.html" title="Template environment - library&amp;#39;s end-user API.">TemplateEnviron</a>;

<span class="comment">// Context array is passed as first argument to Template::render, or as second</span>
<span class="comment">// argument to TemplateEnviron::render.</span>
$tpl = $environ-&gt;<a class="code" href="class_template_environ.html#a83a8ca46797584a7a175198532b220e7" title="Returns template instance.">get</a>(<span class="stringliteral">&#39;string://{{ foo }} &#39;</span>);

echo $tpl-&gt;render(array(<span class="stringliteral">&#39;foo&#39;</span> =&gt; <span class="stringliteral">&#39;first&#39;</span>),  $environ);
echo $tpl-&gt;render(array(<span class="stringliteral">&#39;foo&#39;</span> =&gt; <span class="stringliteral">&#39;second&#39;</span>), $environ);
<span class="comment">// Will produce: &quot;first second &quot;</span>

<span class="comment">// Above is the simplest variable expression. To access nested elements, slightly more</span>
<span class="comment">// complex syntax is required, presented below, with equivalent PHP code:</span>
<span class="comment">//</span>
<span class="comment">// - accessing a named array element</span>
<span class="comment">//   {{ foo.bar }} is equivalent to $context[&#39;foo&#39;][&#39;bar&#39;]</span>
<span class="comment">// - accessing a numeric array index</span>
<span class="comment">//   {{ foo.42 }} is equivalent to $context[&#39;foo&#39;][42]</span>
<span class="comment">// - accessing a named or numeric array index, using value of another variable as key</span>
<span class="comment">//   {{ foo.[bar] }} is equivalent to $context[&#39;foo&#39;][$context[&#39;bar&#39;]]</span>
<span class="comment">//</span>
<span class="comment">// Same syntax rules applies to object properties - you just use -&gt; operator instead of ., e.g.</span>
<span class="comment">// {{ foo-&gt;bar }}.</span>
<span class="comment">//</span>
<span class="comment">// This syntax allows you to create very complex constructs, like:</span>
<span class="comment">//  {{ [one-&gt;[two]].three-&gt;four }} which is equivalent to</span>
<span class="comment">//  $context[ $context[&#39;one&#39;]-&gt;{$context[&#39;two&#39;]} ][&#39;three&#39;]-&gt;four</span>
<span class="comment">//</span>
<span class="comment">// SithTemplate by default generates code to check whether variable really exists in the context</span>
<span class="comment">// before it is used, which triggers E_USER_WARNING if it doesn&#39;t. This can interfere with &quot;optional&quot;</span>
<span class="comment">// variables (e.g. ones used with &#39;default&#39; filter). You can tell compiler to omit this code, by prefixing</span>
<span class="comment">// entire expression with @ sign:</span>
<span class="comment">//  {{ @non-existant-variable }}</span>

<span class="comment">// Filter chains are built with pipe operator. Filter arguments are comma-separated, passed after colon.</span>
<span class="comment">//  {{ variable|filter1|filter2:variable2,&quot;foo&quot; }}</span>
<span class="comment">// is roughly equivalent (if filters were simply functions) to</span>
<span class="comment">//  filter2(filter1($context[&#39;variable&#39;]), $context[&#39;variable2&#39;], &#39;foo&#39;)</span>
</pre></div><h2><a class="anchor" id="tut-syntax"></a>
Template syntax</h2>
<p>SithTemplate uses mostly Django-compatible syntax for templates, and follows its philosophy (but with PHP instead of Python as base language), both found in original docs at <a href="http://docs.djangoproject.com/en/dev/topics/templates/#topics-templates">http://docs.djangoproject.com/en/dev/topics/templates/#topics-templates</a>.</p>
<p>Every template is just a plain text, with special commands for the compiler: </p>
<ul>
<li>
variables, already described in <a class="el" href="tutorial.html#tut-context">Variables and context</a> </li>
<li>
tags, which control template logic (e.g. conditionals, loops) </li>
<li>
comments </li>
</ul>
<p>SithTemplate includes a plugin called <code>StdLibEx</code>, which implements standard library of tags and filters - see <a class="el" href="stdlib.html">Standard library</a> page for reference.</p>
<div class="fragment"><pre class="fragment">{{ this.is.variable }}

There are two kinds of tags:
{% <span class="keyword">inline</span> %} and {% block %} which require an ending tag {% endblock %}

{# <span class="keyword">this</span> is single-line comment - they are ignored by the compiler #}
{% comment %}
 and <span class="keyword">this</span> is
 multi-line comment
 which is implemented as built-in block tag
{% endcomment %}
</pre></div><h2><a class="anchor" id="tut-inheritance"></a>
Template inheritance</h2>
<p>One of key concepts of SithTemplate is template inheritance, which allows you to build hierarchy of templates, e.g. the three-level approach Django docs mentions: </p>
<ol>
<li>
A base template, containing general layout of the site </li>
<li>
A section template, containing more specific layout bits for the site section </li>
<li>
A detail templates, containing the most specific bits for every page type </li>
</ol>
<p>Template inheritance increases maintainability and readability, and the hierarchy feels more natural than with e.g. header and footer included in every template (which is also error-prone).</p>
<p>SithTemplate uses so-called "multi-zoned template inheritance", which means that parent template defines any number of blocks (just like parent class would define a number of methods), and children templates override them with their own content (again, like children classes would override methods), optionally including parent block's code within new block (using <a class="el" href="stdlib.html#stdlib-var-block">{{ block }}</a> special variable). Blocks are created using standard library's <a class="el" href="stdlib.html#stdlib-tag-block">{% block %}</a> tag, and inheritance is done by <a class="el" href="stdlib.html#stdlib-tag-extends">{% extends %}</a> tag.</p>
<p>An example inheritance (parent and then child):</p>
<div class="fragment"><pre class="fragment">&lt;!DOCTYPE html&gt;
&lt;html lang=<span class="stringliteral">&quot;en&quot;</span>&gt;
 &lt;head&gt;
  &lt;link rel=<span class="stringliteral">&quot;stylesheet&quot;</span> href=<span class="stringliteral">&quot;style.css&quot;</span>&gt;
  &lt;title&gt;{% block title %}Awesome HTML5 site{% endblock %}&lt;/title&gt;
 &lt;/head&gt;
 &lt;body&gt;
  &lt;div <span class="keywordtype">id</span>=<span class="stringliteral">&quot;main&quot;</span>&gt;
  {% block contents %}
   &lt;p&gt;
    This is <span class="keywordflow">default</span> content of the block.
   &lt;/p&gt;
   &lt;p&gt;
    It will be used in <span class="keywordflow">case</span> no children <span class="keyword">template</span> will <span class="keyword">override</span> it,
    or when parent <span class="keyword">template</span> will be rendered directly.
   &lt;/p&gt;
  {% endblock %}
  &lt;/div&gt;
  
  &lt;div <span class="keywordtype">id</span>=<span class="stringliteral">&quot;somethingelse&quot;</span>&gt;
  {% block other %}
   &lt;p&gt;
    Foo.
   &lt;/p&gt;
  {% endblock %}
  &lt;/div&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre></div> <div class="fragment"><pre class="fragment">{# This is the most important line: #}
{% extends <span class="stringliteral">&quot;05_inheritance_parent.html&quot;</span> %}

{% block contents %}
 &lt;p&gt;
  And here is overriden contents of <span class="keyword">this</span> block!
 &lt;/p&gt;
{% endblock %}

{% block other %}
 &lt;p&gt;
  This one shows how to use parent block<span class="stringliteral">&#39;s contents.</span>
<span class="stringliteral"> &lt;/p&gt;</span>
<span class="stringliteral"> {{ block.super }}</span>
<span class="stringliteral">{% endblock %}</span>
</pre></div><p>The result of rendering child template would be (actually whitespace would be different, but it's irrelevant here):</p>
<div class="fragment"><pre class="fragment">&lt;!DOCTYPE html&gt;
&lt;html lang=<span class="stringliteral">&quot;en&quot;</span>&gt;
 &lt;head&gt;
  &lt;link rel=<span class="stringliteral">&quot;stylesheet&quot;</span> href=<span class="stringliteral">&quot;style.css&quot;</span>&gt;
  &lt;title&gt;Awesome HTML5 site&lt;/title&gt;
 &lt;/head&gt;
 &lt;body&gt;
  &lt;div <span class="keywordtype">id</span>=<span class="stringliteral">&quot;main&quot;</span>&gt;
   &lt;p&gt;
    And here is overriden contents of <span class="keyword">this</span> block!
   &lt;/p&gt;
  &lt;/div&gt;
  
  &lt;div <span class="keywordtype">id</span>=<span class="stringliteral">&quot;somethingelse&quot;</span>&gt;
   &lt;p&gt;
    This one shows how to use parent block<span class="stringliteral">&#39;s contents.</span>
<span class="stringliteral">   &lt;/p&gt;</span>
<span class="stringliteral">   &lt;p&gt;</span>
<span class="stringliteral">    Foo.</span>
<span class="stringliteral">   &lt;/p&gt;</span>
<span class="stringliteral">  &lt;/div&gt;</span>
<span class="stringliteral">&lt;/body&gt;</span>
<span class="stringliteral">&lt;/html&gt;</span>
</pre></div><h2><a class="anchor" id="tut-security"></a>
Security settings in SithTemplate</h2>
<p>SithTemplate includes several settings that are referred to as "security settings", and implemented by the compiler and the standard library. These include variable autoescaping (using <a class="el" href="stdlib.html#stdlib-filter-escape">escape and safe</a> filter), I/O restrictions (if used, templates will be bound to the originally used I/O driver), element whitelists and blacklists (you can sandbox templates by restricting access to plugins, tags, filters, and plain PHP functions), and <a class="el" href="stdlib.html#stdlib-var-internal">{{ internal }}</a> access restrictions. See <a class="el" href="class_template_environ.html#a1a6916c9094781e70523b3ed7ba20b68">TemplateEnviron::$settings</a> for reference.</p>
<div class="fragment"><pre class="fragment">&lt;?php
require_once <span class="stringliteral">&#39;SithTemplate.php&#39;</span>;

$environ = <span class="keyword">new</span> <a class="code" href="class_template_environ.html" title="Template environment - library&amp;#39;s end-user API.">TemplateEnviron</a>;

<span class="comment">// All security settings are set using environment&#39;s setting array.</span>
<span class="comment">// Some of them may be enforced at runtime, and some at compile time,</span>
<span class="comment">// see TemplateEnviron::$settings documentation for reference.</span>

<span class="comment">// The most common is variable autoescaping, which applies &quot;escape&quot; filter</span>
<span class="comment">// to all stand-alone variables (i.e. {{ vars }}), unless they are marked</span>
<span class="comment">// with &quot;safe&quot; pseudofilter.</span>
<span class="comment">// Autoescaping is turned on with &quot;autoEscape&quot; boolean setting.</span>
$environ-&gt;settings[<span class="stringliteral">&#39;autoEscape&#39;</span>] = <span class="keyword">true</span>;
$environ-&gt;<a class="code" href="class_template_environ.html#a564c04dff7b3d6d026ae07adf64dc8b2" title="Render the template directly.">render</a>(<span class="stringliteral">&#39;string://{{ var }}&#39;</span>, array(<span class="stringliteral">&#39;var&#39;</span> =&gt; <span class="stringliteral">&#39;&lt;b&gt;&#39;</span>));      <span class="comment">// will return &quot;&amp;lt;b&amp;gt;&quot;</span>
$environ-&gt;render(<span class="stringliteral">&#39;string://{{ var|safe }}&#39;</span>, array(<span class="stringliteral">&#39;var&#39;</span> =&gt; <span class="stringliteral">&#39;&lt;b&gt;&#39;</span>)); <span class="comment">// will return &quot;&lt;b&gt;&quot;</span>

<span class="comment">// Next, there are I/O restriction settings. They allow you to enforce specific I/O driver,</span>
<span class="comment">// e.g. when you load template using your own db:// driver, and you don&#39;t want loaded template</span>
<span class="comment">// to use any other I/O driver, like file:// or string://.</span>
<span class="comment">// Note that this is a bit primitive, and may be replaced sometime in the future.</span>
<span class="comment">// I/O restrictions are turned on by &quot;restrictIncludeIO&quot; and &quot;restrictExtendIO&quot; boolean settings.</span>
$environ-&gt;settings[<span class="stringliteral">&#39;restrictIncludeIO&#39;</span>] = <span class="keyword">true</span>;
$environ-&gt;render(<span class="stringliteral">&#39;string://{% include &quot;string://test&quot; %}&#39;</span>, array());    <span class="comment">// will return &quot;test&quot;</span>
$environ-&gt;render(<span class="stringliteral">&#39;string://{% include &quot;file://test.html&quot; %}&#39;</span>, array()); <span class="comment">// will raise TemplateError</span>

<span class="comment">// Next, there are {{ internal }} access restrictions (again, a bit primitive and boolean only).</span>
<span class="comment">// Since {{ internal }} allows template to access global constants and superglobal arrays</span>
<span class="comment">// (like $_SERVER or $_ENV), it may introduce security risk in sandboxed environment</span>
<span class="comment">// (e.g. when templates are loaded from DB, and users can edit them).</span>
<span class="comment">// {{ internal }} restrictions can be set by turning off &quot;allowInternalRequest&quot;</span>
<span class="comment">// and/or &quot;allowInternalConstants&quot; boolean settings.</span>
<span class="comment">// Since this is boolean-only and a bit inconsistent, it may get replaced.</span>
$environ-&gt;render(<span class="stringliteral">&#39;string://{{ internal.request.ENV.PATH.0 }}&#39;</span>, array()); <span class="comment">// will return $_ENV[&#39;PATH&#39;][0]</span>
$environ-&gt;settings[<span class="stringliteral">&#39;allowInternalRequest&#39;</span>] = <span class="keyword">false</span>;
$environ-&gt;render(<span class="stringliteral">&#39;string://{{ internal.request.ENV.PATH.0 }}&#39;</span>, array()); <span class="comment">// will raise TemplateError</span>

<span class="comment">// Finally, there are security lists, that allows you to handpick plugins, tags, filters and</span>
<span class="comment">// plain PHP functions that templates are allowed to use. Lists are the most complex of security</span>
<span class="comment">// settings, as they support multiple modes of evaluation (allow all, deny; allow, deny; deny, allow; deny all, allow),</span>
<span class="comment">// and wildcards (TemplateEnviron::SECURITY_MATCH_EVERYTHING).</span>
<span class="comment">// Evaluation mode is controlled by &quot;securityEvalMode&quot; enumerative setting, and lists themselves</span>
<span class="comment">// are stored in several array settings: &quot;allowedPlugins&quot;, &quot;allowedTags&quot;, &quot;allowedFilters&quot;, &quot;allowedFunctions&quot;</span>
<span class="comment">// and their &quot;disallowed*&quot; counterparts.</span>
$environ-&gt;settings[<span class="stringliteral">&#39;securityEvalMode&#39;</span>] = <a class="code" href="class_template_environ.html#ae3f379fc7bd67ba77f1ad1ad998db3eb" title="One of security modes - first disallow all, then check &amp;#39;allowed&amp;#39; list.">TemplateEnviron::SECURITY_DENY_ALL</a>; <span class="comment">// most restrictive setting</span>
$environ-&gt;settings[<span class="stringliteral">&#39;allowedTags&#39;</span>]      = array(<span class="stringliteral">&#39;block&#39;</span>); <span class="comment">// you don&#39;t have to specify ending tags</span>
$environ-&gt;render(<span class="stringliteral">&#39;string://{% block foo %}foo{% endblock %}&#39;</span>, array()); <span class="comment">// will return &quot;foo&quot;</span>
$environ-&gt;render(<span class="stringliteral">&#39;string://{% comment %}foo{% endcomment %}&#39;</span>, array()); <span class="comment">// will raise TemplateError</span>
</pre></div><h2><a class="anchor" id="tut-errors"></a>
Error handling</h2>
<p>SithTemplate uses PHP exception mechanism to report errors (and standard <code>trigger_error</code> to report warnings). It uses single exception class - <a class="el" href="class_template_error.html">TemplateError</a>, which defines several class constants that indicates error groups.</p>
<div class="fragment"><pre class="fragment">&lt;?php
require_once <span class="stringliteral">&#39;SithTemplate.php&#39;</span>;

$environ = <span class="keyword">new</span> <a class="code" href="class_template_environ.html" title="Template environment - library&amp;#39;s end-user API.">TemplateEnviron</a>;

<span class="comment">// You should always remember about error handling</span>
<span class="comment">// If error occurs during template compilation, exception message</span>
<span class="comment">// may contain template file and approx. line of the mistake.</span>

<span class="comment">// Errors are grouped - every group has it&#39;s own errorcode, specified</span>
<span class="comment">// as class constants in TemplateError.</span>
<span class="keywordflow">try</span> {
 $environ-&gt;<a class="code" href="class_template_environ.html#a564c04dff7b3d6d026ae07adf64dc8b2" title="Render the template directly.">render</a>(<span class="stringliteral">&#39;string://{% bkock foo %}Typos are evil.{% endblock %}&#39;</span>, array());
} <span class="keywordflow">catch</span> (<a class="code" href="class_template_error.html" title="Main and currently the only exception type thrown by SithTemplate internals.">TemplateError</a> $e) {
 echo $e-&gt;getMessage(); <span class="comment">// Unknown tag ...</span>
 echo $e-&gt;getCode();    <span class="comment">// TemplateError::E_UNKNOWN_TAG</span>
}
</pre></div> </div>
<hr class="footer"/><address class="footer"><small>Generated on Fri Jan 14 2011 20:08:37 for SithTemplate by&#160;
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.2 </small></address>
</body>
</html>
Return current item: SithTemplate