API.

uTemplate

The uTemplate class is the engine core. It uses the Singleton pattern, so it needn't be instantiated. Instead, it provides the uTemplate::getInstance() static function.


uTemplateView

The view class is not to be instantiated. Instances of this class are created internally for each view script, and the view script code is then executed inside the uTemplateView class' object context. This means that the methods and members of the uTemplateView class are available inside the view script.

The variables defined in the template are available in view scripts as plain variables, not as object properties. So, if a variable is defined in the template like this:

uTemplate::getInstance()->varAdd("foo","World");

it is possible to use it inside all view scripts:

<p>Hello <?php echo $foo; ?></p>
  • render() - render the view script (or a nested one)

public static function getInstance ();

Fetch an instance of the template object.

$template = uTemplate::getInstance();

public function layoutViewScript ($layoutViewScript);

Set the layout script file.
It is mandatory do define a layout script if using the default layout structure. It is the outermost script and will include nested view scripts. It is the first script to be rendered.
The layout script contanins the contents of the HTML body tag, but without the tag itself. The outer HTML is either rendered by the uTemplate class directly (e.g. the doctype) or by the head script.

The head script is only needed when using the default layout structure.

uTemplate::getInstance()
	->layoutViewScript(PATH."/layout.phtml");

public function headViewScript ($headViewScript);

Set the head script file.
The head script contains the code inside the HTML head tag, without the tag itself. It will contain meta tags, links, scripts, the title and in case of the RDF doctype, possibly also the RDF-specific tags.
The parametre is the file name of the head view script file.

The head script is only needed when using the default layout structure.

uTemplate::getInstance()
	->headViewScript(PATH."/head.phtml");

public function viewScriptAdd ($name, $viewScript);

Add a new view to the template.
The view script is always named. This enables the use of the name inside a view script to render a nested script.

uTemplate::getInstance()
	->viewScriptAdd("content",PATH."/content.phtml");

Then, in the view script:

echo $this->render("content");

public function viewScriptsAdd ($viewScripts);

Add an array of views to the template.

uTemplate::getInstance()
	->viewScriptsAdd(array("content" => PATH."/content.phtml"));

public function viewScripts ();

Fetch all defined view scripts as a name => file keyed array.

public function varAdd ($name, $value);

Add a new variable to the view scripts.
The variable requires a name for it. The view script's rendering method will take all variables defined this way in the uTemplate object and use the extract() function on them. All view scripts will have direct access to the defined variables in the local scope. For instance, if a variable is added in the uTemplate class:

uTemplate::getInstance()
	->varAdd("foo","var");

it can be accessed in the any script:

echo $foo; // output: "bar"

public function varsAdd ($vars);

Add an array of variables to the view scripts.

uTemplate::getInstance()
	->varsAdd(array("foo" => "bar"));

public function vars ();

Fetch all defined variables as a name => value keyed array.

public function render ($name = null, $variables = array());

This method has two uses. Without any parametres or with the $name parametre equal to null, it will autogenerate an HTML structure according to the chosen doctype and use the head and layout scripts to render the whole page structure.

echo uTemplate::getInstance()
	->render();

The other possibility is to provide a view script, either by script name (as set by viewScriptAdd()) or by file name (full path and file name of the actual script).

echo uTemplate::getInstance()
	->viewScriptAdd("content",PATH."/content.php")
	->render("content");
echo uTemplate::getInstance()
	->render(PATH."/content.php");

The second optional parametre is a set of variables explicitly passed to the view script. The array's key names will become local variables in the view script. If there's a collision with the variables already created with varAdd(), the files passed in the render() function will have priority. Note that the change is not global and affects only the view script in question, so it's possible to substitute a variable in just a given view script, but leaving its original content untouched in all the other view scripts.

echo uTemplate::getInstance()
	->render("content",array("foo" => "bar"));

public function doctypeSet ($name);

Set the doctype.
In order to choose the correct doctype name, it is strongly adviseable to use the predefined constants available in the uTemplate class, all prefixed with "DOCTYPE". The preset doctype is HTML5.

The doctype can be rendered manually. However, using the default layout structure, it is rendered automatically.

uTemplate::getInstance()
	->doctypeSet(uTemplate::DOCTYPE_XHTML11);

public function doctype ();

Render the doctype.

Doctype rendering is done automatically using the default layout structure.

echo uTemplate::getInstance()->doctype();

public function headMetaAppend ($attributes);

Append a new meta tag to the head section of the page
The $attributes parametre contains all the required HTML attributes and their values in the form of a keyed array.

The function, just like most other setters, returns the uTemplate object for easy chaining.

uTemplate::getInstance()
	->headMetaAppend(array("name" => "robots", "content" => "index, follow"))
	->headMetaAppend(array("charset" => "utf-8"));

public function headMetaPrepend ($attributes);

Prepend a new meta tag to the head section of the page.

public function headMeta ();

Outputs a string containing the HTML for the defined meta tags.

echo uTemplate::getInstance()->headMeta();

The function, just like the other functions outputting HTML code, may be used in conjunction with regular HTML in the head view script. Its purpose is to output dynamically generated meta tags, such as the keywords or the description, which ideally should vary between pages. Meta tags that should be used across the entire website are better off written by hand:

<meta charset="utf-8">
<?php echo uTemplate::getInstance()->headMeta(); ?>

public function headTitleAppend ($title);

Append a segment to the head title.
Appending and prepending consecutive segments allows for the creation of a breadcrumb-like title.

uTemplate::getInstance()
	->headTitleAppend("API")
	->headTitleAppend("uTemplate");

public function headTitlePrepend ($title);

Prepend a segment to the head title.

public function headTitleSeparator ($separator);

Set the separator to put between head title segments. Defaults to " | ".

uTemplate::getInstance()->headTitleSeparator(" : ");

public function headTitle ();

Outputs a string containing the HTML title tag with the imploded title segments.

echo uTemplate::getInstance()->headTitle();

public function headLinkAppend ($href, $attributes = array(), $conditional = null);

Append a new link tag in the page header.
The attributes array is a set of key-value pairs of HTML attributes and their values, for instance:

uTemplate::getInstance()
	->headLinkAppend("/favicon.png", array("rel" => "icon", "type" => "image/png"));

The last parametre is the condition of an IE conditional comment:

uTemplate::getInstance()
	->headLinkAppend("/css/ie7.css", array("rel" => "stylesheet"), "lt IE 8");

public function headLinkPrepend ($href, $attributes = array(), $conditional = null);

Prepend a new link tag in the page header.

public function headLinkAppendStylesheet ($href, $attributes = array(), $conditional = null);

Append a new stylesheet link in the page header. The rel and type attributes are set automatically.

uTemplate::getInstance()
	->headLinkAppendStylesheet("/css/style.css");

public function headLinkPrependStylesheet ($href, $attributes = array(), $conditional = null);

Prepend a new stylesheet link in the page header.

public function headStyleAppend ($style, $attributes = array(), $conditional = null, $file = false);

Append a new style tag to the head section of the page.

The first argument is the content of the style tags (CSS code). Attributes may be passed as an array of attribute-value pairs.

Optionally, a file name may be passed as the first argument. In this case, the last argument should be set to true and the content of the style tags will be fetched from the external file.

uTemplate::getInstance()
	->headScriptAppend("body {color:red;}")
	->headScriptAppend("body {color:b;ack}", array("media" => "print"))
	->headScriptAppend("ie7.css",array(),"lt IE 8",true)

public function headStylePrepend ($style, $attributes = array(), $conditional = null, $file = false);

Prepend a new style tag to the head section of the page.

public function headStyle ();

Fetch the page header's style tags HTML code.

echo uTemplate::getInstance()->headStyle();

public function headScriptAppend ($script, $conditional = null)

Append a script to the page's head section.
uTemplate will attempt to automatically discover whether the provided script is an URL or a piece of JavaScript code. The script string ending in ".js" or starting with "http" will be considered a URL. Should the automatic type detection fail for some reason (e.g. if you provide code, but start it with "http", which might be a previously defined variable name), it's possible to force a given script type by using the respective *Src and *Code method variants described below.

uTemplate::getInstance()
	->headScriptAppend("/js/jquery.min.js")
	->headScriptAppend("alert('Hello World!');");

public function headScriptAppendSrc ($script, $conditional = null)

Append an external script to the page's head section.
The use of this method is mostly unnecessary since headScriptAppend() does a good job autodetecting external JavaScript file inclusions.

public function headScriptAppendCode ($script, $conditional = null)

Append inline JavaScript code to the page's head section.
The use of this method is mostly unnecessary since headScriptAppend() does a good job autodetecting inline code inclusions.

public function headScriptPrepend ($script, $conditional = null)

Prepend a script to the page's head section.

public function headScriptPrependSrc ($script, $conditional = null)

Prepend an external script to the page's head section.
The use of this method is mostly unnecessary since headScriptPrepend() does a good job autodetecting external JavaScript file inclusions.

public function headScriptPrependCode ($script, $conditional = null)

Prepend inline JavaScript code to the page's head section.
The use of this method is mostly unnecessary since headScriptPrepend() does a good job autodetecting inline code inclusions.

public function headScript ()

Output the HTML & JavaScript code corresponding to the scripts in the page's header.

public function footScriptAppend ($script, $conditional = null)

Append a script to the page's footer.

public function footScriptAppendSrc ($script, $conditional = null)

Append an external script to the page's footer.
The use of this method is mostly unnecessary since footScriptAppend() does a good job autodetecting external JavaScript file inclusions.

public function footScriptAppendCode ($script, $conditional = null)

Append inline JavaScript code to the page's footer.
The use of this method is mostly unnecessary since footScriptAppend() does a good job autodetecting inline code inclusions.

public function footScriptPrepend ($script, $conditional = null)

Prepend a script to the page's footer.

public function footScriptPrependSrc ($script, $conditional = null)

Prepend an external script to the page's footer.
The use of this method is mostly unnecessary since footScriptPrepend() does a good job autodetecting external JavaScript file inclusions.

public function footScriptPrependCode ($script, $conditional = null)

Prepend inline JavaScript code to the page's footer.
The use of this method is mostly unnecessary since footScriptPrepend() does a good job autodetecting inline code inclusions.

public function footScript ()

Output the HTML & JavaScript code corresponding to the scripts in the page's footer.

This method is provided only for use with a custom layout structure. When the default layout structure is used, the scripts in the page footer are rendered automatically.

public function debugModeSet ($enable = true);

Force debug mode on or off.
While in debug mode, uTemplate will perform additional checks, mainly for file existence, and if an error is detected, it will throw an exception with a proper message. If the debug mode is disabled, the application will not perform those checks, resulting in no errors displayed and a faster application execution.
The debug mode is on by default whenever the APPLICATION_ENV variable is set to "development". Otherwise, it is off by default (for "production" and "staging", as well as for when APPLICATION_ENV is not set). Use this method to override the default setting.

uTemplate::getInstance()
	->debugModeSet();

public function debugMode ();

Check whether debug mode is on or off.

public function version ();

Fetch the library's current version.


public function render ($name = null, $variables = array());

Render a nested view script.
When inside the view script, this method will be available via the $this keyword. To render a nested view script, it's enough to echo $this->render(), passing in the name of the view script as parametre. Alternatively, it is possible to render any view script by simply specifying its full filename with path.

echo uTemplate::getInstance()
	->render("content");
echo uTemplate::getInstance()
	->render(PATH."/content.php");

The second optional parametre may be an array of key => value pairs that will become variables available in the rendered view script, but unavailable outside of it. It's possible to replace variables created with uTemplate::varAdd() this way, but the changes take place only locally, in the rendered view script.

echo uTemplate::getInstance()
	->render("content",array("foo" => "bar"));

Note: the first parametre, $name, may be omitted, but this results in rendering the current view script instead of a nested one. Do not attempt to use this inside a view script, as it will trigger an attempt to render the same script recursively. uTemplate detects such attempts and aborts.