diff options
Diffstat (limited to 'library/Smarty/README')
| -rw-r--r-- | library/Smarty/README | 575 |
1 files changed, 0 insertions, 575 deletions
diff --git a/library/Smarty/README b/library/Smarty/README deleted file mode 100644 index 08b397c3f..000000000 --- a/library/Smarty/README +++ /dev/null @@ -1,575 +0,0 @@ -Smarty 3.x - -Author: Monte Ohrt <monte at ohrt dot com > -Author: Uwe Tews - -AN INTRODUCTION TO SMARTY 3 - -NOTICE FOR 3.1 release: - -Please see the SMARTY_3.1_NOTES.txt file that comes with the distribution. - -NOTICE for 3.0.5 release: - -Smarty now follows the PHP error_reporting level by default. If PHP does not mask E_NOTICE and you try to access an unset template variable, you will now get an E_NOTICE warning. To revert to the old behavior: - -$smarty->error_reporting = E_ALL & ~E_NOTICE; - -NOTICE for 3.0 release: - -IMPORTANT: Some API adjustments have been made between the RC4 and 3.0 release. -We felt it is better to make these now instead of after a 3.0 release, then have to -immediately deprecate APIs in 3.1. Online documentation has been updated -to reflect these changes. Specifically: - ----- API CHANGES RC4 -> 3.0 ---- - -$smarty->register->* -$smarty->unregister->* -$smarty->utility->* -$samrty->cache->* - -Have all been changed to local method calls such as: - -$smarty->clearAllCache() -$smarty->registerFoo() -$smarty->unregisterFoo() -$smarty->testInstall() -etc. - -Registration of function, block, compiler, and modifier plugins have been -consolidated under two API calls: - -$smarty->registerPlugin(...) -$smarty->unregisterPlugin(...) - -Registration of pre, post, output and variable filters have been -consolidated under two API calls: - -$smarty->registerFilter(...) -$smarty->unregisterFilter(...) - -Please refer to the online documentation for all specific changes: - -http://www.smarty.net/documentation - ----- - -The Smarty 3 API has been refactored to a syntax geared -for consistency and modularity. The Smarty 2 API syntax is still supported, but -will throw a deprecation notice. You can disable the notices, but it is highly -recommended to adjust your syntax to Smarty 3, as the Smarty 2 syntax must run -through an extra rerouting wrapper. - -Basically, all Smarty methods now follow the "fooBarBaz" camel case syntax. Also, -all Smarty properties now have getters and setters. So for example, the property -$smarty->cache_dir can be set with $smarty->setCacheDir('foo/') and can be -retrieved with $smarty->getCacheDir(). - -Some of the Smarty 3 APIs have been revoked such as the "is*" methods that were -just duplicate functions of the now available "get*" methods. - -Here is a rundown of the Smarty 3 API: - -$smarty->fetch($template, $cache_id = null, $compile_id = null, $parent = null) -$smarty->display($template, $cache_id = null, $compile_id = null, $parent = null) -$smarty->isCached($template, $cache_id = null, $compile_id = null) -$smarty->createData($parent = null) -$smarty->createTemplate($template, $cache_id = null, $compile_id = null, $parent = null) -$smarty->enableSecurity() -$smarty->disableSecurity() -$smarty->setTemplateDir($template_dir) -$smarty->addTemplateDir($template_dir) -$smarty->templateExists($resource_name) -$smarty->loadPlugin($plugin_name, $check = true) -$smarty->loadFilter($type, $name) -$smarty->setExceptionHandler($handler) -$smarty->addPluginsDir($plugins_dir) -$smarty->getGlobal($varname = null) -$smarty->getRegisteredObject($name) -$smarty->getDebugTemplate() -$smarty->setDebugTemplate($tpl_name) -$smarty->assign($tpl_var, $value = null, $nocache = false) -$smarty->assignGlobal($varname, $value = null, $nocache = false) -$smarty->assignByRef($tpl_var, &$value, $nocache = false) -$smarty->append($tpl_var, $value = null, $merge = false, $nocache = false) -$smarty->appendByRef($tpl_var, &$value, $merge = false) -$smarty->clearAssign($tpl_var) -$smarty->clearAllAssign() -$smarty->configLoad($config_file, $sections = null) -$smarty->getVariable($variable, $_ptr = null, $search_parents = true, $error_enable = true) -$smarty->getConfigVariable($variable) -$smarty->getStreamVariable($variable) -$smarty->getConfigVars($varname = null) -$smarty->clearConfig($varname = null) -$smarty->getTemplateVars($varname = null, $_ptr = null, $search_parents = true) -$smarty->clearAllCache($exp_time = null, $type = null) -$smarty->clearCache($template_name, $cache_id = null, $compile_id = null, $exp_time = null, $type = null) - -$smarty->registerPlugin($type, $tag, $callback, $cacheable = true, $cache_attr = array()) - -$smarty->registerObject($object_name, $object_impl, $allowed = array(), $smarty_args = true, $block_methods = array()) - -$smarty->registerFilter($type, $function_name) -$smarty->registerResource($resource_type, $function_names) -$smarty->registerDefaultPluginHandler($function_name) -$smarty->registerDefaultTemplateHandler($function_name) - -$smarty->unregisterPlugin($type, $tag) -$smarty->unregisterObject($object_name) -$smarty->unregisterFilter($type, $function_name) -$smarty->unregisterResource($resource_type) - -$smarty->compileAllTemplates($extension = '.tpl', $force_compile = false, $time_limit = 0, $max_errors = null) -$smarty->clearCompiledTemplate($resource_name = null, $compile_id = null, $exp_time = null) -$smarty->testInstall() - -// then all the getters/setters, available for all properties. Here are a few: - -$caching = $smarty->getCaching(); // get $smarty->caching -$smarty->setCaching(true); // set $smarty->caching -$smarty->setDeprecationNotices(false); // set $smarty->deprecation_notices -$smarty->setCacheId($id); // set $smarty->cache_id -$debugging = $smarty->getDebugging(); // get $smarty->debugging - - -FILE STRUCTURE - -The Smarty 3 file structure is similar to Smarty 2: - -/libs/ - Smarty.class.php -/libs/sysplugins/ - internal.* -/libs/plugins/ - function.mailto.php - modifier.escape.php - ... - -A lot of Smarty 3 core functionality lies in the sysplugins directory; you do -not need to change any files here. The /libs/plugins/ folder is where Smarty -plugins are located. You can add your own here, or create a separate plugin -directory, just the same as Smarty 2. You will still need to create your own -/cache/, /templates/, /templates_c/, /configs/ folders. Be sure /cache/ and -/templates_c/ are writable. - -The typical way to use Smarty 3 should also look familiar: - -require('Smarty.class.php'); -$smarty = new Smarty; -$smarty->assign('foo','bar'); -$smarty->display('index.tpl'); - - -However, Smarty 3 works completely different on the inside. Smarty 3 is mostly -backward compatible with Smarty 2, except for the following items: - -*) Smarty 3 is PHP 5 only. It will not work with PHP 4. -*) The {php} tag is disabled by default. Enable with $smarty->allow_php_tag=true. -*) Delimiters surrounded by whitespace are no longer treated as Smarty tags. - Therefore, { foo } will not compile as a tag, you must use {foo}. This change - Makes Javascript/CSS easier to work with, eliminating the need for {literal}. - This can be disabled by setting $smarty->auto_literal = false; -*) The Smarty 3 API is a bit different. Many Smarty 2 API calls are deprecated - but still work. You will want to update your calls to Smarty 3 for maximum - efficiency. - - -There are many things that are new to Smarty 3. Here are the notable items: - -LEXER/PARSER -============ - -Smarty 3 now uses a lexing tokenizer for its parser/compiler. Basically, this -means Smarty has some syntax additions that make life easier such as in-template -math, shorter/intuitive function parameter options, infinite function recursion, -more accurate error handling, etc. - - -WHAT IS NEW IN SMARTY TEMPLATE SYNTAX -===================================== - -Smarty 3 allows expressions almost anywhere. Expressions can include PHP -functions as long as they are not disabled by the security policy, object -methods and properties, etc. The {math} plugin is no longer necessary but -is still supported for BC. - -Examples: -{$x+$y} will output the sum of x and y. -{$foo = strlen($bar)} function in assignment -{assign var=foo value= $x+$y} in attributes -{$foo = myfunct( ($x+$y)*3 )} as function parameter -{$foo[$x+3]} as array index - -Smarty tags can be used as values within other tags. -Example: {$foo={counter}+3} - -Smarty tags can also be used inside double quoted strings. -Example: {$foo="this is message {counter}"} - -You can define arrays within templates. -Examples: -{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 supported for assigning variables. -Example: {$foo=$bar+2} - -You can assign a value to a specific array element. If the variable exists but -is not an array, it is converted to an array before the new values are assigned. -Examples: -{$foo['bar']=1} -{$foo['bar']['blar']=1} - -You can append values to an array. If the variable exists but is not an array, -it is converted to an array before the new values are assigned. -Example: {$foo[]=1} - -You can use a PHP-like syntax for accessing array elements, as well as the -original "dot" notation. -Examples: -{$foo[1]} normal access -{$foo['bar']} -{$foo['bar'][1]} -{$foo[$x+$x]} index may contain any expression -{$foo[$bar[1]]} nested index -{$foo[section_name]} smarty section access, not array access! - -The original "dot" notation stays, and with improvements. -Examples: -{$foo.a.b.c} => $foo['a']['b']['c'] -{$foo.a.$b.c} => $foo['a'][$b]['c'] with variable index -{$foo.a.{$b+4}.c} => $foo['a'][$b+4]['c'] with expression as index -{$foo.a.{$b.c}} => $foo['a'][$b['c']] with nested index - -note that { and } are used to address ambiguties when nesting the dot syntax. - -Variable names themselves can be variable and contain expressions. -Examples: -$foo normal variable -$foo_{$bar} variable name containing other variable -$foo_{$x+$y} variable name containing expressions -$foo_{$bar}_buh_{$blar} variable name with multiple segments -{$foo_{$x}} will output the variable $foo_1 if $x has a value of 1. - -Object method chaining is implemented. -Example: {$object->method1($x)->method2($y)} - -{for} tag added for looping (replacement for {section} tag): -{for $x=0, $y=count($foo); $x<$y; $x++} .... {/for} -Any number of statements can be used separated by comma as the first -inital expression at {for}. - -{for $x = $start to $end step $step} ... {/for}is in the SVN now . -You can use also -{for $x = $start to $end} ... {/for} -In this case the step value will be automaticall 1 or -1 depending on the start and end values. -Instead of $start and $end you can use any valid expression. -Inside the loop the following special vars can be accessed: -$x@iteration = number of iteration -$x@total = total number of iterations -$x@first = true on first iteration -$x@last = true on last iteration - - -The Smarty 2 {section} syntax is still supported. - -New shorter {foreach} syntax to loop over an array. -Example: {foreach $myarray as $var}...{/foreach} - -Within the foreach loop, properties are access via: - -$var@key foreach $var array key -$var@iteration foreach current iteration count (1,2,3...) -$var@index foreach current index count (0,1,2...) -$var@total foreach $var array total -$var@first true on first iteration -$var@last true on last iteration - -The Smarty 2 {foreach} tag syntax is still supported. - -NOTE: {$bar[foo]} still indicates a variable inside of a {section} named foo. -If you want to access an array element with index foo, you must use quotes -such as {$bar['foo']}, or use the dot syntax {$bar.foo}. - -while block tag is now implemented: -{while $foo}...{/while} -{while $x lt 10}...{/while} - -Direct access to PHP functions: -Just as you can use PHP functions as modifiers directly, you can now access -PHP functions directly, provided they are permitted by security settings: -{time()} - -There is a new {function}...{/function} block tag to implement a template function. -This enables reuse of code sequences like a plugin function. It can call itself recursively. -Template function must be called with the new {call name=foo...} tag. - -Example: - -Template file: -{function name=menu level=0} - <ul class="level{$level}"> - {foreach $data as $entry} - {if is_array($entry)} - <li>{$entry@key}</li> - {call name=menu data=$entry level=$level+1} - {else} - <li>{$entry}</li> - {/if} - {/foreach} - </ul> -{/function} - -{$menu = ['item1','item2','item3' => ['item3-1','item3-2','item3-3' => - ['item3-3-1','item3-3-2']],'item4']} - -{call name=menu data=$menu} - - -Generated output: - * item1 - * item2 - * item3 - o item3-1 - o item3-2 - o item3-3 - + item3-3-1 - + item3-3-2 - * item4 - -The function tag itself must have the "name" attribute. This name is the tag -name when calling the function. The function tag may have any number of -additional attributes. These will be default settings for local variables. - -New {nocache} block function: -{nocache}...{/nocache} will declare a section of the template to be non-cached -when template caching is enabled. - -New nocache attribute: -You can declare variable/function output as non-cached with the nocache attribute. -Examples: - -{$foo nocache=true} -{$foo nocache} /* same */ - -{foo bar="baz" nocache=true} -{foo bar="baz" nocache} /* same */ - -{time() nocache=true} -{time() nocache} /* same */ - -Or you can also assign the variable in your script as nocache: -$smarty->assign('foo',$something,true); // third param is nocache setting -{$foo} /* non-cached */ - -$smarty.current_dir returns the directory name of the current template. - -You can use strings directly as templates with the "string" resource type. -Examples: -$smarty->display('string:This is my template, {$foo}!'); // php -{include file="string:This is my template, {$foo}!"} // template - - - -VARIABLE SCOPE / VARIABLE STORAGE -================================= - -In Smarty 2, all assigned variables were stored within the Smarty object. -Therefore, all variables assigned in PHP were accessible by all subsequent -fetch and display template calls. - -In Smarty 3, we have the choice to assign variables to the main Smarty object, -to user-created data objects, and to user-created template objects. -These objects can be chained. The object at the end of a chain can access all -variables belonging to that template and all variables within the parent objects. -The Smarty object can only be the root of a chain, but a chain can be isolated -from the Smarty object. - -All known Smarty assignment interfaces will work on the data and template objects. - -Besides the above mentioned objects, there is also a special storage area for -global variables. - -A Smarty data object can be created as follows: -$data = $smarty->createData(); // create root data object -$data->assign('foo','bar'); // assign variables as usual -$data->config_load('my.conf'); // load config file - -$data= $smarty->createData($smarty); // create data object having a parent link to -the Smarty object - -$data2= $smarty->createData($data); // create data object having a parent link to -the $data data object - -A template object can be created by using the createTemplate method. It has the -same parameter assignments as the fetch() or display() method. -Function definition: -function createTemplate($template, $cache_id = null, $compile_id = null, $parent = null) - -The first parameter can be a template name, a smarty object or a data object. - -Examples: -$tpl = $smarty->createTemplate('mytpl.tpl'); // create template object not linked to any parent -$tpl->assign('foo','bar'); // directly assign variables -$tpl->config_load('my.conf'); // load config file - -$tpl = $smarty->createTemplate('mytpl.tpl',$smarty); // create template having a parent link to the Smarty object -$tpl = $smarty->createTemplate('mytpl.tpl',$data); // create template having a parent link to the $data object - -The standard fetch() and display() methods will implicitly create a template object. -If the $parent parameter is not specified in these method calls, the template object -is will link back to the Smarty object as it's parent. - -If a template is called by an {include...} tag from another template, the -subtemplate links back to the calling template as it's parent. - -All variables assigned locally or from a parent template are accessible. If the -template creates or modifies a variable by using the {assign var=foo...} or -{$foo=...} tags, these new values are only known locally (local scope). When the -template exits, none of the new variables or modifications can be seen in the -parent template(s). This is same behavior as in Smarty 2. - -With Smarty 3, we can assign variables with a scope attribute which allows the -availablility of these new variables or modifications globally (ie in the parent -templates.) - -Possible scopes are local, parent, root and global. -Examples: -{assign var=foo value='bar'} // no scope is specified, the default 'local' -{$foo='bar'} // same, local scope -{assign var=foo value='bar' scope='local'} // same, local scope - -{assign var=foo value='bar' scope='parent'} // Values will be available to the parent object -{$foo='bar' scope='parent'} // (normally the calling template) - -{assign var=foo value='bar' scope='root'} // Values will be exported up to the root object, so they can -{$foo='bar' scope='root'} // be seen from all templates using the same root. - -{assign var=foo value='bar' scope='global'} // Values will be exported to global variable storage, -{$foo='bar' scope='global'} // they are available to any and all templates. - - -The scope attribute can also be attached to the {include...} tag. In this case, -the specified scope will be the default scope for all assignments within the -included template. - - -PLUGINS -======= - -Smarty 3 plugins follow the same coding rules as in Smarty 2. -The main difference is that the template object is now passed in place of the smarty object. -The smarty object can be still be accessed through $template->smarty. - -smarty_plugintype_name (array $params, Smarty_Internal_Template $template) - -The Smarty 2 plugins are still compatible as long as they do not make use of specific Smarty 2 internals. - - -TEMPLATE INHERITANCE: -===================== - -With template inheritance you can define blocks, which are areas that can be -overriden by child templates, so your templates could look like this: - -parent.tpl: -<html> - <head> - <title>{block name='title'}My site name{/block}</title> - </head> - <body> - <h1>{block name='page-title'}Default page title{/block}</h1> - <div id="content"> - {block name='content'} - Default content - {/block} - </div> - </body> -</html> - -child.tpl: -{extends file='parent.tpl'} -{block name='title'} -Child title -{/block} - -grandchild.tpl: -{extends file='child.tpl'} -{block name='title'}Home - {$smarty.block.parent}{/block} -{block name='page-title'}My home{/block} -{block name='content'} - {foreach $images as $img} - <img src="{$img.url}" alt="{$img.description}" /> - {/foreach} -{/block} - -We redefined all the blocks here, however in the title block we used {$smarty.block.parent}, -which tells Smarty to insert the default content from the parent template in its place. -The content block was overriden to display the image files, and page-title has also be -overriden to display a completely different title. - -If we render grandchild.tpl we will get this: -<html> - <head> - <title>Home - Child title</title> - </head> - <body> - <h1>My home</h1> - <div id="content"> - <img src="/example.jpg" alt="image" /> - <img src="/example2.jpg" alt="image" /> - <img src="/example3.jpg" alt="image" /> - </div> - </body> -</html> - -NOTE: In the child templates everything outside the {extends} or {block} tag sections -is ignored. - -The inheritance tree can be as big as you want (meaning you can extend a file that -extends another one that extends another one and so on..), but be aware that all files -have to be checked for modifications at runtime so the more inheritance the more overhead you add. - -Instead of defining the parent/child relationships with the {extends} tag in the child template you -can use the resource as follow: - -$smarty->display('extends:parent.tpl|child.tpl|grandchild.tpl'); - -Child {block} tags may optionally have a append or prepend attribute. In this case the parent block content -is appended or prepended to the child block content. - -{block name='title' append} My title {/block} - - -PHP STREAMS: -============ - -(see online documentation) - -VARIBLE FILTERS: -================ - -(see online documentation) - - -STATIC CLASS ACCESS AND NAMESPACE SUPPORT -========================================= - -You can register a class with optional namespace for the use in the template like: - -$smarty->register->templateClass('foo','name\name2\myclass'); - -In the template you can use it like this: -{foo::method()} etc. - - -======================= - -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 |