NAME:

	Smarty - the PHP compiling template engine v0.9
	
SYNOPSIS:

	require("smarty.class.php");

	$smarty = new Smarty;

	$smarty->assign("Title","My Homepage");
	$smarty->assign("Names",array("John","Gary","Gregg","James"));

	$smarty->spew("./templates/index.tpl");

DESCRIPTION:

	What is Smarty?
	
	Smarty is a template engine for PHP. One of the unique aspects about
	Smarty that sets it apart from other template solutions is that it
	precompiles the templates to native php scripts once, then executes
	the php scripts from that point forward. There is no costly template
	file parsing for each request!

	Some of Smarty's features:

	* it works.... FAST!
	* it's simple, it lets PHP do the work.
	* no template parsing overhead, only compiles once.
	* it is smart about only recompiling template files that
	  have changed.
	* you can make custom template functions, so it is
	  infinitely extensible.
	* configurable template delimiter syntax, so you can have
	  {}, {{}}, <!--{}-->, etc.
	* uses native PHP if/else/endif, so template
	  code is simpler
	* uses PHP for/endfor loops for sections, so
	  template code is simpler
	* infinitely nested sections allowed
	* imbedded PHP code in your template files is
	  possible (escaped by default.)
	
	
REQUIREMENTS:

	Smarty requires PHP with PCRE (Perl Compatible Regular Expressions)
	Smarty was developed and tested with PHP 4.0.2.

CLASS METHODS:

	assign($var,$val)
	-----------------
	Assign variables to be used in the template engine.
		
	spew($tpl_file)
	----------------------
	Print the results of a parsed template file
				
	fetch($tpl_file)
	--------------------------
	Return the results of a parsed template file

	clear_assign($var)
	------------------	
	Clear an assigned template variable.		

	clear_all_assign()
	------------------
	Clear all the assigned template variables.


CLASS VARIABLES:	(default value in parenthesis)

	$compile_check		Whether or not to check for a needed compile.
						To optimize performance, set this to
						false once development is complete and
						the scripts are initially compiled.
						(true)

	$template_dir		Name of directory containing templates

	$compile_dir_ext	Extention to give the name of the compile
						directory. For example, if your templates
						are stored in a directory named
						"templates", then all compiled template
						files will be kept in "templates_c" in the
						same directory. (_c)

	$tpl_file_ext		The extention used on template files. (.tpl)
						All other files in the template directory
						without this extention are ignored.

	$max_recursion_depth	The maximum recursion depth for template
							files includes. This is to help catch an
							infinite loop. 0 == unlimited. (10)

	$allow_php			Whether or not to allow PHP code in your
						templates. If set to false, PHP code is
						escaped. (false)
	
	
	$left_delimiter		The left delimiter of the template syntax.
						For some development tools, it may be handy
						to change the delimiters to something like
						"<!-- {" and "} -->" respectfully. ({)
	
	$right_delimiter	The right delimiter of the template syntax. (})
	
	$registered_functions	Names of the custom template functions
							that Smarty will recognize.
							To add your own, add them to this array
							and add the actual functions to the
							smarty.functions.php file.
					(array(	"htmlesc","urlesc","default","config" );)


INSTALLATION:

* copy the smarty.class.php and smarty.functions.php scripts to a
  directory that is accessible by PHP. NOTE: Smarty will need to
  create a directory for the compiled templates. Be sure that the
  web server user (or which ever user the PHP parser is run as)
  can write to the directory. You will see appropriate error
  messages if the directory creation fails.

* setup your php and template files. A good working example is
  included to get you started.


EXAMPLE:

A simple example, built out of a few files:

index.php
---------

<?

require("smarty.class.php");

$smarty = new Smarty;

$smarty->assign("Name","Gomer Pyle");
$smarty->assign("loopvar",array("one","two","three","four"));
$smarty->assign("loopvar2",array("one","two","three","<four>"));

$smarty->spew("./templates/index.tpl");

?>

templates/header.tpl
--------------------

<HTML>
<BODY>
<TITLE>My Homepage</TITLE>


templates/footer.tpl
--------------------

</BODY>
</HTML>


templates/index.php
-------------------

{include header.tpl}
{* This is a template comment *}
hello, my name is {$Name}.<br>
{if $Name eq "Joe"}
	I am Joe.<br>
{else}
	I am not Joe.<br>
{/if} 
{* This is a template comment *}
<p>
testing a loop:<br>
{section name="outside" $loopvar}
	loop var is {$outside.loopvar}<br>
	{section name="inside" $loopvar}
		inside loop: {$inside.loopvar}<br>
	{/section}
	<p>
{/section}

{* This is a template comment *}
<p>
Hello, my name is {htmlesc $Name}
{* This is a template comment *}
{include footer.tpl}


INCLUDE LOGIC:

Smarty supports including other template files.

* you must supply the relative path to the
  included template file from the template
  in use. Example: in index.tpl, the file
  header.tpl is included from the same directory:

  {include header.tpl} 

IF/ELSE LOGIC:

Smarty supports if/else logic like so:

{if $Name eq "John"}
	I am John!
{else}
	I am not John.
{/if}

A few important things to know:
* arguments to {if ...} are passed "as is" to the php parser.
* "eq", "ne","neq", "gt", "lt", "lte", "le", "gte" "ge",
  "==","!=",">","<","<=",">=" are all valid conditional
  qualifiers.

SECTIONS:

Sections are portions of the template that are meant to be looped.

Example:

(Assuming $LastName, $MiddleName and $FirstName have been assigned):

{section name="employees" $LastName}
	This employee is {$employees.LastName},{$employees.FirstName}
		{$employees.MiddleName}<br>
{/section}

The first argument to a section is the name of the section.
The second argument is the name of a variable (usually
an array) that determines the number of times the section
will be looped.

A few important things to know:
* ALL sections must be given a name.
* ALL section names MUST be unique from one another.
* All variables meant to be looped within a section
  MUST have the section name prepended to the name
  like so: {$section_name.variable_name}
* It is OK to mention variables of parent sections
  within nested child sections.
* nothing in the section will display if the
  looping array is unset.
  
Sections can be nested, like so:

{section name="employees" $LastName}
	This employee is {$employees.LastName},
		{$employees.FirstName} {$employees.MiddleName}<br>
	{section name="employee_jobs" $JobDescription}
		Available jobs for {$employees.FirstName}:
			{$employee_jobs.JobDescription}<br>
	{/section}
{/section}

SPECIAL FUNCTIONALITY:

There are some special functions that determine the
current loop iteration of a section. These are

rownum:		current row, first row starting with 1
index:		current row, first row starting with 0
odd:		true if value is odd
even:		true if value is even
mod:		true if value is divisible by X

Examples:

{section name=month $var}
	{if $month.rownum eq 4}
		{* in 4th row of section loop *}
	{/if}
	{if $month.rownum.even}
		{* current rownum is even *}
	{/if}
	{if $month.rownum.odd}
		{* current rownum is odd *}
	{/if}
	{if $month.rownum.even.3}
		{* each even row, grouped by 3.
		   so rows 1,2,3 are true (even),
		   4,5,6 are odd (false), etc *}
	{/if}
	{if $month.rownum.odd.3}
		{* each odd row, grouped by 3.
		   so rows 1,2,3 are true (odd),
		   4,5,6 are even (false), etc *}
	{/if}
	{if $month.rownum.mod.4}
		{* true if current row is divisible by 4 *}
	{/if}
{/section}

THE {strip} TAG:

A special tag called {strip} can be used to strip out
extra space, tabs or newlines at the beginning and end
of each template row within {strip} and {/strip}.
For example:

<TR>
<TD>
	<TT>
		{section name=row $weekday}
			{$row.weekday}&nbsp;
		{/section}
	</TT>
</TD>
</TR>

This will return unwanted results because of
the extra tabs and newlines contained within the <TT></TT>
tags. Normally to remedy this, you must run all
the lines together in the template like so:

<TR>
<TD>
<TT>{section name=row $weekday}{$row.weekday}&nbsp;{/section}</TT>
</TD>
</TR>


As you can see, this quickly makes the template unreadable.
An alternate solution is to use the {strip} tag like so:

<TR>
<TD>
	{strip}
	<TT>
		{section name=row $weekday}
			{$row.weekday}&nbsp;
		{/section}
	</TT>
	{/strip}
</TD>
</TR>


What this will do is strip out tabs, spaces and newlines
at the beginning and end of each line before outputting
the results. This helps keep the template file readable
without affecting the output. Only text between {strip}
and {/strip} is affected.

{ldelim} AND {rdelim} TAGS:

These are used in the template to output the literal
left and right delimiters. Normally these are
"{" and "}" if you are using the default delimiters.

CUSTOM FUNCTIONS:

You may create your own custom template functions. There are four
functions that come bundled with Smarty, which are the following:

{htmlesc $var}					prints a variable html escaped.
{urlesc $var}					prints a variable url escaped.
{default $var,"default value"}	prints the default value if
								$var is empty.
{config "file.conf","var"}		prints the value of a variable
								from a config file.

For this "config" function, config files must be in the following syntax:

var = "value"

example:

index.tpl
---------

{config "config/index.conf","title"}

index.conf
----------

title = "My Homepage"
Name = "Gomer"


creating your own:

To create your own custom functions, do the following:

* edit the smarty.functions.php file, add your custom function. Be sure
  the function name is prepended with "smarty_".
* edit the smarty.class.php file, add your custom function name to the
  array (leave off the smarty_ prefix.)
* make a mention of your custom function in a template, like so:
  {function_name [arguments]}
* The arguments are passed "as is" to the custom function.

COPYRIGHT:
	Copyright(c) 2000 ispi. All rights reserved.
	This software is released under the GNU General Public License.
	Please read the disclaimer at the top of the Smarty.class.php file.