A tiny, fast, and easy HTML template engine
The easiest way to use Cleverly is simply to clone the repository (such as with a git submodule) and include or require it in your code. No fancy package managers here.
index.php:
<?php
include(__DIR__ . '/Cleverly.class.php');
$cleverly = new Cleverly();
$cleverly->setTemplateDir(__DIR__ . '/templates');
$cleverly->display('index.tpl', array('greeting' => 'Hello'));
?>
templates/index.tpl:
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<body>
<p>{$greeting}, world!</p>
</body>
</html>
In general, Cleverly provides the same syntax, structure, and features as Smarty, an older and heavier template engine. (In fact, one of the main reasons Cleverly was written at all was to provide a single-file alternative to Smarty.) As such, the extensive Smarty 2 usage documentation is a good reference.
Check out Hell Quotes for an example of a dynamic project and Opcode Table for an example of a statically generated project, both using Cleverly.
-
{foreach from=from item=item} ... {/foreach}
{foreach loop=loop item=item} ... {/foreach}
Either loops over an array of data (from) or just loops a certain number of times (loop). The current value being looped over is stored into a variable called item. This directive corresponds to both
foreachandsectionin Smarty 2. The content between the opening and closingforeachtags is outputted once for each iteration of the loop. -
{if a} ... {/if}
{if a op b} ... {/if}
Only outputs the content between the opening and closing
iftags if a is truthy (if b is not provided) or the comparison between a and b is true (if b is provided). op should be one of the following operations:eqor==: equalsneqor!=: not equalsgtor>: greater thanltor<: less thangteorgeor>=: greater than or equallteorleor<=: less than or equal===: check for identity
This directive corresponds to
ifin Smarty 2. -
{include file=file}
{include from=from}
Either includes another template (file) or the result of a function stored to a variable (from). If file is provided, it should either be a plain string delimited by single quotes or a variable containing the path to include. This directive corresponds to
includein Smarty 2, as well as its concept of plugins. All variables and configurations that apply to the current template also apply to the included template. -
{include_php file=file}
Includes the output of a PHP script. file should either be a plain string delimited by single quotes or a variable containing the path to include. This directive corresponds to
include_phpin Smarty 2. -
{ldelim}
Outputs the left delimiter (the value of
leftDelimiter, which defaults to"{"). This directive corresponds toldelimin Smarty 2. This is basically a way to escape the template delimiter in the output. -
{literal} ... {/literal}
Outputs the content between the opening and closing
literaltags without any further processing. This directive corresponds toliteralin Smarty 2. -
{php} ... {/php}
Executes the content between the opening and closing
phptags as PHP code. This directive corresponds tophpin Smarty 2. -
{rdelim}
Outputs the right delimiter (the value of
rightDelimiter, which defaults to"}"). This directive corresponds tordelimin Smarty 2. This is basically a way to escape the template delimiter in the output. -
{$var}
Outputs the contents of variable $var.
In general, whenever a variable is called for—whether printing it directly or
using it as a parameter to foreach, include, or include_php—you should
provide a standard variable name (a string of letters, numbers, or
underscores), possibly with an index (to fetch a specific element in an array).
The only exception is the item parameter on foreach, which does not permit
an index.
The following are all valid invocations:
{foreach from=$array_var item=element_var} ... {/foreach}
{foreach from=$array_of_arrays_var.key item=element_var} ... {/foreach}
{foreach from=$array_of_arrays_var[42] item=element_var} ... {/foreach}
{if $variable}
{if $first_variable eq 'expected value'}
{if $first_variable neq $second_variable}
{if $first_variable gt 6.02e23}
{include file='file_name.tpl'}
{include file=$string_var}
{include file=$array_of_strings_var.key}
{include file=$array_of_strings_var[42]}
{include from=$string_var}
{include from=$array_of_strings_var.key}
{include from=$array_of_strings_var[42]}
{include_php file='file_name.tpl'}
{include_php file=$string_var}
{include_php file=$array_of_strings_var.key}
{include_php file=$array_of_strings_var[42]}
{$string_var}
{$array_or_object_of_strings_var.key}
{$array_or_object_of_strings_var[42]}
Variables are defined in one of two ways: they are either passed in through the
$vars array when calling display or fetch or assigned to item as part
of a foreach loop.
Plugins are a special type of template variable assigned an anonymous
function and used with
include. The following example illustrates a plugin that displays the current
time.
index.php:
<?php
include(__DIR__ . '/Cleverly.class.php');
$get_date = function() {
return strftime('%c');
}
$cleverly = new Cleverly();
$cleverly->setTemplateDir(__DIR__ . '/templates');
$cleverly->display('index.tpl', array('get_date' => $get_date));
?>
templates/index.tpl:
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<body>
<p>The current time is {include from=get_date}</p>
</body>
</html>
-
addTemplateDir($dir, $key=null)
Adds one (if $dir is a string) or more (if $dir is an array) paths to the list of template directories. If $key is provided, it is associated with a single $dir for the purposes of the
getTemplateDirmethod. Similarly, if $dir is an associative array, each key is associated with each path provided. This method corresponds toaddTemplateDirin Smarty 3. -
display($template, $vars=array())
Displays the output of the template $template. If $template starts with the special protocol
"string:", the remainder of $template is treated as the contents of the template to import. Otherwise, it treats $template as a path (either local or remote) to the template to use. Keys in the optional associative array $vars provides a list of variable names and values (as key--value pairs) which can be used in the template (or any included templates). This method corresponds todisplayin Smarty 3. -
fetch($template, $vars=array())
Returns the output of the template $template as a string. If $template starts with the special protocol
"string:", the remainder of $template is treated as the contents of the template to import. Otherwise, it treats $template as a path (either local or remote) to the template to use. Keys in the optional associative array $vars provides a list of variable names and values (as key--value pairs) which can be used in the template (or any included templates). This method corresponds tofetchin Smarty 3. -
getTemplateDir($key=null)
Returns the list of known template directories (if $key is not provided) or a single template directory associated with a key (if $key is provided). This method corresponds to
getTemplateDirin Smarty 3. -
setTemplateDir($dir)
Sets the list of known template directories to one (if $dir is a string) or more (if $dir is an array) template directories. If $dir is an associative array, each key is associated with each path provided for the purposes of the
getTemplateDirmethod. Thedisplayandfetchmethods, as well as theincludedirective, look for files under known template directories. By default, the only template directory is ./templates. This method corresponds tosetTemplateDirin Smarty 3.
-
leftDelimiter
The left delimiter used by the template language, which defaults to
"{". -
preserveIndent
Whether or not to accumulate indentation in variable expansions and included files. This is basically a pretty-printing toggle.
-
rightDelimiter
The right delimiter used by the template language, which defaults to
"}".