svn: /pear/peardoc/trunk/en/package/html/html-template-sigma/ intro-syntax.xml

--fbc11f2c97ad7fcafc5372bb8e398322584a53af
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 8bit

avb                                      Wed, 15 Jan 2014 12:24:51 +0000

Revision: http://svn.php.net/viewvc?view=revision&revision=332627

Log:
Documented the means to customize template syntax (bug #18147)

Bug: http://pear.php.net/bugs/18147 (unknown) 
      
Changed paths:
    U   pear/peardoc/trunk/en/package/html/html-template-sigma/intro-syntax.xml

Modified: pear/peardoc/trunk/en/package/html/html-template-sigma/intro-syntax.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-template-sigma/intro-syntax.xml	2014-01-15 12:19:13 UTC (rev 332626)
+++ pear/peardoc/trunk/en/package/html/html-template-sigma/intro-syntax.xml	2014-01-15 12:24:51 UTC (rev 332627)
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<refentry xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="package.html.html-template-sigma.intro-syntax">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:phd="http://www.php.net/ns/phd" version="lillet" xml:id="package.html.html-template-sigma.intro-syntax">
    <refnamediv>
     <refname>Introduction - template syntax</refname>
     <refpurpose>Creating and editing templates</refpurpose>
@@ -229,6 +229,88 @@
     </para>
   </refsection>

+  <refsection xml:id="package.html.html-template-sigma.intro-syntax.customization">
+   <info>
+       <title>Customizing the template syntax</title>
+   </info>
+   <para>
+    It is possible to somewhat customize the syntax of templates by changing regular
+    expressions (or their parts) used by Sigma for parsing.
+   </para>
+   <para>
+       The actual regular expressions used to parse templates are generated in constructor
+       using parts specified as class properties. It is generally <emphasis>not</emphasis> safe
+       to change the generated regular expressions (as their format is hardcoded in several places
+       throughout Sigma), but you can override the properties:
+       <variablelist>
+        <varlistentry>
+            <term><phd:pearapi phd:package="HTML_Template_Sigma"
+                phd:linkend="HTML_Template_Sigma::$openingDelimiter">$openingDelimiter</phd:pearapi></term>
+            <listitem><simpara>Start of variable placeholder, defaults to
+                <literal>'{'</literal></simpara></listitem>
+        </varlistentry>
+        <varlistentry>
+            <term><phd:pearapi phd:package="HTML_Template_Sigma"
+                phd:linkend="HTML_Template_Sigma::$closingDelimiter">$closingDelimiter</phd:pearapi></term>
+            <listitem><simpara>Start of variable placeholder, defaults to
+                <literal>'}'</literal></simpara></listitem>
+        </varlistentry>
+        <varlistentry>
+            <term><phd:pearapi phd:package="HTML_Template_Sigma"
+                phd:linkend="HTML_Template_Sigma::$blocknameRegExp">$blocknameRegExp</phd:pearapi></term>
+            <listitem><simpara>Regular expression part for block names, defaults to
+                <literal>'[0-9A-Za-z_-]+'</literal></simpara></listitem>
+        </varlistentry>
+        <varlistentry>
+            <term><phd:pearapi phd:package="HTML_Template_Sigma"
+                phd:linkend="HTML_Template_Sigma::$variablenameRegExp">$variablenameRegExp</phd:pearapi></term>
+            <listitem><simpara>Regular expression part for placeholder names, defaults to
+                <literal>'[0-9A-Za-z._-]+'</literal></simpara></listitem>
+        </varlistentry>
+        <varlistentry>
+            <term><phd:pearapi phd:package="HTML_Template_Sigma"
+                phd:linkend="HTML_Template_Sigma::$functionnameRegExp">$functionnameRegExp</phd:pearapi></term>
+            <listitem><simpara>Regular expression part for function names, defaults to
+                <literal>'[_a-zA-Z][A-Za-z_0-9]*'</literal></simpara></listitem>
+        </varlistentry>
+        <varlistentry>
+            <term><phd:pearapi phd:package="HTML_Template_Sigma"
+                phd:linkend="HTML_Template_Sigma::$includeRegExp">$includeRegExp</phd:pearapi></term>
+            <listitem><simpara>Complete regular expression for processing file inclusion, defaults to
+                <literal>'#&lt;!--\s+INCLUDE\s+(\S+)\s+--&gt;#im'</literal></simpara></listitem>
+        </varlistentry>
+        <varlistentry>
+            <term><phd:pearapi phd:package="HTML_Template_Sigma"
+                phd:linkend="HTML_Template_Sigma::$commentRegExp">$commentRegExp</phd:pearapi></term>
+            <listitem><simpara>Complete regular expression for removing template comments, defaults to
+                <literal>'#&lt;!--\s+COMMENT\s+--&gt;.*?&lt;!--\s+/COMMENT\s+--&gt;#sm'</literal></simpara></listitem>
+        </varlistentry>
+       </variablelist>
+   </para>
+   <para>
+       To customize some of the above parts you need to subclass
+       <classname>HTML_Template_Sigma</classname> and override the relevant properties
+       so that generated regular expressions will use the new parts. For example,
+       if you want to prevent Sigma treating <literal>{1}</literal> (which may appear
+       as a part of Javascript regular expression) as a placeholder (see
+       <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pear.bug;18147">bug #18147</link>)
+       you can do the following
+       <programlisting role="php">
+<![CDATA[
+class SanerPlaceholders extends HTML_Template_Sigma
+{
+    var $variablenameRegExp = '[A-Za-z_][0-9A-Za-z._-]*';
+}
+
+$tpl = new SanerPlaceholders();
+$tpl->setTemplate('{foo} {1} {bar}');
+$tpl->setVariable('foo', 'foo value');
+$tpl->show();
+]]>
+       </programlisting>
+   </para>
+  </refsection>
+
   <refsection xml:id="package.html.html-template-sigma.intro-syntax.example"><info><title>Usage Example</title></info>

    <note><info><title>Other usage examples</title></info>

--fbc11f2c97ad7fcafc5372bb8e398322584a53af--