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.
  </para>

  <para>
   For example, let's say you are creating a web page that is displaying a
   newspaper article.
   </para>
   <itemizedlist>
   <listitem><para>
   The article <literal>$headline</literal>, <literal>$tagline</literal>,
   <literal>$author</literal> and <literal>$body</literal> are
   content elements, they contain no information about how they will be
   presented. They are <link linkend="api.assign">passed</link> into Smarty
   by the application.
   </para></listitem>

   <listitem><para>Then the
   template designer edits the templates and uses a combination of
   HTML tags and <link linkend="language.basic.syntax">template tags</link>
   to format the presentation of these
   <link linkend="language.syntax.variables">variables</link> with elements
   such as tables, div's, background colors, font sizes, style sheets, svg etc.
   </para></listitem>

   <listitem><para>One day
   the programmer needs to change the way the article content is retrieved, ie a
   change in application logic. This change does not affect the template
   designer, the content will still arrive in the template exactly the same.
   </para></listitem>

   <listitem><para>
   Likewise, if the template designer wants to completely redesign the
   templates, this would require no change to the application logic.
   </para></listitem>

   <listitem><para>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></listitem>
  </itemizedlist>

  <para>
   One design goal of Smarty is the separation of business logic and
   presentation logic.
   </para>

   <itemizedlist>
   <listitem><para>
   This means templates can certainly contain logic under
   the condition that it is for presentation only. Things such as
   <link linkend="language.function.include">including</link>
   other templates,
   <link linkend="language.function.cycle">alternating</link> table row colors,
   <link linkend="language.modifier.upper">upper-casing</link> a variable,
   <link linkend="language.function.foreach">looping</link>
   over an array of data and <link linkend="api.display">displaying</link> it
   are  examples of  presentation logic.
   </para></listitem>
   <listitem><para>
   This does not mean however 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.
    </para></listitem>
   <listitem><para>Also, if you
   desire <emphasis>no</emphasis> logic in your templates you certainly can
   do so by boiling the content down to text and variables only.
  </para></listitem>
  </itemizedlist>

  <para>
   One of the unique aspects about Smarty is the template compiling. 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. Each template can
   take full advantage of PHP compiler and  cache solutions such as
   <ulink url="&url.e-accel;">eAccelerator</ulink>,
   <ulink url="&url.ion-accel;">ionCube</ulink>
   <ulink url="&url.mmcache-accel;">mmCache</ulink>
   or <ulink url="&url.zend;">Zend Accelerator</ulink>
   to name a few.
  </para>
  <para>
   <emphasis role="bold">Some of Smarty's features:</emphasis>
  </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 <link linkend="variable.compile.check">recompiling</link>
     only the template files that have changed.
    </para>
   </listitem>
   <listitem>
    <para>
     You can easily create your own custom <link
     linkend="language.custom.functions">functions</link>
     and <link linkend="language.modifiers">variable modifiers</link>, so the
     template language is extremely extensible.
    </para>
   </listitem>
   <listitem>
    <para>
     Configurable template
     <link linkend="variable.left.delimiter">{delimiter}</link> tag
      syntax, so you can use
     <literal>{$foo}</literal>, <literal>{{$foo}}</literal>,
     <literal>&lt;!--{$foo}--&gt;</literal>, etc.
    </para>
   </listitem>
   <listitem>
    <para>
     The <link linkend="language.function.if">
     <literal>{if}..{elseif}..{else}..{/if}</literal></link>
     constructs are passed to the
     PHP parser, so the <literal>{if...}</literal> expression syntax can be as
     simple or as complex an evaluation as you like.
    </para>
   </listitem>
   <listitem>
    <para>
     Allows unlimited nesting of <link linkend="language.function.section">
     <varname>sections</varname></link>, <varname>if's</varname> etc.
    </para>
   </listitem>
   <listitem>
    <para>
     It is possible to
     <link linkend="language.function.php">embed PHP code</link>
     right in your template files, although
     this may not be needed (nor recommended) since the engine is so
     <link linkend="plugins">customizable</link>.
    </para>
   </listitem>
   <listitem>
    <para>
     Built-in <link linkend="caching">caching</link> support
    </para>
   </listitem>
   <listitem>
    <para>
     Arbitrary <link linkend="template.resources">template</link> sources
    </para>
   </listitem>
   <listitem>
    <para>
     Custom <link
     linkend="section.template.cache.handler.func">cache handling</link>
     functions
    </para>
   </listitem>
   <listitem>
    <para>
     <link linkend="plugins">Plugin</link> 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 greater.
   </para>
  </sect1>

  <sect1 id="installing.smarty.basic">
   <title>Basic Installation</title>

   <para>
    Install the Smarty library files which are in the
    <filename class="directory">/libs/</filename>  sub directory of
    the distribution. These are <filename>.php</filename> files that you
    SHOULD NOT edit. They are shared among all applications and only get
    changed when you upgrade to a new version of Smarty.
   </para>
   <para>In the examples below the Smarty tarball has been  unpacked to:
   <itemizedlist>
   <listitem><para>
   <filename class="directory">/usr/local/lib/Smarty-v.e.r/</filename> for *nix
   machines</para></listitem>
   <listitem><para> and
   <filename class="directory">c:\webroot\libs\Smarty-v.e.r\</filename> for the
   windows enviroment.</para></listitem>
   </itemizedlist>
   </para>

   <example>
    <title>Required Smarty library files</title>
    <screen>
<![CDATA[
Smarty-v.e.r/
   libs/
      Smarty.class.php
      Smarty_Compiler.class.php
      Config_File.class.php
      debug.tpl
      internals/*.php  (all of them)
      plugins/*.php    (all of them)
]]>
    </screen>
   </example>

   <para>
    Smarty uses a PHP <ulink url="&url.php-manual;define">constant</ulink>
    named <link linkend="constant.smarty.dir"><constant>SMARTY_DIR</constant>
    </link> which is the <emphasis role="bold">full system file path</emphasis>
    to the Smarty <filename>libs/</filename> directory.
    Basically, if your application can find  the
    <filename>Smarty.class.php</filename> file, you do not need to set the
    <link linkend="constant.smarty.dir"><constant>SMARTY_DIR</constant></link>
    as Smarty will figure it out on its own.
    Therefore, if
    <filename>Smarty.class.php</filename> is not in your
    <ulink url="&url.php-manual;ini.core.php#ini.include-path">include_path</ulink>,
    or you do not supply an absolute path to it in your application,
    then you must define <constant>SMARTY_DIR</constant> manually.
    <constant>SMARTY_DIR</constant> <emphasis role="bold">must include a
    trailing slash/</emphasis>.
   </para>


   <informalexample>
   <para>
    Here's how you create an instance of Smarty in your PHP scripts:
   </para>
    <programlisting role="php">
<![CDATA[
<?php
// NOTE: Smarty has a capital 'S'
require_once('Smarty.class.php');
$smarty = new Smarty();
?>
]]>
    </programlisting>
   </informalexample>

   <para>
    Try running the above script. If you get an error saying the
    <filename>Smarty.class.php</filename> file could not be found, you need to
    do one of the following:
   </para>

   <example>
    <title>Set SMARTY_DIR constant manually</title>
    <programlisting role="php">
<![CDATA[
<?php
// *nix style (note capital 'S')
define('SMARTY_DIR', '/usr/local/lib/Smarty-v.e.r/libs/');

// windows style
define('SMARTY_DIR', 'c:/webroot/libs/Smarty-v.e.r/libs/');

// hack version example that works on both *nix and windows
// Smarty is assumend to be in 'includes/' dir under current script
define('SMARTY_DIR',str_replace("\\","/",getcwd()).'/includes/Smarty-v.e.r/libs/');

require_once(SMARTY_DIR . 'Smarty.class.php');
$smarty = new Smarty();
?>
]]>
    </programlisting>
   </example>

   <example>
    <title>Supply absolute path to library file</title>
    <programlisting role="php">
<![CDATA[
<?php
// *nix style (note capital 'S')
require_once('/usr/local/lib/Smarty-v.e.r/libs/Smarty.class.php');

// windows style
require_once('c:/webroot/libs/Smarty-v.e.r/libs/Smarty.class.php');

$smarty = new Smarty();
?>
]]>
    </programlisting>
   </example>

   <example>
    <title>Add the library path to the <filename>php.ini</filename> file</title>
     <programlisting role="php">
<![CDATA[
;;;;;;;;;;;;;;;;;;;;;;;;;
; Paths and Directories ;
;;;;;;;;;;;;;;;;;;;;;;;;;

; *nix: "/path1:/path2"
include_path = ".:/usr/share/php:/usr/local/lib/Smarty-v.e.r/libs/"

; Windows: "\path1;\path2"
include_path = ".;c:\php\includes;c:\webroot\libs\Smarty-v.e.r\libs\"
]]>
</programlisting>
</example>

<example>
    <title>Appending the include path in a php script with
    <literal><ulink url="&url.e-accel;">ini_set()</ulink></literal></title>
    <programlisting role="php">
<![CDATA[
<?php
// *nix
ini_set('include_path', ini_get('include_path').PATH_SEPARATOR.'/usr/local/lib/Smarty-v.e.r/libs/');

// windows
ini_set('include_path', ini_get('include_path').PATH_SEPARATOR.'c:/webroot/lib/Smarty-v.e.r/libs/');
?>
]]>
    </programlisting>
   </example>

   <para>
    Now that the library files are in place, it's time to setup the Smarty
    directories for your application:</para>

    <itemizedlist>
    <listitem><para>
    Smarty requires four directories which
    are by default named <filename class="directory">templates/</filename>,
    <filename class="directory">templates_c/</filename>, <filename
    class="directory">configs/</filename> and <filename
    class="directory">cache/</filename>
    </para></listitem>

    <listitem><para>Each of these are definable by the
    Smarty class properties
    <link linkend="variable.template.dir">
    <varname>$template_dir</varname></link>,
    <link linkend="variable.compile.dir">
    <varname>$compile_dir</varname></link>,
    <link linkend="variable.config.dir">
    <varname>$config_dir</varname></link>, and
    <link linkend="variable.cache.dir">
    <varname>$cache_dir</varname></link> respectively
    </para></listitem>

    <listitem><para>
    It is highly recommended
    that you setup a separate set of these directories for each application
    that will use Smarty
   </para></listitem>
    </itemizedlist>

    <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 <literal>guestbook/</literal> with
    the name of your application.
    </para>


   <example>
    <title>What the file structure looks like</title>
    <screen>
<![CDATA[
/usr/local/lib/Smarty-v.e.r/libs/
        Smarty.class.php
        Smarty_Compiler.class.php
        Config_File.class.php
        debug.tpl
        internals/*.php
        plugins/*.php

/web/www.example.com/
        guestbook/
                templates/
                    index.tpl
                templates_c/
                configs/
                cache/
                htdocs/
                    index.php
]]>
    </screen>
   </example>

   <para>
    Be sure that you know the location of your web server's document root as a
    file path. In the following examples, the document root is <filename
    class="directory">/web/www.example.com/guestbook/htdocs/</filename>.
    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 (but not mandatory) to place these directories
    <emphasis>outside</emphasis> of the web server's document root.
   </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 name our script
    <filename>index.php</filename>, and place it in a subdirectory under the
    document root <filename class="directory">/htdocs/</filename>.
   </para>


   <para>
    Smarty will need <emphasis role="bold">write access</emphasis>
    (windows users please ignore) to the
    <link linkend="variable.compile.dir">
    <parameter>$compile_dir</parameter></link> and
    <link linkend="variable.cache.dir">
    <parameter>$cache_dir</parameter></link> directories
    (<filename class="directory">templates_c/</filename> and
    <filename class="directory">cache/</filename>), so be sure the web server
    user account can write  to them.

    <note><para>This is usually user <quote>nobody</quote> and
    group <quote>nobody</quote>. For OS X users,
    the default is user <quote>www</quote> and group <quote>www</quote>.
    If you are using Apache, you can  look in your
    <filename>httpd.conf</filename> file to see
    what user and group are being used.</para></note>
    </para>

   <example>
    <title>Permissions and making directories writable</title>
    <programlisting role="shell">
<![CDATA[
chown nobody:nobody /web/www.example.com/guestbook/templates_c/
chmod 770 /web/www.example.com/guestbook/templates_c/

chown nobody:nobody /web/www.example.com/guestbook/cache/
chmod 770 /web/www.example.com/guestbook/cache/
]]>
    </programlisting>
   </example>

   <note>
    <title>Note</title>
    <para>
     <literal>chmod 770</literal> will be fairly tight security, it only allows
     user <quote>nobody</quote> and group <quote>nobody</quote> 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 <literal>775</literal> instead.
    </para>
   </note>

   <para>
    We need to create the <filename>index.tpl</filename> file that Smarty will
    display. This needs to be located in the <link linkend="variable.template.dir">
    <parameter>$template_dir</parameter></link>.
   </para>

   <example>
    <title>/web/www.example.com/guestbook/templates/index.tpl</title>
    <screen>
<![CDATA[
{* Smarty *}

Hello {$name}, welcome to Smarty!
]]>
    </screen>
   </example>

   <note>
    <title>Technical Note</title>
    <para>
     <literal>{* Smarty *}</literal> is a template
     <link linkend="language.syntax.comments">comment</link>.
     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 <filename>index.php</filename>. We'll create an instance of Smarty,
    <link linkend="api.assign"><varname>assign()</varname></link> a
    template variable and <link linkend="api.display"><varname>display()</varname></link>
    the <filename>index.tpl</filename> file.
   </para>

   <example>
    <title>Editing /web/www.example.com/docs/guestbook/index.php</title>
    <programlisting role="php">
<![CDATA[
<?php

require_once(SMARTY_DIR . 'Smarty.class.php');

$smarty = new Smarty();

$smarty->template_dir = '/web/www.example.com/guestbook/templates/';
$smarty->compile_dir  = '/web/www.example.com/guestbook/templates_c/';
$smarty->config_dir   = '/web/www.example.com/guestbook/configs/';
$smarty->cache_dir    = '/web/www.example.com/guestbook/cache/';

$smarty->assign('name','Ned');

//** un-comment the following line to show the debug console
//$smarty->debugging = true;

$smarty->display('index.tpl');

?>
]]>
    </programlisting>
   </example>

   <note>
    <title>Note</title>
    <para>
     In our example, we are setting absolute paths to all of the Smarty
     directories. If <filename
     class="directory">/web/www.example.com/guestbook/</filename> 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 naviagate to the <filename>index.php</filename> file with the web browser.
    You should see <emphasis>"Hello Ned, welcome to Smarty!"</emphasis>
   </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
    <ulink url="&url.php-manual;ref.classobj">extend the class</ulink> and
    initialize your Smarty environment. So instead of repeatedly setting
    directory paths, assigning the same vars, etc., we can do that in one place.
    </para>
    <para>
    Lets create a new directory <filename
    class="directory">/php/includes/guestbook/</filename>
     and make a new file called <filename>setup.php</filename>. In our example
     environment, <filename class="directory">/php/includes</filename> is in our
     <literal>include_path</literal>.
     Be sure you set this up too, or use absolute file paths.
   </para>

   <example>
    <title>/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.example.com/guestbook/templates/';
        $this->compile_dir  = '/web/www.example.com/guestbook/templates_c/';
        $this->config_dir   = '/web/www.example.com/guestbook/configs/';
        $this->cache_dir    = '/web/www.example.com/guestbook/cache/';

        $this->caching = true;
        $this->assign('app_name', 'Guest Book');
   }

}
?>
]]>
    </programlisting>
   </example>

  <para>
   Now lets alter the <filename>index.php</filename> file to use
   <filename>setup.php</filename>:
  </para>

  <example>
   <title>/web/www.example.com/guestbook/htdocs/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
   <literal>Smarty_GuestBook()</literal> 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
-->