smarty-php/smarty
1
0
Fork 0
mirror of https://github.com/smarty-php/smarty.git synced 2025-08-05 10:54:27 +02:00
Code Issues Packages Projects Releases Wiki Activity

cleaning words spacing, killing tabulations, using roles for programlisting..

Browse Source
This commit is contained in:
didou
2004-03-16 14:56:14 +00:00
parent 4c16d2b4d2
commit 40ed088eff
2 changed files with 656 additions and 528 deletions
Download Patch File Download Diff File Expand all files Collapse all files

523
docs/appendixes.sgml
View File

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

651
docs/getting-started.sgml
View File

@@ -2,76 +2,126 @@
<title>Getting Started</title> <title>Getting Started</title>
<chapter id="what.is.smarty"> <chapter id="what.is.smarty">
<title>What is Smarty?</title> <title>What is Smarty?</title>
<para> <para>
Smarty is a template engine for PHP. More specifically, it facilitates a Smarty is a template engine for PHP. More specifically, it facilitates a
manageable way to separate application logic and content from its manageable way to separate application logic and content from its
presentation. This is best described in a situation where the application presentation. This is best described in a situation where the application
programmer and the template designer play different roles, or in most cases programmer and the template designer play different roles, or in most cases
are not the same person. For example, let's say you are creating a web page are not the same person. For example, let's say you are creating a web page
that is displaying a newspaper article. The article headline, tagline, that is displaying a newspaper article. The article headline, tagline,
author and body are content elements, they contain no information about how author and body are content elements, they contain no information about how
they will be presented. They are passed into Smarty by the application, they will be presented. They are passed into Smarty by the application,
then the template designer edits the templates and uses a combination of then the template designer edits the templates and uses a combination of
HTML tags and template tags to format the presentation of these elements HTML tags and template tags to format the presentation of these elements
(HTML tables, background colors, font sizes, style sheets, etc.) One day (HTML tables, background colors, font sizes, style sheets, etc.) One day
the programmer needs to change the way the article content is retrieved (a the programmer needs to change the way the article content is retrieved (a
change in application logic.) This change does not affect the template change in application logic.) This change does not affect the template
designer, the content will still arrive in the template exactly the same. designer, the content will still arrive in the template exactly the same.
Likewise, if the template designer wants to completely redesign the Likewise, if the template designer wants to completely redesign the
templates, this requires no changes to the application logic. Therefore, templates, this requires no changes to the application logic. Therefore,
the programmer can make changes to the application logic without the need the programmer can make changes to the application logic without the need
to restructure templates, and the template designer can make changes to to restructure templates, and the template designer can make changes to
templates without breaking application logic. templates without breaking application logic.
</para> </para>
<para> <para>
One design goal of Smarty is the separation of business logic and One design goal of Smarty is the separation of business logic and
presentation logic. This means templates can certainly contain logic under presentation logic. This means templates can certainly contain logic under
the condition that it is for presentation only. Things such as including the condition that it is for presentation only. Things such as including
other templates, altering table row colors, upper-casing a variable, other templates, altering table row colors, upper-casing a variable,
looping over an array of data and displaying it, etc. are all examples of looping over an array of data and displaying it, etc. are all examples of
presentation logic. This does not mean that Smarty forces a separation of presentation logic. This does not mean that Smarty forces a separation of
business and presentation logic. Smarty has no knowledge of which is which, business and presentation logic. Smarty has no knowledge of which is which,
so placing business logic in the template is your own doing. Also, if you so placing business logic in the template is your own doing. Also, if you
desire NO logic in your templates you certainly can do so by boiling the desire NO logic in your templates you certainly can do so by boiling the
content down to text and variables only. content down to text and variables only.
</para> </para>
<para> <para>
One of the unique aspects about Smarty is the template compling. This means One of the unique aspects about Smarty is the template compling. This means
Smarty reads the template files and creates PHP scripts from them. Once Smarty reads the template files and creates PHP scripts from them. Once
they are created, they are executed from then on. Therefore there is no they are created, they are executed from then on. Therefore there is no
costly template file parsing for each request, and each template can take costly template file parsing for each request, and each template can take
full advantage of PHP compiler cache solutions such as Zend Accelerator full advantage of PHP compiler cache solutions such as Zend Accelerator
(http://www.zend.com) or PHP Accelerator (http://www.zend.com) or PHP Accelerator
(http://www.php-accelerator.co.uk). (http://www.php-accelerator.co.uk).
</para> </para>
<para> <para>
Some of Smarty's features: Some of Smarty's features:
</para> </para>
<itemizedlist> <itemizedlist>
<listitem><para>It is extremely fast.</para></listitem> <listitem>
<listitem><para>It is efficient since the PHP parser does the <para>
dirty work.</para></listitem> It is extremely fast.
<listitem><para>No template parsing overhead, only compiles once.</para></listitem> </para>
<listitem><para>It is smart about recompiling only the template </listitem>
files that have changed.</para></listitem> <listitem>
<listitem><para>You can make <link linkend="language.custom.functions">custom <para>
functions</link> and custom <link linkend="language.modifiers">variable It is efficient since the PHP parser does the dirty work.
modifiers</link>, so the template language is extremely extensible.</para></listitem> </para>
<listitem><para>Configurable template delimiter tag syntax, so you can use </listitem>
{}, {{}}, &lt;!--{}--&gt;, etc.</para></listitem> <listitem>
<listitem><para>The if/elseif/else/endif constructs are passed to the <para>
PHP parser, so the {if ...} expression syntax can be as simple or as complex No template parsing overhead, only compiles once.
as you like.</para></listitem> </para>
<listitem><para>Unlimited nesting of sections, ifs, etc. allowed.</para></listitem> </listitem>
<listitem><para>It is possible to embed PHP code right in your template files, <listitem>
although this may not be needed (nor recommended) <para>
since the engine is so customizable.</para></listitem> It is smart about recompiling only the template files that have changed.
<listitem><para>Built-in caching support</para></listitem> </para>
<listitem><para>Arbitrary template sources</para></listitem> </listitem>
<listitem><para>Custom cache handling functions</para></listitem> <listitem>
<listitem><para>Plugin architecture</para></listitem> <para>
</itemizedlist> You can make <link linkend="language.custom.functions">custom functions</link>
and custom <link linkend="language.modifiers">variable modifiers</link>, so the
template language is extremely extensible.
</para>
</listitem>
<listitem>
<para>
Configurable template delimiter tag syntax, so you can use
{}, {{}}, &lt;!--{}--&gt;, etc.
</para>
</listitem>
<listitem>
<para>
The if/elseif/else/endif constructs are passed to the
PHP parser, so the {if ...} expression syntax can be as simple or as complex
as you like.
</para>
</listitem>
<listitem>
<para>
Unlimited nesting of sections, ifs, etc. allowed.
</para>
</listitem>
<listitem>
<para>
It is possible to embed PHP code right in your template files,
although this may not be needed (nor recommended)
since the engine is so customizable.
</para>
</listitem>
<listitem>
<para>
Built-in caching support
</para>
</listitem>
<listitem>
<para>
Arbitrary template sources
</para>
</listitem>
<listitem>
<para>
Custom cache handling functions
</para>
</listitem>
<listitem>
<para>
Plugin architecture
</para>
</listitem>
</itemizedlist>
</chapter> </chapter>
<chapter id="installation"> <chapter id="installation">
<title>Installation</title> <title>Installation</title>
@@ -79,136 +129,159 @@
<sect1 id="installation.requirements"> <sect1 id="installation.requirements">
<title>Requirements</title> <title>Requirements</title>
<para> <para>
Smarty requires a web server running PHP 4.0.6 or later. Smarty requires a web server running PHP 4.0.6 or later.
</para> </para>
</sect1> </sect1>
<sect1 id="installing.smarty.basic"> <sect1 id="installing.smarty.basic">
<title>Basic Installation</title> <title>Basic Installation</title>
<para> <para>
Install the Smarty library files which are in the /libs/ directory of Install the Smarty library files which are in the /libs/ directory of
the distribution. These are the PHP files that you SHOULD NOT edit. They the distribution. These are the PHP files that you SHOULD NOT edit. They
are shared among all applications and they only get updated when you are shared among all applications and they only get updated when you
upgrade to a new version of Smarty. upgrade to a new version of Smarty.
</para> </para>
<example> <example>
<title>Smarty library files</title> <title>Smarty library files</title>
<screen> <screen>
<![CDATA[
Smarty.class.php Smarty.class.php
Smarty_Compiler.class.php Smarty_Compiler.class.php
Config_File.class.php Config_File.class.php
debug.tpl debug.tpl
/core/*.php (all of them) /core/*.php (all of them)
/plugins/*.php (all of them)</screen> /plugins/*.php (all of them)
</example> ]]>
</screen>
</example>
<para>
Smarty uses a PHP constant named <link
linkend="constant.smarty.dir">SMARTY_DIR</link> which is the system
filepath Smarty library directory. Basically, if your application can find
the <emphasis>Smarty.class.php</emphasis> file, you do not need to set
SMARTY_DIR, Smarty will figure it out on its own. Therefore, if
<emphasis>Smarty.class.php</emphasis> is not in your include_path, or you
do not supply an absolute path to it in your application, then you must
define SMARTY_DIR manually. SMARTY_DIR <emphasis>must</emphasis> include a
trailing slash.
</para>
<para>
Here is how you create an instance of Smarty in your PHP scripts:
</para>
<para> <example>
Smarty uses a PHP constant named <link <title>Create Smarty instance of Smarty</title>
linkend="constant.smarty.dir">SMARTY_DIR</link> which is the system <programlisting role="php">
filepath Smarty library directory. Basically, if your application can find <![CDATA[
the <emphasis>Smarty.class.php</emphasis> file, you do not need to set <?php
SMARTY_DIR, Smarty will figure it out on its own. Therefore, if
<emphasis>Smarty.class.php</emphasis> is not in your include_path, or you
do not supply an absolute path to it in your application, then you must
define SMARTY_DIR manually. SMARTY_DIR <emphasis>must</emphasis> include a
trailing slash.
</para>
<para>
Here is how you create an instance of Smarty in your PHP scripts:
</para>
<example>
<title>Create Smarty instance of Smarty</title>
<screen>
require('Smarty.class.php'); require('Smarty.class.php');
$smarty = new Smarty;</screen> $smarty = new Smarty;
</example> ?>
]]>
</programlisting>
</example>
<para> <para>
Try running the above script. If you get an error saying the Try running the above script. If you get an error saying the
<emphasis>Smarty.class.php</emphasis> file could not be found, you have to <emphasis>Smarty.class.php</emphasis> file could not be found, you have to
do one of the following: do one of the following:
</para> </para>
<example> <example>
<title>Supply absolute path to library file</title> <title>Supply absolute path to library file</title>
<screen> <programlisting role="php">
<![CDATA[
<?php
require('/usr/local/lib/php/Smarty/Smarty.class.php'); require('/usr/local/lib/php/Smarty/Smarty.class.php');
$smarty = new Smarty;</screen> $smarty = new Smarty;
</example> ?>
]]>
</programlisting>
</example>
<example> <example>
<title>Add library directory to php_include path</title> <title>Add library directory to php_include path</title>
<screen> <programlisting role="php">
<![CDATA[
<?php
// Edit your php.ini file, add the Smarty library // Edit your php.ini file, add the Smarty library
// directory to the include_path and restart web server. // directory to the include_path and restart web server.
// Then the following should work: // Then the following should work:
require('Smarty.class.php'); require('Smarty.class.php');
$smarty = new Smarty;</screen> $smarty = new Smarty;
</example> ?>
]]>
</programlisting>
</example>
<example> <example>
<title>Set SMARTY_DIR constant manually</title> <title>Set SMARTY_DIR constant manually</title>
<screen> <programlisting role="php">
define('SMARTY_DIR','/usr/local/lib/php/Smarty/'); <![CDATA[
require(SMARTY_DIR.'Smarty.class.php'); <?php
$smarty = new Smarty;</screen> define('SMARTY_DIR', '/usr/local/lib/php/Smarty/');
</example> require(SMARTY_DIR . 'Smarty.class.php');
$smarty = new Smarty;
?>
]]>
</programlisting>
</example>
<para> <para>
Now that the library files are in place, it's time to setup the Smarty Now that the library files are in place, it's time to setup the Smarty
directories for your application. Smarty requires four directories which directories for your application. Smarty requires four directories which
are (by default) named <emphasis>templates</emphasis>, are (by default) named <emphasis>templates</emphasis>,
<emphasis>templates_c</emphasis>, <emphasis>configs</emphasis> and <emphasis>templates_c</emphasis>, <emphasis>configs</emphasis> and
<emphasis>cache</emphasis>. Each of these are definable by the Smarty class <emphasis>cache</emphasis>. Each of these are definable by the Smarty class
properties <emphasis>$template_dir</emphasis>, properties <emphasis>$template_dir</emphasis>,
<emphasis>$compile_dir</emphasis>, <emphasis>$config_dir</emphasis>, and <emphasis>$compile_dir</emphasis>, <emphasis>$config_dir</emphasis>, and
<emphasis>$cache_dir</emphasis> respectively. It is highly recommended <emphasis>$cache_dir</emphasis> respectively. It is highly recommended
that you setup a separate set of these directories for each application that you setup a separate set of these directories for each application
that will use Smarty. that will use Smarty.
</para> </para>
<para> <para>
Be sure you know the location of your web server document root. In our Be sure you know the location of your web server document root. In our
example, the document root is "/web/www.mydomain.com/docs/". The Smarty example, the document root is "/web/www.mydomain.com/docs/". The Smarty
directories are only accessed by the Smarty library and never accessed directories are only accessed by the Smarty library and never accessed
directly by the web browser. Therefore to avoid any security concerns, it directly by the web browser. Therefore to avoid any security concerns, it
is recommended to place these directories <emphasis>outside</emphasis> of is recommended to place these directories <emphasis>outside</emphasis> of
the document root. the document root.
</para> </para>
<para> <para>
For our installation example, we will be setting up the Smarty environment For our installation example, we will be setting up the Smarty environment
for a guest book application. We picked an application only for the purpose for a guest book application. We picked an application only for the purpose
of a directory naming convention. You can use the same environment for any of a directory naming convention. You can use the same environment for any
application, just replace "guestbook" with the name of your app. We'll application, just replace "guestbook" with the name of your app. We'll
place our Smarty directories under place our Smarty directories under
"/web/www.mydomain.com/smarty/guestbook/". "/web/www.mydomain.com/smarty/guestbook/".
</para> </para>
<para> <para>
You will need as least one file under your document root, and that is the You will need as least one file under your document root, and that is the
script accessed by the web browser. We will call our script "index.php", script accessed by the web browser. We will call our script "index.php",
and place it in a subdirectory under the document root called and place it in a subdirectory under the document root called
"/guestbook/". "/guestbook/".
</para> </para>
<note> <note>
<title>Technical Note</title> <title>Technical Note</title>
<para> <para>
It is convenient to setup the web server so that "index.php" can be It is convenient to setup the web server so that "index.php" can be
identified as the default directory index, so if you access identified as the default directory index, so if you access
"http://www.mydomain.com/guestbook/", the index.php script will be executed "http://www.mydomain.com/guestbook/", the index.php script will be executed
without "index.php" in the URL. In Apache you can set this up by adding without "index.php" in the URL. In Apache you can set this up by adding
"index.php" onto the end of your DirectoryIndex setting (separate each "index.php" onto the end of your DirectoryIndex setting (separate each
entry with a space.) entry with a space.)
</para> </para>
</note> </note>
<para> <para>
Lets take a look at the file structure so far: Lets take a look at the file structure so far:
</para> </para>
<example> <example>
<title>Example file structure</title> <title>Example file structure</title>
<screen> <screen>
<![CDATA[
/usr/local/lib/php/Smarty/Smarty.class.php /usr/local/lib/php/Smarty/Smarty.class.php
/usr/local/lib/php/Smarty/Smarty_Compiler.class.php /usr/local/lib/php/Smarty/Smarty_Compiler.class.php
/usr/local/lib/php/Smarty/Config_File.class.php /usr/local/lib/php/Smarty/Config_File.class.php
@@ -221,75 +294,84 @@ $smarty = new Smarty;</screen>
/web/www.mydomain.com/smarty/guestbook/configs/ /web/www.mydomain.com/smarty/guestbook/configs/
/web/www.mydomain.com/smarty/guestbook/cache/ /web/www.mydomain.com/smarty/guestbook/cache/
/web/www.mydomain.com/docs/guestbook/index.php</screen> /web/www.mydomain.com/docs/guestbook/index.php
</example> ]]>
</screen>
</example>
<para> <para>
Smarty will need write access to the <emphasis>$compile_dir</emphasis> and Smarty will need write access to the <emphasis>$compile_dir</emphasis> and
<emphasis>$cache_dir</emphasis>, so be sure the web server user can write <emphasis>$cache_dir</emphasis>, so be sure the web server user can write
to them. This is usually user "nobody" and group "nobody". For OS X users, to them. This is usually user "nobody" and group "nobody". For OS X users,
the default is user "www" and group "www". If you are using Apache, you can the default is user "www" and group "www". If you are using Apache, you can
look in your httpd.conf file (usually in "/usr/local/apache/conf/") to see look in your httpd.conf file (usually in "/usr/local/apache/conf/") to see
what user and group are being used. what user and group are being used.
</para> </para>
<example>
<title>Setting file permissions</title>
<screen>
<example>
<title>Setting file permissions</title>
<programlisting role="shell">
<![CDATA[
chown nobody:nobody /web/www.mydomain.com/smarty/guestbook/templates_c/ chown nobody:nobody /web/www.mydomain.com/smarty/guestbook/templates_c/
chmod 770 /web/www.mydomain.com/smarty/guestbook/templates_c/ chmod 770 /web/www.mydomain.com/smarty/guestbook/templates_c/
chown nobody:nobody /web/www.mydomain.com/smarty/guestbook/cache/ chown nobody:nobody /web/www.mydomain.com/smarty/guestbook/cache/
chmod 770 /web/www.mydomain.com/smarty/guestbook/cache/</screen> chmod 770 /web/www.mydomain.com/smarty/guestbook/cache/
</example> ]]>
</programlisting>
</example>
<note> <note>
<title>Technical Note</title> <title>Technical Note</title>
<para> <para>
chmod 770 will be fairly tight security, it only allows user "nobody" and chmod 770 will be fairly tight security, it only allows user "nobody" and
group "nobody" read/write access to the directories. If you would like to group "nobody" read/write access to the directories. If you would like to
open up read access to anyone (mostly for your own convenience of viewing open up read access to anyone (mostly for your own convenience of viewing
these files), you can use 775 instead. these files), you can use 775 instead.
</para> </para>
</note> </note>
<para> <para>
We need to create the index.tpl file that Smarty will load. This will be We need to create the index.tpl file that Smarty will load. This will be
located in your $template_dir. located in your $template_dir.
</para> </para>
<example> <example>
<title>Editing /web/www.mydomain.com/smarty/guestbook/templates/index.tpl</title> <title>Editing /web/www.mydomain.com/smarty/guestbook/templates/index.tpl</title>
<screen> <screen>
<![CDATA[
{* Smarty *} {* Smarty *}
Hello, {$name}!</screen> Hello, {$name}!
</example> ]]>
</screen>
</example>
<note>
<title>Technical Note</title>
<para>
{* Smarty *} is a template comment. It is not required, but it is good
practice to start all your template files with this comment. It makes
the file easy to recognize regardless of the file extension. For
example, text editors could recognize the file and turn on special
syntax highlighting.
</para>
</note>
<note> <para>
<title>Technical Note</title> Now lets edit index.php. We'll create an instance of Smarty, assign a
<para> template variable and display the index.tpl file. In our example
{* Smarty *} is a template comment. It is not required, but it is good environment, "/usr/local/lib/php/Smarty" is in our include_path. Be sure you
practice to start all your template files with this comment. It makes do the same, or use absolute paths.
the file easy to recognize regardless of the file extension. For </para>
example, text editors could recognize the file and turn on special
syntax highlighting.
</para>
</note>
<para> <example>
Now lets edit index.php. We'll create an instance of Smarty, assign a <title>Editing /web/www.mydomain.com/docs/guestbook/index.php</title>
template variable and display the index.tpl file. In our example <programlisting role="php">
environment, "/usr/local/lib/php/Smarty" is in our include_path. Be sure you <![CDATA[
do the same, or use absolute paths. <?php
</para>
<example>
<title>Editing /web/www.mydomain.com/docs/guestbook/index.php</title>
<screen>
// load Smarty library // load Smarty library
require('Smarty.class.php'); require('Smarty.class.php');
@@ -302,49 +384,54 @@ $smarty->cache_dir = '/web/www.mydomain.com/smarty/guestbook/cache/';
$smarty->assign('name','Ned'); $smarty->assign('name','Ned');
$smarty->display('index.tpl');</screen> $smarty->display('index.tpl');
</example> ?>
]]>
</programlisting>
</example>
<note> <note>
<title>Technical Note</title> <title>Technical Note</title>
<para> <para>
In our example, we are setting absolute paths to all of the Smarty In our example, we are setting absolute paths to all of the Smarty
directories. If '/web/www.mydomain.com/smarty/guestbook/' is within your directories. If '/web/www.mydomain.com/smarty/guestbook/' is within your
PHP include_path, then these settings are not necessary. However, it is PHP include_path, then these settings are not necessary. However, it is
more efficient and (from experience) less error-prone to set them to more efficient and (from experience) less error-prone to set them to
absolute paths. This ensures that Smarty is getting files from the absolute paths. This ensures that Smarty is getting files from the
directories you intended. directories you intended.
</para> </para>
</note> </note>
<para> <para>
Now load the index.php file from your web browser. You should see "Hello, Now load the index.php file from your web browser. You should see "Hello,
Ned!" Ned!"
</para> </para>
<para> <para>
You have completed the basic setup for Smarty! You have completed the basic setup for Smarty!
</para> </para>
</sect1> </sect1>
<sect1 id="installing.smarty.extended"> <sect1 id="installing.smarty.extended">
<title>Extended Setup</title> <title>Extended Setup</title>
<para> <para>
This is a continuation of the <link This is a continuation of the <link
linkend="installing.smarty.basic">basic installation</link>, please read linkend="installing.smarty.basic">basic installation</link>, please read
that first! that first!
</para> </para>
<para> <para>
A slightly more flexible way to setup Smarty is to extend the class and A slightly more flexible way to setup Smarty is to extend the class and
initialize your Smarty environment. So instead of repeatedly setting initialize your Smarty environment. So instead of repeatedly setting
directory paths, assigning the same vars, etc., we can do that in one place. directory paths, assigning the same vars, etc., we can do that in one place.
Lets create a new directory "/php/includes/guestbook/" and make a new file Lets create a new directory "/php/includes/guestbook/" and make a new file
called "setup.php". In our example environment, "/php/includes" is in our called "setup.php". In our example environment, "/php/includes" is in our
include_path. Be sure you set this up too, or use absolute file paths. include_path. Be sure you set this up too, or use absolute file paths.
</para> </para>
<example> <example>
<title>Editing /php/includes/guestbook/setup.php</title> <title>Editing /php/includes/guestbook/setup.php</title>
<screen> <programlisting role="php">
<![CDATA[
<?php
// load Smarty library // load Smarty library
require('Smarty.class.php'); require('Smarty.class.php');
@@ -358,29 +445,34 @@ class Smarty_GuestBook extends Smarty {
function Smarty_GuestBook() { function Smarty_GuestBook() {
// Class Constructor. These automatically get set with each new instance. // Class Constructor. These automatically get set with each new instance.
$this->Smarty(); $this->Smarty();
$this->template_dir = '/web/www.mydomain.com/smarty/guestbook/templates/'; $this->template_dir = '/web/www.mydomain.com/smarty/guestbook/templates/';
$this->compile_dir = '/web/www.mydomain.com/smarty/guestbook/templates_c/'; $this->compile_dir = '/web/www.mydomain.com/smarty/guestbook/templates_c/';
$this->config_dir = '/web/www.mydomain.com/smarty/guestbook/configs/'; $this->config_dir = '/web/www.mydomain.com/smarty/guestbook/configs/';
$this->cache_dir = '/web/www.mydomain.com/smarty/guestbook/cache/'; $this->cache_dir = '/web/www.mydomain.com/smarty/guestbook/cache/';
$this->caching = true; $this->caching = true;
$this->assign('app_name','Guest Book'); $this->assign('app_name','Guest Book');
} }
}</screen> }
?>
]]>
</programlisting>
</example> </example>
<para> <para>
Now lets alter the index.php file to use setup.php: Now lets alter the index.php file to use setup.php:
</para> </para>
<example> <example>
<title>Editing /web/www.mydomain.com/docs/guestbook/index.php</title> <title>Editing /web/www.mydomain.com/docs/guestbook/index.php</title>
<screen> <programlisting role="php">
<![CDATA[
<?php
require('guestbook/setup.php'); require('guestbook/setup.php');
@@ -388,12 +480,15 @@ $smarty = new Smarty_GuestBook;
$smarty->assign('name','Ned'); $smarty->assign('name','Ned');
$smarty->display('index.tpl');</screen> $smarty->display('index.tpl');
</example> ?>
]]>
</programlisting>
</example>
<para> <para>
Now you see it is quite simple to bring up an instance of Smarty, just use Now you see it is quite simple to bring up an instance of Smarty, just use
Smarty_GuestBook which automatically initializes everything for our application. Smarty_GuestBook which automatically initializes everything for our application.
</para> </para>
</sect1> </sect1>