PageRenderTime 33ms CodeModel.GetById 17ms RepoModel.GetById 0ms app.codeStats 0ms

/framework/vendor/smarty3/lib/README

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