smarty/docs/en/getting-started.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<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
   (<ulink url="&url.zend;">&url.zend;</ulink>) or PHP Accelerator
   (<ulink url="&url.php-accelerator;">&url.php-accelerator;</ulink>).
  </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
     {}, {{}}, &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 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
-->