cvs: smarty /docs appendixes.sgml

http://cvs.php.net/diff.php/smarty/docs/appendixes.sgml?r1=1.14&r2=1.15&ty=u
Index: smarty/docs/appendixes.sgml
diff -u smarty/docs/appendixes.sgml:1.14 smarty/docs/appendixes.sgml:1.15
--- smarty/docs/appendixes.sgml:1.14	Mon Mar  1 15:08:54 2004
+++ smarty/docs/appendixes.sgml	Tue Mar 16 09:56:14 2004
@@ -1,119 +1,128 @@
 <part id="appendixes">
  <title>Appendixes</title>
-<chapter id="troubleshooting">
-   <title>Troubleshooting</title>
-   <para></para>
-   <sect1 id="smarty.php.errors">
-       <title>Smarty/PHP errors</title>
-       <para>
-       Smarty can catch many errors such as missing tag attributes
-       or malformed variable names. If this happens, you will see an error
-       similar to the following:
-       </para>
-
-<example>
-<title>Smarty errors</title>
-<programlisting>
+ <chapter id="troubleshooting">
+  <title>Troubleshooting</title>
+  <para></para>
+  <sect1 id="smarty.php.errors">
+   <title>Smarty/PHP errors</title>
+   <para>
+    Smarty can catch many errors such as missing tag attributes
+    or malformed variable names. If this happens, you will see an error
+    similar to the following:
+   </para>
+   <example>
+    <title>Smarty errors</title>
+    <screen>
+<![CDATA[
 Warning: Smarty: [in index.tpl line 4]: syntax error: unknown tag - '%blah'
-        in /path/to/smarty/Smarty.class.php on line 1041
+       in /path/to/smarty/Smarty.class.php on line 1041
 
 Fatal error: Smarty: [in index.tpl line 28]: syntax error: missing section name
-        in /path/to/smarty/Smarty.class.php on line 1041</programlisting>
-</example>
-
-       <para>
-        Smarty shows you the template name, the line number and the error.
-        After that, the error consists of the actual line number in the Smarty
-        class that the error occured.
-       </para>
-       
-       <para>
-        There are certain errors that Smarty cannot catch, such as missing
-        close tags. These types of errors usually end up in PHP compile-time
-        parsing errors.
-       </para>
-
-<example>
-<title>PHP parsing errors</title>
-<programlisting>
-Parse error: parse error in /path/to/smarty/templates_c/index.tpl.php on line 75</programlisting>
-</example>
-       
-       <para>
-        When you encounter a PHP parsing error, the error line number will
-        correspond to the compiled PHP script, not the template itself. Usually
-        you can look at the template and spot the syntax error. Here are some
-        common things to look for: missing close tags for {if}{/if} or
-        {section}{/section}, or syntax of logic within an {if} tag. If you
-        can't find the error, you might have to open the compiled PHP file and
-        go to the line number to figure out where the corresponding error is in
-        the template.
-       </para>
-   </sect1>
-</chapter>
-<chapter id="tips">
-   <title>Tips &amp; Tricks</title>
-   <para>
-   </para>
-   <sect1 id="tips.blank.var.handling">
-		<title>Blank Variable Handling</title>
-		<para>
-		There may be times when you want to print a default value for an empty
-		variable instead of printing nothing, such as printing "&amp;nbsp;" so that
-		table backgrounds work properly. Many would use an {if} statement to
-		handle this, but there is a shorthand way with Smarty, using the
-		<emphasis>default</emphasis> variable modifier.
-		</para>
-<example>
-<title>Printing &amp;nbsp; when a variable is empty</title>
-<programlisting>
+       in /path/to/smarty/Smarty.class.php on line 1041
+]]>
+    </screen>
+   </example>
+   <para>
+    Smarty shows you the template name, the line number and the error.
+    After that, the error consists of the actual line number in the Smarty
+    class that the error occured.
+   </para>
+      
+   <para>
+    There are certain errors that Smarty cannot catch, such as missing
+    close tags. These types of errors usually end up in PHP compile-time
+    parsing errors.
+   </para>
 
+   <example>
+    <title>PHP parsing errors</title>
+    <screen>
+<![CDATA[
+Parse error: parse error in /path/to/smarty/templates_c/index.tpl.php on line 75
+]]>
+    </screen>
+   </example>
+      
+   <para>
+    When you encounter a PHP parsing error, the error line number will
+    correspond to the compiled PHP script, not the template itself. Usually
+    you can look at the template and spot the syntax error. Here are some
+    common things to look for: missing close tags for {if}{/if} or
+    {section}{/section}, or syntax of logic within an {if} tag. If you
+    can't find the error, you might have to open the compiled PHP file and
+    go to the line number to figure out where the corresponding error is in
+    the template.
+   </para>
+  </sect1>
+ </chapter>
+ <chapter id="tips">
+  <title>Tips &amp; Tricks</title>
+  <para>
+  </para>
+  <sect1 id="tips.blank.var.handling">
+   <title>Blank Variable Handling</title>
+   <para>
+    There may be times when you want to print a default value for an empty
+    variable instead of printing nothing, such as printing "&amp;nbsp;" so that
+    table backgrounds work properly. Many would use an {if} statement to
+    handle this, but there is a shorthand way with Smarty, using the
+    <emphasis>default</emphasis> variable modifier.
+   </para>
+   <example>
+    <title>Printing &amp;nbsp; when a variable is empty</title>
+    <programlisting>
+<![CDATA[
 {* the long way *}
 
 {if $title eq ""}
-	&amp;nbsp;
+   &amp;nbsp;
 {else}
-	{$title}
+   {$title}
 {/if}
 
 
 {* the short way *}
 
-{$title|default:"&amp;nbsp;"}</programlisting>
-</example>
-	</sect1>
-
-    <sect1 id="tips.default.var.handling">
-		<title>Default Variable Handling</title>
-		<para>
-		If a variable is used frequently throughout your templates, applying
-		the default modifier every time it is mentioned can get a bit ugly. You
-		can remedy this by assigning the variable its default value with the
-		<link linkend="language.function.assign">assign</link> function.
-		</para>
-<example>
-<title>Assigning a template variable its default value</title>
-<programlisting>
+{$title|default:"&amp;nbsp;"}
+]]>
+    </programlisting>
+   </example>
+  </sect1>
+
+  <sect1 id="tips.default.var.handling">
+   <title>Default Variable Handling</title>
+   <para>
+    If a variable is used frequently throughout your templates, applying
+    the default modifier every time it is mentioned can get a bit ugly. You
+    can remedy this by assigning the variable its default value with the
+    <link linkend="language.function.assign">assign</link> function.
+   </para>
+   <example>
+    <title>Assigning a template variable its default value</title>
+    <programlisting>
+<![CDATA[
 {* do this somewhere at the top of your template *}
 {assign var="title" value=$title|default:"no title"}
 
 {* if $title was empty, it now contains the value "no title" when you print it *}
-{$title}</programlisting>
-</example>
-	</sect1>
-    <sect1 id="tips.passing.vars">
-		<title>Passing variable title to header template</title>
-		<para>
-		When the majority of your templates use the same headers and footers, it
-		is common to split those out into their own templates and include them.
-		But what if the header needs to have a different title, depending on
-		what page you are coming from? You can pass the title to the header when
-		it is included.
-		</para>
-<example>
-<title>Passing the title variable to the header template</title>
-<programlisting>
-
+{$title}
+]]>
+    </programlisting>
+   </example>
+  </sect1>
+  <sect1 id="tips.passing.vars">
+   <title>Passing variable title to header template</title>
+   <para>
+    When the majority of your templates use the same headers and footers, it
+    is common to split those out into their own templates and include them.
+    But what if the header needs to have a different title, depending on
+    what page you are coming from? You can pass the title to the header when
+    it is included.
+   </para>
+   <example>
+    <title>Passing the title variable to the header template</title>
+    <programlisting>
+<![CDATA[
 mainpage.tpl
 ------------
 
@@ -143,34 +152,37 @@
 footer.tpl
 ----------
 &lt;/BODY&gt;
-&lt;/HTML&gt;</programlisting>
-</example>
-	<para>
-		When the main page is drawn, the title of "Main Page" is passed to the
-		header.tpl, and will subsequently be used as the title. When the
-		archives page is drawn, the title will be "Archives". Notice in the
-		archive example, we are using a variable from the archives_page.conf
-		file instead of a hard coded variable. Also notice that "BC News" is
-		printed if the $title variable is not set, using the
-		<emphasis>default</emphasis> variable modifier.
-	</para>
-	</sect1>
-    <sect1 id="tips.dates">
-       <title>Dates</title>
-       <para>
-	   As a rule of thumb, always pass dates to Smarty as timestamps. This
-	   allows template designers to use <link
-	   linkend="language.modifier.date.format">date_format</link> for full
-	   control over date formatting, and also makes it easy to compare dates if
-	   necessary.
-       </para>
-       <para>
-       NOTE: As of Smarty 1.4.0, you can pass dates to Smarty as unix
-       timestamps, mysql timestamps, or any date parsable by strtotime().
-       </para>
-<example>
-<title>using date_format</title>
-<programlisting>
+&lt;/HTML&gt;
+]]>
+    </programlisting>
+   </example>
+   <para>
+    When the main page is drawn, the title of "Main Page" is passed to the
+    header.tpl, and will subsequently be used as the title. When the
+    archives page is drawn, the title will be "Archives". Notice in the
+    archive example, we are using a variable from the archives_page.conf
+    file instead of a hard coded variable. Also notice that "BC News" is
+    printed if the $title variable is not set, using the
+    <emphasis>default</emphasis> variable modifier.
+   </para>
+  </sect1>
+  <sect1 id="tips.dates">
+   <title>Dates</title>
+   <para>
+    As a rule of thumb, always pass dates to Smarty as timestamps. This
+    allows template designers to use <link
+    linkend="language.modifier.date.format">date_format</link> for full
+    control over date formatting, and also makes it easy to compare dates if
+    necessary.
+   </para>
+   <para>
+    NOTE: As of Smarty 1.4.0, you can pass dates to Smarty as unix
+    timestamps, mysql timestamps, or any date parsable by strtotime().
+   </para>
+   <example>
+    <title>using date_format</title>
+    <programlisting>
+<![CDATA[
 {$startDate|date_format}
 
 OUTPUT:
@@ -186,17 +198,20 @@
 
 
 {if $date1 &lt; $date2}
-	...
-{/if}</programlisting>
-</example>
-		<para>
-        When using {html_select_date} in a template, The programmer will most
-        likely want to convert the output from the form back into timestamp
-        format. Here is a function to help you with that.
-		</para>
-<example>
-<title>converting form date elements back to a timestamp</title>
-<programlisting>
+   ...
+{/if}
+]]>
+    </programlisting>
+   </example>
+   <para>
+    When using {html_select_date} in a template, The programmer will most
+    likely want to convert the output from the form back into timestamp
+    format. Here is a function to help you with that.
+   </para>
+   <example>
+    <title>converting form date elements back to a timestamp</title>
+    <programlisting role="php">
+<![CDATA[
 // this assumes your form elements are named
 // startDate_Day, startDate_Month, startDate_Year
 
@@ -204,42 +219,53 @@
 
 function makeTimeStamp($year="",$month="",$day="")
 {
-	if(empty($year))
-		$year = strftime("%Y");
-	if(empty($month))
-		$month = strftime("%m");
-	if(empty($day))
-		$day = strftime("%d");
-
-	return mktime(0,0,0,$month,$day,$year);
-}</programlisting>
-</example>
-	</sect1>
-    <sect1 id="tips.wap">
-		<title>WAP/WML</title>
-		<para>
-        WAP/WML templates require a php Content-Type header to be passed along
-        with the template. The easist way to do this would be to write a custom
-        function that prints the header. If you are using caching, that won't
-        work so we'll do it using the insert tag (remember insert tags are not
-        cached!) Be sure that there is nothing output to the browser before the
-        template, or else the header may fail.
-		</para>
-<example>
-<title>using insert to write a WML Content-Type header</title>
-<programlisting>
+   if(empty($year))
+       $year = strftime("%Y");
+   if(empty($month))
+       $month = strftime("%m");
+   if(empty($day))
+       $day = strftime("%d");
+
+   return mktime(0,0,0,$month,$day,$year);
+}
+]]>
+    </programlisting>
+   </example>
+  </sect1>
+  <sect1 id="tips.wap">
+   <title>WAP/WML</title>
+   <para>
+    WAP/WML templates require a php Content-Type header to be passed along
+    with the template. The easist way to do this would be to write a custom
+    function that prints the header. If you are using caching, that won't
+    work so we'll do it using the insert tag (remember insert tags are not
+    cached!) Be sure that there is nothing output to the browser before the
+    template, or else the header may fail.
+   </para>
+   <example>
+    <title>using insert to write a WML Content-Type header</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
 // be sure apache is configure for the .wml extensions!                                    
 // put this function somewhere in your application, or in Smarty.addons.php
 function insert_header($params) {
-    // this function expects $content argument
-    if(empty($params['content']))
-        return;
-    header($params['content']);
-    return;
+   // this function expects $content argument
+   if(empty($params['content']))
+       return;
+   header($params['content']);
+   return;
 }
 
-// your Smarty template _must_ begin with the insert tag example:
-
+?>
+]]>
+    </programlisting>
+    <para>
+     your Smarty template <emphasis>must</emphasis> begin with the insert tag :
+    </para>
+    <programlisting>
+<![CDATA[
 {insert name=header content="Content-Type: text/vnd.wap.wml"}
 
 &lt;?xml version="1.0"?&gt;  
@@ -263,49 +289,54 @@
 Pretty easy isn't it?
 &lt;/p&gt; 
 &lt;/card&gt; 
-&lt;/wml&gt;</programlisting>
-</example>
-	</sect1>
-	<sect1 id="tips.componentized.templates">
-		<title>Componentized Templates</title>
-		<para>
-        Traditionally, programming templates into your applications goes as
-        follows: First, you accumulate your variables within your PHP
-        application, (maybe with database queries.) Then, you instantiate your
-        Smarty object, assign the variables and display the template. So lets
-        say for example we have a stock ticker on our template. We would
-        collect the stock data in our application, then assign these variables
-        in the template and display it. Now wouldn't it be nice if you could
-        add this stock ticker to any application by merely including the
-        template, and not worry about fetching the data up front?
-		</para>
-        <para>
-        You can do this by writing a custom plugin for fetching the content and
-        assigning it to a template variable.
-        </para>
-<example>
-<title>componentized template</title>
-<programlisting>
-function.load_ticker.php
----------------
+&lt;/wml&gt;
+]]>
+    </programlisting>
+   </example>
+  </sect1>
+  <sect1 id="tips.componentized.templates">
+   <title>Componentized Templates</title>
+   <para>
+    Traditionally, programming templates into your applications goes as
+    follows: First, you accumulate your variables within your PHP
+    application, (maybe with database queries.) Then, you instantiate your
+    Smarty object, assign the variables and display the template. So lets
+    say for example we have a stock ticker on our template. We would
+    collect the stock data in our application, then assign these variables
+    in the template and display it. Now wouldn't it be nice if you could
+    add this stock ticker to any application by merely including the
+    template, and not worry about fetching the data up front?
+   </para>
+   <para>
+    You can do this by writing a custom plugin for fetching the content and
+    assigning it to a template variable.
+   </para>
+   <example>
+    <title>componentized template</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
 
-&lt;?php
+// function.load_ticker.php
 function smarty_function_load_ticker($params, &amp;$smarty) {
-	// setup our function for fetching stock data
-	function fetch_ticker($params['symbol']) {
-		// put logic here that fetches $ticker_info
-		// from some resource
-        return $ticker_info;
-	}
-
-	// call the function
-	$ticker_info = fetch_ticker("YHOO",$ticker_info);
-	
-	// assign template variable
-    $smarty->assign($params['assign'],$ticker_info);
+   // setup our function for fetching stock data
+   function fetch_ticker($params['symbol']) {
+       // put logic here that fetches $ticker_info
+       // from some resource
+       return $ticker_info;
+   }
+
+   // call the function
+   $ticker_info = fetch_ticker("YHOO",$ticker_info);
+   
+   // assign template variable
+   $smarty->assign($params['assign'],$ticker_info);
 }
-?&gt;
-
+?>
+]]>
+    </programlisting>
+    <programlisting>
+<![CDATA[
 index.tpl
 ---------
 
@@ -313,53 +344,55 @@
 
 {load_ticker symbol="YHOO" assign="ticker"}
 
-Stock Name: {$ticker.name} Stock Price: {$ticker.price}</programlisting>
-</example>
-	</sect1>
-	<sect1 id="tips.obfuscating.email">
-		<title>Obfuscating E-mail Addresses</title>
-		<para>
-		Do you ever wonder how your E-mail address gets on so many spam mailing
-		lists? One way spammers collect E-mail addresses is from web pages. To
-		help combat this problem, you can make your E-mail address show up in
-		scrambled javascript in the HTML source, yet it it will look and work
-		correctly in the browser. This is done with the mailto plugin.
-		</para>
-<example>
-<title>Example of Obfuscating an E-mail Address</title>
-<programlisting>
-
+Stock Name: {$ticker.name} Stock Price: {$ticker.price}
+]]>
+    </programlisting>
+   </example>
+  </sect1>
+  <sect1 id="tips.obfuscating.email">
+   <title>Obfuscating E-mail Addresses</title>
+   <para>
+    Do you ever wonder how your E-mail address gets on so many spam mailing
+    lists? One way spammers collect E-mail addresses is from web pages. To
+    help combat this problem, you can make your E-mail address show up in
+    scrambled javascript in the HTML source, yet it it will look and work
+    correctly in the browser. This is done with the mailto plugin.
+   </para>
+   <example>
+    <title>Example of Obfuscating an E-mail Address</title>
+    <programlisting>
+<![CDATA[
 index.tpl
 ---------
 
 Send inquiries to
 {mailto address=$EmailAddress encode="javascript" subject="Hello"}
-
-</programlisting>
-</example>
-	<note>
-	<title>Technical Note</title>
-	<para>
-	This method isn't 100% foolproof. A spammer could conceivably program his
-	e-mail collector to decode these values, but not likely.
-	</para>
-	</note>
-	</sect1>
-</chapter>
-<chapter id="resources">
-	<title>Resources</title>
-	<para>
-	Smarty's homepage is located at http://smarty.php.net/.
-	You can join the mailing list by sending an e-mail to
-	[email protected]. An archive of the mailing list can be
-	viewed at http://marc.theaimsgroup.com/?l=smarty&amp;r=1&amp;w=2
-	</para>
-</chapter>
-<chapter id="bugs">
-	<title>BUGS</title>
-	<para>
-	Check the BUGS file that comes with the latest distribution of Smarty, or
-	check the website.
-	</para>
-</chapter>
+]]>
+    </programlisting>
+   </example>
+   <note>
+    <title>Technical Note</title>
+    <para>
+     This method isn't 100% foolproof. A spammer could conceivably program his
+     e-mail collector to decode these values, but not likely.
+    </para>
+   </note>
+  </sect1>
+ </chapter>
+ <chapter id="resources">
+  <title>Resources</title>
+  <para>
+   Smarty's homepage is located at http://smarty.php.net/.
+   You can join the mailing list by sending an e-mail to
+   [email protected]. An archive of the mailing list can be
+   viewed at http://marc.theaimsgroup.com/?l=smarty&amp;r=1&amp;w=2
+  </para>
+ </chapter>
+ <chapter id="bugs">
+  <title>BUGS</title>
+  <para>
+   Check the BUGS file that comes with the latest distribution of Smarty, or
+   check the website.
+  </para>
+ </chapter>
 </part>