/framework/vendor/smarty3/lib/README

  1Smarty 3.0 Beta
  2
  3Author: Monte Ohrt <monte at ohrt dot com >
  4Author: Uwe Tews
  5
  6AN INTRODUCTION TO SMARTY 3 BETA
  7
  8NOTICE for BETA 8:
  9
 10The Smarty 3 API (as of beta 8) has been refactored to a syntax geared
 11for consistency and modularity. The Smarty 2 API syntax is still supported, but
 12will throw a deprecation notice. You can disable the notices, but it is highly
 13recommended to adjust your syntax to Smarty 3, as the Smarty 2 syntax must run
 14through an extra rerouting wrapper.
 15
 16Basically, all Smarty methods now follow the "fooBarBaz" camel case syntax. Also,
 17all Smarty properties now have getters and setters. So for example, the property
 18$smarty->cache_dir can be set with $smarty->setCacheDir('foo/') and can be
 19retrieved with $smarty->getCacheDir().
 20
 21Some of the Smarty 3 APIs have been revoked such as the "is*" methods that were
 22just duplicate functions of the now available "get*" methods.
 23
 24Here is a rundown of the Smarty 3 API:
 25
 26$smarty->fetch($template, $cache_id = null, $compile_id = null, $parent = null)
 27$smarty->display($template, $cache_id = null, $compile_id = null, $parent = null)
 28$smarty->isCached($template, $cache_id = null, $compile_id = null)
 29$smarty->createData($parent = null)
 30$smarty->createTemplate($template, $cache_id = null, $compile_id = null, $parent = null)
 31$smarty->enableSecurity()
 32$smarty->disableSecurity()
 33$smarty->setTemplateDir($template_dir)
 34$smarty->addTemplateDir($template_dir)
 35$smarty->templateExists($resource_name)
 36$smarty->loadPlugin($plugin_name, $check = true)
 37$smarty->loadFilter($type, $name)
 38$smarty->setExceptionHandler($handler)
 39$smarty->addPluginsDir($plugins_dir)
 40$smarty->getGlobal($varname = null)
 41$smarty->getRegisteredObject($name)
 42$smarty->getDebugTemplate()
 43$smarty->setDebugTemplate($tpl_name)
 44$smarty->assign($tpl_var, $value = null, $nocache = false, $scope = SMARTY_LOCAL_SCOPE)
 45$smarty->assignGlobal($varname, $value = null, $nocache = false)
 46$smarty->assignByRef($tpl_var, &$value, $nocache = false, $scope = SMARTY_LOCAL_SCOPE)
 47$smarty->append($tpl_var, $value = null, $merge = false, $nocache = false, $scope = SMARTY_LOCAL_SCOPE)
 48$smarty->appendByRef($tpl_var, &$value, $merge = false)
 49$smarty->clearAssign($tpl_var)
 50$smarty->clearAllAssign()
 51$smarty->configLoad($config_file, $sections = null)
 52$smarty->getVariable($variable, $_ptr = null, $search_parents = true, $error_enable = true)
 53$smarty->getConfigVariable($variable)
 54$smarty->getStreamVariable($variable)
 55$smarty->getConfigVars($varname = null)
 56$smarty->clearConfig($varname = null)
 57$smarty->getTemplateVars($varname = null, $_ptr = null, $search_parents = true)
 58
 59// some API calls are moved into their own objects:
 60
 61$smarty->cache->loadResource($type = null)
 62$smarty->cache->clearAll($exp_time = null, $type = null)
 63$smarty->cache->clear($template_name, $cache_id = null, $compile_id = null, $exp_time = null, $type = null)
 64
 65$smarty->register->block($block_tag, $block_impl, $cacheable = true, $cache_attr = array())
 66$smarty->register->compilerFunction($compiler_tag, $compiler_impl, $cacheable = true)
 67$smarty->register->templateFunction($function_tag, $function_impl, $cacheable = true, $cache_attr = array())
 68$smarty->register->modifier($modifier_name, $modifier_impl)
 69$smarty->register->templateObject($object_name, $object_impl, $allowed = array(), $smarty_args = true, $block_methods = array())
 70$smarty->register->outputFilter($function_name)
 71$smarty->register->postFilter($function_name)
 72$smarty->register->preFilter($function_name)
 73$smarty->register->resource($resource_type, $function_names)
 74$smarty->register->variableFilter($function_name)
 75$smarty->register->defaultPluginHandler($function_name)
 76$smarty->register->defaultTemplateHandler($function_name)
 77
 78$smarty->unregister->block($block_tag)
 79$smarty->unregister->compilerFunction($compiler_tag)
 80$smarty->unregister->templateFunction($function_tag)
 81$smarty->unregister->modifier($modifier)
 82$smarty->unregister->templateObject($object_name)
 83$smarty->unregister->outputFilter($function_name)
 84$smarty->unregister->postFilter($function_name)
 85$smarty->unregister->preFilter($function_name)
 86$smarty->unregister->resource($resource_type)
 87$smarty->unregister->variableFilter($function_name)
 88
 89$smarty->utility->compileAllTemplates($extention = '.tpl', $force_compile = false, $time_limit = 0, $max_errors = null)
 90$smarty->utility->clearCompiledTemplate($resource_name = null, $compile_id = null, $exp_time = null)
 91$smarty->utility->testInstall()
 92
 93// then all the getters/setters, available for all properties. Here are a few:
 94
 95$caching = $smarty->getCaching();      // get $smarty->caching
 96$smarty->setCaching(true);             // set $smarty->caching
 97$smarty->setDeprecationNotices(false); // set $smarty->deprecation_notices
 98$smarty->setCacheId($id);              // set $smarty->cache_id
 99$debugging = $smarty->getDebugging();  // get $smarty->debugging
100
101
102FILE STRUCTURE
103
104The Smarty 3 file structure is similar to Smarty 2:
105
106/libs/
107  Smarty.class.php
108/libs/sysplugins/
109  internal.*
110/libs/plugins/
111  function.mailto.php
112  modifier.escape.php
113  ...
114
115A lot of Smarty 3 core functionality lies in the sysplugins directory; you do
116not need to change any files here. The /libs/plugins/ folder is where Smarty
117plugins are located. You can add your own here, or create a separate plugin
118directory, just the same as Smarty 2. You will still need to create your own
119/cache/, /templates/, /templates_c/, /configs/ folders. Be sure /cache/ and
120/templates_c/ are writable.
121
122The typical way to use Smarty 3 should also look familiar:
123
124require('Smarty.class.php');
125$smarty = new Smarty;
126$smarty->assign('foo','bar');
127$smarty->display('index.tpl');
128
129
130However, Smarty 3 works completely different on the inside. Smarty 3 is mostly
131backward compatible with Smarty 2, except for the following items:
132
133*) Smarty 3 is PHP 5 only. It will not work with PHP 4.
134*) The {php} tag is disabled by default. Enable with $smarty->allow_php_tag=true.
135*) Delimiters surrounded by whitespace are no longer treated as Smarty tags.
136   Therefore, { foo } will not compile as a tag, you must use {foo}. This change
137   Makes Javascript/CSS easier to work with, eliminating the need for {literal}.
138   This can be disabled by setting $smarty->auto_literal = false;
139*) The Smarty 3 API is a bit different. Many Smarty 2 API calls are deprecated
140   but still work. You will want to update your calls to Smarty 3 for maximum
141   efficiency.
142
143
144There are many things that are new to Smarty 3. Here are the notable items:
145   
146LEXER/PARSER
147============
148
149Smarty 3 now uses a lexing tokenizer for its parser/compiler. Basically, this
150means Smarty has some syntax additions that make life easier such as in-template
151math, shorter/intuitive function parameter options, infinite function recursion,
152more accurate error handling, etc.
153
154
155WHAT IS NEW IN SMARTY TEMPLATE SYNTAX
156=====================================
157
158Smarty 3 allows expressions almost anywhere. Expressions can include PHP
159functions as long as they are not disabled by the security policy, object
160methods and properties, etc. The {math} plugin is no longer necessary but
161is still supported for BC.
162
163Examples:
164{$x+$y}                           will output the sum of x and y.
165{$foo = strlen($bar)}             function in assignment
166{assign var=foo value= $x+$y}     in attributes 
167{$foo = myfunct( ($x+$y)*3 )}     as function parameter 
168{$foo[$x+3]}                      as array index
169
170Smarty tags can be used as values within other tags.
171Example:  {$foo={counter}+3}
172
173Smarty tags can also be used inside double quoted strings.
174Example:  {$foo="this is message {counter}"}
175
176You can define arrays within templates.
177Examples:
178{assign var=foo value=[1,2,3]}
179{assign var=foo value=['y'=>'yellow','b'=>'blue']}
180Arrays can be nested.
181{assign var=foo value=[1,[9,8],3]}
182
183There is a new short syntax supported for assigning variables.
184Example: {$foo=$bar+2}
185
186You can assign a value to a specific array element. If the variable exists but
187is not an array, it is converted to an array before the new values are assigned.
188Examples:
189{$foo['bar']=1}
190{$foo['bar']['blar']=1}
191
192You can append values to an array. If the variable exists but is not an array,
193it is converted to an array before the new values are assigned.
194Example: {$foo[]=1}
195
196You can use a PHP-like syntax for accessing array elements, as well as the
197original "dot" notation.
198Examples:
199{$foo[1]}             normal access
200{$foo['bar']}
201{$foo['bar'][1]}
202{$foo[$x+$x]}         index may contain any expression
203{$foo[$bar[1]]}       nested index
204{$foo[section_name]}  smarty section access, not array access!
205
206The original "dot" notation stays, and with improvements.
207Examples:
208{$foo.a.b.c}        =>  $foo['a']['b']['c'] 
209{$foo.a.$b.c}       =>  $foo['a'][$b]['c']        with variable index
210{$foo.a.{$b+4}.c}   =>  $foo['a'][$b+4]['c']       with expression as index
211{$foo.a.{$b.c}}     =>  $foo['a'][$b['c']]         with nested index
212
213note that { and } are used to address ambiguties when nesting the dot syntax. 
214
215Variable names themselves can be variable and contain expressions.
216Examples:
217$foo         normal variable
218$foo_{$bar}  variable name containing other variable 
219$foo_{$x+$y} variable name containing expressions 
220$foo_{$bar}_buh_{$blar}  variable name with multiple segments
221{$foo_{$x}}  will output the variable $foo_1 if $x has a value of 1.
222
223Object method chaining is implemented.
224Example: {$object->method1($x)->method2($y)}
225
226{for} tag added for looping (replacement for {section} tag):
227{for $x=0, $y=count($foo); $x<$y; $x++}  ....  {/for}
228Any number of statements can be used separated by comma as the first
229inital expression at {for}.
230
231{for $x = $start to $end step $step} ... {/for}is in the SVN now .
232You can use also
233{for $x = $start to $end} ... {/for}
234In this case the step value will be automaticall 1 or -1 depending on the start and end values.
235Instead of $start and $end you can use any valid expression.
236Inside the loop the following special vars can be accessed:
237$x@iteration = number of iteration
238$x@total = total number of iterations
239$x@first = true on first iteration
240$x@last = true on last iteration
241
242
243The Smarty 2 {section} syntax is still supported.
244
245New shorter {foreach} syntax to loop over an array.
246Example: {foreach $myarray as $var}...{/foreach}
247
248Within the foreach loop, properties are access via:
249
250$var@key            foreach $var array key
251$var@iteration      foreach current iteration count (1,2,3...)
252$var@index          foreach current index count (0,1,2...)
253$var@total          foreach $var array total
254$var@first          true on first iteration
255$var@last           true on last iteration
256
257The Smarty 2 {foreach} tag syntax is still supported.
258
259NOTE: {$bar[foo]} still indicates a variable inside of a {section} named foo. 
260If you want to access an array element with index foo, you must use quotes
261such as {$bar['foo']}, or use the dot syntax {$bar.foo}.
262
263while block tag is now implemented:
264{while $foo}...{/while}
265{while $x lt 10}...{/while}
266
267Direct access to PHP functions:
268Just as you can use PHP functions as modifiers directly, you can now access
269PHP functions directly, provided they are permitted by security settings:
270{time()}
271
272There is a new {function}...{/function} block tag.  This enables reuse of code
273sequences like a plugin function. It can call itself recursively.
274
275Example:
276
277Template file:
278{function name=menu level=0}
279  <ul class="level{$level}">
280  {foreach $data as $entry}
281    {if is_array($entry)}
282      <li>{$entry@key}</li>
283       {menu data=$entry level=$level+1}
284    {else}
285      <li>{$entry}</li>
286    {/if}
287  {/foreach}
288  </ul>
289{/function}
290
291{$menu = ['item1','item2','item3' => ['item3-1','item3-2','item3-3' =>
292  ['item3-3-1','item3-3-2']],'item4']}
293
294{menu data=$menu}
295
296
297Generated output:
298    * item1
299    * item2
300    * item3
301          o item3-1
302          o item3-2
303          o item3-3
304                + item3-3-1
305                + item3-3-2
306    * item4
307
308The function tag itself must have the "name" attribute. This name is the tag
309name when calling the function. The function tag may have any number of
310additional attributes. These will be default settings for local variables.
311
312New {nocache} block function:
313{nocache}...{/nocache} will declare a section of the template to be non-cached
314when template caching is enabled.
315
316New nocache attribute:
317You can declare variable/function output as non-cached with the nocache attribute.
318Examples:
319
320{$foo nocache=true}
321{$foo nocache} /* same */
322
323{foo bar="baz" nocache=true}
324{foo bar="baz" nocache} /* same */
325
326{time() nocache=true}
327{time() nocache} /* same */
328
329Or you can also assign the variable in your script as nocache:
330$smarty->assign('foo',$something,true); // third param is nocache setting
331{$foo} /* non-cached */
332
333$smarty.current_dir returns the directory name of the current template.
334
335You can use strings directly as templates with the "string" resource type.
336Examples:
337$smarty->display('string:This is my template, {$foo}!'); // php
338{include file="string:This is my template, {$foo}!"} // template
339
340
341
342VARIABLE SCOPE / VARIABLE STORAGE
343=================================
344
345In Smarty 2, all assigned variables were stored within the Smarty object. 
346Therefore, all variables assigned in PHP were accessible by all subsequent 
347fetch and display template calls.
348
349In Smarty 3, we have the choice to assign variables to the main Smarty object, 
350to user-created data objects, and to user-created template objects. 
351These objects can be chained. The object at the end of a chain can access all
352variables belonging to that template and all variables within the parent objects.
353The Smarty object can only be the root of a chain, but a chain can be isolated
354from the Smarty object.
355
356All known Smarty assignment interfaces will work on the data and template objects.
357
358Besides the above mentioned objects, there is also a special storage area for
359global variables.
360
361A Smarty data object can be created as follows:
362$data = $smarty->createData();    // create root data object
363$data->assign('foo','bar');       // assign variables as usual
364$data->config_load('my.conf');									 // load config file    
365
366$data= $smarty->createData($smarty);  // create data object having a parent link to
367the Smarty object
368
369$data2= $smarty->createData($data);   // create data object having a parent link to
370the $data data object
371
372A template object can be created by using the createTemplate method. It has the
373same parameter assignments as the fetch() or display() method.
374Function definition:
375function createTemplate($template, $cache_id = null, $compile_id = null, $parent = null)
376
377The first parameter can be a template name, a smarty object or a data object.
378
379Examples:
380$tpl = $smarty->createTemplate('mytpl.tpl'); // create template object not linked to any parent
381$tpl->assign('foo','bar');                   // directly assign variables
382$tpl->config_load('my.conf');									 // load config file    
383
384$tpl = $smarty->createTemplate('mytpl.tpl',$smarty);  // create template having a parent link to the Smarty object
385$tpl = $smarty->createTemplate('mytpl.tpl',$data);    // create template having a parent link to the $data object
386
387The standard fetch() and display() methods will implicitly create a template object.
388If the $parent parameter is not specified in these method calls, the template object
389is will link back to the Smarty object as it's parent.
390
391If a template is called by an {include...} tag from another template, the
392subtemplate links back to the calling template as it's parent. 
393
394All variables assigned locally or from a parent template are accessible. If the
395template creates or modifies a variable by using the {assign var=foo...} or
396{$foo=...} tags, these new values are only known locally (local scope). When the
397template exits, none of the new variables or modifications can be seen in the
398parent template(s). This is same behavior as in Smarty 2. 
399
400With Smarty 3, we can assign variables with a scope attribute which allows the
401availablility of these new variables or modifications globally (ie in the parent
402templates.)
403
404Possible scopes are local, parent, root and global. 
405Examples:
406{assign var=foo value='bar'}       // no scope is specified, the default 'local'
407{$foo='bar'}                       // same, local scope
408{assign var=foo value='bar' scope='local'} // same, local scope
409
410{assign var=foo value='bar' scope='parent'} // Values will be available to the parent object 
411{$foo='bar' scope='parent'}                 // (normally the calling template)
412
413{assign var=foo value='bar' scope='root'}   // Values will be exported up to the root object, so they can 
414{$foo='bar' scope='root'}                   // be seen from all templates using the same root.
415
416{assign var=foo value='bar' scope='global'} // Values will be exported to global variable storage, 
417{$foo='bar' scope='global'}                 // they are available to any and all templates.
418
419
420The scope attribute can also be attached to the {include...} tag. In this case,
421the specified scope will be the default scope for all assignments within the
422included template.
423
424
425PLUGINS
426=======
427
428Smarty 3 plugins are now objects that extend Smarty_Internal_PluginBase. All
429plugins have the property $this->smarty available as a reference to the Smarty
430object instance. The Smarty 2 function-style plugins are still compatible, you
431can drop them right into the Smarty 3 plugin directory.
432
433
434TEMPLATE INHERITANCE:
435=====================
436
437With template inheritance you can define blocks, which are areas that can be
438overriden by child templates, so your templates could look like this: 
439
440parent.tpl:
441<html>
442  <head>
443    <title>{block name='title'}My site name{/block}</title>
444  </head>
445  <body>
446    <h1>{block name='page-title'}Default page title{/block}</h1>
447    <div id="content">
448      {block name='content'}
449        Default content
450      {/block}
451    </div>
452  </body>
453</html>
454
455child.tpl:
456{extends file='parent.tpl'} 
457{block name='title'}
458Child title
459{/block}
460
461grandchild.tpl:
462{extends file='child.tpl'} 
463{block name='title'}Home - {$smarty.block.parent}{/block} 
464{block name='page-title'}My home{/block}
465{block name='content'}
466  {foreach $images as $img}
467    <img src="{$img.url}" alt="{$img.description}" />
468  {/foreach}
469{/block}
470
471We redefined all the blocks here, however in the title block we used {$smarty.block.parent},
472which tells Smarty to insert the default content from the parent template in its place.
473The content block was overriden to display the image files, and page-title has also be 
474overriden to display a completely different title. 
475
476If we render grandchild.tpl we will get this: 
477<html>
478  <head>
479    <title>Home - Child title</title>
480  </head>
481  <body>
482    <h1>My home</h1>
483    <div id="content">
484      <img src="/example.jpg" alt="image" />
485      <img src="/example2.jpg" alt="image" />
486      <img src="/example3.jpg" alt="image" />
487    </div>
488  </body>
489</html>
490
491NOTE: In the child templates everything outside the {extends} or {block} tag sections
492is ignored.
493
494The inheritance tree can be as big as you want (meaning you can extend a file that 
495extends another one that extends another one and so on..), but be aware that all files 
496have to be checked for modifications at runtime so the more inheritance the more overhead you add.
497
498Instead of defining the parent/child relationships with the {extends} tag in the child template you
499can use the resource as follow:
500
501$smarty->display('extends:parent.tpl|child.tpl|grandchild.tpl');
502
503Child {block} tags may optionally have a append or prepend attribute. In this case the parent block content 
504is appended or prepended to the child block content.
505
506{block name='title' append} My title {/block}
507
508
509PHP STREAMS:
510============
511
512(to be filled in)
513
514VARIBLE FILTERS:
515================
516
517(to be filled in)
518
519PHP TEMPLATES
520=============
521
522For those that prefer pure PHP over the {tag} based syntax, Smarty now offers
523a PHP option for template syntax. PHP templates have several differences over
524the tag-based templates:
525
526*) PHP templates are not compiled, they are included directly by the engine.
527*) None of Smarty's security features are applied to PHP templates.
528*) By default, PHP templates are disabled, set $smarty->allow_php_templates=true.
529
530If you want to use a PHP template, just use the "php" resource type:
531
532$smarty->display('php:foo.php');
533
534You can also mix PHP templates with {tag} templates:
535
536{include file="php:foo.php"}
537
538In PHP templates, assigned vars are available simply as:
539
540// same as {$foo}
541<?php echo $foo; ?>
542<?=$foo?> // php short tags
543
544At this point, smarty modifier/function plugins are not
545conveniently accessible from PHP templates. A wrapper
546function may become available in the future.
547
548You can call PHP functions a usual:
549<?php echo foo($bar); ?>
550
551Please look through it and send any questions/suggestions/etc to the forums.
552
553http://www.phpinsider.com/smarty-forum/viewtopic.php?t=14168
554
555Monte and Uwe