smarty/docs/appendixes.sgml

<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>
Warning: Smarty: [in index.tpl line 4]: syntax error: unknown tag - '%blah'
        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 & 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>

{* the long way *}

{if $title eq ""}
	&amp;nbsp;
{else}
	{$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>
{* 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>

mainpage.tpl
------------

{include file="header.tpl" title="Main Page"}
{* template body goes here *}
{include file="footer.tpl"}


archives.tpl
------------

{config_load file="archive_page.conf"}
{include file="header.tpl" title=#archivePageTitle#}
{* template body goes here *}
{include file="footer.tpl"}


header.tpl
----------
&lt;HTML&gt;
&lt;HEAD&gt;
&lt;TITLE&gt;{$title|default:"BC News"}&lt;/TITLE&gt;
&lt;/HEAD&gt;
&lt;BODY&gt;


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="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>
{$startDate|date_format}

OUTPUT:

Jan 4, 2001


{$startDate|date_format:"%Y/%m/%d"}

OUTPUT:

2001/01/04


{if $date1 < $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>
// this assumes your form elements are named
// startDate_Day, startDate_Month, startDate_Year

$startDate = makeTimeStamp($startDate_Year,$startDate_Month,$startDate_Day);

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>
// be sure apache is configure for the .wml extensions!                                    
// put this function somewhere in your application, or in Smarty.addons.php
function insert_header() {
    // this function expects $content argument
    extract(func_get_arg(0));
    if(empty($content))
        return;
    header($content);
    return;
}

// your Smarty template _must_ begin with the insert tag example:

{insert name=header content="Content-Type: text/vnd.wap.wml"}

&lt;?xml version="1.0"?&gt;  
&lt;!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN" "http://www.wapforum.org/DTD/wml_1.1.xml"&gt; 

&lt;!-- begin new wml deck --&gt; 
&lt;wml&gt; 
&lt;!-- begin first card --&gt; 
&lt;card&gt; 
&lt;do type="accept"&gt; 
&lt;go href="#two"/&gt; 
&lt;/do&gt;  
&lt;p&gt; 
Welcome to WAP with Smarty!
Press OK to continue...  
&lt;/p&gt; 
&lt;/card&gt;  
&lt;!-- begin second card --&gt; 
&lt;card id="two"&gt;  
&lt;p&gt; 
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>
		This tip is a bit of a hack, but still a neat idea. Use at your own
		risk. ;-)
		</para>
		<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 embed PHP into your templates with the {php}{/php} tags.
        With this, you can setup self contained templates with their own
        data structures for assigning their own variables. With the logic
        embedded like this, you can keep the template & logic together. This
        way no matter where the template source is coming from, it is always
        together as one component.
        </para>
<example>
<title>componentized template</title>
<programlisting>
{* Smarty *}

{php}

	// setup our function for fetching stock data
	function fetch_ticker($symbol,&$ticker_name,&$ticker_price) {
		// put logic here that fetches $ticker_name
		// and $ticker_price from some resource
	}

	// call the function
	fetch_ticker("YHOO",$ticker_name,$ticker_price);
	
	// assign template variables
    $this->assign("ticker_name",$ticker_name);
    $this->assign("ticker_price",$ticker_price);

{/php}

Stock Name: {$ticker_name} Stock Price: {$ticker_price}</programlisting>
</example>
        <para>
		As of Smarty 1.5.0, there is even a cleaner way. You can include php in
		your templates with the {include_php ...} tag. This way you can keep
		your PHP logic separated from the template logic. See the <link
		linkend="language.function.include.php">include_php</link> function for
		more information.
        </para>
<example>
<title>componentized template with include_php</title>
<programlisting>
load_ticker.php
---------------

&lt;?php
	// setup our function for fetching stock data
	function fetch_ticker($symbol,&$ticker_name,&$ticker_price) {
		// put logic here that fetches $ticker_name
		// and $ticker_price from some resource
	}

	// call the function
	fetch_ticker("YHOO",$ticker_name,$ticker_price);
	
	// assign template variables
    $this->assign("ticker_name",$ticker_name);
    $this->assign("ticker_price",$ticker_price);
?&gt;


index.tpl
---------

{* Smarty *}

{include_php file="load_ticker.php"}

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 a
		scrambled looking form in the HTML source, yet it it will look and work
		correctly in the browser. This is done with the escape modifier.
		</para>
<example>
<title>Example of Obfuscating an E-mail Address</title>
<programlisting>

index.tpl
---------

Send inquiries to
&lt;a href="mailto:{$EmailAddress|escape:"hex"}"&gt;{$EmailAddress|escape:"hexentity"}&lt;/a&gt;

OUTPUT:

Send inquiries to 
&lt;a
href="mailto:%62%6f%62%40%6d%65%2e%6e%65%74"&gt;&amp;#x62;&amp;#x6f;&amp;#x62;&amp;#x40;&amp;#x6d;&amp;#x65;&amp;#x2e;&amp;#x6e;&amp;#x65;&amp;#x74;&lt;/a&gt;

</programlisting>
</example>
	<para>
	Although this looks like a mess in the HTML source, it will render
	correctly in your browser, and the mailto: hyperlink will go to the correct
	address.
	</para>
	<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.
	</para>
	</note>
	</sect1>
</chapter>
<chapter id="resources">
	<title>Resources</title>
	<para>
	Smarty's homepage is located at http://www.phpinsider.com/php/code/Smarty/.
	You can join the mailing list by sending an e-mail to
	smarty-general-subscribe@lists.php.net. 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>