Gumbo PHP Library API Documentation

Source for file Engine.class.php

Documentation is available at Engine.class.php

<?php
/**
* Gumbo Library Framework
*
* LICENSE
* This library is being released under the terms of the New BSD License. A
* copy of the license is packaged with the software (LICENSE.txt). If no
* copy is found, a copy of the license template can be found at:
* http://www.opensource.org/licenses/bsd-license.php
*
* @category Gumbo
* @package Template
* @license http://www.opensource.org/licenses/bsd-license.php New BSD License
* @author Michael Luster <mluster79@yahoo.com>
* @link http://sourceforge.net/projects/phpgumbo
* @version 0.0.1
*/
/**
* Abstract Template Engine Class
*
* A Template Engine defines common methods involved in running template systems.
* There are many different ways to use template (PHP includes, string replacement,
* Smarty). A Template system will basically load a file, replacing keywords
* with values defined inside the program. Each Engine will define a specific
* implementation for parsing Template files.
*
* The class provides a basic implementation. This allows an Engine to only
* override certain methods for custom implementation. The common methods allow
* access to Template variables (and assignment), setting the Template file name
* (file name or full path), setting the Template directory path (including extra
* Smarty defined paths), loading global Template settings, and setting the
* surrounding characters of keywords inside the Template file.
*
* To create a new Template_Engine, simply extend this class, placing the new
* file into the 'gumbo/template/engine/*' directory. The name should be
* unique 'Gumbo_Template_Engine_[Name]'. The new Engine will be responsible
* for parsing a particular type of Template file. Details on how to use the
* Engine should be defined inside the class.
*
* Template File
* The Template File can either be a simple file name (combined with the Template
* Directory) or a full path. When the Template File is parsed, the 'getFullPath'
* should be used.
* <pre>
* $this->setFile ("my_file.txt");
* $this->setDirTpl ("/path/to/file/");
* ...
* $this->getFullPath (); // outputs '/path/to/file/my_file.txt', if file exists
* </pre>
*
* Template Variables
* Template Variables are assigned keywords referencing a value determined by the
* program code. The assigned keys are paired with the Template file, replacing
* the 'keyword' with the value. Template Variables can be any type, however check
* the specific Engine on any restrictions defined.
* <pre>
* $this->assign ("key", my_value);
* $this->key = my_value;
* </pre>
*
* Delimeters
* This is simply a left and right character string surrounding keywords, helping
* to separate raw text. Inside a basic string replacement Engine, curly braces
* could surround the keyword '{keyword}' (or any other characters). The parser
* (if used) should find these replacements.
*
* @category Gumbo
* @package Template
* @license http://www.opensource.org/licenses/bsd-license.php New BSD License
* @author Michael Luster <mluster79@yahoo.com>
* @link http://sourceforge.net/projects/phpgumbo
* @desc Abstract Template Engine Class
* @version 0.0.1
*/
gumbo_load ("Interface_Output");
abstract class Gumbo_Template_Engine implements Gumbo_Interface_Output {
/** @var array $_vars assigned tempalte variables as key=>val pair */
protected $_vars = array ();
/** @var string $_file template file name */
private $_file;
/** @var string $_dir_tpl template file directory */
private $_dir_tpl;
/** @var string $_dir_compile template file compile directory */
private $_dir_compile;
/** @var string $_dir_cache template file cache directory */
private $_dir_cache;
/** @var string $_dir_config template file config directory */
private $_dir_config;
/** @var string $_left_del left delimeter */
private $_left_del;
/** @var string $_right_del right delimeter */
private $_right_del;
/** @var bool $_formatted if the template has been formatted into a string */
private $_formatted;
/** @var string $_output formatted template string */
private $_output;
/** ABSTRACT METHODS **/
/**
* Parses the template file into an HTML string
* @precondition setFormatted (false)
* @precondition setOutput (null)
* @postcondition isFormatted ()
*/
abstract protected function parse ();
/**
* Assigns a template variable with a value
* @param string $key template file reference
* @param mixed $val primitive type or Gumbo_Interface_Output
*/
public function __set ($key, $val) {
$this->assign ($key, $val);
}
/**
* Returns the value of a template key reference
* @param string $key
* @return mixed
*/
public function __get ($key) {
return $this->getVar ($key);
}
/**
* Returns if the template reference key isset
* @param string $key
* @return bool
*/
public function __isset ($key) {
return isset ($this->_vars [$key]);
}
/**
* Unassigns a template reference key
* @param string $key
*/
public function __unset ($key) {
unset ($this->_vars [$key]);
}
/** ACTION METHODS **/
/**
* Displays the formatted template file
*/
public function display () {
echo $this->fetch ();
}
/**
* Returns the formatted template file string
* @precondition exists()
* @param bool $reload parses the template file again
* @return string
* @throws Gumbo_Exception
*/
public function fetch ($reload=false) {
try {
// verify precondition
try {
if (!is_bool ($reload)) {
throw new Gumbo_Exception ("Invalid Argument 'reload:bool' => {$reload}:" . gettype ($reload));
}
} catch (Gumbo_Exception $e) {
$e->setFunction (__METHOD__);
gumbo_trigger ($e);
$reload = false;
}
if (!$this->exists ()) {
throw new Gumbo_Exception ("File Not Found: {$this->getFullPath ()}");
}
// check if the template has been formatted
if (!$this->isFormatted () || $reload) {
$this->parse ();
}
return $this->getHtml ();
} catch (Gumbo_Exception $e) {
$e->setFunction (__METHOD__);
gumbo_trigger ($e);
}
return null;
}
/**
* Assigns a template variable with a value
* @param string|array$key template file reference
* @param mixed $val
* @throws Gumbo_Exception
*/
public function assign ($key, $val=null) {
try {
// verify precondition
if (!is_string ($key) && !is_array ($key)) {
throw new Gumbo_Exception ("Invalid Argument 'key:str|arr' => {$key}:" . gettype ($key));
}
// check for an array
if (is_array ($key)) {
foreach ($key as $ref=>$value) {
$this->assign ($ref, $value);
}
return;
}
// default assignment
$this->_vars [$key] = $val;
} catch (Gumbo_Exception $e) {
$e->setFunction (__METHOD__);
gumbo_trigger ($e);
}
}
/**
* Unassigns a template variable
* @param string $key
* @throws Gumbo_Exception
*/
public function unassign ($key) {
try {
// verify precondition
if (!is_string ($key)) {
throw new Gumbo_Exception ("Invalid Argument 'key:str' => {$key}:" . gettype ($key));
}
if (!isset ($this->_vars [$key])) {
throw new Gumbo_Exception ("Undefined Key: {$key}");
}
unset ($this->_vars [$key]);
} catch (Gumbo_Exception $e) {
$e->setFunction (__METHOD__);
gumbo_trigger ($e);
}
}
/**
* Resets the template variables (useful for reloading a List)
* @postcondition !getVars()
* @postcondition !isFormatted()
*/
public function reset () {
$this->_vars = array ();
$this->setFormatted (false);
}
/**
* Loads the global template variables (does not load global Template variables)
* @param bool $assign_global_vars also assigns global variables
* @throws Gumbo_Exception
* @uses Gumbo_Template
*/
public function loadGlobals ($assign_global_vars=false) {
gumbo_load ("Template");
try {
// verify precondition
if (!is_bool ($assign_global_vars)) {
throw new Gumbo_Exception ("Invalid Argument 'assign_global_vars:bool' => {$assign_global_vars}:" . gettype ($assign_global_vars));
}
} catch (Gumbo_Exception $e) {
$e->setFunction (__METHOD__);
gumbo_trigger ($e);
$assign_global_vars = false;
}
$this->setDirTpl (Gumbo_Template::getDirTpl ());
$this->setDirCompile (Gumbo_Template::getDirCompile ());
$this->setDirCache (Gumbo_Template::getDirCache ());
$this->setDirConfig (Gumbo_Template::getDirConfig ());
$this->setLeftDelimeter (Gumbo_Template::getLeftDelimeter ());
$this->setRightDelimeter (Gumbo_Template::getRightDelimeter ());
if ($assign_global_vars) {
$this->assign (Gumbo_Template::getVars ());
}
}
/** MUTATOR METHODS **/
/**
* Sets the template file name
* @param string $file
*/
public function setFile ($file) {
try {
// verify precondition
if (!is_string ($file)) {
throw new Gumbo_Exception ("Invalid Argument 'file:str' => {$file}:" . gettype ($file));
}
$this->_file = $file;
} catch (Gumbo_Exception $e) {
$e->setFunction (__METHOD__);
trigger ($e);
}
}
/**
* Sets the template file directory
* @precondition is_dir ($loc)
* @param string $loc
* @throws Gumbo_Exception
*/
public function setDirTpl ($loc) {
try {
// verify precondition
if (!is_string ($loc)) {
throw new Gumbo_Exception ("Invalid Argument 'loc:str' => {$loc}:" . gettype ($loc));
}
if (!is_dir ($loc)) {
throw new Gumbo_Exception ("Directory Not Found: {$loc}");
}
$this->_dir_tpl = $loc;
} catch (Gumbo_Exception $e) {
$e->setFunction (__METHOD__);
gumbo_trigger ($e);
}
}
/**
* Sets the template file compile directory
* @precondition is_dir ($loc)
* @param string $loc
* @throws Gumbo_Exception
*/
public function setDirCompile ($loc) {
if (is_null ($loc)) { return; }
try {
// verify precondition
if (!is_string ($loc)) {
throw new Gumbo_Exception ("Invalid Argument 'loc:str' => {$loc}:" . gettype ($loc));
}
if (!is_dir ($loc)) {
throw new Gumbo_Exception ("Directory Not Found: {$loc}");
}
$this->_dir_compile = $loc;
} catch (Gumbo_Exception $e) {
$e->setFunction (__METHOD__);
gumbo_trigger ($e);
}
}
/**
* Sets the template file cache directory
* @precondition is_dir ($loc)
* @param string $loc
* @throws Gumbo_Exception
*/
public function setDirCache ($loc) {
if (is_null ($loc)) { return; }
try {
// verify precondition
if (!is_string ($loc)) {
throw new Gumbo_Exception ("Invalid Argument 'loc:str' => {$loc}:" . gettype ($loc));
}
if (!is_dir ($loc)) {
throw new Gumbo_Exception ("Directory Not Found: {$loc}");
}
$this->_dir_cache = $loc;
} catch (Gumbo_Exception $e) {
$e->setFunction (__METHOD__);
gumbo_trigger ($e);
}
}
/**
* Sets the template file config directory
* @precondition is_dir ($loc)
* @param string $loc
* @throws Gumbo_Exception
*/
public function setDirConfig ($loc) {
if (is_null ($loc)) { return; }
try {
// verify precondition
if (!is_string ($loc)) {
throw new Gumbo_Exception ("Invalid Argument 'loc:str' => {$loc}:" . gettype ($loc));
}
if (!is_dir ($loc)) {
throw new Gumbo_Exception ("Directory Not Found: {$loc}");
}
$this->_dir_config = $loc;
} catch (Gumbo_Exception $e) {
$e->setFunction (__METHOD__);
gumbo_trigger ($e);
}
}
/**
* Sets the left delimeter value
* @param string $val
* @throws Gumbo_Exception
*/
public function setLeftDelimeter ($val) {
if (is_null ($val)) { return; }
try {
// verify precondition
if (!is_string ($val)) {
throw new Gumbo_Exception ("Invalid Argument 'val:str' => {$val}:" . gettype ($val));
}
$this->_left_del = $val;
} catch (Gumbo_Exception $e) {
$e->setFunction (__METHOD__);
gumbo_trigger ($e);
}
}
/**
* Sets the right delimeter value
* @param string $val
* @throws Gumbo_Exception
*/
public function setRightDelimeter ($val) {
if (is_null ($val)) { return; }
try {
// verify precondition
if (!is_string ($val)) {
throw new Gumbo_Exception ("Invalid Argument 'val:str' => {$val}:" . gettype ($val));
}
$this->_right_del = $val;
} catch (Gumbo_Exception $e) {
$e->setFunction (__METHOD__);
gumbo_trigger ($e);
}
}
/**
* Sets the template file as formatted
* @param bool $val
* @throws Gumbo_Exception
*/
protected function setFormatted ($val) {
try {
// verify precondition
if (!is_bool ($val)) {
throw new Gumbo_Exception ("Invalid Argument 'val:str' => {$val}:" . gettype ($val));
}
$this->_formatted = $val;
} catch (Gumbo_Exception $e) {
$e->setFunction (__METHOD__);
gumbo_trigger ($e);
}
}
/**
* Sets the formatted output template string
* @param string $output
* @throws Gumbo_Exception
*/
protected function setOutput ($output) {
try {
// verify precondition
if (!is_string ($output) && !is_null ($output)) {
throw new Gumbo_Exception ("Invalid Argument 'output:str|null' => {$output}:" . gettype ($output));
}
$this->_output = $output;
} catch (Gumbo_Exception $e) {
$e->setFunction (__METHOD__);
gumbo_trigger ($e);
}
}
/** ACCESSOR METHODS **/
/**
* Returns the full path to the Template file
* @return string
*/
public function getFullPath () {
if (file_exists ($this->getDirTpl () . $this->getFile ())) {
return $this->getDirTpl () . $this->getFile ();
}
return $this->getFile ();
}
/**
* Returns the template file name
* @return string
*/
public function getFile () {
return $this->_file;
}
/**
* Returns the template file directory
* @return string
*/
public function getDirTpl () {
return $this->_dir_tpl;
}
/**
* Returns the template file compile directory
* @return string
*/
public function getDirCompile () {
return $this->_dir_compile;
}
/**
* Returns the template file cache directory
* @return string
*/
public function getDirCache () {
return $this->_dir_cache;
}
/**
* Returns the template file config directory
* @return string
*/
public function getDirConfig () {
return $this->_dir_config;
}
/**
* Returns the value of the key reference
* @param string $key reference key
* @return mixed
* @throws Gumbo_Exception
*/
public function getVar ($key) {
try {
// verify precondition
if (!is_string ($key)) {
throw new Gumbo_Exception ("Invalid Argument 'key:str' => {$key}:" . gettype ($key));
}
if (!isset ($this->_vars [$key])) {
throw new Gumbo_Exception ("Undefined Key: {$key}");
}
return $this->_vars [$key];
} catch (Gumbo_Exception $e) {
$e->setFunction (__METHOD__);
gumbo_trigger ($e);
}
}
/**
* Returns all the template variables
* @return array
*/
public function getVars () {
return $this->_vars;
}
/**
* Returns the left delimeter
* @return string
*/
public function getLeftDelimeter () {
return $this->_left_del;
}
/**
* Returns the right delimeter
* @return string
*/
public function getRightDelimeter () {
return $this->_right_del;
}
/**
* Returns if the template has been formatted
* @return bool
*/
protected function isFormatted () {
return $this->_formatted;
}
/**
* Returns the formatted output template string
* @return string
*/
protected function getOutput () {
return $this->_output;
}
/**
* Returns if the template file exists
* @return bool
*/
public function exists () {
if (!$this->getFile ()) { return false; }
if (!$this->getDirTpl ()) { return false; }
return file_exists ($this->getFullPath ());
}
}
?>

Gumbo PHP Library API Documentation

Template

Todo List

Packages:

Source for file Engine.class.php