cvs: pear /Template Template.php

jausions Sun Jul 4 12:41:15 2004 EDT Modified files: /pear/Template Template.php Log: More CS stuff Turn debug mode off by default Turn off $options['local'] by default

http://cvs.php.net/diff.php/pear/Template/Template.php?r1=1.16&r2=1.17&ty=u Index: pear/Template/Template.php diff -u pear/Template/Template.php:1.16 pear/Template/Template.php:1.17 --- pear/Template/Template.php:1.16 Sun Jul 4 10:27:35 2004 +++ pear/Template/Template.php Sun Jul 4 12:41:15 2004 @@ -43,27 +43,21 @@ /** -* -* This class implements a "universal" template provider for PEAR. -* -* See example usage and in-progress documentation at {@link -* http://wiki.ciaweb.net/yawiki/index.php?area=Template} -* -* $Id: Template.php,v 1.16 2004/07/04 14:27:35 jausions Exp $ -* -* @package Template -* -* @author Philippe Jausions <Philippe.Jausions@11abacus.com> -* -* @author Alan Knowles <alan@akbkhome.com> -* -* @author Paul M. Jones <pmjones@ciaweb.net> -* -*/ - -class Template { - - + * This class implements a "universal" template provider for PEAR. + * + * See example usage and in-progress documentation at {@link + * http://wiki.ciaweb.net/yawiki/index.php?area=Template} + * + * $Id: Template.php,v 1.17 2004/07/04 16:41:15 jausions Exp $ + * + * @package Template + * + * @author Philippe Jausions <Philippe -dot- Jausions -@- 11abacus -dot- com> + * @author Alan Knowles <alan -@- akbkhome -dot- com> + * @author Paul M. Jones <pmjones -@- ciaweb -dot- net> + */ +class Template +{ /** * The options for initializing the template class. * @@ -94,37 +88,32 @@ * 'MyClass/Plugins.php') Class, and where to include * it from.. * - * @access public * @var array + * @access public */ - - var $options = array( 'template.dir' => '', 'compiler' => '', - 'debug.level' => 1, + 'debug.level' => 0, 'output.strict' => false, 'errors.behaviour' => TEMPLATE_ERROR_DIE, - 'plugins' => array() + 'plugins' => array(), + 'locale' => false ); /** - * - * Array of files used by the Template - * some may be with full path, others may just be what the user requested - * - * current_template = full path of the template that is being used. - * requested_template = local path (relative to options['template.dir'] of the template - * being used. - * compiled_template = file to be output (when using compiled templates) - * - * @access public - * - * @var string - * - */ - + * Array of files used by the Template + * some may be with full path, others may just be what the user requested + * + * current_template = full path of the template that is being used. + * requested_template = local path (relative to options['template.dir'] of the template + * being used. + * compiled_template = file to be output (when using compiled templates) + * + * @var string + * @access public + */ var $files = array( 'current_template' => '', 'requested_template' => '', @@ -133,33 +122,30 @@ /** - * - * Array of various data portions stored in engine. - * - * 'variables' => Data assigned to the template by copy. - * 'byref' => Data assigned to the template by reference. - * 'object' => single object with public variables representing data you want - * overlayed onto the template - * - * - * 'template_src' => the template as a string (used by block/compile from string situations) - * 'template_compiled' => the complied template as a string (when using compiling - * templates to a string) - * - * 'elements' => array of XML_Tree type elements you want to overlay onto the - * template - * 'elements_original' => array of XML_Tree type elements that are in the template - * to be rendered. - * - * Providers have full access to these, - * you have read access to them. - * write access should be carefully considered.. - * - * @var array - * @access semi-private - * - */ - + * Array of various data portions stored in engine. + * + * 'variables' => Data assigned to the template by copy. + * 'byref' => Data assigned to the template by reference. + * 'object' => single object with public variables representing data you want + * overlayed onto the template + * + * + * 'template_src' => the template as a string (used by block/compile from string situations) + * 'template_compiled' => the complied template as a string (when using compiling + * templates to a string) + * + * 'elements' => array of XML_Tree type elements you want to overlay onto the + * template + * 'elements_original' => array of XML_Tree type elements that are in the template + * to be rendered. + * + * Providers have full access to these, + * you have read access to them. + * write access should be carefully considered.. + * + * @var array + * @access semi-private + */ var $data = array( 'variables' => array(), 'byref' => array(), @@ -170,15 +156,11 @@ /** - * - * Array of feature providers - * - * @access private - * - * @var array - * - */ - + * Array of feature providers + * + * @var array + * @access private + */ var $provider = array( 'Assign' => null, // assign API 'Filters' => null, // Output filters @@ -190,20 +172,16 @@ /** - * - * Constructor. - * - * Initializes the Template engine, and sets up behaviour based on - * the provided options. - * this doesnt handle pass by ref setting of things..! - * - * @access public - * - * @param array $options An array of options to pass to the Template object; - * @see the $options property. - * - */ - + * Constructor. + * + * Initializes the Template engine, and sets up behaviour based on + * the provided options. + * this doesnt handle pass by ref setting of things..! + * + * @param array $options an array of options to pass to the Template object; + * @access public + * @see the $options property. + */ function Template($options = array()) { $this->options = array_merge($this->options, $options); @@ -218,24 +196,19 @@ /** - * - * Open and optionally parse or compile a template. - * - * TODO : Possible alternatives : use / useTemplate - * - * @access public - * - * @param mixed $location The file path of the template source, relative - * to the 'template.dir' option set in the constructor. - * use array('string'=>$template_string) or $filepointer - * for other types of source. - * - * @return mixed Boolean true on success (or string, if - * 'compiler.toString' is set), or PEAR_Error on failure. - * - */ - - function open( $location ) + * Opens and optionally parses or compiles a template. + * + * @param mixed $location the file path of the template source, relative + * to the 'template.dir' option set in the constructor. + * use array('string'=>$template_string) or $filepointer + * for other types of source. + * + * @return bool|PEAR_Error TRUE or string, if 'compiler.toString' is set), + * or PEAR_Error on failure. + * @access public + * @todo Possible alternatives : use / useTemplate + */ + function open($location) { if (!$location) { @@ -319,9 +292,8 @@ /** * Outputs the template. * - * @access public - * * @return bool|PEAR_Error TRUE or PEAR_Error object on error + * @access public */ function output() { @@ -410,16 +382,13 @@ /** - * - * Gets the result of the template overlaid with data as a string. - * - * @access public - * - * @param object The object to output as $t - * - * @return string - result - * - */ + * Gets the result of the template overlaid with data as a string. + * + * @return string|PEAR_Error the result of template, or PEAR_Error object + * on error + * + * @access public + */ function toString() { if (!empty($this->options['filters']) @@ -441,18 +410,15 @@ /** - * - * Prints the debug info to the screen if debugging is on. - * - * @access public - * - * @param string $string Debug message to display. - * @param integer $level Verbose debug level (The higher the level the more - * detailed the information should be.) - * @return void - * - */ - + * Prints the debug info to the screen if debugging is on. + * + * @param string $string debug message to display. + * @param integer $level verbose debug level (The higher the level the more + * detailed the information should be.) + * @return void + * + * @access public + */ function debug($string, $level= 1) { if ($level > $this->options['debug.level'] ) { @@ -465,23 +431,21 @@ /** - * - * Global RaiseError - very lightweight! - * - * This may return a PEAR_Error/ErrorStack, or throw an exception! - * - * @access public - * @param string $mesage The error message text. - * @param int $type Error type. - * @param int $severity An equivalent to PEAR_ERROR_[RETURN|DIE|etc] - * @param array $args Args for printf view of message. - * - * @return object PEAR_Error object. - * - */ - - function raiseError($message, $type = null, $severity = TEMPLATE_ERROR_RETURN, - $args = array()) + * Global RaiseError - very lightweight! + * + * This may return a PEAR_Error/ErrorStack, or throw an exception! + * + * @param string $mesage the error message text. + * @param int $type error type. + * @param int $severity an equivalent to PEAR_ERROR_[RETURN|DIE|etc] + * @param array $args args for printf view of message. + * + * @return object PEAR_Error object. + * + * @access public + */ + function raiseError($message, $type = null, + $severity = TEMPLATE_ERROR_RETURN, $args = array()) { $this->debug("<B>TEMPLATE::raiseError</B>$message ($type/$severity)".print_r($args,true)); $this->assertProvider('Error'); @@ -491,43 +455,40 @@ /** - * - * Assign Variables to the template - * - * read the docs on TEMPLATE_Assign::setData() - * - * @param varargs .... - * - * - * @return mixed PEAR_Error or true? - * @access public - * @see TEMPLATE_Assign::setData() - * @status alpha - */ - - function setData() { + * Assigns variable(s) to the template + * + * Read the docs on Template_Assign::setData() + * + * @param varargs .... + * + * @return bool|PEAR_Error TRUE or PEAR_Error object on error + * @access public + * @see Template_Assign::setData() + * @status alpha + */ + function setData() + { $this->assertProvider('Assign'); return call_user_func_array(array(&$this->provider['Assign'],'setData'),func_get_args()); } /** - * - * Assign Variables to the template by Reference - * normally usefull if you are going to use methods on them.. - * - * read the docs on TEMPLATE_Assign::setDataByRef() - * - * @param key string - * @param value mixed - * - * @return mixed PEAR_Error or true? - * @access public - * @see TEMPLATE_Assign::setDataByRef() - */ - - function setDataByRef($k, &$v) { - + * Assigns a variable to the template by reference + * normally usefull if you are going to use methods on them + * or for huge values + * + * Read the docs on Template_Assign::setDataByRef() + * + * @param string $k name of variable + * @param mixed $v value to assign + * + * @return bool|PEAR_Error TRUE or PEAR_Error object on error + * @access public + * @see Template_Assign::setDataByRef() + */ + function setDataByRef($k, &$v) + { // load assigner.. $this->assertProvider('Assign'); return $this->provider['Assign']->setDataByRef($k, $v); @@ -535,14 +496,11 @@ /** - * - * reset __All__ the data.. - * - * - * @return none - * @access public - */ - + * Resets all the data. + * + * @return void + * @access public + */ function clearData() { $x = new Template; @@ -551,21 +509,19 @@ /** - * - * Plugin (used by templates as $this->plugin(...) or {this.plugin(#...#,#....#)} - * - * read the docs on Template_Plugin() - * - * @param varargs .... - * - * @return mixed PEAR_Error or true? - * @access public - * @see TEMPLATE_Plugin - * @status alpha - */ - - function plugin() { - + * Calls a plugin (used by templates as $this->plugin(...) or {this.plugin(#...#,#....#)} + * + * Read the docs on Template_Plugin() + * + * @param varargs .... + * + * @return bool|PEAR_Error TRUE or PEAR_Error object on error + * @access public + * @see Template_Plugin + * @status alpha + */ + function plugin() + { // load pluginManager. $this->assertProvider('Plugin'); return $this->provider['Plugin']->call(func_get_args()); @@ -573,29 +529,28 @@ /** - * Block API support - * - * An idea to support block regex/str_replace tempaltes - * useing the idea - * $template->block('set','.....'); // set current block - * $template->block('get','.....'); // get the parsed results of a block??? - * $template->block('touch','.....'); // touch block - * $template->block('hide','.....'); // hide block - * $template->block('add','.....'); // add a block - * $template->block('addFile','.....'); // add a block from a file? - * $template->block('exists','.....'); // does a block exist? - * $template->block('list','.....'); // list the blocks - * $template->block('show','.....'); // output? a block - - * - * @param string action - * @param varargs ... - * - * @return mixed - * @access public - */ - - function block($name) { + * Block API support + * + * An idea to support block regex/str_replace tempaltes + * useing the idea + * $template->block('set','.....'); // set current block + * $template->block('get','.....'); // get the parsed results of a block??? + * $template->block('touch','.....'); // touch block + * $template->block('hide','.....'); // hide block + * $template->block('add','.....'); // add a block + * $template->block('addFile','.....'); // add a block from a file? + * $template->block('exists','.....'); // does a block exist? + * $template->block('list','.....'); // list the blocks + * $template->block('show','.....'); // output? a block + * + * @param string action + * @param varargs ... + * + * @return mixed + * @access public + */ + function block($name) + { $this->assertProvider('Block'); $args = func_get_args(); array_shift($args); @@ -604,26 +559,26 @@ /** - * Assert that a provider is loaded, Load if it isnt.. - * - * 'Providers' provide the features that can be used by the varous engines - * This is how features are added without bloating the core too much.. - * - * This can be used by any of the backends to load classes, and instance - * them in the provider array eg: - * <code> - * $template->assignProvider('Compiler/Flexy'); - * </code> - * - * @todo Possibly return a PEAR_Error or trigger_error() on class loading - * issue... - * @param string Name of feature.. - * - * @return true or PEAR::Error. - * @access public - */ - - function assertProvider($name) { + * Asserts that a provider is loaded, Load if it isn't.. + * + * 'Providers' provide the features that can be used by the varous engines + * This is how features are added without bloating the core too much.. + * + * This can be used by any of the backends to load classes, and instance + * them in the provider array eg: + * <code> + * $template->assignProvider('Compiler/Flexy'); + * </code> + * + * @todo Possibly return a PEAR_Error or trigger_error() on class loading + * issue... + * @param string $name name of feature. + * + * @return bool|PEAR_Error TRUE or PEAR_Error object on error. + * @access public + */ + function assertProvider($name) + { if (isset($this->providers[$name])) { return true; } @@ -634,7 +589,7 @@ $class = $this->options['provider'][$name][1]; } else { $file = "Template/$name.php"; - $class = 'Template_'.str_replace('/','_',$name); + $class = 'Template_' . str_replace('/', '_', $name); } require_once $file; @@ -649,23 +604,21 @@ // ------------------------------------------ Short Cuts ----------------------------------- /** - * Sets Data in the store directly (bypassing assign API) - * Thens outputs. - * - * - * examples : - * $engine->outputData(&$this); - * - * $engine->outputData( - * 'object' => &$this - * 'elements' => $ellements - * - * provides the lightweight output without assigment that outputObject used to do.. - * - * @access public - * @return none - */ - + * Sets Data in the store directly (bypassing assign API) + * Thens outputs. + * + * examples : + * $engine->outputData(&$this); + * + * $engine->outputData( + * 'object' => &$this + * 'elements' => $ellements + * + * provides the lightweight output without assigment that outputObject used to do.. + * + * @access public + * @return none + */ function outputData(&$data) { // options : object: - @@ -707,8 +660,8 @@ * @return array of TEMPLATE_Element s * @access public */ - - function getElement($name=false) { + function getElement($name = false) + { // load the elements if required: if (!isset($this->data['elements_original']) &&