mirror of
https://github.com/smarty-php/smarty.git
synced 2025-10-04 08:10:55 +02:00
9d4d0c08a1
- domain.com => example.com, as suggested by RFC 2606 - fix and introduce more dockbook tags - fix white spaces and use CDATA sections - add some paras to make the text more reader friendly
368 lines
9.6 KiB
XML
368 lines
9.6 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision$ -->
|
|
<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 "&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 &nbsp; when a variable is empty</title>
|
|
<programlisting>
|
|
<![CDATA[
|
|
{* the long way *}
|
|
|
|
{if $title eq ""}
|
|
|
|
{else}
|
|
{$title}
|
|
{/if}
|
|
|
|
|
|
{* the short way *}
|
|
|
|
{$title|default:" "}
|
|
]]>
|
|
</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>
|
|
<![CDATA[
|
|
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
|
|
----------
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>{$title|default:"BC News"}</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
|
|
|
|
footer.tpl
|
|
----------
|
|
</BODY>
|
|
</HTML>
|
|
]]>
|
|
</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>
|
|
<note>
|
|
<para>
|
|
As of Smarty 1.4.0, you can pass dates to Smarty as unix
|
|
timestamps, mysql timestamps, or any date parsable by strtotime().
|
|
</para>
|
|
</note>
|
|
<example>
|
|
<title>using date_format</title>
|
|
<programlisting>
|
|
<![CDATA[
|
|
{$startDate|date_format}
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
This will output:
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
Jan 4, 2001
|
|
]]>
|
|
</screen>
|
|
<programlisting>
|
|
<![CDATA[
|
|
{$startDate|date_format:"%Y/%m/%d"}
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
This will output:
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
2001/01/04
|
|
]]>
|
|
</screen>
|
|
<programlisting>
|
|
<![CDATA[
|
|
{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 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>
|
|
</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;
|
|
}
|
|
|
|
?>
|
|
]]>
|
|
</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, 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
|
|
|
|
// drop file "function.load_ticker.php" in plugin directory
|
|
|
|
// 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>
|
|
<programlisting>
|
|
<![CDATA[
|
|
{* in index.tpl *}
|
|
|
|
{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>
|
|
<![CDATA[
|
|
{* in 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>
|
|
<!-- 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
|
|
-->
|