mirror of
https://github.com/smarty-php/smarty.git
synced 2025-08-05 10:54:27 +02:00
remove this one too
This commit is contained in:
nlopess
@@ -1,518 +0,0 @@
|
|||||||
<part id="getting.started">
|
|
||||||
<title>Getting Started</title>
|
|
||||||
|
|
||||||
<chapter id="what.is.smarty">
|
|
||||||
<title>What is Smarty?</title>
|
|
||||||
<para>
|
|
||||||
Smarty is a template engine for PHP. More specifically, it facilitates a
|
|
||||||
manageable way to separate application logic and content from its
|
|
||||||
presentation. This is best described in a situation where the application
|
|
||||||
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
|
|
||||||
that is displaying a newspaper article. The article headline, tagline,
|
|
||||||
author and body are content elements, they contain no information about how
|
|
||||||
they will be presented. They are passed into Smarty by the application,
|
|
||||||
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 tables, background colors, font sizes, style sheets, etc.) One day
|
|
||||||
the programmer needs to change the way the article content is retrieved (a
|
|
||||||
change in application logic.) This change does not affect the template
|
|
||||||
designer, the content will still arrive in the template exactly the same.
|
|
||||||
Likewise, if the template designer wants to completely redesign the
|
|
||||||
templates, this requires no changes to the application logic. Therefore,
|
|
||||||
the programmer can make changes to the application logic without the need
|
|
||||||
to restructure templates, and the template designer can make changes to
|
|
||||||
templates without breaking application logic.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
One design goal of Smarty is the separation of business logic and
|
|
||||||
presentation logic. This means templates can certainly contain logic under
|
|
||||||
the condition that it is for presentation only. Things such as including
|
|
||||||
other templates, altering table row colors, upper-casing a variable,
|
|
||||||
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
|
|
||||||
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
|
|
||||||
desire NO logic in your templates you certainly can do so by boiling the
|
|
||||||
content down to text and variables only.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
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
|
|
||||||
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
|
|
||||||
full advantage of PHP compiler cache solutions such as Zend Accelerator
|
|
||||||
(http://www.zend.com) or PHP Accelerator
|
|
||||||
(http://www.php-accelerator.co.uk).
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Some of Smarty's features:
|
|
||||||
</para>
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
It is extremely fast.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
It is efficient since the PHP parser does the dirty work.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
No template parsing overhead, only compiles once.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
It is smart about recompiling only the template files that have changed.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
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
|
|
||||||
{}, {{}}, <!--{}-->, 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 id="installation">
|
|
||||||
<title>Installation</title>
|
|
||||||
|
|
||||||
<sect1 id="installation.requirements">
|
|
||||||
<title>Requirements</title>
|
|
||||||
<para>
|
|
||||||
Smarty requires a web server running PHP 4.0.6 or later.
|
|
||||||
</para>
|
|
||||||
</sect1>
|
|
||||||
|
|
||||||
<sect1 id="installing.smarty.basic">
|
|
||||||
<title>Basic Installation</title>
|
|
||||||
<para>
|
|
||||||
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
|
|
||||||
are shared among all applications and they only get updated when you
|
|
||||||
upgrade to a new version of Smarty.
|
|
||||||
</para>
|
|
||||||
<example>
|
|
||||||
<title>Smarty library files</title>
|
|
||||||
<screen>
|
|
||||||
<![CDATA[
|
|
||||||
Smarty.class.php
|
|
||||||
Smarty_Compiler.class.php
|
|
||||||
Config_File.class.php
|
|
||||||
debug.tpl
|
|
||||||
/core/*.php (all of them)
|
|
||||||
/plugins/*.php (all of them)
|
|
||||||
]]>
|
|
||||||
</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>
|
|
||||||
|
|
||||||
<example>
|
|
||||||
<title>Create Smarty instance of Smarty</title>
|
|
||||||
<programlisting role="php">
|
|
||||||
<![CDATA[
|
|
||||||
<?php
|
|
||||||
require('Smarty.class.php');
|
|
||||||
$smarty = new Smarty;
|
|
||||||
?>
|
|
||||||
]]>
|
|
||||||
</programlisting>
|
|
||||||
</example>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
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
|
|
||||||
do one of the following:
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<example>
|
|
||||||
<title>Supply absolute path to library file</title>
|
|
||||||
<programlisting role="php">
|
|
||||||
<![CDATA[
|
|
||||||
<?php
|
|
||||||
require('/usr/local/lib/php/Smarty/Smarty.class.php');
|
|
||||||
$smarty = new Smarty;
|
|
||||||
?>
|
|
||||||
]]>
|
|
||||||
</programlisting>
|
|
||||||
</example>
|
|
||||||
|
|
||||||
<example>
|
|
||||||
<title>Add library directory to php_include path</title>
|
|
||||||
<programlisting role="php">
|
|
||||||
<![CDATA[
|
|
||||||
<?php
|
|
||||||
// Edit your php.ini file, add the Smarty library
|
|
||||||
// directory to the include_path and restart web server.
|
|
||||||
// Then the following should work:
|
|
||||||
require('Smarty.class.php');
|
|
||||||
$smarty = new Smarty;
|
|
||||||
?>
|
|
||||||
]]>
|
|
||||||
</programlisting>
|
|
||||||
</example>
|
|
||||||
|
|
||||||
<example>
|
|
||||||
<title>Set SMARTY_DIR constant manually</title>
|
|
||||||
<programlisting role="php">
|
|
||||||
<![CDATA[
|
|
||||||
<?php
|
|
||||||
define('SMARTY_DIR', '/usr/local/lib/php/Smarty/');
|
|
||||||
require(SMARTY_DIR . 'Smarty.class.php');
|
|
||||||
$smarty = new Smarty;
|
|
||||||
?>
|
|
||||||
]]>
|
|
||||||
</programlisting>
|
|
||||||
</example>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Now that the library files are in place, it's time to setup the Smarty
|
|
||||||
directories for your application. Smarty requires four directories which
|
|
||||||
are (by default) named <emphasis>templates</emphasis>,
|
|
||||||
<emphasis>templates_c</emphasis>, <emphasis>configs</emphasis> and
|
|
||||||
<emphasis>cache</emphasis>. Each of these are definable by the Smarty class
|
|
||||||
properties <emphasis>$template_dir</emphasis>,
|
|
||||||
<emphasis>$compile_dir</emphasis>, <emphasis>$config_dir</emphasis>, and
|
|
||||||
<emphasis>$cache_dir</emphasis> respectively. It is highly recommended
|
|
||||||
that you setup a separate set of these directories for each application
|
|
||||||
that will use Smarty.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
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
|
|
||||||
directories are only accessed by the Smarty library and never accessed
|
|
||||||
directly by the web browser. Therefore to avoid any security concerns, it
|
|
||||||
is recommended to place these directories <emphasis>outside</emphasis> of
|
|
||||||
the document root.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
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
|
|
||||||
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
|
|
||||||
place our Smarty directories under
|
|
||||||
"/web/www.mydomain.com/smarty/guestbook/".
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
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",
|
|
||||||
and place it in a subdirectory under the document root called
|
|
||||||
"/guestbook/".
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<note>
|
|
||||||
<title>Technical Note</title>
|
|
||||||
<para>
|
|
||||||
It is convenient to setup the web server so that "index.php" can be
|
|
||||||
identified as the default directory index, so if you access
|
|
||||||
"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
|
|
||||||
"index.php" onto the end of your DirectoryIndex setting (separate each
|
|
||||||
entry with a space.)
|
|
||||||
</para>
|
|
||||||
</note>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Lets take a look at the file structure so far:
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<example>
|
|
||||||
<title>Example file structure</title>
|
|
||||||
<screen>
|
|
||||||
<![CDATA[
|
|
||||||
/usr/local/lib/php/Smarty/Smarty.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/debug.tpl
|
|
||||||
/usr/local/lib/php/Smarty/core/*.php
|
|
||||||
/usr/local/lib/php/Smarty/plugins/*.php
|
|
||||||
|
|
||||||
/web/www.mydomain.com/smarty/guestbook/templates/
|
|
||||||
/web/www.mydomain.com/smarty/guestbook/templates_c/
|
|
||||||
/web/www.mydomain.com/smarty/guestbook/configs/
|
|
||||||
/web/www.mydomain.com/smarty/guestbook/cache/
|
|
||||||
|
|
||||||
/web/www.mydomain.com/docs/guestbook/index.php
|
|
||||||
]]>
|
|
||||||
</screen>
|
|
||||||
</example>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
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
|
|
||||||
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
|
|
||||||
look in your httpd.conf file (usually in "/usr/local/apache/conf/") to see
|
|
||||||
what user and group are being used.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<example>
|
|
||||||
<title>Setting file permissions</title>
|
|
||||||
<programlisting role="shell">
|
|
||||||
<![CDATA[
|
|
||||||
chown nobody:nobody /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/
|
|
||||||
chmod 770 /web/www.mydomain.com/smarty/guestbook/cache/
|
|
||||||
]]>
|
|
||||||
</programlisting>
|
|
||||||
</example>
|
|
||||||
|
|
||||||
<note>
|
|
||||||
<title>Technical Note</title>
|
|
||||||
<para>
|
|
||||||
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
|
|
||||||
open up read access to anyone (mostly for your own convenience of viewing
|
|
||||||
these files), you can use 775 instead.
|
|
||||||
</para>
|
|
||||||
</note>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
We need to create the index.tpl file that Smarty will load. This will be
|
|
||||||
located in your $template_dir.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<example>
|
|
||||||
<title>Editing /web/www.mydomain.com/smarty/guestbook/templates/index.tpl</title>
|
|
||||||
<screen>
|
|
||||||
<![CDATA[
|
|
||||||
|
|
||||||
{* Smarty *}
|
|
||||||
|
|
||||||
Hello, {$name}!
|
|
||||||
]]>
|
|
||||||
</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>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Now lets edit index.php. We'll create an instance of Smarty, assign a
|
|
||||||
template variable and display the index.tpl file. In our example
|
|
||||||
environment, "/usr/local/lib/php/Smarty" is in our include_path. Be sure you
|
|
||||||
do the same, or use absolute paths.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<example>
|
|
||||||
<title>Editing /web/www.mydomain.com/docs/guestbook/index.php</title>
|
|
||||||
<programlisting role="php">
|
|
||||||
<![CDATA[
|
|
||||||
<?php
|
|
||||||
|
|
||||||
// load Smarty library
|
|
||||||
require('Smarty.class.php');
|
|
||||||
|
|
||||||
$smarty = new Smarty;
|
|
||||||
|
|
||||||
$smarty->template_dir = '/web/www.mydomain.com/smarty/guestbook/templates/';
|
|
||||||
$smarty->compile_dir = '/web/www.mydomain.com/smarty/guestbook/templates_c/';
|
|
||||||
$smarty->config_dir = '/web/www.mydomain.com/smarty/guestbook/configs/';
|
|
||||||
$smarty->cache_dir = '/web/www.mydomain.com/smarty/guestbook/cache/';
|
|
||||||
|
|
||||||
$smarty->assign('name','Ned');
|
|
||||||
|
|
||||||
$smarty->display('index.tpl');
|
|
||||||
?>
|
|
||||||
]]>
|
|
||||||
</programlisting>
|
|
||||||
</example>
|
|
||||||
|
|
||||||
<note>
|
|
||||||
<title>Technical Note</title>
|
|
||||||
<para>
|
|
||||||
In our example, we are setting absolute paths to all of the Smarty
|
|
||||||
directories. If '/web/www.mydomain.com/smarty/guestbook/' is within your
|
|
||||||
PHP include_path, then these settings are not necessary. However, it is
|
|
||||||
more efficient and (from experience) less error-prone to set them to
|
|
||||||
absolute paths. This ensures that Smarty is getting files from the
|
|
||||||
directories you intended.
|
|
||||||
</para>
|
|
||||||
</note>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Now load the index.php file from your web browser. You should see "Hello,
|
|
||||||
Ned!"
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
You have completed the basic setup for Smarty!
|
|
||||||
</para>
|
|
||||||
</sect1>
|
|
||||||
<sect1 id="installing.smarty.extended">
|
|
||||||
<title>Extended Setup</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
This is a continuation of the <link
|
|
||||||
linkend="installing.smarty.basic">basic installation</link>, please read
|
|
||||||
that first!
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
A slightly more flexible way to setup Smarty is to extend the class and
|
|
||||||
initialize your Smarty environment. So instead of repeatedly setting
|
|
||||||
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
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<example>
|
|
||||||
<title>Editing /php/includes/guestbook/setup.php</title>
|
|
||||||
<programlisting role="php">
|
|
||||||
<![CDATA[
|
|
||||||
<?php
|
|
||||||
|
|
||||||
// load Smarty library
|
|
||||||
require('Smarty.class.php');
|
|
||||||
|
|
||||||
// The setup.php file is a good place to load
|
|
||||||
// required application library files, and you
|
|
||||||
// can do that right here. An example:
|
|
||||||
// require('guestbook/guestbook.lib.php');
|
|
||||||
|
|
||||||
class Smarty_GuestBook extends Smarty {
|
|
||||||
|
|
||||||
function Smarty_GuestBook() {
|
|
||||||
|
|
||||||
// Class Constructor. These automatically get set with each new instance.
|
|
||||||
|
|
||||||
$this->Smarty();
|
|
||||||
|
|
||||||
$this->template_dir = '/web/www.mydomain.com/smarty/guestbook/templates/';
|
|
||||||
$this->compile_dir = '/web/www.mydomain.com/smarty/guestbook/templates_c/';
|
|
||||||
$this->config_dir = '/web/www.mydomain.com/smarty/guestbook/configs/';
|
|
||||||
$this->cache_dir = '/web/www.mydomain.com/smarty/guestbook/cache/';
|
|
||||||
|
|
||||||
$this->caching = true;
|
|
||||||
$this->assign('app_name','Guest Book');
|
|
||||||
}
|
|
||||||
|
|
||||||
}
|
|
||||||
?>
|
|
||||||
]]>
|
|
||||||
</programlisting>
|
|
||||||
</example>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Now lets alter the index.php file to use setup.php:
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<example>
|
|
||||||
<title>Editing /web/www.mydomain.com/docs/guestbook/index.php</title>
|
|
||||||
<programlisting role="php">
|
|
||||||
<![CDATA[
|
|
||||||
<?php
|
|
||||||
|
|
||||||
require('guestbook/setup.php');
|
|
||||||
|
|
||||||
$smarty = new Smarty_GuestBook;
|
|
||||||
|
|
||||||
$smarty->assign('name','Ned');
|
|
||||||
|
|
||||||
$smarty->display('index.tpl');
|
|
||||||
?>
|
|
||||||
]]>
|
|
||||||
</programlisting>
|
|
||||||
</example>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
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.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
</sect1>
|
|
||||||
|
|
||||||
</chapter>
|
|
||||||
</part>
|
|
||||||
|
|
||||||
<!-- 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
|
|
||||||
-->
|
|
||||||
Reference in New Issue
Block a user