cvs: peardoc /en/packages it.xml

alexmerz Wed Jan 2 13:06:07 2002 EDT Added files: /peardoc/en/packages it.xml Log: add IT manual entrie. Please check typo

Index: peardoc/en/packages/it.xml +++ peardoc/en/packages/it.xml <!-- $Id: it.xml,v 1.1 2002/01/02 18:06:07 alexmerz Exp $ --> <reference id="packages.it"> <title>IntegratedTemplate</title> <!-- Partintro --> <partintro> <para> The PEAR::IntegratedTemplate package is a light-weight template system. it provides placeholder and block support. </para> </partintro> <!-- Partintro --> <!-- it.it {{{ --> <refentry id="packages.it.it"> <refnamediv> <refname><classname>IntegratedTemplate</classname></refname> <refpurpose> Light-weight template system </refpurpose> </refnamediv> <refsect1 id="packages.it.it.placeholder"> <title>Placeholder</title> <para> The format of placeholder is <programlisting role="php"> {[0-9A-Za-z_-]+} </programlisting> This means, the name of the placeholder can consists of upper- and lowercase letters, underscores and hypens. The name must placed between curly brackets without any spaces. Valid name are i.e.: <simplelist> <member>{Placeholder}</member> <member>{place2_holder}</member> <member>{PLACEHOLDER1}</member> <member>{Place-Holder}</member> </simplelist> Non-valid names are i.e. <simplelist> <member>{ Placeholder 3 } (spaces)</member> <member>{place*holder} (char isn't permitted)</member> </simplelist> </para> </refsect1> <refsect1 id="packages.it.it.block"> <title>Blocks</title> <para> The format of a block is <programlisting role="php"> <![CDATA[ <!-- BEGIN [0-9A-Za-z_-]+ --> ... block content ... <!-- END [0-9A-Za-z_-]+ --> ]]> </programlisting> The rules for the block name are the same like for placeholders. In contrast to placeholders the spaces in the block markup are required. </para> <para> The nesting of blocks is permitted, but be carefully while parsing. You have to set and parse the deepest inner block first and then set and parse from inner to outer. </para> </refsect1> <refsect1 id="packages.it.it.example"> <title>Usage Example</title> <example> <title>The template</title> <programlisting role="php"> <![CDATA[ <html> <table border> <!-- BEGIN row --> <tr> <!-- BEGIN cell --> <td> {DATA} </td> <!-- END cell --> </tr> <!-- END row --> </table> </html> ]]> </programlisting> </example> <example> <title>The script</title> <programlisting role="php"> <![CDATA[ <?php require_once "HTML/IT.php"; $data = array ( "0" => array("Stig", "Bakken"), "1" => array("Martin", "Jansen"), "2" => array("Alexander", "Merz") ); $tpl = new IntegratedTemplate("./templates"); $tpl->loadTemplatefile("main.tpl.htm", true, true); foreach($data as $name) { foreach($name as $cell) { // Assign data to the inner block $tpl->setCurrentBlock("cell") ; $tpl->setVariable("DATA", $cell) ; $tpl->parseCurrentBlock("cell") ; } // Assign data and the inner block to the // outer block $tpl->setCurrentBlock("row") ; $tpl->parseCurrentBlock("row") ; } // print the output $tpl->show(); ?> ]]> </programlisting> </example> <example> <title>The output</title> <programlisting role="php"> <![CDATA[ <html> <table border> <tr> <td> Stig </td> <td> Bakken </td> </tr> <tr> <td> Martin </td> <td> Jansen </td> </tr> <tr> <td> Alexander </td> <td> Merz </td> </tr> </table> </html> ]]> </programlisting> </example> </refsect1> <refsect1 id="packages.it.it.integratedtemplate"> <title>IntegratedTemplate::IntegratedTemplate</title> <funcsynopsis> <funcprototype> <funcdef>void <function>IntegratedTemplate::IntegratedTemplate</function></funcdef> <paramdef>[string <parameter>$root</parameter>]</paramdef> </funcprototype> </funcsynopsis> <para> Builds some complex regular expressions and optinally sets the file root directory. Make sure that you call this constructor if you derive your templateclass from this one. </para> <para> Parameter <itemizedlist> <listitem> <para> <parameter>$root</parameter> - root directory, prefix for all filenames given to the object. </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="packages.it.it.get"> <title>IntegratedTemplate::get</title> <funcsynopsis> <funcprototype> <funcdef>string <function>IntegratedTemplate::get</function></funcdef> <paramdef>[string <parameter>$block</parameter>]</paramdef> </funcprototype> </funcsynopsis> <para> Returns a block with all replacements done. </para> <para> Parameter <itemizedlist> <listitem> <para> <parameter>$block</parameter> - block to return, when not set the complete template will returned. </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="packages.it.it.parse"> <title>IntegratedTemplate::parse</title> <funcsynopsis> <funcprototype> <funcdef>void <function>IntegratedTemplate::parse</function></funcdef> <paramdef> [string <parameter>$block</parameter>], [boolean <parameter>$flag_recursion</parameter>] </paramdef> </funcprototype> </funcsynopsis> <para> Parses the given block. </para> <para> Parameter <itemizedlist> <listitem> <para> <parameter>$block</parameter> - block to parse, when not set the complete template will be parsed. </para> </listitem> <listitem> <para> <parameter>$flag_recursion</parameter> - can be ignored </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="packages.it.it.parsecurrentblock"> <title>IntegratedTemplate::parseCurrentBlock</title> <funcsynopsis> <funcprototype> <funcdef>void <function>IntegratedTemplate::parseCurrentBlock</function></funcdef> <paramdef> </paramdef> </funcprototype> </funcsynopsis> <para> Parses the current block </para> </refsect1> <refsect1 id="packages.it.it.setvariable"> <title>IntegratedTemplate::setVariable</title> <funcsynopsis> <funcprototype> <funcdef>void <function>IntegratedTemplate::setVariable</function></funcdef> <paramdef> mixed <parameter>$placeholder</parameter>, [string <parameter>$variable</parameter>] </paramdef> </funcprototype> </funcsynopsis> <para> Sets a variable value. The function can be used eighter like setVariable( "varname", "value") or with one array $variables["varname"] = "value" given setVariable($variables). </para> <para> Parameter <itemizedlist> <listitem> <para> <parameter>$placeholder</parameter> - Name of the placeholder to substitute or a array with the placeholder as key and the data to assign as value. </para> </listitem> <listitem> <para> <parameter>$variable</parameter> - when $placeholder isn't a array, the value to assign to the placeholder. </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="packages.it.it.setCurrentBlock"> <title>IntegratedTemplate::parse</title> <funcsynopsis> <funcprototype> <funcdef>boolean <function>IntegratedTemplate::setCurrentBlock</function></funcdef> <paramdef> [string <parameter>$block</parameter>] </paramdef> </funcprototype> </funcsynopsis> <para> Sets the name of the current block, that is the block where variables are added. </para> <para> Parameter <itemizedlist> <listitem> <para> <parameter>$block</parameter> - block to set, when not given the complete template is set (shows on the placeholders outside of all block). </para> </listitem> </itemizedlist> </para> <para> Returns <itemizedlist> <listitem> <para> <parameter>Boolean</parameter> - false on failure, otherwise true </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="packages.it.it.touchblock"> <title>IntegratedTemplate::touchBlock</title> <funcsynopsis> <funcprototype> <funcdef>boolean <function>IntegratedTemplate::touchBlock</function></funcdef> <paramdef> string <parameter>$block</parameter> </paramdef> </funcprototype> </funcsynopsis> <para> Preserves an empty block even if removeEmptyBlocks is true </para> <para> Parameter <itemizedlist> <listitem> <para> <parameter>$block</parameter> - block to preserve </para> </listitem> </itemizedlist> </para> <para> Returns <itemizedlist> <listitem> <para> <parameter>Boolean</parameter> - false on false, otherwise true </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="packages.it.it.init"> <title>IntegratedTemplate::init</title> <funcsynopsis> <funcprototype> <funcdef>void <function>IntegratedTemplate::init</function></funcdef> <paramdef> </paramdef> </funcprototype> </funcsynopsis> <para> Clears all datafields of the object and rebuild the internal blocklist LoadTemplatefile() and setTemplate() automatically call this functionwhen a new template is given. Don't use this functionunless you know what you're doing. </para> </refsect1> <refsect1 id="packages.it.it.free"> <title>IntegratedTemplate::free</title> <funcsynopsis> <funcprototype> <funcdef>void <function>IntegratedTemplate::free</function></funcdef> <paramdef> </paramdef> </funcprototype> </funcsynopsis> <para> Clears all datafields of the object. Don't use this function unless you know what you're doing. </para> </refsect1> <refsect1 id="packages.it.it.setTemplate"> <title>IntegratedTemplate::setTemplate</title> <funcsynopsis> <funcprototype> <funcdef>void <function>IntegratedTemplate::setTemplate</function></funcdef> <paramdef> string <parameter>$template</parameter> </paramdef> </funcprototype> </funcsynopsis> <para> Sets the template. You can eighter load a template file from disk with LoadTemplatefile() or set the template manually using this function. </para> <para> Parameter <itemizedlist> <listitem> <para> <parameter>$template</parameter> - content </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="packages.it.it.loadTemplatefile"> <title>IntegratedTemplate::loadTemplatefile</title> <funcsynopsis> <funcprototype> <funcdef>boolean <function>IntegratedTemplate::loadTemplatefile</function></funcdef> <paramdef> string <parameter>$filename</parameter>, [boolean <parameter>$removeUnknownVariables</parameter>], [boolean <parameter>$removeEmptyBlocks</parameter>] </paramdef> </funcprototype> </funcsynopsis> <para> Reads a template file from the disk. </para> <para> Parameter <itemizedlist> <listitem> <para> <parameter>$filename</parameter> - name of the template file </para> </listitem> <listitem> <para> <parameter>$removeUnknownVariables</parameter> - when true not assigned placeholders will be deleted </para> </listitem> <listitem> <para> <parameter>$removeEmptyBlocks</parameter> - when true unused blocks will be removed </para> </listitem> </itemizedlist> </para> <para> Returns <itemizedlist> <listitem> <para> <parameter>Boolean</parameter> - false on false, otherwise true </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="packages.it.it.setRoot"> <title>IntegratedTemplate::setRoot</title> <funcsynopsis> <funcprototype> <funcdef>void <function>IntegratedTemplate::setRoot</function></funcdef> <paramdef> string <parameter>$root</parameter> </paramdef> </funcprototype> </funcsynopsis> <para> Sets the file root. The file root gets prefixed to all filenames passed to the object. </para> <para> Parameter <itemizedlist> <listitem> <para> <parameter>$root</parameter> - root directory for the templates </para> </listitem> <listitem> <para> <parameter>$removeUnknownVariables</parameter> - when true not assigned placeholders will be deleted </para> </listitem> <listitem> <para> <parameter>$removeEmptyBlocks</parameter> - when true unused blocks will be removed </para> </listitem> </itemizedlist> </para> </refsect1> <refsect1 id="packages.it.it.show"> <title>IntegratedTemplate::show</title> <funcsynopsis> <funcprototype> <funcdef>void <function>IntegratedTemplate::show</function></funcdef> <paramdef> [string <parameter>$block</parameter>] </paramdef> </funcprototype> </funcsynopsis> <para> Print a certain block with all replacements done. </para> <para> Parameter <itemizedlist> <listitem> <para> <parameter>$block</parameter> - when not set the whole content will be printed. </para> </listitem> </itemizedlist> </para> </refsect1> </refentry> <!-- }}} it.it --> <!-- it.itx {{{ --> <refentry id="packages.it.itx"> <refnamediv> <refname><classname>IntegratedTemplateExtension</classname></refname> <refpurpose> Wrapper class around IntegratedTemplate, compatible to the PHPLIB template system </refpurpose> </refnamediv> <refsect1 id="packages.it.itx.desc"> <title>Description</title> <para> IntegratedTemplateExtension was created as a wrapper class for the <ulink url="&url.phplib">PHPLIB</ulink> template system. it helps you to migrate PHPLIB-based projects to PEAR-based. </para> <para> <acronym>ITX</acronym> is API-compatible, but based on <link linkend="packages.it.it">IntegratedTemplate</link>. Due to the different concepts of processing and organizing blocks in a template, the behavior of itx can differ in some situations. </para> <para> it is not recommended to start a project based ITX. If you want a PHPLIB-styled template system, then you should use <classname>Template_PHPLIB</classname>, which is the PHPLIB template system following the PEAR coding standards. </para> </refsect1> </refentry> <!-- }}} it.itx --> </reference>