smarty/docs/getting-started.sgml

<part id="getting.started">
 <title>Getting Started</title>

 <chapter id="overview">
  <title>Overview</title>
  <sect1 id="what.is.smarty">
   <title>What is Smarty?</title>
   <para>
    Smarty is a template engine for PHP. One of the unique aspects about
    Smarty is that it compiles the template files into native PHP scripts
    upon the first invocation. After that, it just executes the compiled
    PHP scripts. 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 Cache (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
      {}, {{}}, &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>
  </sect1>

  <sect1 id="how.smarty.works">
   <title>How Smarty works</title>

   <sect2 id="features.compiling"><title>Compiling</title>
    <para>
     Smarty compiles the templates into native PHP code on-the-fly. The actual
     PHP scripts that are generated are created implicitly, so theoretically you
     should never have to worry about touching these files, or even know of their
     existence. The exception to this is debugging Smarty template syntax errors,
     discussed later in this document.
    </para>
   </sect2>

   <sect2 id="features.caching">
    <title>Caching</title>
    <para>
     Smarty can cache the output of your generated templates. By default
     this is disabled. If you <link linkend="variable.caching">enable
      caching</link>, Smarty will store a copy of the generated template
     output, and use this until the copy <link
      linkend="variable.cache.lifetime">expires</link>, regenerating a new
     one. The default cache expire time can be configured from the
     class. The exception to the rule is the <link
      linkend="language.function.insert">insert</link> tag. Anything
     generated by the insert tag is not cached, but run dynamically on
     every invocation, even within cached content.
    </para>
	<note>
	<title>Technical Note</title>
	<para>
     Any time you change a template, change values in
     config files or change the content that gets displayed in a
     template, you can turn on compile_check to regenerate the caches
     that are affected, or wait for the cache to expire to see the
     results of the changes. You clear caches manually by deleting files
     from the cache directory, programatically with <link
      linkend="api.clear.cache">clear_cache</link> or <link
      linkend="api.clear.all.cache">clear_all_cache</link>, or turn on
     $compile_check (or $force_compile).
    </para>
	</note>
	<note>
	<title>Technical Note</title>
	<para>
     As of Smarty 1.4.6, if you have caching enabled AND
     you have compile_check enabled, the cached file will regenerate if
     an involved template or config file has been modified, regardless
     of the cache expire time. This results in a slight performance hit
     since it has to check the templates and config files for
     modification times. Therefore if you are not actively changing
     templates or config files, it is advisable to leave compile_check
     off. As of Smarty 1.4.7, enabling $force_compile will cause cache
     files to always be regenerated.
    </para>
	</note>
   </sect2>
  </sect1>
 </chapter>

 <chapter id="installation">
  <title>Installation</title>

  <sect1 id="installation.requirements">
   <title>Requirements</title>
   <para>
    Smarty requires PHP 4.0.6 or later. See the
    <link linkend="bugs">BUGS</link> section for caveats.
   </para>
  </sect1>

  <sect1 id="installing.smarty">
   <title>Installing Smarty</title>
   <para>
   First install the Smarty library files. These are the PHP files that you DO
   NOT edit. They only get updated when you upgrade to a new version of Smarty.
   These files are shared among all applications installed on your server that
   utilize Smarty.
   </para>
   <note>
	<title>Technical Note</title>
	<para>
	We highly recommend you do not edit the Smarty files unless you know what
	you're doing. This makes upgrades much easier for you. You DO NOT need to
	edit these files to configure your applications! Use an instance of the
	Smarty class, which we'll get to in the sample setup below.
   </para>
   </note>
   
   <para>
   Here is a list of the library files that come with Smarty:
   </para>
   <example>
    <title>Smarty library files list</title>
    <screen>
Smarty.class.php
Smarty_Compiler.class.php
Config_File.class.php
/plugins/(all files)</screen>
   </example>

   <para>
   Place these library files in a directory located within your PHP
   include_path. Your include_path is usually set in your php.ini file, and you
   can get your current include_path setting from the phpinfo() function. Call
   Smarty in your applications like this:
   </para>

   <example>
    <title>Loading Smarty library files from include_path</title>
    <screen>
// Smarty.class.php will be found in your include_path
require('Smarty.class.php');
$smarty = new Smarty;</screen>
   </example>
  
   <para>
   If you would like to place your library files outside of your include path,
   you must supply the absolute path in your application via the SMARTY_DIR
   constant. SMARTY_DIR must end with a slash. Lets say we place our Smarty
   library files in /usr/local/lib/php/Smarty/.
   </para>
 
   <example>
    <title>Loading Smarty library files directly</title>
    <screen>
define(SMARTY_DIR,'/usr/local/lib/php/Smarty/');
require(SMARTY_DIR.'Smarty.class.php');
$smarty = new Smarty;</screen>
   </example>

   <para>
	Now we need to setup the directories for our application. These are
	$template_dir, $compile_dir, $config_dir and $cache_dir. It is your
	discretion to have your applications share any of these directories, or
	make them separate. None of these directories need be in the document root
	of your web server, so keep them out of there to avoid the issue of prying
	eyes getting to these files directly with a browser.
   </para>
   <para>
   Lets take a look at an example of a complete file structure for all of our
   files:
   </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/plugins/*.php

/web/www.mydomain.com/smarty/templates/
/web/www.mydomain.com/smarty/templates_c/
/web/www.mydomain.com/smarty/configs/
/web/www.mydomain.com/smarty/cache/

/web/www.mydomain.com/docs/myapp/index.php</screen>
   </example>

   <para>
   Smarty will need write access to the $compile_dir and $cache_dir, 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 "web" and group "web".
   </para>
   <example>
    <title>Setting file permissions</title>
    <screen>

chown nobody:nobody /web/www.mydomain.com/smarty/templates_c/
chmod 550 /web/www.mydomain.com/smarty/templates_c/

chown nobody:nobody /web/www.mydomain.com/smarty/cache/
chmod 550 /web/www.mydomain.com/smarty/cache/

/web/www.mydomain.com/docs/index.php</screen>
   </example>
   
   <para>
   In this example, index.php is in our document root under the subdirectory
   "myapp". Lets edit this file and call a Smarty template.
   </para>
   
   <example>
    <title>Editing index.php</title>
    <screen>

// contents of /web/www.mydomain.com/docs/myapp/index.php

define(SMARTY_DIR,'/usr/local/lib/php/Smarty/');
require(SMARTY_DIR.'Smarty.class.php');

$smarty = new Smarty;

/*
   NOTE: the following four lines do not need to be set if
   /web/www.mydomain.com/smarty/ is in your include_path.
*/

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

$smarty->display('index.tpl');</screen>
   </example>
   
   <para>
   Before we execute this, we need to create the index.tpl file that Smarty will
   load. This will be located in your $template_dir.
   </para>

   <example>
    <title>Editing index.tpl</title>
    <screen>

{* contents of /web/www.mydomain.com/smarty/templates/index.tpl *}

Hello World!</screen>
   </example>
   
   <para>
   Now load the index.php file from your web browser. You should see "Hello
   World!" That's it for the basic setup for Smarty!
   </para>
   
  </sect1>

  <sect1 id="smarty.constants">
   <title>Constants</title>
   <para></para>

   <sect2 id="constant.smarty.dir">
    <title>SMARTY_DIR</title>
    <para>
     This should be the full system path to the location of the Smarty
     class files. If this is not defined, then Smarty will attempt to
     determine the appropriate value automatically. If defined, the path
     must end with a slash.
    </para>
    <example>
     <title>SMARTY_DIR</title>
     <programlisting>
// set path to Smarty directory
define("SMARTY_DIR","/usr/local/lib/php/Smarty/");

require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
    </example>
   </sect2>
  </sect1>
 </chapter>
</part>