The implementation of the Stupid Template Engine.
| stupid_template_engine.php | The implementation of the Stupid Template Engine. |
| License | This file is licensed under the MIT/X11 License. |
| ste | Everything in this file is in this namespace. |
| RuntimeError | An Exception that a tag can throw, if a non-fatal runtime error occurred. |
| FatalRuntimeError | An Exception a tag can throw, if a fatal (irreparable) runtime error occurred. |
| Functions | |
| precompile | Precompiling STE T/PL templates. |
| parse | Parsing a STE T/PL template. |
| transcompile | Transcompiles an abstract syntax tree to PHP. |
| Constants | |
| Template modes | |
| CantLoadTemplate | An exception that a StorageAccess implementation can throw, if it is unable to load a template. |
| CantSaveTemplate | An exception that a StorageAccess implementation can throw, if it is unable to save a template. |
| StorageAccess | An interface. |
| Functions | |
| load | Loading a template. |
| save | Saves a template. |
| FilesystemStorageAccess | The default StorageAccess implementation for loading / saving templates into a directory structure. |
| Functions | |
| __construct | |
| STECore | The Core of STE |
| Variables | |
| Public variables | |
| Functions | |
| __construct | |
| register_tag | Register a custom tag. |
| call_tag | Calling a custom tag (builtin ones can not be called) |
| exectemplate | Executes a template and returns the result. |
| get_var_reference | Get a reference to a template variable using a variable name. |
| set_var_by_name | Set a template variable by its name. |
| get_var_by_name | Get a template variable by its name. |
| load | Load a template and return its result (blocks not included, use exectemplate for this). |
| evalbool | Test, if a text represents false (an empty / only whitespace text) or true (everything else). |
An Exception that a tag can throw, if a non-fatal runtime error occurred. By default this will return in no output at all. But if STECore::$mute_runtime_errors is false, this will generate a error message instead of the tag’s output.
An Exception a tag can throw, if a fatal (irreparable) runtime error occurred. This Exception will always “bubble up” so you probably want to catch them. Remember that this exception is also in the namespace ste!
| Functions | |
| precompile | Precompiling STE T/PL templates. |
| parse | Parsing a STE T/PL template. |
| transcompile | Transcompiles an abstract syntax tree to PHP. |
| Constants | |
| Template modes |
function parse( $code, $tpl )
Parsing a STE T/PL template. You only need this function, if you want to manually transcompile a template.
| $code | The STE T/PL code. |
| $tpl | The name of the template. |
An abstract syntax tree, which can be used with transcompile.
function transcompile( $ast ) /* Transcompile and add some boilerplate code. */
Transcompiles an abstract syntax tree to PHP. You only need this function, if you want to manually transcompile a template.
| $ast | The abstract syntax tree to transcompile. |
PHP code. The PHP code is an anonymous function expecting a STECore instance as its parameter and returns a string (everything that was not pached into a section).
An exception that a StorageAccess implementation can throw, if it is unable to load a template.
An exception that a StorageAccess implementation can throw, if it is unable to save a template.
public function load( $tpl, & $mode )
Loading a template.
| $tpl | The name of the template. |
| &$mode | Which mode is preferred? One of the <Template modes>. If <MODE_SOURCE>, the raw sourcecode is expected, if <MODE_TRANSCOMPILED> the transcompiled template as a callable function (expecting an STECore instance as first parameter) is expected. If the transcompiled version is not available or older than the source, you can set this parameter to <MODE_SOURCE> and return the source. |
A CantLoadTemplate exception if the template could not be loaded.
Either the sourcecode or a callable function (first, and only parameter: an STECore instance).
public function save( $tpl, $data, $mode )
Saves a template.
A CantSaveTemplate exception if the template could not be saved.
$tpl -The name of the template. $data - The data to be saved. $mode - A <Template mode> constant.
The default StorageAccess implementation for loading / saving templates into a directory structure.
public function __construct( $src, $transc )
| $src | The directory with the sources (Writing permissions are not mandatory, because STE does not save template sources). |
| $transc | The directory with the transcompiled templates (the PHP instance / the HTTP Server needs writing permissions to this directory). |
The Core of STE
| Variables | |
| Public variables | |
| Functions | |
| __construct | |
| register_tag | Register a custom tag. |
| call_tag | Calling a custom tag (builtin ones can not be called) |
| exectemplate | Executes a template and returns the result. |
| get_var_reference | Get a reference to a template variable using a variable name. |
| set_var_by_name | Set a template variable by its name. |
| get_var_by_name | Get a template variable by its name. |
| load | Load a template and return its result (blocks not included, use exectemplate for this). |
| evalbool | Test, if a text represents false (an empty / only whitespace text) or true (everything else). |
| $blocks | Associative array of blocks (see the language definition). |
| $blockorder | The order of the blocks (an array) |
| $vars | Associative array of all template variables. Use this to pass data to your templates. |
| $mute_runtime_errors | If True (default) a RuntimeError exception will result in no output from the tag, if False a error message will be written to output. |
| $fatal_error_on_missing_tag | If True, STE will throw a FatalRuntimeError if a tag was called that was not registered, otherwise (default) a regular RuntimeError will be thrown and automatically handled by STE (see <$mute_runtime_errors>). |
public function __construct( $storage_access )
| $storage_access | An Instance of a StorageAccess implementation. |
public function register_tag( $name, $callback )
Register a custom tag.
| $name | The name of the tag. |
| $callback | A callable function (This must tage three parameters: The STECore instance, an associative array of parameters, and a function representing the tags content(This expects the STECore instance as its only parameter and returns its text result, i.e to get the text, you neeed to call this function with the STECore instance as a parameter)). |
An Exception if the tag could not be registered (if $callback is not callable or if $name is empty)
public function call_tag( $name, $params, $sub )
Calling a custom tag (builtin ones can not be called)
| $name | The Tag’s name |
| $params | Associative array of parameters |
| $sub | A callable function (expecting an STECore instance as it’s parameter) that represents the tag’s content. |
Might throw a FatalRuntimeError (see $fatal_error_on_missing_tag.
The output of the tag or, if a RuntimeError was thrown, the appropiate result (see <$mute_runtime_errors>).
public function exectemplate( $tpl )
Executes a template and returns the result. The huge difference to load is that this function will also output all blocks.
| $tpl | The name of the template to execute. |
The output of the template.
public function &get_var_reference( $name, $create_if_not_exist )
Get a reference to a template variable using a variable name. This can be used,if your custom tag takes a variable name as a parameter.
| $name | The variables name. |
| $create_if_not_exist | Should the variable be created, if it does not exist? Otherwise NULL will be returned, if the variable does not exist. |
RuntimeError if the variable name can not be parsed (e.g. unbalanced brackets).
A Reference to the variable.
public function set_var_by_name( $name, $val )
Set a template variable by its name. This can be used,if your custom tag takes a variable name as a parameter.
| $name | The variables name. |
| $val | The new value. |
RuntimeError if the variable name can not be parsed (e.g. unbalanced brackets).
public function get_var_by_name( $name )
Get a template variable by its name. This can be used,if your custom tag takes a variable name as a parameter.
| $name | The variables name. |
RuntimeError if the variable name can not be parsed (e.g. unbalanced brackets).
The variables value.
public function load( $tpl, $quiet = False )
Load a template and return its result (blocks not included, use exectemplate for this).
| $tpl | The name of the template to be loaded. |
| $quiet | If true, do not output anything and do notmodify the blocks. This can be useful to load custom tags that are programmed in STE T/PL. Default: false. |
The result of the template (if $quiet == false).
Precompiling STE T/PL templates.
function precompile( $code )
Parsing a STE T/PL template.
function parse( $code, $tpl )
Transcompiles an abstract syntax tree to PHP.
function transcompile( $ast ) /* Transcompile and add some boilerplate code. */
Loading a template.
public function load( $tpl, & $mode )
Saves a template.
public function save( $tpl, $data, $mode )
public function __construct( $src, $transc )
public function __construct( $storage_access )
Register a custom tag.
public function register_tag( $name, $callback )
Calling a custom tag (builtin ones can not be called)
public function call_tag( $name, $params, $sub )
Executes a template and returns the result.
public function exectemplate( $tpl )
Get a reference to a template variable using a variable name.
public function &get_var_reference( $name, $create_if_not_exist )
Set a template variable by its name.
public function set_var_by_name( $name, $val )
Get a template variable by its name.
public function get_var_by_name( $name )
Load a template and return its result (blocks not included, use exectemplate for this).
public function load( $tpl, $quiet = False )
Test, if a text represents false (an empty / only whitespace text) or true (everything else).
public function evalbool( $txt )