NAME:

	Smarty - the PHP compiling template engine v0.9
	

AUTHORS:
	
	Monte Ohrt <monte@ispi.net>
	Andrei Zmievski <andrei@ispi.net>

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 templating solutions is that it
	precompiles the templates into native php scripts upon the first
	execution, then executes the php scripts from that point forward.
	Therefore, there is no costly template file parsing for each request.
	Smarty also has built-in page caching to minimize the regeneration
	of unchanged content.

	Some of Smarty's features:

	* it is extremely fast
	* it is relatively simple since the PHP parser does the dirty work.
	* no template parsing overhead, only compiles once.
	* it is smart about automatically recompiling the template
	  files that have changed.
	* you can make custom functions and custom variable modifiers, so
	  the template language is extremely extensible.
	* configurable template delimiter tag syntax, so you can use
	  {}, {{}}, <!--{}-->, or whatever your fancy.
	* template if/else/endif constructs are passed to the PHP parser,
	  so the if syntax can be as simple or as complex as you like
	* unlimited nesting of sections,ifs, etc. allowed
	* it is possible to imbed PHP code right in your template files,
	  although doubtfully needed since the engine is so customizable.
	
	
REQUIREMENTS:

	Smarty requires PHP 4.0.4 or later (4.0.3 and earlier contain
	a bug in preg_grep() that won't allow the parser to function
	properly.)

VARIABLE TYPES:

	Smarty has two different syntaxes for variables. One for script
	variables (prefixed with $), and one for internal variables
	generated by the template parser (prefixed and suffixed with %).

	Variable examples:
	{$Name}			<-- prints the value of $Name
	{%News.rownum%}		<-- prints the current iteration
				    of the section named "News"
	{if %News.rownum% is even}	<-- checks if the rownum is even
		...
	{/if}

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 or php file 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;

// simulate some variable assignments. Normally this
// would come from a database or other data source.

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

// now simply display the template
$smarty->spew("./templates/index.tpl");

?>

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

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


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

</BODY>
</HTML>


templates/index.tpl
-------------------

{* include the header.tpl file here *}
{include header.tpl}
hello, my name is {$Name}.<br>
{if $Name eq "Joe"}
	I am Joe.<br>
{else}
	I am not Joe.<br>
{/if} 
{* now lets test a section loop *}
<p>
testing a loop:<br>
{* $loopvar is used to determine the number
   of times the section is looped *}
{section name="outside" loop=$loopvar}
	{* show the current loop iteration *}
	current loop iteration is {%outside.rownum%}<br>
	{* show the current index value of $loopvar
           within the "outside" section *}
	loop var is {$outside/loopvar}<br>
	{* now we'll loop through a nested section *}
	{section name="inside" loop=$loopvar}
		{* show the current index value of $loopvar
                   within the "inside" section *}
		inside loop: {$inside/loopvar}<br>
	{/section}
	<p>
{/section}

<p>
{* display $Name as HTML escaped *}
Hello, my name is {$Name|htmlesc}
{* include the footer.tpl file here *}
{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:
* "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" loop=$LastName}
	This employee is {$employees/LastName},{$employees/FirstName}
		{$employees/MiddleName}<br>
{/section}

The "name" attribute of a section is the name of the section.
The "loop" attribute is the name of an array that determines
the number of times the section will be looped. In this example
if $LastName has four elements, the section will loop four times.

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" loop=$LastName}
	This employee is {$employees/LastName},
		{$employees/FirstName} {$employees/MiddleName}<br>
	{section name="employee_jobs" loop=$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 surrounded
with "%" characters, and they are:

rownum:		current row, first row treated as 1
index:		current row, first row treated as 0

The following are possible "is" expression types
for these functions:

odd:		true if value is odd
even:		true if value is even
mod:		true if value is divisible by X

Examples:

{section name=month loop=$var}
	{if %month.rownum% eq 4}
		{* in 4th row of section loop *}
	{/if}
	{if %month.rownum% is even}
		{* current rownum is even *}
	{/if}
	{if %month.rownum% is odd}
		{* current rownum is odd *}
	{/if}
	{if %month.rownum% is even by 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% is odd by 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% is 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 loop=$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 loop=$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 loop=$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.

VARIABLE MODIFIERS:

Optionally, you can modify variables on-the-fly by passing
them through variable modifiers. Several variable modifiers
come with the default template engine. For example, if you
want a variable to be all uppercase when it is displayed,
you can do the following:

{$Name|upper}

This will display the value of $Name in uppercase.
Notice the vertical pipe "|" between the variable name
and the modifier. This is how the template parser
distinguishes that you want to pass the variable through
a modifier before being displayed. Anything to the right
of the variable name after a pipe "|" is a variable
modifier.

Here is an example of printing the variable $Name
as HTML escaped:

{$Name|htmlesc}

You are also allowed to mix any variable modifiers
on a single variable:

{$Name|upper|htmlesc}

Variable modifiers are read from left to right. In the
above example, the variable will first be uppercased,
then HTML escaped, then finally displayed.

Variable modifiers are passed the value of of the
variable (or the results of the previous modifier)
as the first argument. They can also be passed additional
arguments by specifying them in context, separated by
colons. For example, lets say you want to display only
the first 40 characters of a variable:

{$article|length:40}

This will print out the first 40 characters of the
variable $article.

Variable modifiers are also allowed within template logic
constructs, such as {if ...} tags. Example:

{if $Name|upper eq "JOE"}
	His name is JOE.
{else}
	His name is not JOE.
{/if}

You may also use PHP functions as variable
modifiers. If a modifier is not found in the registered
template modifiers, it will be assumed that it is a PHP
function, and will be passed as so. Be careful though,
all modifiers must take the input as the first value
and return a modified value, otherwise it won't do much good!

Example of using a PHP function:

<PRE>
{$article|wordwrap:72}
</PRE>

This will print the value of $article wordwrapped at 72 chars.

TIP: For PHP functions that do not expect the variable
arguments in the correct order, you can write a variable
modifier "wrapper" that passes them in the correct order.
For instance, strftime() expects the date format first,
followed by the date. You can write a wrapper that passes
them in the correct order:

{$date|dateFormat:"%Y-%m-%d"}

This will pass the value of $date, followed by the specified
date format to your variable modifier "dateFormat". This
can in turn pass the values to strftime() in the correct
order, then return the results.


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.