added format addon function

README

@@ -2,6 +2,12 @@ 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");
@@ -18,35 +24,50 @@ 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
+	Smarty that sets it apart from other templating solutions is that it
-	precompiles the templates to native php scripts once, then executes
+	precompiles the templates into native php scripts upon the first
-	the php scripts from that point forward. There is no costly template
+	execution, then executes the php scripts from that point forward.
-	file parsing for each request!
+	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 works.... FAST!
+	* it is extremely fast
-	* it's simple, it lets PHP do the work.
+	* it is relatively simple since the PHP parser does the dirty work.
 	* no template parsing overhead, only compiles once.
-	* it is smart about only recompiling template files that
+	* it is smart about automatically recompiling the template
-	  have changed.
+	  files that have changed.
-	* you can make custom template functions, so it is
+	* you can make custom functions and custom variable modifiers, so
-	  infinitely extensible.
+	  the template language is extremely extensible.
-	* configurable template delimiter syntax, so you can have
+	* configurable template delimiter tag syntax, so you can use
-	  {}, {{}}, <!--{}-->, etc.
+	  {}, {{}}, <!--{}-->, or whatever your fancy.
-	* uses native PHP if/else/endif, so template
+	* template if/else/endif constructs are passed to the PHP parser,
-	  code is simpler
+	  so the if syntax can be as simple or as complex as you like
-	* uses PHP for/endfor loops for sections, so
+	* unlimited nesting of sections,ifs, etc. allowed
-	  template code is simpler
+	* it is possible to imbed PHP code right in your template files,
-	* infinitely nested sections allowed
+	  although doubtfully needed since the engine is so customizable.
-	* imbedded PHP code in your template files is
-	  possible (escaped by default.)
 	
 	
 REQUIREMENTS:
 
-	Smarty requires PHP with PCRE (Perl Compatible Regular Expressions)
+	Smarty requires PHP 4.0.4 or later (4.0.3 and earlier contain
-	Smarty was developed and tested with PHP 4.0.2.
+	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:
 
@@ -123,7 +144,7 @@ INSTALLATION:
   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.
+  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.
@@ -142,10 +163,14 @@ 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");
 
 ?>
@@ -165,32 +190,41 @@ templates/footer.tpl
 </HTML>
 
 
-templates/index.php
+templates/index.tpl
 -------------------
 
+{* include the header.tpl file here *}
 {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 *}
+{* now lets test a section loop *}
 <p>
 testing a loop:<br>
-{section name="outside" $loopvar}
+{* $loopvar is used to determine the number
-	loop var is {$outside.loopvar}<br>
+   of times the section is looped *}
-	{section name="inside" $loopvar}
+{section name="outside" loop=$loopvar}
-		inside loop: {$inside.loopvar}<br>
+	{* 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}
 
-{* This is a template comment *}
 <p>
-Hello, my name is {htmlesc $Name}
+{* display $Name as HTML escaped *}
-{* This is a template comment *}
+Hello, my name is {$Name|htmlesc}
+{* include the footer.tpl file here *}
 {include footer.tpl}
 
 
@@ -216,7 +250,6 @@ Smarty supports if/else logic like so:
 {/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.
@@ -229,22 +262,22 @@ Example:
 
 (Assuming $LastName, $MiddleName and $FirstName have been assigned):
 
-{section name="employees" $LastName}
+{section name="employees" loop=$LastName}
-	This employee is {$employees.LastName},{$employees.FirstName}
+	This employee is {$employees/LastName},{$employees/FirstName}
-		{$employees.MiddleName}<br>
+		{$employees/MiddleName}<br>
 {/section}
 
-The first argument to a section is the name of the section.
+The "name" attribute of a section is the name of the section.
-The second argument is the name of a variable (usually
+The "loop" attribute is the name of an array that determines
-an array) that determines the number of times the section
+the number of times the section will be looped. In this example
-will be looped.
+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}
+  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
@@ -252,49 +285,54 @@ A few important things to know:
   
 Sections can be nested, like so:
 
-{section name="employees" $LastName}
+{section name="employees" loop=$LastName}
-	This employee is {$employees.LastName},
+	This employee is {$employees/LastName},
-		{$employees.FirstName} {$employees.MiddleName}<br>
+		{$employees/FirstName} {$employees/MiddleName}<br>
-	{section name="employee_jobs" $JobDescription}
+	{section name="employee_jobs" loop=$JobDescription}
-		Available jobs for {$employees.FirstName}:
+		Available jobs for {$employees/FirstName}:
-			{$employee_jobs.JobDescription}<br>
+			{$employee_jobs/JobDescription}<br>
 	{/section}
 {/section}
 
 SPECIAL FUNCTIONALITY:
 
 There are some special functions that determine the
-current loop iteration of a section. These are
+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:
 
-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}
+{section name=month loop=$var}
-	{if $month.rownum eq 4}
+	{if %month.rownum% eq 4}
 		{* in 4th row of section loop *}
 	{/if}
-	{if $month.rownum.even}
+	{if %month.rownum% is even}
 		{* current rownum is even *}
 	{/if}
-	{if $month.rownum.odd}
+	{if %month.rownum% is odd}
 		{* current rownum is odd *}
 	{/if}
-	{if $month.rownum.even.3}
+	{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.odd.3}
+	{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.mod.4}
+	{if %month.rownum% is mod 4}
 		{* true if current row is divisible by 4 *}
 	{/if}
 {/section}
@@ -309,8 +347,8 @@ For example:
 <TR>
 <TD>
 	<TT>
-		{section name=row $weekday}
+		{section name=row loop=$weekday}
-			{$row.weekday}&nbsp;
+			{%row.weekday%}&nbsp;
 		{/section}
 	</TT>
 </TD>
@@ -323,7 +361,7 @@ the lines together in the template like so:
 
 <TR>
 <TD>
-<TT>{section name=row $weekday}{$row.weekday}&nbsp;{/section}</TT>
+<TT>{section name=row loop=$weekday}{%row.weekday%}&nbsp;{/section}</TT>
 </TD>
 </TR>
 
@@ -335,8 +373,8 @@ An alternate solution is to use the {strip} tag like so:
 <TD>
 	{strip}
 	<TT>
-		{section name=row $weekday}
+		{section name=row loop=$weekday}
-			{$row.weekday}&nbsp;
+			{%row.weekday%}&nbsp;
 		{/section}
 	</TT>
 	{/strip}
@@ -350,12 +388,95 @@ 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:
+{%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

Smarty.addons.php

@@ -81,6 +81,11 @@ function smarty_mod_date_format($string, $format)
 }
 
 
+function smarty_mod_format($string, $format)
+{
+	return sprintf($format, $string);
+}
+
 function smarty_mod_replace($string, $search, $replace)
 {
 	return str_replace($search, $replace, $string);