From a8eea9562d9961fb9b55ccbf4b01cc9c8bc10e63 Mon Sep 17 00:00:00 2001 From: Kevin Chabowski Date: Wed, 29 Feb 2012 22:22:28 +0100 Subject: Forgot to include the new documentation. --- docu/nd/files/stupid_template_engine-php.html | 54 +++++++++++++++------------ 1 file changed, 31 insertions(+), 23 deletions(-) (limited to 'docu/nd/files/stupid_template_engine-php.html') diff --git a/docu/nd/files/stupid_template_engine-php.html b/docu/nd/files/stupid_template_engine-php.html index b7b8ea3..2d68e6b 100644 --- a/docu/nd/files/stupid_template_engine-php.html +++ b/docu/nd/files/stupid_template_engine-php.html @@ -11,61 +11,69 @@ if (browserType) {document.write("
");if (browserV -

stupid_template_engine.php

The implementation of the Stupid Template Engine.

Summary
stupid_template_engine.phpThe implementation of the Stupid Template Engine.
LicenseThis file is licensed under the MIT/X11 License.
steEverything in this file is in this namespace.
Functions
precompilePrecompiling STE T/PL templates.
parseParsing a STE T/PL template.
transcompileTranscompiles an abstract syntax tree to PHP.
Constants
Template modes
StorageAccessAn interface.
Functions
loadLoading a template.
saveSaves a template.
FilesystemStorageAccessThe default StorageAccess implementation for loading / saving templates into a directory structure.
Functions
__construct
STECoreThe Core of STE
Variables
Public variables
Functions
__construct
register_tagRegister a custom tag.
call_tagCalling a custom tag (builtin ones can not be called)
exectemplateExecutes a template and returns the result.
get_var_referenceGet a reference to a template variable using a variable name.
set_var_by_nameSet a template variable by its name.
get_var_by_nameGet a template variable by its name.
loadLoad a template and return its result (blocks not included, use exectemplate for this).
evalboolTest, if a text represents false (an empty / only whitespace text) or true (everything else).
+

stupid_template_engine.php

The implementation of the Stupid Template Engine.

Summary
stupid_template_engine.phpThe implementation of the Stupid Template Engine.
LicenseThis file is licensed under the MIT/X11 License.
steEverything in this file is in this namespace.
RuntimeErrorAn Exception that a tag can throw, if a non-fatal runtime error occurred.
FatalRuntimeErrorAn Exception a tag can throw, if a fatal (irreparable) runtime error occurred.
Functions
precompilePrecompiling STE T/PL templates.
parseParsing a STE T/PL template.
transcompileTranscompiles an abstract syntax tree to PHP.
Constants
Template modes
CantLoadTemplateAn exception that a StorageAccess implementation can throw, if it is unable to load a template.
CantSaveTemplateAn exception that a StorageAccess implementation can throw, if it is unable to save a template.
StorageAccessAn interface.
Functions
loadLoading a template.
saveSaves a template.
FilesystemStorageAccessThe default StorageAccess implementation for loading / saving templates into a directory structure.
Functions
__construct
STECoreThe Core of STE
Variables
Public variables
Functions
__construct
register_tagRegister a custom tag.
call_tagCalling a custom tag (builtin ones can not be called)
exectemplateExecutes a template and returns the result.
get_var_referenceGet a reference to a template variable using a variable name.
set_var_by_nameSet a template variable by its name.
get_var_by_nameGet a template variable by its name.
loadLoad a template and return its result (blocks not included, use exectemplate for this).
evalboolTest, if a text represents false (an empty / only whitespace text) or true (everything else).

License

This file is licensed under the MIT/X11 License.  See COPYING for more details.

-

ste

Everything in this file is in this namespace.

Summary
Functions
precompilePrecompiling STE T/PL templates.
parseParsing a STE T/PL template.
transcompileTranscompiles an abstract syntax tree to PHP.
Constants
Template modes
+

ste

Everything in this file is in this namespace.

-

Functions

+

RuntimeError

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.

-

precompile

function precompile($code)

Precompiling STE T/PL templates.  You only need this function, if you want to manually transcompile a template.

Parameters

$codeThe input code

Returns

The precompiled code.

+

FatalRuntimeError

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!

Summary
Functions
precompilePrecompiling STE T/PL templates.
parseParsing a STE T/PL template.
transcompileTranscompiles an abstract syntax tree to PHP.
Constants
Template modes
-

parse

function parse($code,
$tpl)

Parsing a STE T/PL template.  You only need this function, if you want to manually transcompile a template.

Parameters

$codeThe STE T/PL code.
$tplThe name of the template.

Returns

An abstract syntax tree, which can be used with transcompile.

+

Functions

-

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.

Parameters

$astThe abstract syntax tree to transcompile.

Returns

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).

+

precompile

function precompile($code)

Precompiling STE T/PL templates.  You only need this function, if you want to manually transcompile a template.

Parameters

$codeThe input code

Returns

The precompiled code.

-

Constants

+

parse

function parse($code,
$tpl)

Parsing a STE T/PL template.  You only need this function, if you want to manually transcompile a template.

Parameters

$codeThe STE T/PL code.
$tplThe name of the template.

Returns

An abstract syntax tree, which can be used with transcompile.

-

Template modes

MODE_SOURCEThe Templates source
MODE_TRANSCOMPILEDThe transcompiled template
+

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.

Parameters

$astThe abstract syntax tree to transcompile.

Returns

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).

-

StorageAccess

An interface.  A StorageAccess implementation is used to access the templates from any storage.  This means, that you are not limited to store the Templates inside directories, you can also use a database or something else.

Summary
Functions
loadLoading a template.
saveSaves a template.
+

Constants

+ +

Template modes

MODE_SOURCEThe Templates source
MODE_TRANSCOMPILEDThe transcompiled template
+ +

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.  A StorageAccess implementation is used to access the templates from any storage.  This means, that you are not limited to store the Templates inside directories, you can also use a database or something else.

Summary
Functions
loadLoading a template.
saveSaves a template.

Functions

-

load

public function load($tpl,
&$mode)

Loading a template.

Parameters

$tplThe name of the template.
&$modeWhich 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.

Returns

Either the sourcecode or a callable function (first, and only parameter: an STECore instance).

+

load

public function load($tpl,
&$mode)

Loading a template.

Parameters

$tplThe name of the template.
&$modeWhich 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.

Throws

A CantLoadTemplate exception if the template could not be loaded.

Returns

Either the sourcecode or a callable function (first, and only parameter: an STECore instance).

-

save

public function save($tpl,
$data,
$mode)

Saves a template.

Parameters

$tpl -The name of the template.  $data - The data to be saved.  $mode - A <Template mode> constant.

+

save

public function save($tpl,
$data,
$mode)

Saves a template.

Throws

A CantSaveTemplate exception if the template could not be saved.

Parameters

$tpl -The name of the template.  $data - The data to be saved.  $mode - A <Template mode> constant.

-

FilesystemStorageAccess

The default StorageAccess implementation for loading / saving templates into a directory structure.

Summary
Functions
__construct
+

FilesystemStorageAccess

The default StorageAccess implementation for loading / saving templates into a directory structure.

Summary
Functions
__construct

Functions

__construct

public function __construct($src,
$transc)

Parameters

$srcThe directory with the sources (Writing permissions are not mandatory, because STE does not save template sources).
$transcThe directory with the transcompiled templates (the PHP instance / the HTTP Server needs writing permissions to this directory).
-

STECore

The Core of STE

Summary
Variables
Public variables
Functions
__construct
register_tagRegister a custom tag.
call_tagCalling a custom tag (builtin ones can not be called)
exectemplateExecutes a template and returns the result.
get_var_referenceGet a reference to a template variable using a variable name.
set_var_by_nameSet a template variable by its name.
get_var_by_nameGet a template variable by its name.
loadLoad a template and return its result (blocks not included, use exectemplate for this).
evalboolTest, if a text represents false (an empty / only whitespace text) or true (everything else).
+

STECore

The Core of STE

Summary
Variables
Public variables
Functions
__construct
register_tagRegister a custom tag.
call_tagCalling a custom tag (builtin ones can not be called)
exectemplateExecutes a template and returns the result.
get_var_referenceGet a reference to a template variable using a variable name.
set_var_by_nameSet a template variable by its name.
get_var_by_nameGet a template variable by its name.
loadLoad a template and return its result (blocks not included, use exectemplate for this).
evalboolTest, if a text represents false (an empty / only whitespace text) or true (everything else).

Variables

-

Public variables

$blocksAssociative array of blocks (see the language definition).
$blockorderThe order of the blocks (an array)
$varsAssociative array of all template variables.  Use this to pass data to your templates.
+

Public variables

$blocksAssociative array of blocks (see the language definition).
$blockorderThe order of the blocks (an array)
$varsAssociative array of all template variables.  Use this to pass data to your templates.
$mute_runtime_errorsIf 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_tagIf 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>).

Functions

-

__construct

public function __construct($storage_access)

Parameters

$storage_accessAn Instance of a StorageAccess implementation.
+

__construct

public function __construct($storage_access)

Parameters

$storage_accessAn Instance of a StorageAccess implementation.
-

register_tag

public function register_tag($name,
$callback)

Register a custom tag.

Parameters

$nameThe name of the tag.
$callbackA 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)).
+

register_tag

public function register_tag($name,
$callback)

Register a custom tag.

Parameters

$nameThe name of the tag.
$callbackA 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)).

Throws

An Exception if the tag could not be registered (if $callback is not callable or if $name is empty)

-

call_tag

public function call_tag($name,
$params,
$sub)

Calling a custom tag (builtin ones can not be called)

Parameters

$nameThe Tag’s name
$paramsAssociative array of parameters
$subA callable function (expecting an STECore instance as it’s parameter) that represents the tag’s content.

Returns

The output of the tag.

+

call_tag

public function call_tag($name,
$params,
$sub)

Calling a custom tag (builtin ones can not be called)

Parameters

$nameThe Tag’s name
$paramsAssociative array of parameters
$subA callable function (expecting an STECore instance as it’s parameter) that represents the tag’s content.

Throws

Might throw a FatalRuntimeError.

Returns

The output of the tag or, if a RuntimeError was thrown, the appropiate result (see <$mute_runtime_errors>).

-

exectemplate

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.

Parameters

$tplThe name of the template to execute.

Returns

The output of the template.

+

exectemplate

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.

Parameters

$tplThe name of the template to execute.

Returns

The output of the template.

-

get_var_reference

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.

Parameters

$nameThe variables name.
$create_if_not_existShould the variable be created, if it does not exist?  Otherwise NULL will be returned, if the variable does not exist.

Returns

A Reference to the variable.

+

get_var_reference

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.

Parameters

$nameThe variables name.
$create_if_not_existShould the variable be created, if it does not exist?  Otherwise NULL will be returned, if the variable does not exist.

Throws

RuntimeError if the variable name can not be parsed (e.g. unbalanced brackets).

Returns

A Reference to the variable.

-

set_var_by_name

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.

Parameters

$nameThe variables name.
$valThe new value.
+

set_var_by_name

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.

Parameters

$nameThe variables name.
$valThe new value.

Throws

RuntimeError if the variable name can not be parsed (e.g. unbalanced brackets).

-

get_var_by_name

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.

Parameters

$nameThe variables name.

Returns

The variables value.

+

get_var_by_name

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.

Parameters

$nameThe variables name.

Throws

RuntimeError if the variable name can not be parsed (e.g. unbalanced brackets).

Returns

The variables value.

-

load

public function load($tpl,  
$quiet = False)

Load a template and return its result (blocks not included, use exectemplate for this).

Parameters

$tplThe name of the template to be loaded.
$quietIf 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.

Returns

The result of the template (if $quiet == false).

+

load

public function load($tpl,  
$quiet = False)

Load a template and return its result (blocks not included, use exectemplate for this).

Parameters

$tplThe name of the template to be loaded.
$quietIf 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.

Throws

Returns

The result of the template (if $quiet == false).

evalbool

public function evalbool($txt)

Test, if a text represents false (an empty / only whitespace text) or true (everything else).

Parameters

$txtThe text to test.

Returns

true/false.

@@ -82,7 +90,7 @@ var searchPanel = new SearchPanel("searchPanel", "HTML", "../search"); -
function precompile($code)
Precompiling STE T/PL templates.
function parse($code,
$tpl)
Parsing a STE T/PL template.
function transcompile($ast) /* Transcompile and add some boilerplate code. */
Transcompiles an abstract syntax tree to PHP.
public function load($tpl,
&$mode)
Loading a template.
public function save($tpl,
$data,
$mode)
Saves a template.
An interface.
public function __construct($src,
$transc)
public function __construct($storage_access)
public function register_tag($name,
$callback)
Register a custom tag.
public function call_tag($name,
$params,
$sub)
Calling a custom tag (builtin ones can not be called)
public function exectemplate($tpl)
Executes a template and returns the result.
public function &get_var_reference($name,
$create_if_not_exist)
Get a reference to a template variable using a variable name.
public function set_var_by_name($name,
$val)
Set a template variable by its name.
public function get_var_by_name($name)
Get a template variable by its name.
public function load($tpl,  
$quiet = False)
Load a template and return its result (blocks not included, use exectemplate for this).
public function evalbool($txt)
Test, if a text represents false (an empty / only whitespace text) or true (everything else).
The Core of STE
+
function precompile($code)
Precompiling STE T/PL templates.
function parse($code,
$tpl)
Parsing a STE T/PL template.
function transcompile($ast) /* Transcompile and add some boilerplate code. */
Transcompiles an abstract syntax tree to PHP.
An interface.
public function load($tpl,
&$mode)
Loading a template.
public function save($tpl,
$data,
$mode)
Saves a template.
public function __construct($src,
$transc)
public function __construct($storage_access)
public function register_tag($name,
$callback)
Register a custom tag.
public function call_tag($name,
$params,
$sub)
Calling a custom tag (builtin ones can not be called)
public function exectemplate($tpl)
Executes a template and returns the result.
public function &get_var_reference($name,
$create_if_not_exist)
Get a reference to a template variable using a variable name.
public function set_var_by_name($name,
$val)
Set a template variable by its name.
public function get_var_by_name($name)
Get a template variable by its name.
public function load($tpl,  
$quiet = False)
Load a template and return its result (blocks not included, use exectemplate for this).
public function evalbool($txt)
Test, if a text represents false (an empty / only whitespace text) or true (everything else).
If True (default) a RuntimeError exception will result in no output from the tag, if False a error message will be written to output.
The Core of STE
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.
An Exception that a tag can throw, if a non-fatal runtime error occurred.
An Exception a tag can throw, if a fatal (irreparable) runtime error occurred.
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>).
-- cgit v1.2.3-70-g09d2