cvs: peardoc /en/packages/templates flexy.xml
| From: | Alan Knowles | Date: | Fri, 23 Aug 2002 09:23:50 +0000 |
| Subject: | cvs: peardoc /en/packages/templates flexy.xml | ||
| Groups: | php.pear.cvs | ||
| Request: | Send a blank email to pear-cvs+get-5893@lists.php.net to get a copy of this message | ||
alan_k Fri Aug 23 05:23:50 2002 EDT
Added files:
/peardoc/en/packages/templates flexy.xml
Log:
adding HTML_Template_Flexys manual, its a breaks the xml parser a bit cause it has subsections
Index: peardoc/en/packages/templates/flexy.xml +++ peardoc/en/packages/templates/flexy.xml <?xml version="1.0" encoding="iso-8859-1" ?> <!-- $Revision: 1.1 $ --> <reference id="packages.templates.flexy"> <title>HTML_Template_Flexy - the flexible template system</title> <titleabbrev>HTML_Template_Flexy</titleabbrev> <partintro> <simpara> This chapter describes how to use the HTML_Template_Flexy flexible template system. </simpara> </partintro> <refentry id="packages.templates.flexy.Introduction"> <refnamediv> <refname>Introduction</refname> <refpurpose> What HTML_Template_Flexy can do </refpurpose> </refnamediv> <refsect1> <title>Introduction</title> <para> HTML_Template_Flexy is a, flexible, simple extendable, fast templating engine, Its main reasons for existing are </para> <para> <itemizedlist> <listitem> <simpara>Simple API, easier to learn...</simpara> </listitem> <listitem> <simpara>Targeted at Object based systems - default behavior is to display object variables</simpara> </listitem> <listitem> <simpara>Designed to allow the documentation of available variables using the o_name standard</simpara> </listitem> <listitem> <simpara>Ability to edit the templates in WYSIWYG editors, without breaking the tags</simpara> </listitem> <listitem> <simpara>Fast to do looping a blocks both for designing and runtime</simpara> </listitem> </itemizedlist> </para> </refsect1> <refsect1> <title>How does HTML_Template_Flexy differ from other template systems</title> <para> If you look around you will see there are other template systems available in PHP, they generally fall into two categories, Replacement Systems, or PHP Code builders. </para> <para> Replacement systems like IntegratedTemplate, FastTemplate, PhpLib Template tend to be slower at doing block and nested block type templates. </para> <para> Php Code builders like Flexy, Smarty, SimpleTemplate tend better at more complex templates, and can offer a better approach to extendability. </para> <para> HTML_Template_Flexy core is designed to be easily understood and extendable, with a minimal of PHP knowledge, and yet provide a consistant, easy to document codebase. Along with being able to handle XML, Email templates, RTF, and any thing you care to throw at it. </para> </refsect1> <refsect1> <title>Typical use example</title> <para> Flexy template is normally called from within a Controller Class (in the Model,View,Controller paragam). Note that you just send HTML_Template_Flexy, the name of the template, and the class to output. - the object variables var $o_title, can be documented and related directly to a tag in the template. </para> <example> <title>Typical usage example for <classname>HTML_Template_Flexy</classname></title> <programlisting role="php"> <![CDATA[ <? /* configure the application - probably done elsewhere */ require_once 'Template/Flexy.php'; $options = &PEAR::getStaticProperty('HTML_Template_Flexy','options'); $config = parse_ini_file('example.ini',TRUE); $options = $config['HTML_Template_Flexy']; /* the page controller class */ class controller_test { var $template = "home.html"; // name of template var $o_title; // page title; var $o_numbers = array(); // an array example /* start section - deals with posts, get variables etc.*/ function start() { $this->o_title = "<Hello World>"; for ($i = 1;$i< 5;$i++) { $this->o_numbers[$i] = "Number $i"; } } /* output section - probably best to put this in the default_controller class */ function output() { $output = new HTML_Template_Flexy(); $output->compiler($this->template); $output->outputObject($this); } } /* the page controller instantaation - probably done from your master page controller class */ $page = new controller_test; $page->start(); $page->output(); ?> ]]> </programlisting> </example> <para> Now the example template, </para> <example> <title>Example Template for <classname>HTML_Template_Flexy</classname></title> <programlisting role="php"> <![CDATA[ <html><head> <title>{o.title}</title> </head> <body> <table> <tr> <td> some numbers {foreach:o.numbers,number,string} </td> </tr> <tr> <td> <a href="mypage.html?id=%7Bnumber%7D">{string}</a> {end:} </td> </tr> </table> </body> </html> ]]> </programlisting> </example> <para> And the output </para> <example> <title>Output of example for <classname>HTML_Template_Flexy</classname></title> <programlisting role="php"> <![CDATA[ some numbers Number 1 Number 2 Number 3 Number 4 ]]> </programlisting> </example> </refsect1> </refentry> <!-- ****************************************** Configuraton file ******************************************* --> <refentry id="packages.templates.flexy.configuration"> <refnamediv> <refname>Configuration Options</refname> <refpurpose> Setting the defaults for HTML_Template_Flexy </refpurpose> </refnamediv> <refsect1> <title>Configuration</title> <para> HTML_Template_Flexy can either be configured globally or on each instance, using an associated array. The easiest way to configure HTML_Template_Flexy is to use ini files (although you may also like to consider the PEAR::Config class, or your own configuration system) </para> <example> <title> This is a typical configuration file for <classname>HTML_Template_Flexy</classname></title> <programlisting role="ini"> [HTML_Template_Flexy] templateDir = /home/me/Projects/myapplication/templates compileDir = /home/me/Projects/myapplication/compiled_templates forceCompile = 0 filters = Php,SimpleTags debug = 0 </programlisting> </example> <para> To use this ini file with HTML_Template_Flexy, (and Possibly any other classes that use options like this) </para> <example> <title> Setting the default options</title> <programlisting role="php"><![CDATA[ <?php $config = parse_ini_file('example.ini',TRUE); foreach($config as $class=>$values) { $options = &PEAR::getStaticProperty($class,'options'); $options = $values; } ?> ]]> </programlisting> </example> <para> Alternatively you can set (or override) the configuration when you instantate the class </para> <example> <title> Setting the default options</title> <programlisting role="php"><![CDATA[ <?php $options = array( 'templateDir' => '/home/me/Projects/myapplication/templates', 'compileDir' => '/home/me/Projects/myapplication/compiled_templates', 'forceCompile' => 0, 'filters' => 'Php,SimpleTags', 'debug' => 0 ); $template = new HTML_Template_Flexy($options); ?> ]]> </programlisting> </example> </refsect1> <!-- Config Options --> <refsect1> <title>Configuration Options</title> <variablelist> <varlistentry> <term> <parameter>templateDir</parameter> <type>directory</type> </term> <listitem> <para> This is the directory where all your templates are located </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>compileDir</parameter> <type>directory</type> </term> <listitem> <para> The directory where the compiled templates will be stored, This directory should be writable by the web server </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>forceCompile</parameter> <type>boolean</type> </term> <listitem> <para> Normally 0, means that the template will only be compiled once (or if the template file is altered), this is only really usefull if you are developing filters and need to test the result. </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>filters</parameter> <type>string</type> </term> <listitem> <para> A comma delimited string of the filters you wish to use, the normal set is Php, Simpletags, BodyOnly, which are described in the filters sections </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>debug</parameter> <type>integer</type> </term> <listitem> <para> The default debugging level (default 0=off), 1= shows some debugging information </para> </listitem> </varlistentry> </variablelist> </refsect1> </refentry> <!-- ****************************************** PHP side initializing, Compiling and displaying ******************************************* --> <refentry id="packages.templates.flexy.php"> <refnamediv> <refname>The Class Methods </refname> <refpurpose> HTML_Template_Flexy(), ::compile(), ::outputObject(), ::bufferedOutputObject() </refpurpose> </refnamediv> <refsect1> <title>HTML_Template_Flexy()</title> <para> Initialization </para> <funcsynopsis> <funcprototype> <funcdef>new <function>HTML_Template_Flexy</function></funcdef> <paramdef>array <parameter><optional>options</optional></parameter></paramdef> </funcprototype> </funcsynopsis> <para> class initialization - if you set the default settings using PEAR::getStaticProperty('HTML_Template_Flexy','options');, you do shouldn't need to use the options array, other wise see the Configuration page for more details on the options </para> </refsect1> <refsect1> <title>::compile()</title> <para> Compile the template into PHP </para> <funcsynopsis> <funcprototype> <funcdef>string <function>$flexy->compile</function></funcdef> <paramdef>string <parameter>Template_name</parameter></paramdef> </funcprototype> </funcsynopsis> <para> Compiles the Template into php and puts it in the compiledDir folder. This is only done if the template has changed or, the forceCompile option is set to TRUE or 1. It returns the location of the compiled template (that can be used in an include statement) </para> </refsect1> <refsect1> <title>::outputObject()</title> <para> Merges a controller object with the template and outputs the result </para> <funcsynopsis> <funcprototype> <funcdef> <function>$flexy->outputObject</function></funcdef> <paramdef>object <parameter>Controller_object</parameter></paramdef> </funcprototype> </funcsynopsis> <para> This maps the values of the supplied object and runs the compiled template, and outputs the result. </para> <para> The Template engine performs the following replacements </para> <variablelist> <varlistentry> <term> <parameter>{o.*}</parameter> <type>$object->o.*</type> </term> <listitem> <para> The output variables, in Simpetags $object->o_item becomes {o.item} </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{t.*}</parameter> <type>$object</type> </term> <listitem> <para> The base object, in simpletags you can call a method of the class using {t.output_pulldown()} </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{m.NNN.*}</parameter> <type>$object->modules[NNNN]->*</type> </term> <listitem> <para> The module objects, if you have a modules associative array, the keys a mapped to object variables, and if the module has a variable $template, then it is compiled </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{c.*}</parameter> <type>$object->config</type> </term> <listitem> <para> The config object, if you have an configuration settings you can assign $object->config = (object) $config; prior to running outputObject </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{i.*}</parameter> <type>$object->input</type> </term> <listitem> <para> The input object, you can assign $object->input = (object) $_REQUEST </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{a.*}</parameter> <type>will correspond to PEAR::getStaticProperty('Auth','singleton')</type> </term> <listitem> <para> if you use a session for the controller object you can assign the objects session variable and it can be accessed using {s.variable_name} </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{email_boundary}</parameter> <type>string</type> </term> <listitem> <para> If you need use the template engine with a email template, {email_boundary} will contain a distinct string for mime boundaries </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{email_date}</parameter> <type>string</type> </term> <listitem> <para> Todays date and time for insertion into an email header's Date: field. </para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1> <title>::bufferedOutputObject()</title> <para> Merges a controller object with the template and returns the result </para> <funcsynopsis> <funcprototype> <funcdef> string <function>$flexy->bufferedoutputObject</function></funcdef> <paramdef>object <parameter>Controller_object</parameter></paramdef> </funcprototype> </funcsynopsis> <para> This maps the values of the supplied object and runs the compiled template, and returns the output string. This uses output buffering. It is usefull for caching or using the template engine with emails, rtf, excel files etc. <example> <title> Example of sending email using HTML_Template_Flexy and the PEAR mail classes</title> <programlisting role="php"><![CDATA[ <? function send_password() { $options = &PEAR::getStaticProperty('users_password_new','options'); $template = new HTML_Template_Flexy($options); $template->compile($options['template']); $this->person = DataObjects_Person::staticGet($_GET['id']); $this->person->generatePassword(); $this->options = (object) $options; $mailtext = $template->bufferedOutputObject($this); $decoder = new Mail_mimeDecode($mailtext); $parts = $decoder->getSendArray(); if (PEAR::isError($parts)) { echo "PROBLEM: {$parts->message}"; exit; } list($recipents,$headers,$body) = $parts; $mail = Mail::factory($options['driver'],$options); $mail->send($recipents,$headers,$body); } ?> ]]> </programlisting> </example> </para> </refsect1> </refentry> <!-- ****************************************** SimpleTags: variables, conditionals, looping, method calls, includes ******************************************* --> <refentry id="packages.templates.flexy.filters_simpletags"> <refnamediv> <refname>SimpleTags</refname> <refpurpose> The template tags for variables, conditionals, looping, method calls, includes, these can be used if the Filter option contains the 'SimpleTags' string. </refpurpose> </refnamediv> <refsect1> <title>Variables</title> <para> Displaying Variables </para> <variablelist> <varlistentry> <term> <parameter>{o.string}</parameter> <type>html escaped string</type> </term> <listitem> <para> Outputs a value of string, equivialant to <?php echo htmlspecialchars($this->o_string); ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{o.string:h}</parameter> <type>raw string</type> </term> <listitem> <para> Outputs a value of string, equivialant to <?php echo $this->o_string ; ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{o.string:u}</parameter> <type>url encoded string</type> </term> <listitem> <para> Outputs a value of string, equivialant to <?php echo urlencode($this->o_string); ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{o.string:n}</parameter> <type>line break to br taged output of string</type> </term> <listitem> <para> Outputs a a variable changing line breaks to br tags, equivialant to <?php nl2br(htmlspecialchars($this->o_string)); ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{o.string:r}</parameter> <type>var dump variable</type> </term> <listitem> <para> Outputs a print_r of a variable , equivialant to <PRE><?php print_r($this->o_string); ?></PRE> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>%7Bo.string%7D</parameter> <type>html escaped string</type> </term> <listitem> <para> Outputs a html escaped value of string, equivialant to <?php echo htmlspecialchars($this->o_string); ?>, useful when working with html editors that encode attribute values </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>%7Bo.string:h%7D</parameter> <type>raw string</type> </term> <listitem> <para> Outputs a value of string, equivialant to <?php echo $this->o_string ; ?> useful when working with html editors that encode attribute values </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>%7Bo.string:u%7D</parameter> <type>url encoded string</type> </term> <listitem> <para> Outputs a value of string, equivialant to <?php echo urlencode($this->o_string); ?> useful when working with html editors that encode attribute values </para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1> <title>Methods</title> <para> calls a object method, (all these work with urlencoded tags - eg. %7D etc.) </para> <variablelist> <varlistentry> <term> <parameter>{t.method()}</parameter> <type>call a method</type> </term> <listitem> <para> Outputs a result of method call, equivialant to <?php echo htmlspecialchars($this->method()); ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{t.method(somevar)}</parameter> <type>call a method with a single variable (html escape result)</type> </term> <listitem> <para> Outputs a result of method call, equivialant to <?php echo htmlspecialchars($this->method($somevar)); ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{t.method(somevar):h}</parameter> <type>call a method with a single variable</type> </term> <listitem> <para> Outputs a result of method call, equivialant to <?php echo $this->method($somevar); ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{t.method(somevar):s}</parameter> <type>call a method with a single variable (and php highlight result)</type> </term> <listitem> <para> Outputs a result of method call, equivialant to <?php echo highlight_string($this->method($somevar)); ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{t.method(#some string#)}</parameter> <type>call a method with a string or constant value (and html escapes result)</type> </term> <listitem> <para> Outputs a result of method call, equivialant to <?php echo htmlspecialchars($this->method('some string')); ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{t.method(#some string#):h}</parameter> <type>call a method with a string or constant value</type> </term> <listitem> <para> Outputs a result of method call, equivialant to <?php echo $this->method('some string'); ?> </para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1> <title>Looping and conditional - blocks</title> <para> Simple tags only allows a single type of looping - foreach, it is often used with an array of objects to display rows of table information (for example using DB_DataObject) </para> <variablelist> <varlistentry> <term> <parameter>{foreach:o.items,item}</parameter> <type>loop on items and use the variable item</type> </term> <listitem> <para> Loops on each of the values of the items array , equivialant to <?php if ($object->o_items) (foreach($this->o_items as $item); { ?> ,should be closed with the {end:} tag. </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{foreach:o.items,key,value}</parameter> <type>loop on items and extracts each rows key and value</type> </term> <listitem> <para> Loops on each of the values of the items array , equivialant to <?php if ($object->o_items) foreach($this->o_items as $key=>$value); { ?> ,should be closed with the {end:} tag. </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{end:}</parameter> <type>termintes a loop or conditional</type> </term> <listitem> <para> equivialant to <?php } ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{if:o.value}</parameter> <type>conditional includes a block of html</type> </term> <listitem> <para> equivialant to <?php if ($object->o_value) { ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{if:t.method()}</parameter> <type>conditional includes a block of html</type> </term> <listitem> <para> equivialant to <?php if ($object->method()) { ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{else:}</parameter> <type>alternative outcome to an conditional statement</type> </term> <listitem> <para> equivialant to <?php } else { ?> </para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1> <title>Including other files</title> <para> To include sub templates (eg. body or modules), you can use the {include:*} methods </para> <variablelist> <varlistentry> <term> <parameter>{include:t.somevar}</parameter> <type>includes code from base on the value of a variable</type> </term> <listitem> <para> equivialant to <?php include($options['compiledDir'].$object->somevar . ".en.php") ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{include:#menu.html#}</parameter> <type>includes code from the named file</type> </term> <listitem> <para> equivialant to <?php include($options['compiledDir']."menu.html") ?> </para> </listitem> </varlistentry> </variablelist> </refsect1> </refentry> <!-- ****************************************** Advanced Filters, Body only, Php stripping, .... ******************************************* --> <refentry id="packages.templates.flexy.filters_advanced"> <refnamediv> <refname>Advanced filters</refname> <refpurpose> The Php, BodyOnly, Mail, RtfSimpleTags Filters </refpurpose> </refnamediv> <refsect1> <title>Using other filters</title> <para> HTML_Template_Flexy includes a few other filters that are usefull when working with templates, you can very easily add your own filter by adding a file in the Flexy/Filters folder, and just copying the format of the existing Filter files. </para> <para> The common addition filters to use are Php, and BodyOnly, other filters like Mail and RtfSimpleTags are usefull when working with Mail and Rtf file templates. </para> </refsect1> <refsect1> <title>Php Filter</title> <para> The Php Filter strips out any php <?php tags prior to parsing and replaces them with htmlescaped tags afterwards. </para> </refsect1> <refsect1> <title>BodyOnly Filter</title> <para> When using a template as the body of a page, The BodyOnly filter will remove the HTML before and including the <BODY> tag and after and including the </BODY> tag </para> </refsect1> <refsect1> <title>Mail Filter</title> <para> Due to php's habit of removing CRLF's after php tags, this filter adds an extra line to alieviate this effect. enabling you to create mail templates. </para> </refsect1> <refsect1> <title>RtfSimpletags Filter</title> <para> Rtf will escape all { with \{, so this Filter replaces the SimpleTags filter when using HTML_Template_Flexy with rtf files. </para> </refsect1> </refentry> </reference> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 -->
Index: peardoc/en/packages/templates/flexy.xml +++ peardoc/en/packages/templates/flexy.xml <?xml version="1.0" encoding="iso-8859-1" ?> <!-- $Revision: 1.1 $ --> <reference id="packages.templates.flexy"> <title>HTML_Template_Flexy - the flexible template system</title> <titleabbrev>HTML_Template_Flexy</titleabbrev> <partintro> <simpara> This chapter describes how to use the HTML_Template_Flexy flexible template system. </simpara> </partintro> <refentry id="packages.templates.flexy.Introduction"> <refnamediv> <refname>Introduction</refname> <refpurpose> What HTML_Template_Flexy can do </refpurpose> </refnamediv> <refsect1> <title>Introduction</title> <para> HTML_Template_Flexy is a, flexible, simple extendable, fast templating engine, Its main reasons for existing are </para> <para> <itemizedlist> <listitem> <simpara>Simple API, easier to learn...</simpara> </listitem> <listitem> <simpara>Targeted at Object based systems - default behavior is to display object variables</simpara> </listitem> <listitem> <simpara>Designed to allow the documentation of available variables using the o_name standard</simpara> </listitem> <listitem> <simpara>Ability to edit the templates in WYSIWYG editors, without breaking the tags</simpara> </listitem> <listitem> <simpara>Fast to do looping a blocks both for designing and runtime</simpara> </listitem> </itemizedlist> </para> </refsect1> <refsect1> <title>How does HTML_Template_Flexy differ from other template systems</title> <para> If you look around you will see there are other template systems available in PHP, they generally fall into two categories, Replacement Systems, or PHP Code builders. </para> <para> Replacement systems like IntegratedTemplate, FastTemplate, PhpLib Template tend to be slower at doing block and nested block type templates. </para> <para> Php Code builders like Flexy, Smarty, SimpleTemplate tend better at more complex templates, and can offer a better approach to extendability. </para> <para> HTML_Template_Flexy core is designed to be easily understood and extendable, with a minimal of PHP knowledge, and yet provide a consistant, easy to document codebase. Along with being able to handle XML, Email templates, RTF, and any thing you care to throw at it. </para> </refsect1> <refsect1> <title>Typical use example</title> <para> Flexy template is normally called from within a Controller Class (in the Model,View,Controller paragam). Note that you just send HTML_Template_Flexy, the name of the template, and the class to output. - the object variables var $o_title, can be documented and related directly to a tag in the template. </para> <example> <title>Typical usage example for <classname>HTML_Template_Flexy</classname></title> <programlisting role="php"> <![CDATA[ <? /* configure the application - probably done elsewhere */ require_once 'Template/Flexy.php'; $options = &PEAR::getStaticProperty('HTML_Template_Flexy','options'); $config = parse_ini_file('example.ini',TRUE); $options = $config['HTML_Template_Flexy']; /* the page controller class */ class controller_test { var $template = "home.html"; // name of template var $o_title; // page title; var $o_numbers = array(); // an array example /* start section - deals with posts, get variables etc.*/ function start() { $this->o_title = "<Hello World>"; for ($i = 1;$i< 5;$i++) { $this->o_numbers[$i] = "Number $i"; } } /* output section - probably best to put this in the default_controller class */ function output() { $output = new HTML_Template_Flexy(); $output->compiler($this->template); $output->outputObject($this); } } /* the page controller instantaation - probably done from your master page controller class */ $page = new controller_test; $page->start(); $page->output(); ?> ]]> </programlisting> </example> <para> Now the example template, </para> <example> <title>Example Template for <classname>HTML_Template_Flexy</classname></title> <programlisting role="php"> <![CDATA[ <html><head> <title>{o.title}</title> </head> <body> <table> <tr> <td> some numbers {foreach:o.numbers,number,string} </td> </tr> <tr> <td> <a href="mypage.html?id=%7Bnumber%7D">{string}</a> {end:} </td> </tr> </table> </body> </html> ]]> </programlisting> </example> <para> And the output </para> <example> <title>Output of example for <classname>HTML_Template_Flexy</classname></title> <programlisting role="php"> <![CDATA[ some numbers Number 1 Number 2 Number 3 Number 4 ]]> </programlisting> </example> </refsect1> </refentry> <!-- ****************************************** Configuraton file ******************************************* --> <refentry id="packages.templates.flexy.configuration"> <refnamediv> <refname>Configuration Options</refname> <refpurpose> Setting the defaults for HTML_Template_Flexy </refpurpose> </refnamediv> <refsect1> <title>Configuration</title> <para> HTML_Template_Flexy can either be configured globally or on each instance, using an associated array. The easiest way to configure HTML_Template_Flexy is to use ini files (although you may also like to consider the PEAR::Config class, or your own configuration system) </para> <example> <title> This is a typical configuration file for <classname>HTML_Template_Flexy</classname></title> <programlisting role="ini"> [HTML_Template_Flexy] templateDir = /home/me/Projects/myapplication/templates compileDir = /home/me/Projects/myapplication/compiled_templates forceCompile = 0 filters = Php,SimpleTags debug = 0 </programlisting> </example> <para> To use this ini file with HTML_Template_Flexy, (and Possibly any other classes that use options like this) </para> <example> <title> Setting the default options</title> <programlisting role="php"><![CDATA[ <?php $config = parse_ini_file('example.ini',TRUE); foreach($config as $class=>$values) { $options = &PEAR::getStaticProperty($class,'options'); $options = $values; } ?> ]]> </programlisting> </example> <para> Alternatively you can set (or override) the configuration when you instantate the class </para> <example> <title> Setting the default options</title> <programlisting role="php"><![CDATA[ <?php $options = array( 'templateDir' => '/home/me/Projects/myapplication/templates', 'compileDir' => '/home/me/Projects/myapplication/compiled_templates', 'forceCompile' => 0, 'filters' => 'Php,SimpleTags', 'debug' => 0 ); $template = new HTML_Template_Flexy($options); ?> ]]> </programlisting> </example> </refsect1> <!-- Config Options --> <refsect1> <title>Configuration Options</title> <variablelist> <varlistentry> <term> <parameter>templateDir</parameter> <type>directory</type> </term> <listitem> <para> This is the directory where all your templates are located </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>compileDir</parameter> <type>directory</type> </term> <listitem> <para> The directory where the compiled templates will be stored, This directory should be writable by the web server </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>forceCompile</parameter> <type>boolean</type> </term> <listitem> <para> Normally 0, means that the template will only be compiled once (or if the template file is altered), this is only really usefull if you are developing filters and need to test the result. </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>filters</parameter> <type>string</type> </term> <listitem> <para> A comma delimited string of the filters you wish to use, the normal set is Php, Simpletags, BodyOnly, which are described in the filters sections </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>debug</parameter> <type>integer</type> </term> <listitem> <para> The default debugging level (default 0=off), 1= shows some debugging information </para> </listitem> </varlistentry> </variablelist> </refsect1> </refentry> <!-- ****************************************** PHP side initializing, Compiling and displaying ******************************************* --> <refentry id="packages.templates.flexy.php"> <refnamediv> <refname>The Class Methods </refname> <refpurpose> HTML_Template_Flexy(), ::compile(), ::outputObject(), ::bufferedOutputObject() </refpurpose> </refnamediv> <refsect1> <title>HTML_Template_Flexy()</title> <para> Initialization </para> <funcsynopsis> <funcprototype> <funcdef>new <function>HTML_Template_Flexy</function></funcdef> <paramdef>array <parameter><optional>options</optional></parameter></paramdef> </funcprototype> </funcsynopsis> <para> class initialization - if you set the default settings using PEAR::getStaticProperty('HTML_Template_Flexy','options');, you do shouldn't need to use the options array, other wise see the Configuration page for more details on the options </para> </refsect1> <refsect1> <title>::compile()</title> <para> Compile the template into PHP </para> <funcsynopsis> <funcprototype> <funcdef>string <function>$flexy->compile</function></funcdef> <paramdef>string <parameter>Template_name</parameter></paramdef> </funcprototype> </funcsynopsis> <para> Compiles the Template into php and puts it in the compiledDir folder. This is only done if the template has changed or, the forceCompile option is set to TRUE or 1. It returns the location of the compiled template (that can be used in an include statement) </para> </refsect1> <refsect1> <title>::outputObject()</title> <para> Merges a controller object with the template and outputs the result </para> <funcsynopsis> <funcprototype> <funcdef> <function>$flexy->outputObject</function></funcdef> <paramdef>object <parameter>Controller_object</parameter></paramdef> </funcprototype> </funcsynopsis> <para> This maps the values of the supplied object and runs the compiled template, and outputs the result. </para> <para> The Template engine performs the following replacements </para> <variablelist> <varlistentry> <term> <parameter>{o.*}</parameter> <type>$object->o.*</type> </term> <listitem> <para> The output variables, in Simpetags $object->o_item becomes {o.item} </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{t.*}</parameter> <type>$object</type> </term> <listitem> <para> The base object, in simpletags you can call a method of the class using {t.output_pulldown()} </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{m.NNN.*}</parameter> <type>$object->modules[NNNN]->*</type> </term> <listitem> <para> The module objects, if you have a modules associative array, the keys a mapped to object variables, and if the module has a variable $template, then it is compiled </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{c.*}</parameter> <type>$object->config</type> </term> <listitem> <para> The config object, if you have an configuration settings you can assign $object->config = (object) $config; prior to running outputObject </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{i.*}</parameter> <type>$object->input</type> </term> <listitem> <para> The input object, you can assign $object->input = (object) $_REQUEST </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{a.*}</parameter> <type>will correspond to PEAR::getStaticProperty('Auth','singleton')</type> </term> <listitem> <para> if you use a session for the controller object you can assign the objects session variable and it can be accessed using {s.variable_name} </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{email_boundary}</parameter> <type>string</type> </term> <listitem> <para> If you need use the template engine with a email template, {email_boundary} will contain a distinct string for mime boundaries </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{email_date}</parameter> <type>string</type> </term> <listitem> <para> Todays date and time for insertion into an email header's Date: field. </para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1> <title>::bufferedOutputObject()</title> <para> Merges a controller object with the template and returns the result </para> <funcsynopsis> <funcprototype> <funcdef> string <function>$flexy->bufferedoutputObject</function></funcdef> <paramdef>object <parameter>Controller_object</parameter></paramdef> </funcprototype> </funcsynopsis> <para> This maps the values of the supplied object and runs the compiled template, and returns the output string. This uses output buffering. It is usefull for caching or using the template engine with emails, rtf, excel files etc. <example> <title> Example of sending email using HTML_Template_Flexy and the PEAR mail classes</title> <programlisting role="php"><![CDATA[ <? function send_password() { $options = &PEAR::getStaticProperty('users_password_new','options'); $template = new HTML_Template_Flexy($options); $template->compile($options['template']); $this->person = DataObjects_Person::staticGet($_GET['id']); $this->person->generatePassword(); $this->options = (object) $options; $mailtext = $template->bufferedOutputObject($this); $decoder = new Mail_mimeDecode($mailtext); $parts = $decoder->getSendArray(); if (PEAR::isError($parts)) { echo "PROBLEM: {$parts->message}"; exit; } list($recipents,$headers,$body) = $parts; $mail = Mail::factory($options['driver'],$options); $mail->send($recipents,$headers,$body); } ?> ]]> </programlisting> </example> </para> </refsect1> </refentry> <!-- ****************************************** SimpleTags: variables, conditionals, looping, method calls, includes ******************************************* --> <refentry id="packages.templates.flexy.filters_simpletags"> <refnamediv> <refname>SimpleTags</refname> <refpurpose> The template tags for variables, conditionals, looping, method calls, includes, these can be used if the Filter option contains the 'SimpleTags' string. </refpurpose> </refnamediv> <refsect1> <title>Variables</title> <para> Displaying Variables </para> <variablelist> <varlistentry> <term> <parameter>{o.string}</parameter> <type>html escaped string</type> </term> <listitem> <para> Outputs a value of string, equivialant to <?php echo htmlspecialchars($this->o_string); ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{o.string:h}</parameter> <type>raw string</type> </term> <listitem> <para> Outputs a value of string, equivialant to <?php echo $this->o_string ; ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{o.string:u}</parameter> <type>url encoded string</type> </term> <listitem> <para> Outputs a value of string, equivialant to <?php echo urlencode($this->o_string); ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{o.string:n}</parameter> <type>line break to br taged output of string</type> </term> <listitem> <para> Outputs a a variable changing line breaks to br tags, equivialant to <?php nl2br(htmlspecialchars($this->o_string)); ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{o.string:r}</parameter> <type>var dump variable</type> </term> <listitem> <para> Outputs a print_r of a variable , equivialant to <PRE><?php print_r($this->o_string); ?></PRE> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>%7Bo.string%7D</parameter> <type>html escaped string</type> </term> <listitem> <para> Outputs a html escaped value of string, equivialant to <?php echo htmlspecialchars($this->o_string); ?>, useful when working with html editors that encode attribute values </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>%7Bo.string:h%7D</parameter> <type>raw string</type> </term> <listitem> <para> Outputs a value of string, equivialant to <?php echo $this->o_string ; ?> useful when working with html editors that encode attribute values </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>%7Bo.string:u%7D</parameter> <type>url encoded string</type> </term> <listitem> <para> Outputs a value of string, equivialant to <?php echo urlencode($this->o_string); ?> useful when working with html editors that encode attribute values </para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1> <title>Methods</title> <para> calls a object method, (all these work with urlencoded tags - eg. %7D etc.) </para> <variablelist> <varlistentry> <term> <parameter>{t.method()}</parameter> <type>call a method</type> </term> <listitem> <para> Outputs a result of method call, equivialant to <?php echo htmlspecialchars($this->method()); ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{t.method(somevar)}</parameter> <type>call a method with a single variable (html escape result)</type> </term> <listitem> <para> Outputs a result of method call, equivialant to <?php echo htmlspecialchars($this->method($somevar)); ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{t.method(somevar):h}</parameter> <type>call a method with a single variable</type> </term> <listitem> <para> Outputs a result of method call, equivialant to <?php echo $this->method($somevar); ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{t.method(somevar):s}</parameter> <type>call a method with a single variable (and php highlight result)</type> </term> <listitem> <para> Outputs a result of method call, equivialant to <?php echo highlight_string($this->method($somevar)); ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{t.method(#some string#)}</parameter> <type>call a method with a string or constant value (and html escapes result)</type> </term> <listitem> <para> Outputs a result of method call, equivialant to <?php echo htmlspecialchars($this->method('some string')); ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{t.method(#some string#):h}</parameter> <type>call a method with a string or constant value</type> </term> <listitem> <para> Outputs a result of method call, equivialant to <?php echo $this->method('some string'); ?> </para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1> <title>Looping and conditional - blocks</title> <para> Simple tags only allows a single type of looping - foreach, it is often used with an array of objects to display rows of table information (for example using DB_DataObject) </para> <variablelist> <varlistentry> <term> <parameter>{foreach:o.items,item}</parameter> <type>loop on items and use the variable item</type> </term> <listitem> <para> Loops on each of the values of the items array , equivialant to <?php if ($object->o_items) (foreach($this->o_items as $item); { ?> ,should be closed with the {end:} tag. </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{foreach:o.items,key,value}</parameter> <type>loop on items and extracts each rows key and value</type> </term> <listitem> <para> Loops on each of the values of the items array , equivialant to <?php if ($object->o_items) foreach($this->o_items as $key=>$value); { ?> ,should be closed with the {end:} tag. </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{end:}</parameter> <type>termintes a loop or conditional</type> </term> <listitem> <para> equivialant to <?php } ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{if:o.value}</parameter> <type>conditional includes a block of html</type> </term> <listitem> <para> equivialant to <?php if ($object->o_value) { ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{if:t.method()}</parameter> <type>conditional includes a block of html</type> </term> <listitem> <para> equivialant to <?php if ($object->method()) { ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{else:}</parameter> <type>alternative outcome to an conditional statement</type> </term> <listitem> <para> equivialant to <?php } else { ?> </para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1> <title>Including other files</title> <para> To include sub templates (eg. body or modules), you can use the {include:*} methods </para> <variablelist> <varlistentry> <term> <parameter>{include:t.somevar}</parameter> <type>includes code from base on the value of a variable</type> </term> <listitem> <para> equivialant to <?php include($options['compiledDir'].$object->somevar . ".en.php") ?> </para> </listitem> </varlistentry> <varlistentry> <term> <parameter>{include:#menu.html#}</parameter> <type>includes code from the named file</type> </term> <listitem> <para> equivialant to <?php include($options['compiledDir']."menu.html") ?> </para> </listitem> </varlistentry> </variablelist> </refsect1> </refentry> <!-- ****************************************** Advanced Filters, Body only, Php stripping, .... ******************************************* --> <refentry id="packages.templates.flexy.filters_advanced"> <refnamediv> <refname>Advanced filters</refname> <refpurpose> The Php, BodyOnly, Mail, RtfSimpleTags Filters </refpurpose> </refnamediv> <refsect1> <title>Using other filters</title> <para> HTML_Template_Flexy includes a few other filters that are usefull when working with templates, you can very easily add your own filter by adding a file in the Flexy/Filters folder, and just copying the format of the existing Filter files. </para> <para> The common addition filters to use are Php, and BodyOnly, other filters like Mail and RtfSimpleTags are usefull when working with Mail and Rtf file templates. </para> </refsect1> <refsect1> <title>Php Filter</title> <para> The Php Filter strips out any php <?php tags prior to parsing and replaces them with htmlescaped tags afterwards. </para> </refsect1> <refsect1> <title>BodyOnly Filter</title> <para> When using a template as the body of a page, The BodyOnly filter will remove the HTML before and including the <BODY> tag and after and including the </BODY> tag </para> </refsect1> <refsect1> <title>Mail Filter</title> <para> Due to php's habit of removing CRLF's after php tags, this filter adds an extra line to alieviate this effect. enabling you to create mail templates. </para> </refsect1> <refsect1> <title>RtfSimpletags Filter</title> <para> Rtf will escape all { with \{, so this Filter replaces the SimpleTags filter when using HTML_Template_Flexy with rtf files. </para> </refsect1> </refentry> </reference> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"../../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 -->