smarty/README

Smarty 3.0 Alpha 1 : Proof of Concept

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

This code is a proof of concept as a basis of the Smarty 3 template engine.
It is by no means complete, it is only a shell of an infrastructure to build
the 3.0 codebase upon. What I need is feedback before continuing! Now is the
time to make decisions that will affect the engine fundamentals.

So, a quick intro to the thinking behind this alpha code.

If you take a look at the file structure, you should see this:

index.php
/libs/
  Smarty.class.php
/libs/sysplugins/
  internal.*
/plugins/
  function.mailto.php
  modifier.escape.php
/templates/
  index.tpl
  index_view.php
  

If you execute the index.php file, you will see an example of using Smarty to
display a couple of template files.

The way to use Smarty 3 should look extremely familiar:

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


However, Smarty works completely different on the inside. The majority of
the Smarty system now lies in the plugin directory. The core Smarty.class.php
class is extremely slim. The fundamental idea is for Smarty to lazy-load all
requirements (objects) on an as-needed basis.

LEXER/PARSER!

Smarty 3 now uses a real lexing tokenizer and a parser. This opens all kinds of doors
such as template math, function recursion, among many other things.

$smarty OBJECT SINGLETON

Do you need a reference to the Smarty object instance? No problem:

$smarty = Smarty::instance();

You can do this from anywhere in your PHP code, and get the instance. You can
be buried in a php function, in a class method, or wherever. The $smarty
object is quickly obtainable.

Since all internal plugins are now classes (did I mention that yet?), They all extend
Smarty_Internal_PluginBase, which makes $this->smarty a reference to the Smarty
object instance. This is available to all plugins.

PHP TEMPLATES

Smarty's fundamental design goals are meant to separate business logic from
presentation logic. Since Smarty 2.0 templates work on a tag-based syntax, this
has usually equated to "Don't put PHP in the templates." But, these two
philosophies are completely separate. You could conceivably use plain PHP
scripts as your templates and still maintain business logic separation.
Even though PHP is used in the template, it is still just presentation logic.

So now you have your choice: Use templates that are just plain PHP code, or
use the compiled templates using the familiar {$foo} tag syntax. Whatever is
more important to you (PHP or tags/security/etc), make your own choice. Just
remember, PHP templates require YOU to keep the separation yourself. It won't
be as obvious.

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

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

Smarty will not compile it, it will just get executed as PHP. You have full
reign of PHP in your template code. Your assigned template vars are available
simply as <?=$foo?> <?=$bar?>, etc.

How to add modifiers in PHP templates:
Modifier are added like a method to the variables.
<?=$foo->escape('html')?>
Modifier can be chained.
<?=$foo->truncate(5)->escape('html')?>

How to output function results in PHP templates:
Functions will require a $_f prefix.
<?=$_f->time()?>
Again you can add modifier.
<?=$_f->time()->truncate(2)?>



WHAT IS NEW IN SMARTY TEMPLATE SYNTAX

The special variable  $smarty.current_dir  does return the dirname of the current template.

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

You can use complex expressions almost anywhere.
{$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['colour']}
The old syntax {$foo.colour} will still work.

Variable names can be variable.
{$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)}

New {for....} tag:
For a counting for loop:
{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}

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 {for} and new {foreach} will replace Smarty2's {foreach} and {section}.  For BC Smarty2 {foreach} are {section} syntax is still supported.

NOTE:  {$bar[foo]} will always be parsed that foo is the name of a section. 
If you want to access an array element with index foo,you must use quotes like {$bar['foo']}

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

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

You can declare output to be not cached with the nocache attribute.
{$foo nocache=true}
{time() nocache=true}

Ok that pretty much wraps up the principles and fetures behind the alpha code.
But this list is not complete yet. 
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