smarty/README

Smarty 3.0 Beta

Author: Monte Ohrt <monte at ohrt dot com >
Author: Uwe Tews

AN INTRODUCTION TO SMARTY 3 BETA

The file structure is similar to Smarty 2:

/libs/
  Smarty.class.php
/libs/sysplugins/
  internal.*
/libs/plugins/
  function.mailto.php
  modifier.escape.php
  ...

A lot of Smarty 3 core functionality lies in the sysplugins directory, you do
not need to change any files here. The /libs/plugins/ folder is where Smarty
plugins are located. You can add your own here, or create a separate plugin
directory, just the same as Smarty 2. You will still need to create your own
/cache/, /templates/, /templates_c/, /configs/ folders. Be sure /cache/ and
/templates_c/ are writable.

The typical way to use Smarty 3 should also look familiar:

require('Smarty.class.php');
$smarty = new Smarty;
$smarty->assign('foo','bar');
$smarty->display('index.tpl');


However, Smarty 3 works completely different on the inside. Smarty 3 is mostly
backward compatible with Smarty 2, except for the following items:

*) Smarty 3 is PHP 5 only. It will not work with PHP 4.
*) The {php} tag is disabled by default. Enable with $smarty->allow_php_tag=true.
*) Delimiters surrounded by whitespace are no longer treated as Smarty tags.
   Therefore, { foo } will not compile as a tag, you must use {foo}. This change
   Makes Javascript/CSS easier to work with, eliminating the need for {literal}.


There are many things that are new to Smarty 3. Here are the notable items:
   
LEXER/PARSER

Smarty 3 now uses a lexing tokenizer for it's parser/compiler. Basically, this
means Smarty has some syntax additions that make life easier such as in-template
math, shorter/intuitive function parameter options, infinite function recursion,
more accurate error handling, etc.

OBJECTS

Smarty 3 plugins are now objects that extend Smarty_Internal_PluginBase. All
plugins have the property $this->smarty available as a reference to the Smarty
object instance. The Smarty 2 function-style plugins are still compatible, you
can drop them right into the Smarty 3 plugin directory.

PHP TEMPLATES

For those that prefer pure PHP over the {tag} based syntax, Smarty now offers
a PHP option for template syntax. PHP templates have several differences over
the tag-based templates:

*) PHP templates are not compiled, they are included directly by the engine.
*) None of Smarty's security features are applied to PHP templates.
*) By default, PHP templates are disabled, set $smarty->allow_php_templates=true.

If you want to use a PHP template, just use the "php" resource type:

$smarty->display('php:foo.php');

You can also mix PHP templates with {tag} templates:

{include file="php:foo.php"}

In PHP templates, assigned vars are available simply as:

// same as {$foo}
<?php echo $foo; ?>
<?=$foo?> // php short tags

Modifiers are used as such:

// same as {foo|trim|truncate:50}
$foo->trim()->truncate(50);

Template functions are used as such:

// same as {foo bar=$baz}
$_f->foo($baz);


WHAT IS NEW IN SMARTY TEMPLATE SYNTAX

Smarty tags can be used as values within other tags.
Example:  {$foo={counter}+3}

They can also be used inside double quoted strings.
Example:  {$foo="this is message {counter}"}

$smarty.current_dir returns the dirname of the current template.

You can use strings directly as templates with the "string" resource type:
$smarty->display('string:This is my template, {$foo}!');
{include file="string:This is my template, {$foo}!"}

You can use math expressions in the templates.
{$x+$y} will output the sum of x and y.
PHP functions can be used in expressions unless they are disabled by the security policy.
{assign var=foo value=2*(3+sqrt($bar))}

You can define arrays.
{assign var=foo value=[1,2,3]}
{assign var=foo value=['y'=>'yellow','b'=>'blue']}
Arrays can be nested.
{assign var=foo value=[1,[9,8],3]}

There is a new "short" syntax for assigning variables.
{$foo=$bar+2}

Arrays can be accessed now also with a new syntax. 
{$foo['bar']} // same as {$foo.bar}
The quotes are required. This syntax addition addresses ambiguties when nesting
the dot syntax. The dot syntax {$foo.bar} will still work.

Variable names can be handled with variables directly.
{$foo_{$x}} will output the variable $foo_1 if $x has a value of 1.

Object method chaining is implemented.
{$object->method1($x)->method2($y)}

{for} tag added for looping (replacement for {section} tag):
{for $x=0, $y=count($foo); $x<$y; $i++}  ....  {/for}
Any number of statements can be used separated by comma as the first
inital expression at {for}.

The Smarty 2 {section} syntax is still supported.

New {foreach} syntax to loop over an array:
{foreach $myarray as $var}   ....  {/foreach}
$var@key            will deliver the key
$var@iteration      will deliver the iteration
$var@index          will deliver the index
$var@total          will deliver the total number of array entries
$var@first          will deliver true for the first iteration
$var@last           will deliver true for the last iteration

The Smarty 2 {foreach} tag syntax is still supported.

NOTE: {$bar[foo]} still indicates a variable inside of a {section} named foo. 
If you want to access an array element with index foo, you must use quotes
such as {$bar['foo']}, or use the dot syntax {$bar.foo}.

New {while....} tag:
{while $i<10}  ....  {/while}

Direct access to PHP functions:
Just as you can use PHP functions as modifiers directly, you can now access
PHP functions directly, provided they are permitted by security settings:
{time()}

New {nocache} block function:
{nocache} ... {/nocache} will declare a section of the template to be not cached.

New nocache attribute:
You can declare variable/function output as non-cached with the nocache attribute.
{$foo nocache=true}
{foo bar="baz" nocache=true}
{time() nocache=true}

Please look through it and send any questions/suggestions/etc to the forums.

http://www.phpinsider.com/smarty-forum/viewtopic.php?t=14168

Monte and Uwe