Location: PHPKode > projects > SithTemplate > SithTemplate-1.1/docs/html/stdlib.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">
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>SithTemplate: Standard library</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
<!-- 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>
<div class="header">
  <div class="headertitle">
<h1>Standard library </h1>  </div>
<div class="contents">
<p>SithTemplate comes with one plugin - <code>StdLibEx</code>.</p>
<p>It implements so-called <b>standard library</b>, that is set of tags and filters always available (by default, at least, as you can opt to not use it at all) to all templates. Standard library tries to be Django-compatbile, while providing several SithTemplate-specific extensions.</p>
<h2><a class="anchor" id="stdlib-tags"></a>
Standard tags</h2>
<h3><a class="anchor" id="stdlib-tag-autoescape"></a>
{% autoescape %}</h3>
<p><code>{% autoescape on|off %} ... {% endautoescape %}</code></p>
<p>Activates or deactivates variable auto-escaping inside the block. Also see <a class="el" href="stdlib.html#stdlib-filter-escape">escape and safe</a> filters.</p>
<div class="fragment"><pre class="fragment">{# assumptions: variable = <span class="stringliteral">&quot;&lt;b&gt;foo&lt;/b&gt;&quot;</span>, global autoescape is off #}

{{ variable }} {# =&gt; &lt;b&gt;foo&lt;/b&gt; #}

{% autoescape on %}
 {{ variable }}      {# =&gt; &amp;lt;b&amp;gt;foo&amp;lt;/b&amp;gt; #}
 {{ variable|safe }} {# =&gt; &lt;b&gt;foo&lt;/b&gt; #}
{% endautoescape %}
</pre></div><h3><a class="anchor" id="stdlib-tag-block"></a>
{% block %}</h3>
<p><code>{% block &lt;name&gt; %} ... {% endblock %}</code></p>
<p><code>{% block &lt;name&gt; store %} ... {% endblock %}</code> (<b>non-Django extension</b>)</p>
<p>Creates a new overridable, named block (see <a class="el" href="tutorial.html#tut-inheritance">Template inheritance</a>). <code>name</code> argument must be non-quoted string. You can access <a class="el" href="stdlib.html#stdlib-var-block">{{ block }}</a> special variable from within the block.</p>
<p>If <code>store</code> is used, then block contents will be remembered, but not displayed (see <a class="el" href="stdlib.html#stdlib-tag-putblock">{% putblock %}</a>).</p>
<div class="fragment"><pre class="fragment">{% block foo %}
 &lt;p&gt;Hello&lt;/p&gt; {# will be outputted #}
{% endblock %}

{% block bar store %}
 &lt;p&gt;world&lt;/p&gt; {# will not be outputted #}
{% endblock %}
</pre></div><h3><a class="anchor" id="stdlib-tag-call"></a>
{% call %}</h3>
<p><b>Non-Django tag.</b></p>
<p><code>{% call &lt;callback&gt; [&lt;argument&gt; [&lt;argument&gt; [...]]] %}</code></p>
<p><code>{% call &lt;callback&gt; [&lt;argument&gt; [&lt;argument&gt; [...]]] as &lt;variable&gt; %}</code></p>
<p>Calls raw PHP function, specified by <code>callback</code> (checked against security lists - see <a class="el" href="tutorial.html#tut-security">Security settings in SithTemplate</a>), and either displays it (first signature) or stores in a new context variable (second signature).</p>
<p><code>callback</code> can be a quoted string constant, or a variable expression (that must evaluate to <code>call_user_func_array</code> compatible callback value). You can pass as many arguments as you need; every <code>argument</code> can be either constant or variable. If second version is used, <code>variable</code> must be a simple variable name (i.e. it's not parsed as an expression, and cannot contain access operators, or filters).</p>
<div class="fragment"><pre class="fragment">{% call <span class="stringliteral">&quot;sha1&quot;</span> <span class="stringliteral">&quot;foo&quot;</span> %}            {# =&gt; 0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33 #}
{% call <span class="stringliteral">&quot;sha1&quot;</span> <span class="stringliteral">&quot;foo&quot;</span> as fooHash %} {# will create fooHash variable instead of outputting #}

&lt;p&gt;{{ fooHash }}&lt;/p&gt; {# =&gt; 0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33 #}
</pre></div><h3><a class="anchor" id="stdlib-tag-cycle"></a>
{% cycle %}</h3>
<p><code>{% cycle &lt;value&gt; &lt;value&gt; [&lt;value&gt; [...]] %}</code></p>
<p><code>{% cycle &lt;value&gt; &lt;value&gt; [&lt;value&gt; [...]] as &lt;name&gt; %}</code></p>
<p><code>{% cycle &lt;name&gt; %}</code></p>
<p>Cycles through given list of values. It can be used in two ways: inside the loop (first signature), or outside, as named cycle (second signature creates named cycle, third calls already created one).</p>
<p><code>value</code> can be either constant or filtered variable expression. <code>name</code> must be non-quoted constant string.</p>
<div class="fragment"><pre class="fragment">{% <span class="keywordflow">for</span> entry in entries %}
 {% cycle <span class="stringliteral">&quot;red&quot;</span> <span class="stringliteral">&quot;blue&quot;</span> <span class="stringliteral">&quot;green&quot;</span> %}
{% endfor %}

{% cycle <span class="stringliteral">&quot;red&quot;</span> <span class="stringliteral">&quot;blue&quot;</span> <span class="stringliteral">&quot;green&quot;</span> as rgbCycle %} {# =&gt; red #}
{% cycle rgbCycle %}                         {# =&gt; blue #}
{% cycle rgbCycle %}                         {# =&gt; green #}
{% cycle rgbCycle %}                         {# =&gt; red #}
</pre></div><h3><a class="anchor" id="stdlib-tag-debug"></a>
{% debug %}</h3>
<p><code>{% debug %}</code></p>
<p>As for now, it only <code>var_dump's</code> the context. Maybe will be extended in the future.</p>
<h3><a class="anchor" id="stdlib-tag-extends"></a>
{% extends %}</h3>
<p><code>{% extends &lt;template&gt; %}</code></p>
<p>Extends given template. <code>template</code> must be a quoted constant string, and be a correct template ID (see <a class="el" href="tutorial.html#tut-io">I/O system</a>). Argument is tested against <code>restrictExtendIO</code> setting (see <a class="el" href="tutorial.html#tut-security">Security settings in SithTemplate</a>).</p>
<p>If you use <code>{% extends %}</code> more than once in one template, an error will be raised (see <a class="el" href="tutorial.html#tut-errors">Error handling</a>).</p>
<p>For more complex example on inheritance, see <a class="el" href="tutorial.html#tut-inheritance">Template inheritance</a>.</p>
<div class="fragment"><pre class="fragment">{% extends <span class="stringliteral">&quot;another.html&quot;</span> %}

{# extending from <span class="keywordtype">string</span> is allowed, but very limited ATM #}
{# extending from a different I/O driver is perfectly fine, though #}
{% extends <span class="stringliteral">&quot;string://another&quot;</span> %}

{# note that in one <span class="keyword">template</span>, there may be only one {% extends %} #}
</pre></div><h3><a class="anchor" id="stdlib-tag-filter"></a>
{% filter %}</h3>
<p><code>{% filter &lt;filters&gt; %} ... {% endfilter %}</code></p>
<p>Filters the block contents. <code>filters</code> must be a correct filter chain (i.e. a variable expression, but without variable part; see <a class="el" href="tutorial.html#tut-context">Variables and context</a>), and contain at least one filter.</p>
<div class="fragment"><pre class="fragment">{% filter lower|cut:<span class="stringliteral">&quot;foo&quot;</span> %}
 FoO bAr FoO {# =&gt; bar #}
{% endfilter %}
</pre></div><h3><a class="anchor" id="stdlib-tag-firstof"></a>
{% firstof %}</h3>
<p><code>{% firstof &lt;variable&gt; &lt;variable&gt; [&lt;variable&gt; [...]] [&lt;fallback&gt;] %}</code></p>
<p>Outputs first variable that exists and evaluates to <code>true</code>, or a fallback value (unless it's not specified, then nothing is outputted).</p>
<p><code>variable</code> must be a correct variable expression (see <a class="el" href="tutorial.html#tut-context">Variables and context</a>), and <code>fallback</code>, if specified, must a quoted constant string.</p>
<div class="fragment"><pre class="fragment">{# assumptions: foo and bar does not exist, baz exists #}
{# foo = <span class="stringliteral">&quot;foo&quot;</span>, bar = <span class="stringliteral">&quot;bar&quot;</span>, baz = <span class="stringliteral">&quot;baz&quot;</span> #}

{% firstof foo bar baz %}    {# =&gt; baz #}
{% firstof foo bar <span class="stringliteral">&quot;none&quot;</span> %} {# =&gt; none #}
</pre></div><h3><a class="anchor" id="stdlib-tag-for"></a>
{% for %} and {% empty %}</h3>
<p><code>{% for [&lt;key&gt;,] &lt;value&gt; in &lt;iterable&gt; %} ... [{% empty %} ...] {% endfor %}</code></p>
<p>Iterates through variable using <code>foreach</code> statement. <code>key</code> and <code>value</code> must be simple variable names (no filters, no operators), <code>iterable</code> must be a variable expression evaluating to an iterable value (i.e. an array, or an object that implements <code>Traversable</code> interface).</p>
<p><code>{% empty %}</code> can be used to specify alternate block, which will be used if <code>iterable</code> yields no results (i.e. an empty array).</p>
<p>You can also access <a class="el" href="stdlib.html#stdlib-var-internal">{{ internal }}</a> special variable from inside the for loop.</p>
<div class="fragment"><pre class="fragment">{# assumptions: entries is a non-empty array, tags is an empty array #}

{# <span class="keyword">this</span> will output the entries array #}
{% <span class="keywordflow">for</span> entry in entries %}
 {{ entry }}
{% empty %}
 No entries.
{% endfor %}

{# <span class="keyword">this</span> will output <span class="stringliteral">&quot;No tags.&quot;</span> #}
{% <span class="keywordflow">for</span> tag in tags %}
 {{ tag }}
{% empty %}
 No tags.
{% endfor %}
</pre></div><h3><a class="anchor" id="stdlib-tag-if"></a>
{% if %}, {% else %} and {% elseif %}</h3>
<p><b>Non-Django behaviour: Django has simpler <code>{% if %}</code>, without rich comparison operators or grouping, and also have no <code>{% elseif %}</code>.</b></p>
<p><code>{% if &lt;condition&gt; %} ... [{% elseif &lt;condition&gt; %} ... [{% elseif &lt;condition&gt; %} ... [...]]] [{% else %} ...] {% endif %}</code></p>
<p>Conditional block. You can specify alternate condition blocks using one or more <code>{% elseif %}</code> tags, and an <code>{% else %}</code> tag (only one else is allowed).</p>
<p><code>condition</code> is a conditional expression that supports statement grouping (like in PHP, using parentheses) and rich operators: </p>
<code>eq</code> - PHP's <code>==</code> </li>
<code>neq</code> - PHP's <code>!=</code> </li>
<code>lt</code> - PHP's <code>&lt;</code> </li>
<code>lte</code> - PHP's <code>&lt;=</code> </li>
<code>gt</code> - PHP's <code>&gt;</code> </li>
<code>gte</code> - PHP's <code>&gt;=</code> </li>
<code>and</code> - PHP's <code>&amp;&amp;</code> </li>
<code>or</code> - PHP's <code>||</code> </li>
<code>not</code> - PHP's <code>!</code> </li>
<code>id</code> - PHP's <code>===</code> (<b>added in 1.1a2</b>) </li>
<code>nid</code> - PHP's <code>!==</code> (<b>added in 1.1a2</b>) </li>
<div class="fragment"><pre class="fragment">{% <span class="keywordflow">if</span> foo %}
{% elseif ((bar eq <span class="stringliteral">&quot;foo&quot;</span>) and baz) %}
{% elseif quux %}
{% <span class="keywordflow">else</span> %}
 something <span class="keywordflow">else</span>
{% endif %}
</pre></div><h3><a class="anchor" id="stdlib-tag-ifchanged"></a>
{% ifchanged %} and {% else %}</h3>
<p><b>This tag may only appear inside the loop.</b></p>
<p><code>{% ifchanged %} ... [{% else %} ...] {% endifchanged %}</code></p>
<p>On every iteration, checks whether its contents has changed, and outputs correct block accordingly (or nothing, if it hasn't changed, and <code>{% else %}</code> block was not given).</p>
<p><code>{% ifchanged &lt;variable&gt; %} ... [{% else %} ...] {% endifchanged %}</code></p>
<p>Behaves like the first signature, but compares variable value instead of block content. <code>variable</code> must be a filtered variable expression.</p>
<div class="fragment"><pre class="fragment"></pre></div><h3><a class="anchor" id="stdlib-tag-ifequal"></a>
{% ifequal %}, {% ifnotequal %} and {% else %}</h3>
<p><code>{% ifequal &lt;variable&gt; &lt;variable&gt; %} ... [{% else %} ...] {% endif %}</code></p>
<p><code>{% ifnotequal &lt;variable&gt; &lt;variable&gt; %} ... [{% else %} ...] {% endif %}</code></p>
<p>Simplified versions of <code>{% if %}</code> provided for Django compatibility. Equivalent to <code>{% if &lt;variable&gt; eq &lt;variable&gt; %}</code> and <code>{% if &lt;variable&gt; neq &lt;variable&gt; %}</code>, accordingly.</p>
<h3><a class="anchor" id="stdlib-tag-include"></a>
{% include %}</h3>
<p><code>{% include &lt;template&gt; %}</code></p>
<p>Includes another template's contents. <code>template</code> must be either quoted constant string, or a variable expression evaluating to correct template ID (see <a class="el" href="tutorial.html#tut-io">I/O system</a>). Argument is tested against <code>restrictIncludeIO</code> setting (see <a class="el" href="tutorial.html#tut-security">Security settings in SithTemplate</a>).</p>
<div class="fragment"><pre class="fragment">{% include <span class="stringliteral">&quot;template.html&quot;</span> %}
{% include variable %} {# =&gt; contents of the variable will be used #}
</pre></div><h3><a class="anchor" id="stdlib-tag-load"></a>
{% load %}</h3>
<p><b>This tag is a built-in (e.g. a part of the core itself, not standard library)</b></p>
<p><code>{% load &lt;plugin&gt; %}</code></p>
<p>Loads new plugin for current template, making its tags, filter and hooks immediately accessible. <code>plugin</code> must be a non-quoted constant string.</p>
<p>This tag respects security lists (see <a class="el" href="tutorial.html#tut-security">Security settings in SithTemplate</a>).</p>
<div class="fragment"><pre class="fragment">{% load SomeLibrary %}
</pre></div><h3><a class="anchor" id="stdlib-tag-meta"></a>
{% meta %}</h3>
<p><b>Non-Django tag.</b></p>
<p><code>{% meta &lt;name&gt; &lt;value&gt; %}</code></p>
<p>Creates an entry in template's metadata. <code>name</code> must be a non-quoted constant string, <code>value</code> must be a quoted constant string.</p>
<p>Custom metadata will be prefixed <code>user:</code> internally, and can be retrieved using <a class="el" href="class_template_environ.html#a132df401c128e10eafa3a5e923622964">TemplateEnviron::getMeta</a> API call.</p>
<div class="fragment"><pre class="fragment">{% meta foo <span class="stringliteral">&quot;This template&#39;s foo is bar&quot;</span> %}
{% meta bar <span class="stringliteral">&quot;This template&#39;s bar is foo&quot;</span> %}
</pre></div><h3><a class="anchor" id="stdlib-tag-now"></a>
{% now %}</h3>
<p><code>{% now &lt;format&gt; %}</code></p>
<p>Outputs current timestamp, formatted using <code>format</code> argument, which must be either quoted constant string, or a variable expression that evaluates to string.</p>
<p>For format codes see PHP's <code>date</code> function documentation.</p>
<div class="fragment"><pre class="fragment">{% now <span class="stringliteral">&quot;d-m-Y, H:i:s&quot;</span> %}
</pre></div><h3><a class="anchor" id="stdlib-tag-putblock"></a>
{% putblock %}</h3>
<p><b>Non-Django tag.</b></p>
<p><code>{% putblock &lt;name&gt; %}</code></p>
<p>Outputs previously defined block (see <a class="el" href="stdlib.html#stdlib-tag-block">{% block %}</a>). You can use store blocks to maximize code reuse within single template (blocks are always evaluated with current context).</p>
<p>Keep in mind that blocks are internal to template, and can only be inherited. You cannot e.g. <code>{% putblock %}</code> a block from a included template (see <a class="el" href="stdlib.html#stdlib-tag-include">{% include %}</a>).</p>
<div class="fragment"><pre class="fragment">{% block foo store %}Hello{% endblock %} world {% putblock foo %} {# =&gt; world Hello #}
</pre></div><h3><a class="anchor" id="stdlib-tag-spaceless"></a>
{% spaceless %}</h3>
<p><code>{% spaceless %} ... {% endspaceless %}</code></p>
<p>Removes all whitespace between HTML tags (but not inside the tags).</p>
<div class="fragment"><pre class="fragment">{% spaceless %}
            &lt;b&gt;  foo  &lt;/b&gt;
{% endspaceless %}

{# =&gt; &lt;p&gt;&lt;b&gt;  foo  &lt;/b&gt;&lt;/p&gt; #}
</pre></div><h3><a class="anchor" id="stdlib-tag-templatetag"></a>
{% templatetag %}</h3>
<p><code>{% templatetag &lt;tag&gt; %}</code></p>
<p>Inserts literal bit of template syntax, <code>tag</code> must be one of: </p>
<code>openblock</code> - inserts <code>{%</code> </li>
<code>closeblock</code> - inserts <code>%}</code> </li>
<code>openvariable</code> - inserts <code>{{</code> </li>
<code>closevariable</code> - inserts <code>}}</code> </li>
<code>opencomment</code> - inserts <code>{#</code> </li>
<code>closecomment</code> - inserts <code>#}</code> </li>
<code>openbrace</code> - inserts <code>{</code> (<b>added in 1.1a2</b>) </li>
<code>closebrace</code> - inserts <code>}</code> (<b>added in 1.1a2</b>) </li>
<p><b>Non-Django behaviour follows.</b></p>
<p>In addition to above, Django-compatible tags, SithTemplate also defines several aliases on its own (although you are encouraged to use full versions, these are kept mainly for backwards compatibility): </p>
<code>ob</code>, <code>ot</code> and <code>opentag</code> - alias to <code>openblock</code> </li>
<code>cb</code>, <code>ct</code> and <code>closetag</code> - alias to <code>closeblock</code> </li>
<code>ov</code>, and <code>openvar</code> - alias to <code>openvariable</code> </li>
<code>cv</code>, and <code>closevar</code> - alias to <code>closevariable</code> </li>
<code>oc</code> - alias to <code>opencomment</code> </li>
<code>cc</code> - alias to <code>closecomment</code> </li>
<h3><a class="anchor" id="stdlib-tag-widthratio"></a>
{% widthratio %}</h3>
<p><code>{% widthratio &lt;value&gt; &lt;maxValue&gt; &lt;constant&gt; %}</code></p>
<p>Calculates width ratio using formula: <code>round((value/maxValue)*constant)</code>.</p>
<p>Both <code>value</code> and <code>maxValue</code> must be either numeric constants, or a variable expression evaluating to integer or float. <code>constant</code> must be an integer constant.</p>
<div class="fragment"><pre class="fragment">{# assumptions: current = 175, max = 200 #}

{% widthratio current max 100 %} {# =&gt; 88 #}
</pre></div><h3><a class="anchor" id="stdlib-tag-with"></a>
{% with %}</h3>
<p><code>{% with &lt;variable&gt; as &lt;name&gt; %} ... {% endwith %}</code></p>
<p>Creates a new variable, using value of filtered variable expression, visible only within the block.</p>
<p><code>variable</code> must be a filtered variable expression, and <code>name</code> must be a simple variable name.</p>
<div class="fragment"><pre class="fragment">{% with one.two-&gt;three.[four]|lower as simpler %}
 {{ simpler }}
{% endwith %}
</pre></div><h2><a class="anchor" id="stdlib-filters"></a>
Standard filters</h2>
<h3><a class="anchor" id="stdlib-filter-add"></a>
<p>Adds the argument to the variable. <code>argument</code> must be either constant string (operator <code></code>. (join strings) is used), or constant number/numeric variable (operator <code>+</code> (add numbers) is used).</p>
<div class="fragment"><pre class="fragment">{# assumptions: var = 5, var2 = <span class="stringliteral">&quot;foo&quot;</span> #}

{{ var|add:5 }}       {# =&gt; 10 #}
{{ var2|add:<span class="stringliteral">&quot; bar&quot;</span> }} {# =&gt; foo bar #}
</pre></div><h3><a class="anchor" id="stdlib-filter-addslashes"></a>
<p>See PHP's <code>addslashes</code> function.</p>
<div class="fragment"><pre class="fragment">{# var = foo\bar<span class="stringliteral">&#39; #}</span>
<span class="stringliteral"></span>
<span class="stringliteral">{{ var|addslashes }} {# =&gt; foo\\bar\&#39; #}</span>
</pre></div><h3><a class="anchor" id="stdlib-filter-capfirst"></a>
capfirst, lower, upper, title</h3>
<p>Changes capitalization of the string variable - <code>capfirst</code> capitalizes first letter, <code>lower</code> converts entire string into lowercase, <code>upper</code> converts entire string into uppercase, and <code>title</code> converts entire string into titlecase (e.g. converts every first letter of a word into uppercase).</p>
<p>Also see PHP's <code>mb_convert_case</code> function.</p>
<div class="fragment"><pre class="fragment">{# var = hEllo woRld #}

{{ var|capfirst }} {# =&gt; HEllo woRld #}
{{ var|lower }}    {# =&gt; hello world #}
{{ var|upper }}    {# =&gt; HELLO WORLD #}
{{ var|title }}    {# =&gt; HEllo WoRld #}
</pre></div><h3><a class="anchor" id="stdlib-filter-cut"></a>
<p>Removes the argument from the string variable. <code>argument</code> can be a variable or a constant. Uses PHP's <code>preg_replace</code>.</p>
<div class="fragment"><pre class="fragment">{# var = <span class="stringliteral">&quot;foo bar baz&quot;</span> #}

{{ var|cut:<span class="stringliteral">&quot;bar&quot;</span> }} {# =&gt; foo  baz #}
</pre></div><h3><a class="anchor" id="stdlib-filter-date"></a>
<p>Formats the timestamp according to the <code>format</code>. See PHP's <code>date</code> function.</p>
<div class="fragment"><pre class="fragment">{# var = 123456789 #}

{{ var|date:<span class="stringliteral">&quot;d-m-Y, H:i:s&quot;</span> }} {# =&gt; 29-11-1973, 22:33:09 #}
</pre></div><h3><a class="anchor" id="stdlib-filter-default"></a>
default, default_if_none</h3>
<p>Uses default value if variable doesn't exist (or evaluates to false, <code>default</code>) or is NULL (<code>default_if_none</code>). <code>value</code> can be a constant, or a variable.</p>
<div class="fragment"><pre class="fragment">{# nonexistant does not exist, nullvar is NULL #}

{{ @nonexistant|<span class="keywordflow">default</span>:<span class="stringliteral">&quot;none&quot;</span> }}    {# =&gt; none; silenced, otherwise a warning would be issued #}
{{ nullvar|default_if_none:<span class="stringliteral">&quot;none&quot;</span> }} {# =&gt; none #}
</pre></div><h3><a class="anchor" id="stdlib-filter-divisibleby"></a>
<p>Returns <code>true</code> if variable is evenly divisible by <code>value</code> (which can be either variable or a constant number different than zero).</p>
<div class="fragment"><pre class="fragment">{# var1 = 2, var2 = 3 #}

{% <span class="keywordflow">if</span> var1|divisibleby:2 %} yes {% <span class="keywordflow">else</span> %} no {% endif %} {# =&gt; yes #}
{% <span class="keywordflow">if</span> var2|divisibleby:2 %} yes {% <span class="keywordflow">else</span> %} no {% endif %} {# =&gt; no #}
</pre></div><h3><a class="anchor" id="stdlib-filter-escape"></a>
escape and safe</h3>
<p><code>escape</code> applies <code>htmlspecialchars</code> function to the variable. <code>safe</code> is a pseudofilter (i.e. it's not actually defined and it's handled by hooks instead) that marks variable as safe (i.e. already escaped, or that it doesn't need escaping at all) causing autoescaping (see <a class="el" href="tutorial.html#tut-security">Security settings in SithTemplate</a>) to skip it.</p>
<div class="fragment"><pre class="fragment">{# var = <span class="stringliteral">&quot;&lt;b&gt;foo&lt;/b&gt;&quot;</span> #}

{{ var|escape }} {# =&gt; &amp;lt;b&amp;gt;foo&amp;lt;/b&amp;gt; #}
</pre></div><h3><a class="anchor" id="stdlib-filter-filesizeformat"></a>
<p>Formats the integer variable as human-readable filesize (e.g. to bytes, kilobytes, megabytes, gigabytes).</p>
<div class="fragment"><pre class="fragment">{# var1 = 1000, var2 = 41211, var3 = 5230121, var4 = 5232338952 #}

{{ var1|filesizeformat }} {# =&gt; 1000 b #}
{{ var2|filesizeformat }} {# =&gt; 40.25 kB #}
{{ var3|filesizeformat }} {# =&gt; 4.99 MB #}
{{ var4|filesizeformat }} {# =&gt; 4.87 GB #}
</pre></div><h3><a class="anchor" id="stdlib-filter-fixampersands"></a>
<p>Changes every <code>&amp;</code> into <code>&amp;</code> HTML entity.</p>
<div class="fragment"><pre class="fragment">{# var = <span class="stringliteral">&quot;foo&amp;bar&quot;</span> #}

{{ var|fix_ampersands }} {# =&gt; foo&amp;amp;bar #}
</pre></div><h3><a class="anchor" id="stdlib-filter-join"></a>
<p><code>implode's</code> an array variable using <code>separator</code> (a variable, or a constant).</p>
<div class="fragment"><pre class="fragment">{# var = array(<span class="charliteral">&#39;a&#39;</span>, <span class="charliteral">&#39;b&#39;</span>, <span class="charliteral">&#39;c&#39;</span>) <span class="preprocessor">#}</span>
<span class="preprocessor"></span>
{{ var|join:<span class="stringliteral">&quot;, &quot;</span> }} {# =&gt; a, b, c #}
</pre></div><h3><a class="anchor" id="stdlib-filter-length"></a>
length, length_is</h3>
<p><code>length</code> returns length of a string or count of an array elements. <code>length_is</code> compares that length with a <code>number</code> (a variable, or a constant number), and returns boolean.</p>
<div class="fragment"><pre class="fragment">{# var1 = <span class="stringliteral">&quot;foo&quot;</span>, var2 = array(<span class="charliteral">&#39;a&#39;</span>, <span class="charliteral">&#39;b&#39;</span>) <span class="preprocessor">#}</span>
<span class="preprocessor"></span>
{{ var1|length }}                                       {# =&gt; 3 #}
{% <span class="keywordflow">if</span> var2|length_is:3 %} yes {% <span class="keywordflow">else</span> %} no {% endif %} {# =&gt; no #}
</pre></div><h3><a class="anchor" id="stdlib-filter-linebreaks"></a>
linebreaks, linebreaksbr</h3>
<p><code>linebreaks</code> converts newlines in the variable into HTML paragraphs and linebreaks. <code>linebreaksbr</code> applies <code>nl2br</code>.</p>
<div class="fragment"><pre class="fragment">{% comment %}
 var = <span class="stringliteral">&quot;foo</span>
<span class="stringliteral"> </span>
<span class="stringliteral"> bar</span>
<span class="stringliteral"> baz&quot;</span>
{% endcomment %}

{{ var|linebreaks }}
{% comment %}
 Outputs (whitespace may vary):
 &lt;p&gt;bar&lt;br /&gt;
{% endcomment %}

{{ var|linebreaksbr }}
{% comment %}
 Outputs (whitespace may vary):
 foo&lt;br /&gt;
 &lt;br /&gt;
 bar&lt;br /&gt;
{% endcomment %}
</pre></div><h3><a class="anchor" id="stdlib-filter-ljust"></a>
ljust, rjust</h3>
<p>Aligns the text inside the field of given <code>width</code>.</p>
<div class="fragment"><pre class="fragment">{# var = <span class="stringliteral">&quot;foo&quot;</span> #}

{{ var|ljust:5 }} {# =&gt; <span class="stringliteral">&quot;foo  &quot;</span> #}
{{ var|rjust:5 }} {# =&gt; <span class="stringliteral">&quot;  foo&quot;</span> #}
</pre></div><h3><a class="anchor" id="stdlib-filter-makelist"></a>
<p>Splits the string/numeric variable into an array of characters/digits.</p>
<div class="fragment"><pre class="fragment">{# var = <span class="stringliteral">&quot;foo&quot;</span> #}

{{ var|make_list|join:<span class="stringliteral">&quot;, &quot;</span> }} {# =&gt; f, o, o #}
</pre></div><h3><a class="anchor" id="stdlib-filter-pluralize"></a>
<p>Returns plural suffix <code>-s</code> if the filtered variable evaluates to integer bigger than 1.</p>
<p>Returns user-specified plural suffix instead. <code>suffix</code> must be a quoted constant string.</p>
<p>Returns either singular or plural suffix, both user-specified in <code>suffixes</code>, and delimited by a comma. <code>suffixes</code> must be a quoted constant string.</p>
<div class="fragment"><pre class="fragment">{# var1 = 1, var2 = 7 #}

{{ var1|pluralize }} {# outputs nothing #}
{{ var2|pluralize }} {# outputs <span class="charliteral">&#39;s&#39;</span> #}

{{ var1|pluralize:<span class="stringliteral">&quot;es&quot;</span> }} {# outputs nothing #}
{{ var2|pluralize:<span class="stringliteral">&quot;es&quot;</span> }} {# outputs <span class="stringliteral">&#39;es&#39;</span> #}

{{ var1|pluralize:<span class="stringliteral">&quot;e,es&quot;</span> }} {# outputs <span class="charliteral">&#39;e&#39;</span> #}
{{ var2|pluralize:<span class="stringliteral">&quot;e,es&quot;</span> }} {# outputs <span class="stringliteral">&#39;es&#39;</span> #}
</pre></div><h3><a class="anchor" id="stdlib-filter-random"></a>
<p>Returns random element of the filtered array.</p>
<div class="fragment"><pre class="fragment">{# var = array(<span class="charliteral">&#39;a&#39;</span>, <span class="charliteral">&#39;b&#39;</span>) <span class="preprocessor">#}</span>
<span class="preprocessor"></span>
{{ var|random }} {# will output either <span class="charliteral">&#39;a&#39;</span> or <span class="charliteral">&#39;b&#39;</span> #}
</pre></div><h3><a class="anchor" id="stdlib-filter-removetags"></a>
<p>Applies PHP's <code>strip_tags</code> on filtered variable.</p>
<div class="fragment"><pre class="fragment">{# var = <span class="stringliteral">&quot;&lt;b&gt;foo&lt;/b&gt;&quot;</span> #}

{{ var|removetags }} {# =&gt; foo #}
</pre></div><h3><a class="anchor" id="stdlib-filter-slugify"></a>
<p>Converts the string into a URL-friendly "slug", i.e. converts it to lowercase, strips HTML tags, converts all whitespace and underscores into dashes, and removes all remaining characters that are neither dash, nor alphanumeric.</p>
<div class="fragment"><pre class="fragment">{# UTF-8 ahead #}
{# var = <span class="stringliteral">&quot;Hai ąą   #1331&quot;</span> #}

{{ var|slugify }} {# =&gt; hai--1331 #}
</pre></div><h3><a class="anchor" id="stdlib-filter-urlencode"></a>
urlencode, urldecode</h3>
<p>PHP's <code>urlencode</code> and <code>urldecode</code>, respectively.</p>
<div class="fragment"><pre class="fragment">{# var = <span class="stringliteral">&quot;http://example.com&quot;</span> #}

{{ var|urlencode }}           {# =&gt; http%3A%2F%2Fexample.com #}
{{ var|urlencode|urldecode }} {# =&gt; http:<span class="comment">//example.com #}</span>
</pre></div><h3><a class="anchor" id="stdlib-filter-wordcount"></a>
<p>Counts the words in the string, using PHP's <code>str_word_count</code>.</p>
<div class="fragment"><pre class="fragment">{# var = <span class="stringliteral">&quot;foo bar baz&quot;</span> #}

{{ var|wordcount }} {# =&gt; 3 #}
</pre></div><h3><a class="anchor" id="stdlib-filter-wordwrap"></a>
<p>Applies PHP's <code>wordwrap</code>, using given <code>length</code> (a variable or a constant number).</p>
<div class="fragment"><pre class="fragment">{# var = <span class="stringliteral">&quot;foobar foobar foobar&quot;</span> #}

{{ var|wordwrap:6|linebreaksbr }}
{% comment %}
 Will output:
 foobar&lt;br /&gt;
 foobar&lt;br /&gt;
{% endcomment %}
</pre></div><h2><a class="anchor" id="stdlib-variables"></a>
Special variables</h2>
<h3><a class="anchor" id="stdlib-var-block"></a>
{{ block }}</h3>
<p>This variable is accessible from within <a class="el" href="stdlib.html#stdlib-tag-block">{% block %}</a> tag.</p>
<p>It contains only one subkey - <code>{{ block.super }}</code> which evaluates to the contents of parent block.</p>
<div class="fragment"><pre class="fragment">{# parent <span class="keyword">template</span>: #}
{% block something %}
{% endblock %}

{# child <span class="keyword">template</span>: #}
{% block something %}
 &lt;p&gt;something <span class="keywordflow">else</span>?&lt;/p&gt; {{ block.super }}
{% endblock %}

{# output: &lt;p&gt;something <span class="keywordflow">else</span>?&lt;/p&gt; &lt;p&gt;something!&lt;/p&gt; #}
{# whitespace may vary #}
</pre></div><h3><a class="anchor" id="stdlib-var-forloop"></a>
{{ forloop }}</h3>
<p>This variable is accessible from within the <code>for</code> loop (see <a class="el" href="stdlib.html#stdlib-tag-for">{% for %} and {% empty %}</a>).</p>
<p>It contains several subkeys: </p>
<code>{{ forloop.counter }}</code> - current iteration, starting from 1 </li>
<code>{{ forloop.counter0 }}</code> - current iteration, starting from 0 </li>
<code>{{ forloop.revcounter }}</code> - number of iterations left, ending on 1 </li>
<code>{{ forloop.revcounter0 }}</code> - number of iterations left, ending on 0 </li>
<code>{{ forloop.first }}</code> - true if first iteration </li>
<code>{{ forloop.last }}</code> - true if last iteration </li>
<code>{{ forloop.parentloop }}</code> - <code>forloop</code> variable of the parent loop, available in nested loops </li>
<div class="fragment"><pre class="fragment">{% <span class="keywordflow">for</span> v in vs %}
 {% <span class="keywordflow">if</span> forloop.first %}first!{% endif %}
 {% <span class="keywordflow">if</span> forloop.last %}last!{% endif %}
 {{ forloop.counter }}/{{ forloop.counter0 }}
 {{ forloop.revcounter }}/{{ forloop.revcounter0 }}
 {% <span class="keywordflow">for</span> x in xs %}
  {{ forloop.parentloop.counter }}
 {% endfor %}
{% endfor %}
</pre></div><h3><a class="anchor" id="stdlib-var-internal"></a>
{{ internal }}</h3>
<p>This variable is accessible in the entire template.</p>
<p>It contains several subkeys: </p>
<code>{{ internal.request }}</code> - allows you to access PHP's superglobals (also see <a class="el" href="tutorial.html#tut-security">Security settings in SithTemplate</a>) </li>
<code>{{ internal.const }}</code> - allows you to access PHP's constants (also see <a class="el" href="tutorial.html#tut-security">Security settings in SithTemplate</a>) </li>
<code>{{ internal.version }}</code> - evaluates to the current engine's version (e.g. SITHTEMPLATE_VERSION)<ul>
<li>keep in mind that this value is hardcoded into the template's code, so it won't change without recompilation  </li>
<div class="fragment"><pre class="fragment">{{ <span class="keyword">internal</span>.request.POST.foo }}
{{ <span class="keyword">internal</span>.const.PHP_VERSION }}
{{ <span class="keyword">internal</span>.version }}
</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>
Return current item: SithTemplate