smarty/docs/en/appendixes/tips.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
 <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
    <literal>&amp;nbsp;</literal> so that
    html table backgrounds work properly. Many would use an
    <link linkend="language.function.if"><varname>{if}</varname></link>
    statement to  handle this, but there is a shorthand way with Smarty, using
    the <link linkend="language.modifier.default"><varname>default</varname>
    </link> variable modifier.
    <note>
    <para><quote>Undefined variable</quote> errors will show if PHP
    <ulink url="&url.php-manual;error_reporting">
    <varname>error_reporting()</varname></ulink> is <constant>E_ALL</constant>
     and a variable had not been assigned to Smarty.
    </para>
    </note>
   </para>

   <example>
    <title>Printing &amp;nbsp; when a variable is empty</title>
    <programlisting>
<![CDATA[
{* the long way *}
{if $title eq ''}
   &nbsp;
{else}
   {$title}
{/if}

{* the short way *}
{$title|default:'&nbsp;'}
]]>
    </programlisting>
   </example>
<para>
See also <link linkend="language.modifier.default">
<varname>default</varname></link> modifier and
<link linkend="tips.default.var.handling">default variable handling</link>.
</para>
  </sect1>


  <sect1 id="tips.default.var.handling">
   <title>Default Variable Handling</title>
   <para>
    If a variable is used frequently throughout your templates, applying
    the <link linkend="language.modifier.default"><varname>default</varname>
    </link> 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"><varname>{assign}</varname></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 use it *}
{$title}
]]>
    </programlisting>
   </example>
   <para>
    See also
    <link linkend="language.modifier.default"><varname>default</varname></link>
     modifier and <link linkend="tips.blank.var.handling">blank variable handling</link>.
   </para>
  </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
    <link linkend="language.function.include">
    <varname>{include}</varname></link> 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
    as an <link linkend="language.syntax.attributes">attribute</link> when
    it is included.
   </para>

 <example>
    <title>Passing the title variable to the header template</title>

   <para>
    <filename>mainpage.tpl</filename> - When the main page is drawn,
    the title of <quote>Main Page</quote> is passed to the
    <filename>header.tpl</filename>, and will subsequently be used as the title.
    </para>
    <programlisting>
<![CDATA[
{include file='header.tpl' title='Main Page'}
{* template body goes here *}
{include file='footer.tpl'}
]]>
    </programlisting>

    <para>
    <filename>archives.tpl</filename> - When the
    archives page is drawn, the title will be <quote>Archives</quote>.
    Notice in the  archive example, we are using a variable from the
    <filename>archives_page.conf</filename>
    file instead of a hard coded variable.
    </para>
    <programlisting>
<![CDATA[
{config_load file='archive_page.conf'}

{include file='header.tpl' title=#archivePageTitle#}
{* template body goes here *}
{include file='footer.tpl'}
]]>
    </programlisting>

    <para>
    <filename>header.tpl</filename> - Notice that <quote>Smarty News</quote> is
    printed if the <literal>$title</literal> variable is not set, using the
    <link linkend="language.modifier.default"><varname>default</varname></link>
    variable modifier.
    </para>
    <programlisting>
<![CDATA[
<html>
<head>
<title>{$title|default:'Smarty News'}</title>
</head>
<body>
]]>
    </programlisting>

    <para>
    <filename>footer.tpl</filename>
    </para>
    <programlisting>
<![CDATA[
</body>
</html>
]]>
    </programlisting>
 </example>
  </sect1>

  <sect1 id="tips.dates">
   <title>Dates</title>
   <para>
    As a rule of thumb, always pass dates to Smarty as
    <ulink url="&url.php-manual;time">timestamps</ulink>. This
    allows template designers to use the <link
    linkend="language.modifier.date.format"><varname>date_format</varname>
    </link> modifier for full control over date formatting, and also makes it
    easy to compare dates if necessary.
   </para>
   <example>
    <title>Using date_format</title>
    <programlisting>
<![CDATA[
{$startDate|date_format}
]]>
    </programlisting>
    <para>
     This will output:
    </para>
    <screen>
<![CDATA[
Jan 4, 2009
]]>
    </screen>
    <programlisting>
<![CDATA[
{$startDate|date_format:"%Y/%m/%d"}
]]>
    </programlisting>
    <para>
     This will output:
    </para>
    <screen>
<![CDATA[
2009/01/04
]]>
    </screen>
        <para>
     Dates can be compared in the template by timestamps with:
    </para>
    <programlisting>
<![CDATA[
{if $order_date < $invoice_date}
   ...do something..
{/if}
]]>
    </programlisting>
   </example>
   <para>
    When using <link linkend="language.function.html.select.date">
    <varname>{html_select_date}</varname></link> 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[
<?php

// 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>

   <para>
   See also
   <link linkend="language.function.html.select.date">
   <varname>{html_select_date}</varname></link>,
   <link linkend="language.function.html.select.time">
   <varname>{html_select_time}</varname></link>,
   <link linkend="language.modifier.date.format">
   <varname>date_format</varname></link>
   and <link linkend="language.variables.smarty.now">
   <parameter>$smarty.now</parameter></link>,
   </para>
  </sect1>

  <sect1 id="tips.wap">
   <title>WAP/WML</title>
   <para>
    WAP/WML templates require a php
    <ulink url="&url.php-manual;header">Content-Type header</ulink>
    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
    <link linkend="caching">caching</link>, that won't
    work so we'll do it using the
    <link linkend="language.function.insert"><varname>{insert}</varname></link>
    tag; remember <varname>{insert}</varname> 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;
}

?>
]]>
    </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"}

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

<!-- begin new wml deck -->
<wml>
 <!-- begin first card -->
 <card>
  <do type="accept">
   <go href="#two"/>
  </do>
  <p>
   Welcome to WAP with Smarty!
   Press OK to continue...
  </p>
 </card>
 <!-- begin second card -->
 <card id="two">
  <p>
   Pretty easy isn't it?
  </p>
 </card>
</wml>
]]>
    </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, <link linkend="api.assign"><varname>assign()</varname></link>
    the variables and <link linkend="api.display"><varname>display()</varname>
    </link> 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>
    <para>
      <filename>function.load_ticker.php</filename> -
      drop file in
      <link linkend="variable.plugins.dir">
      <parameter>$plugins directory</parameter></link>
    </para>
    <programlisting role="php">
<![CDATA[
<?php

// setup our function for fetching stock data
function fetch_ticker($symbol)
{
   // put logic here that fetches $ticker_info
   // from some ticker resource
   return $ticker_info;
}

function smarty_function_load_ticker($params, &$smarty)
{
   // call the function
   $ticker_info = fetch_ticker($params['symbol']);

   // assign template variable
   $smarty->assign($params['assign'], $ticker_info);
}
?>
]]>
    </programlisting>
        <para>
          <filename>index.tpl</filename>
    </para>
    <programlisting>
<![CDATA[
{load_ticker symbol='SMARTY' assign='ticker'}

Stock Name: {$ticker.name} Stock Price: {$ticker.price}
]]>
    </programlisting>
   </example>
   <para>
    See also
    <link linkend="language.function.include.php"><varname>{include_php}</varname></link>,
    <link linkend="language.function.include"><varname>{include}</varname></link>
    and
    <link linkend="language.function.php"><varname>{php}</varname></link>.
   </para>
  </sect1>

  <sect1 id="tips.obfuscating.email">
   <title>Obfuscating E-mail Addresses</title>
   <para>
    Do you ever wonder how your email address gets on so many spam mailing
    lists? One way spammers collect email addresses is from web pages. To
    help combat this problem, you can make your email 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
    <link linkend="language.function.mailto">
    <varname>{mailto}</varname></link> plugin.
   </para>
   <example>
    <title>Example of template the Obfuscating an email address</title>
    <programlisting>
<![CDATA[
<div id="contact">Send inquiries to
{mailto address=$EmailAddress encode='javascript' subject='Hello'}
</div>
]]>
    </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....
     hopefully..yet ...  wheres that quantum computer :-?.
    </para>
   </note>
   <para>
    See also
    <link linkend="language.modifier.escape"><varname>escape</varname></link>
    modifier and
    <link linkend="language.function.mailto"><varname>{mailto}</varname></link>.
   </para>
  </sect1>
 </chapter>

<!-- 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
indent-tabs-mode:nil
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
-->