mirror of
https://github.com/smarty-php/smarty.git
synced 2025-11-03 22:01:36 +01:00
390 lines
14 KiB
Plaintext
390 lines
14 KiB
Plaintext
<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>
|
|
Now for a short word on what Smarty does NOT do. Smarty does not attempt to
|
|
completely separate logic from the templates. There is no problem with
|
|
logic in your templates under the condition that this logic is strictly for
|
|
presentation. A word of advice: keep application logic out of the
|
|
templates, and presentation logic out of the application. This will most
|
|
definately keep things manageable and scalable for the foreseeable future.
|
|
</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>
|
|
Smarty.class.php
|
|
Smarty_Compiler.class.php
|
|
Config_File.class.php
|
|
debug.tpl
|
|
/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>
|
|
<screen>
|
|
require('Smarty.class.php');
|
|
$smarty = new Smarty;</screen>
|
|
</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 directory</title>
|
|
<screen>
|
|
require('/usr/local/lib/php/Smarty/Smarty.class.php');
|
|
$smarty = new Smarty;</screen>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Add library directory to php_include path</title>
|
|
<screen>
|
|
// 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;</screen>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Set SMARTY_DIR constant manually</title>
|
|
<screen>
|
|
define('SMARTY_DIR','/usr/local/lib/php/Smarty/');
|
|
require(SMARTY_DIR.'Smarty.class.php');
|
|
$smarty = new Smarty;</screen>
|
|
</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 in a directory
|
|
<emphasis>off</emphasis> 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/". 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>
|
|
|
|
<para>
|
|
Lets take a look at the file structure so far:
|
|
</para>
|
|
|
|
<example>
|
|
<title>Example file structure</title>
|
|
<screen>
|
|
/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/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>
|
|
<screen>
|
|
|
|
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/</screen>
|
|
</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>
|
|
|
|
{* 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>
|
|
<screen>
|
|
// 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');</screen>
|
|
</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>
|
|
<screen>
|
|
|
|
// 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');
|
|
}
|
|
|
|
}</screen>
|
|
</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>
|
|
<screen>
|
|
|
|
require('guestbook/setup.php');
|
|
|
|
$smarty = new Smarty_GuestBook;
|
|
|
|
$smarty->assign('name','Ned');
|
|
|
|
$smarty->display('index.tpl');</screen>
|
|
</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>
|