/framework/vendor/smarty3/lib/README
#! | 555 lines | 424 code | 131 blank | 0 comment | 0 complexity | 01dec2b75de3620352919ec6eca890e9 MD5 | raw file
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