Smarty - the compiling PHP template engine

Monte Ohrt <monte at ohrt dot com>

Uwe Tews <uwe dot tews at googlemail dot com>

2012-02-20


Table of Contents

Preface
I. Getting Started
1. What is Smarty?
2. Installation
Requirements
Basic Installation
Extended Setup
II. Smarty For Template Designers
3. Basic Syntax
Comments
Variables
Functions
Attributes
Embedding Vars in Double Quotes
Math
Escaping Smarty Parsing
4. Variables
Variables assigned from PHP
Associative arrays
Array indexes
Objects
Variable scopes
Variables loaded from config files
{$smarty} reserved variable
Request variables
{$smarty.now}
{$smarty.const}
{$smarty.capture}
{$smarty.config}
{$smarty.section}
{$smarty.template}
{$smarty.template_object}
{$smarty.current_dir}
{$smarty.version}
{$smarty.block.child}
{$smarty.block.parent}
{$smarty.ldelim}, {$smarty.rdelim}
5. Variable Modifiers
capitalize
cat
count_characters
count_paragraphs
count_sentences
count_words
date_format
default
escape
from_charset
indent
lower
nl2br
regex_replace
replace
spacify
string_format
strip
strip_tags
to_charset
truncate
unescape
upper
wordwrap
6. Combining Modifiers
7. Built-in Functions
{$var=...}
{append}
{assign}
{block}
{call}
{capture}
{config_load}
{debug}
{extends}
{for}
{foreach},{foreachelse}
@index
@iteration
@first
@last
@show
@total
{break}
{continue}
{function}
{if},{elseif},{else}
{include}
{include_php}
{insert}
{ldelim},{rdelim}
{literal}
{nocache}
{php}
{section},{sectionelse}
.index
.index_prev
.index_next
.iteration
.first
.last
.rownum
.loop
.show
.total
{setfilter}
{strip}
{while}
8. Custom Functions
{counter}
{cycle}
{eval}
{fetch}
{html_checkboxes}
{html_image}
{html_options}
{html_radios}
{html_select_date}
{html_select_time}
{html_table}
{mailto}
{math}
{textformat}
9. Config Files
10. Debugging Console
III. Smarty For Programmers
11. Charset Encoding
Charset Encoding
12. Constants
SMARTY_DIR
13. Smarty Class Variables
$allow_php_templates
$auto_literal
$autoload_filters
$cache_dir
$cache_id
$cache_lifetime
$cache_locking
$cache_modified_check
$caching
$caching_type
$compile_check
$compile_dir
$compile_id
$compile_locking
$compiler_class
$config_booleanize
$config_dir
$config_overwrite
$config_read_hidden
$debug_tpl
$debugging
$debugging_ctrl
$default_config_type
$default_modifiers
$default_resource_type
$default_config_handler_func
$default_template_handler_func
$direct_access_security
$error_reporting
$escape_html
$force_cache
$force_compile
$left_delimiter
$locking_timeout
$merge_compiled_includes
$php_handling
$plugins_dir
$right_delimiter
$smarty_debug_id
$template_dir
$trusted_dir
$use_include_path
$use_sub_dirs
14. Smarty Class Methods
addConfigDir() — add a directory to the list of directories where config files are stored
addPluginsDir() — add a directory to the list of directories where plugins are stored
addTemplateDir() — add a directory to the list of directories where templates are stored
append() — append an element to an assigned array
appendByRef() — append values by reference
assign() — assign variables/objects to the templates
assignByRef() — assign values by reference
clearAllAssign() — clears the values of all assigned variables
clearAllCache() — clears the entire template cache
clearAssign() — clears the value of an assigned variable
clearCache() — clears the cache for a specific template
clearCompiledTemplate() — clears the compiled version of the specified template resource
clearConfig() — clears assigned config variables
compileAllConfig() — compiles all known config files
compileAllTemplates() — compiles all known templates
configLoad() — loads config file data and assigns it to the template
createData() — creates a data object
createTemplate() — returns a template object
disableSecurity() — disables template security
display() — displays the template
enableSecurity() — enables template security
fetch() — returns the template output
getCacheDir() — return the directory where the rendered template's output is stored
getCompileDir() — returns the directory where compiled templates are stored
getConfigDir() — return the directory where config files are stored
getConfigVars() — returns the given loaded config variable value
getPluginsDir() — return the directory where plugins are stored
getRegisteredObject() — returns a reference to a registered object
getTags() — return tags used by template
getTemplateDir() — return the directory where templates are stored
getTemplateVars() — returns assigned variable value(s)
isCached() — returns true if there is a valid cache for this template
loadFilter() — load a filter plugin
Smarty::muteExpectedErrors() — mutes expected warnings and notices deliberately generated by Smarty
registerCacheResource() — dynamically register CacheResources
registerClass() — register a class for use in the templates
registerDefaultPluginHandler() — register a function which gets called on undefined tags
registerFilter() — dynamically register filters
registerPlugin() — dynamically register plugins
registerObject() — register an object for use in the templates
registerResource() — dynamically register resources
setCacheDir() — set the directory where the rendered template's output is stored
setCompileDir() — set the directory where compiled templates are stored
setConfigDir() — set the directories where config files are stored
setPluginsDir() — set the directories where plugins are stored
setTemplateDir() — set the directories where templates are stored
templateExists() — checks whether the specified template exists
unregisterCacheResource() — dynamically unregister a CacheResource plugin
unregisterFilter() — dynamically unregister a filter
unregisterPlugin — dynamically unregister plugins
unregisterObject() — dynamically unregister an object
unregisterResource() — dynamically unregister a resource plugin
testInstall() — checks Smarty installation
15. Caching
Setting Up Caching
Multiple Caches Per Page
Cache Groups
Controlling Cacheability of Output
Cacheability of Template Section
Cacheability of Tags
Cacheability of Variables
Cacheability of Plugins
Custom Cache Implementation
16. Resources
File Template Resources
Templates from $template_dir
Templates from a specific $template_dir
Templates from any directory
Windows Filepaths
String Template Resources
Stream Template Resources
Extends Template Resources
Custom Template Resources
17. Advanced Features
Security
Changing settings by template
Template Inheritance
Streams
Objects
Static Classes
Prefilters
Postfilters
Output Filters
18. Extending Smarty With Plugins
How Plugins Work
Naming Conventions
Writing Plugins
Template Functions
Modifiers
Block Functions
Compiler Functions
Prefilters/Postfilters
Output Filters
Resources
Inserts
19. SmartyBC - Backwards Compatibility Wrapper
SmartyBC class
IV. Appendixes
20. Troubleshooting
Smarty/PHP errors
21. Tips & Tricks
Blank Variable Handling
Default Variable Handling
Passing variable title to header template
Dates
WAP/WML
Componentized Templates
Obfuscating E-mail Addresses
22. Resources
23. BUGS

List of Examples

2.1. Required Smarty library files
2.2. Set SMARTY_DIR constant manually
2.3. Supply absolute path to library file
2.4. Add the library path to the php.ini file
2.5. Appending the include path in a php script with ini_set()
2.6. What the file structure looks like
2.7. Permissions and making directories writable
2.8. /web/www.example.com/guestbook/templates/index.tpl
2.9. Editing /web/www.example.com/docs/guestbook/index.php
2.10. /php/includes/guestbook/setup.php
2.11. /web/www.example.com/guestbook/htdocs/index.php
3.1. Comments within a template
3.2. Variables
3.3. function syntax
3.4. function attribute syntax
3.5. Syntax examples
3.6. Examples
3.7. math examples
3.8. Using the auto-literal feature
3.9. changing delimiters example
4.1. Example variables
4.2. Assigned variables
4.3. Accessing associative array variables
4.4. Accessing arrays by index
4.5. Accessing object properties
4.6. Variable scope examples
4.7. config variables
4.8. Displaying request variables
5.1. Modifier examples
5.2. capitalize
5.3. cat
5.4. count_characters
5.5. count_paragraphs
5.6. count_sentences
5.7. count_words
5.8. date_format
5.9. default
5.10. escape
5.11. Other examples
5.12. indent
5.13. lower
5.14. nl2br
5.15. regex_replace
5.16. replace
5.17. spacify
5.18. string_format
5.19. strip
5.20. strip_tags
5.21. truncate
5.22. escape
5.23. upper
5.24. wordwrap
6.1. combining modifiers
7.1. Simple assignment
7.2. Assignment with math
7.3. Assignment of an array element
7.4. Assignment of an multidimensional array element
7.5. Appending an array
7.6. Assigment in the scope of calling template
7.7. {append}
7.8. {assign}
7.9. {assign} as a nocache variable
7.10. {assign} with some maths
7.11. {assign} in the scope of calling template
7.12. {assign} a variable to current scope tree
7.13. {assign} a global variable
7.14. Accessing {assign} variables from a PHP script
7.15. Simple {block} example
7.16. Prepend {block} example
7.17. Append {block} example
7.18. {$smarty.block.child} example
7.19. {$smarty.block.parent} example
7.20. Calling a recursive menu example
7.21. {capture} with the name attribute
7.22. {capture} into a template variable
7.23. {capture} into a template array variable
7.24. {config_load}
7.25. function {config_load} with section
7.26. Simple {extends} example
7.27. A simple {for} loop
7.28. Using the max attribute
7.29. Excution of {forelse}
7.30. A simple {foreach} loop
7.31. Demonstrates the an additional key variable
7.32. {foreach} with nested item and key
7.33. Database example with {foreachelse}
7.34. index example
7.35. iteration example: is div by
7.36. iteration example: is even/odd by
7.37. first property example
7.38. last property example
7.39. show property example
7.40. total property example
7.41. {break} example
7.42. {continue} example
7.43. Recursive menu {function} example
7.44. {if} statements
7.45. {if} with more examples
7.46. Simple {include} example
7.47. {include} passing variables
7.48. {include} using parent scope
7.49. {include} with disabled caching
7.50. {include} with individual cache lifetime
7.51. {include} with forced caching
7.52. {include} and assign to variable
7.53. {include} with relative paths
7.54. Various {include} resource examples
7.55. function {include_php}
7.56. function {insert}
7.57. {ldelim}, {rdelim}
7.58. Another Javascript example
7.59. {literal} tags
7.60. Preventing a template section from being cached
7.61. php code within {php} tags
7.62. {php} tags with global and assigning a variable
7.63. Looping a simple array with {section}
7.64. {section} without an assigned array
7.65. Naming a {section}
7.66. Looping an associative array with {section}
7.67. {section} demonstrating the loop variable
7.68. Nested {section}'s
7.69. Database example with a {sectionelse}
7.70. {section} index property
7.71. index, index_next and index_prev properties
7.72. A section's iteration property
7.73. {section} property first and last
7.74. {section} property loop
7.75. show property
7.76. total property example
7.77. {setfilter} tags
7.78. {strip} tags
7.79. {while} loop
8.1. {counter}
8.2. {cycle}
8.3. {eval}
8.4. Another {eval} example
8.5. {fetch} examples
8.6. {html_checkboxes}
8.7. Database example (eg PEAR or ADODB):
8.8. {html_image} example
8.9. Associative array with the options attribute
8.10. Dropdown with seperate arrays for values and ouptut
8.11. Database example (eg ADODB or PEAR)
8.12. Dropdown's with <optgroup>
8.13. {html_radios} first example
8.14. {html_radios} second example
8.15. {html_radios} - Database example (eg PEAR or ADODB):
8.16. {html_select_date}
8.17. {html_select_date} second example
8.18. {html_select_time}
8.19. {html_table}
8.20. {mailto} example lines followed by the result
8.21. {math}
8.22. {textformat}
9.1. Example of config file syntax
11.1. Setting a different Charset Encoding
12.1. SMARTY_DIR
13.1. $compile_id in a virtual host environment
13.2. Array of config #variables#
13.3. $debugging_ctrl on localhost
13.4. $default_config_handler_func
13.5. $default_template_handler_func
14.1. addConfigDir()
14.2. addPluginsDir()
14.3. addTemplateDir()
14.4. append
14.5. appendByRef
14.6. assign()
14.7. assignByRef()
14.8. clearAllAssign()
14.9. clearAllCache
14.10. clearAssign()
14.11. clearCache()
14.12. clearCompiledTemplate()
14.13. clearConfig()
14.14. compileAllConfig()
14.15. compileAllTemplates()
14.16. configLoad()
14.17. createData()
14.18. createTemplate()
14.19. display()
14.20. Other display() template resource examples
14.21. fetch()
14.22. Using fetch() to send an email
14.23. getCacheDir()
14.24. getCompileDir()
14.25. getConfigDir()
14.26. getConfigVars()
14.27. getPluginsDir()
14.28. getRegisteredObject()
14.29. getTags()
14.30. getTemplateDir()
14.31. getTemplateVars
14.32. isCached()
14.33. isCached() with multiple-cache template
14.34. Loading filter plugins
14.35. registerCacheResource()
14.36. Register class for use within a template
14.37. Register namespaced class for use within a template
14.38. Default Plugin Handler Example
14.39. register a function plugin
14.40. register block function plugin
14.41. register modifier plugin
14.42. registerResource()
14.43. setCacheDir()
14.44. setCompileDir()
14.45. setConfigDir()
14.46. setPluginsDir()
14.47. setTemplateDir()
14.48. templateExists()
14.49. unregisterCacheResource()
14.50. unregister function plugin
14.51. unregisterResource()
14.52. testInstall()
15.1. Enabling caching
15.2. Setting $cache_lifetime per cache
15.3. Disabling $compile_check
15.4. Using isCached()
15.5. Clearing the cache
15.6. Passing a $cache_id to display()
15.7. Passing a cache_id to isCached()
15.8. Clearing all caches for a particular $cache_id
15.9. $cache_id groups
15.10. Preventing a template section from being cached
15.11. Preventing tag output from being cached
15.12. Nocache Variables
15.13. Preventing a plugin's output from being cached
15.14. Preventing a whole passage of a template from being cached
15.15. Smarty_CacheResource_Mysql
15.16. Smarty_CacheResource_Memcache
16.1. Using templates from the $template_dir
16.2. Specifying the $template_dir to use
16.3. Using templates from any directory
16.4. Using templates from windows file paths
16.5. Using templates from strings
16.6. Using templates from encoded strings
16.7. Stream from PHP
16.8. Stream from Template
16.9. Using template inheritance from the PHP script
16.10. Using custom resources
17.1. Setting security policy by extending the Smarty_Security class
17.2. Setting security policy by instance of the Smarty_Security class
17.3. Enable security with the default settings
17.4. changing Smarty settings by template
17.5. register plugins by template
17.6. Template inheritance example
17.7. Template inheritance by template resource extends:
17.8. Stream Variable
17.9. Using a registered or assigned object
17.10. static class access syntax
17.11. Using a template prefilter
17.12. Using a template postfilter
17.13. Using a template outputfilter
18.1. function plugin with output
18.2. function plugin without output
18.3. A simple modifier plugin
18.4. More complex modifier plugin
18.5. block function
18.6. A simple compiler function
18.7. prefilter plugin
18.8. postfilter plugin
18.9. An output filter plugin
18.10. Using custom resources
18.11. insert plugin
19.1. Using SmartyBC
20.1. Smarty errors
20.2. PHP parsing errors
20.3. Other common errors
21.1. Printing &nbsp; when a variable is empty
21.2. Assigning a template variable its default value
21.3. Passing the title variable to the header template
21.4. Using date_format
21.5. Converting form date elements back to a timestamp
21.6. Using {insert} to write a WML Content-Type header
21.7. componentized template
21.8. Example of template the Obfuscating an email address