From dafcbf419bd98ce4b5f29b1ca5bc9a23a180ea52 Mon Sep 17 00:00:00 2001 From: andrei Date: Mon, 29 Apr 2002 21:13:40 +0000 Subject: [PATCH] A whole bunch of docs. --- docs/designers.sgml | 15 +- docs/programmers.sgml | 1068 ++++++++++++++++++++++++++--------------- 2 files changed, 690 insertions(+), 393 deletions(-) diff --git a/docs/designers.sgml b/docs/designers.sgml index a8e8a7b8..32f75bf5 100644 --- a/docs/designers.sgml +++ b/docs/designers.sgml @@ -289,7 +289,7 @@ email: zaphod@slartibartfast.com<br> - Current timestamp + {$smarty.now} The current timestamp can be accessed with {$smarty.now}. The number reflects the number of seconds passed since the so-called @@ -306,7 +306,7 @@ email: zaphod@slartibartfast.com<br> - Output capture buffer + {$smarty.capture} The output captured via {capture}..{/capture} construct can be accessed using {$smarty} variable. See section on @@ -315,7 +315,7 @@ email: zaphod@slartibartfast.com<br> - Loop properties + {$smarty.section}, {$smarty.foreach} {$smarty} variable can be used to refer to 'section' and 'foreach' loop properties. See docs for @@ -323,6 +323,15 @@ email: zaphod@slartibartfast.com<br> foreach. + + + {$smarty.template} + + This variable contains the name of the current template being + processed. + + + diff --git a/docs/programmers.sgml b/docs/programmers.sgml index 3da3552e..8f9a1bd5 100644 --- a/docs/programmers.sgml +++ b/docs/programmers.sgml @@ -136,6 +136,22 @@ $global_assign to a default value. + + $autoload_filters + + If there are some filters that you wish to load on every template + invocation, you can specify them using this variable and Smarty will + automatically load them for you. The variable is an associative array + where keys are filter types and values are arrays of the filter + names. For example: + + +$smarty->autoload_filters = array('pre' => array('trim', 'stamp'), + 'output' => array('convert')); + + + + $compile_check @@ -395,35 +411,6 @@ Methods - - assign - - - void assign - mixed var - - - void assign - string varname - mixed var - - - - This is used to assign values to the templates. You can - explicitly pass name/value pairs, or associative arrays - containing the name/value pairs. - - - assign - -// passing name/value pairs -$smarty->assign("Name","Fred"); -$smarty->assign("Address",$address); - -// passing an associative array -$smarty->assign(array("city" => "Lincoln","state" => "Nebraska")); - - append @@ -451,6 +438,72 @@ $smarty->append("Address",$address); // passing an associative array $smarty->append(array("city" => "Lincoln","state" => "Nebraska")); + + + + assign + + + void assign + mixed var + + + void assign + string varname + mixed var + + + + This is used to assign values to the templates. You can + explicitly pass name/value pairs, or associative arrays + containing the name/value pairs. + + + assign + +// passing name/value pairs +$smarty->assign("Name","Fred"); +$smarty->assign("Address",$address); + +// passing an associative array +$smarty->assign(array("city" => "Lincoln","state" => "Nebraska")); + + + + clear_all_assign + + + void clear_all_assign + + + + + This clears the values of all assigned variables. + + +clear_all_assign + +// clear all assigned variables +$smarty->clear_all_assign(); + + + + clear_all_cache + + + void clear_all_cache + + + + + This clears the entire template cache. This was added to Smarty + 1.3.0. + + +clear_all_cache + +// clear the entire cache +$smarty->clear_all_cache(); @@ -474,24 +527,6 @@ $smarty->clear_assign("Name"); // clear multiple variables $smarty->clear_assign(array("Name","Address","Zip")); - - - - clear_all_assign - - - void clear_all_assign - - - - - This clears the values of all assigned variables. - - -clear_all_assign - -// clear all assigned variables -$smarty->clear_all_assign(); @@ -518,25 +553,6 @@ $smarty->clear_cache("index.tpl"); // clear the cache for a particular cache id in an multiple-cache template $smarty->clear_cache("index.tpl","CACHEID"); - - - - clear_all_cache - - - void clear_all_cache - - - - - This clears the entire template cache. This was added to Smarty - 1.3.0. - - -clear_all_cache - -// clear the entire cache -$smarty->clear_all_cache(); @@ -560,307 +576,6 @@ $smarty->clear_compiled_tpl("index.tpl"); // clear entire compile directory $smarty->clear_compiled_tpl(); - - - - register_function - - - void register_function - string name - string impl - - - - Use this to dynamically register template function plugins. - Pass in the template function name, followed by the PHP - function name that implements it. - - -register_function - -$smarty->register_function("date_now", "print_current_date"); - -function print_current_date ($params) { - extract($params); - if(empty($format)) - $format="%b %e, %Y"; - echo strftime($format,time()); -} - -// now you can use this in Smarty to print the current date: {date_now} -// or, {date_now format="%Y/%m/%d"} to format it. - - - - unregister_function - - - void unregister_function - string name - - - - Use this to dynamically unregister template function plugin. - Pass in the template function name. - - -unregister_function - -// we don't want template designers to have access to system files - -$smarty->unregister_function("fetch"); - - - - register_modifier - - - void register_modifier - string name - string impl - - - - Use this to dynamically register modifier plugin. Pass in the - template modifier name, followed by the PHP function that it - implements it. - - -register_modifier - -// let's map PHP's stripslashes function to a Smarty modifier. - -$smarty->register_modifier("sslash","stripslashes"); - -// now you can use {$var|sslash} to strip slashes from variables - - - - unregister_modifier - - - void unregister_modifier - string name - - - - Use this to dynamically unregister modifier plugin. Pass in the - template modifier name. - - -unregister_modifier - -// we don't want template designers to strip tags from elements - -$smarty->unregister_modifier("strip_tags"); - - - - register_resource - - - void register_resource - string name - array resource_funcs - - - - Use this to dynamically register a resource plugin with Smarty. - Pass in the name of the resource and the array of PHP functions - implementing it. See - template resources - for more information on how to setup a function for fetching - templates. - - -register_resource - -$smarty->register_resource("db", array("db_get_template", - "db_get_timestamp", - "db_get_secure", - "db_get_trusted")); - - - - unregister_resource - - - void unregister_resource - string name - - - - Use this to dynamically unregister a resource plugin. Pass in the - name of the resource. - - -unregister_resource - -$smarty->unregister_resource("db"); - - - - register_prefilter - - - void register_prefilter - string function_name - - - - Use this to dynamically register prefilters to run templates - through before they are compiled. See template prefilters for - more information on how to setup a prefiltering function. - - - - unregister_prefilter - - - void unregister_prefilter - string function_name - - - - Use this to dynamically unregister a prefilter. - - - - register_postfilter - - - void register_postfilter - string function_name - - - - Use this to dynamically register postfilters to run templates - through after they are compiled. See template postfilters for - more information on how to setup a postfiltering function. - - - - unregister_postfilter - - - void unregister_postfilter - string function_name - - - - Use this to dynamically unregister a postfilter. - - - - register_compiler_function - - - void register_compiler_function - string name - string impl - - - - Use this to dynamically register a compiler function plugin. - Pass in the compiler function name, followed by the PHP - function that implements it. - - - - unregister_compiler_function - - - void unregister_compiler_function - string name - - - - Use this to dynamically unregister a compiler function. Pass in - the name of the compiler function. - - - - trigger_error - - - void trigger_error - string error_msg - [int level] - - - - This function can be used to output an error message using Smarty. - level parameter can be one of the values - used for trigger_error() PHP function, i.e. E_USER_NOTICE, - E_USER_WARNING, etc. By default it's E_USER_WARNING. This function - was added to Smarty 2.0. - - - - - is_cached - - - void is_cached - string template - [string cache_id] - - - - This returns true if there is a valid cache for this template. - This only works if caching is set to true. This - was added to Smarty 1.3.0. - - -is_cached - -$smarty->caching = true; - -if(!$smarty->is_cached("index.tpl")) { - // do database calls, assign vars here -} - -$smarty->display("index.tpl"); - - - You can also pass a cache id as an an optional second parameter - in case you want multiple caches for the given template. - - -is_cached with multiple-cache template - -$smarty->caching = true; - -if(!$smarty->is_cached("index.tpl","FrontPage")) { - // do database calls, assign vars here -} - -$smarty->display("index.tpl","FrontPage"); - - - - get_template_vars - - - array get_template_vars - - - - - This gets an array of the currently assigned template vars. - - -get_template_vars - -// get all assigned template vars -$tpl_vars = $smarty->get_template_vars(); - -// take a look at them -var_dump($tpl_vars); @@ -992,6 +707,419 @@ $output = $smarty->fetch("index.tpl"); // do something with $output here echo $output; + + + + get_template_vars + + + array get_template_vars + + + + + This gets an array of the currently assigned template vars. + + +get_template_vars + +// get all assigned template vars +$tpl_vars = $smarty->get_template_vars(); + +// take a look at them +var_dump($tpl_vars); + + + + is_cached + + + void is_cached + string template + [string cache_id] + + + + This returns true if there is a valid cache for this template. + This only works if caching is set to true. This + was added to Smarty 1.3.0. + + +is_cached + +$smarty->caching = true; + +if(!$smarty->is_cached("index.tpl")) { + // do database calls, assign vars here +} + +$smarty->display("index.tpl"); + + + You can also pass a cache id as an an optional second parameter + in case you want multiple caches for the given template. + + +is_cached with multiple-cache template + +$smarty->caching = true; + +if(!$smarty->is_cached("index.tpl","FrontPage")) { + // do database calls, assign vars here +} + +$smarty->display("index.tpl","FrontPage"); + + + + load_filter + + + void load_filter + string type + string name + + + + This function can be used to load a filter plugin. The first + argument specifies the type of the filter to load and can be one + of the following: 'pre', 'post', or 'output'. The second argument + specifies the name of the filter plugin, for example, 'trim'. + + +loading filter plugins + +$smarty->load('pre', 'trim'); // load prefilter named 'trim' +$smarty->load('pre', 'datefooter'); // load another prefilter named 'datefooter' +$smarty->load('output', 'compress'); // load output filter named 'compress' + + + + register_block + + + void register_block + string name + string impl + + + + Use this to dynamically register block functions plugins. + Pass in the block function name, followed by the PHP + function name that implements it. + + +register_block + +/* PHP */ +$smarty->register_block("translate", "do_translation"); + +function do_translation ($params, $content, &$smarty) { + if ($content) { + $lang = $params['lang']; + // do some translation with $content + echo $translation; + } +} + +{* template *} +{translate lang="br"} + Hello, world! +{/translate} + + + + register_compiler_function + + + void register_compiler_function + string name + string impl + + + + Use this to dynamically register a compiler function plugin. + Pass in the compiler function name, followed by the PHP + function that implements it. + + + + register_function + + + void register_function + string name + string impl + + + + Use this to dynamically register template function plugins. + Pass in the template function name, followed by the PHP + function name that implements it. + + +register_function + +$smarty->register_function("date_now", "print_current_date"); + +function print_current_date ($params) { + extract($params); + if(empty($format)) + $format="%b %e, %Y"; + echo strftime($format,time()); +} + +// now you can use this in Smarty to print the current date: {date_now} +// or, {date_now format="%Y/%m/%d"} to format it. + + + + register_modifier + + + void register_modifier + string name + string impl + + + + Use this to dynamically register modifier plugin. Pass in the + template modifier name, followed by the PHP function that it + implements it. + + +register_modifier + +// let's map PHP's stripslashes function to a Smarty modifier. + +$smarty->register_modifier("sslash","stripslashes"); + +// now you can use {$var|sslash} to strip slashes from variables + + + + register_outputfilter + + + void register_outputfilter + string function_name + + + + Use this to dynamically register outputfilters to operate on + a template's output before it is displayed. See + template output + filters + for more information on how to set up an output filter function. + + + + register_postfilter + + + void register_postfilter + string function_name + + + + Use this to dynamically register postfilters to run templates + through after they are compiled. See template postfilters for + more information on how to setup a postfiltering function. + + + + register_prefilter + + + void register_prefilter + string function_name + + + + Use this to dynamically register prefilters to run templates + through before they are compiled. See template prefilters for + more information on how to setup a prefiltering function. + + + + register_resource + + + void register_resource + string name + array resource_funcs + + + + Use this to dynamically register a resource plugin with Smarty. + Pass in the name of the resource and the array of PHP functions + implementing it. See + template resources + for more information on how to setup a function for fetching + templates. + + +register_resource + +$smarty->register_resource("db", array("db_get_template", + "db_get_timestamp", + "db_get_secure", + "db_get_trusted")); + + + + trigger_error + + + void trigger_error + string error_msg + [int level] + + + + This function can be used to output an error message using Smarty. + level parameter can be one of the values + used for trigger_error() PHP function, i.e. E_USER_NOTICE, + E_USER_WARNING, etc. By default it's E_USER_WARNING. This function + was added to Smarty 2.0. + + + + + template_exists + + + bool template_exists + string template + + + + This function checks whether the specified template exists. It can + accept either a path to the template on the filesystem or a + resource string specifying the template. + + + + unregister_block + + + void unregister_block + string name + + + + Use this to dynamically unregister block function plugin. + Pass in the block function name. + + + + unregister_compiler_function + + + void unregister_compiler_function + string name + + + + Use this to dynamically unregister a compiler function. Pass in + the name of the compiler function. + + + + unregister_function + + + void unregister_function + string name + + + + Use this to dynamically unregister template function plugin. + Pass in the template function name. + + +unregister_function + +// we don't want template designers to have access to system files + +$smarty->unregister_function("fetch"); + + + + unregister_modifier + + + void unregister_modifier + string name + + + + Use this to dynamically unregister modifier plugin. Pass in the + template modifier name. + + +unregister_modifier + +// we don't want template designers to strip tags from elements + +$smarty->unregister_modifier("strip_tags"); + + + + unregister_outputfilter + + + void unregister_outputfilter + string function_name + + + + Use this to dynamically unregister an output filter. + + + + unregister_postfilter + + + void unregister_postfilter + string function_name + + + + Use this to dynamically unregister a postfilter. + + + + unregister_prefilter + + + void unregister_prefilter + string function_name + + + + Use this to dynamically unregister a prefilter. + + + + unregister_resource + + + void unregister_resource + string name + + + + Use this to dynamically unregister a resource plugin. Pass in the + name of the resource. + + +unregister_resource + +$smarty->unregister_resource("db"); @@ -1004,10 +1132,13 @@ echo $output; Template prefilters are PHP functions that your templates are ran through before they are compiled. This is good for preprocessing your templates to remove unwanted comments, keeping an eye on what people are putting - in their templates, etc. Prefilters are processed in the order they are + in their templates, etc. Prefilters can be either registered or loaded from - the plugin directory. - Smarty will pass the template source code as the first argument, an + the plugins directory by using + load_filter() function or by + setting + $autoload_filters variable. + Smarty will pass the template source code as the first argument, and expect the function to return the resulting template source code. @@ -1015,7 +1146,7 @@ echo $output; <?php // put this in your application -function remove_dw_comments($tpl_source) +function remove_dw_comments($tpl_source, &$smarty) { return preg_replace("/<!--#.*-->/U","",$tpl_source); } @@ -1034,11 +1165,14 @@ $smarty->display("index.tpl"); Postfilters Template postfilters are PHP functions that your templates are ran through - after they are compiled. Postfilters are processed in the order they are + after they are compiled. Postfilters can be either registered or loaded - from the plugin - directory. Smarty will pass the compiled template code as the first - argument, an expect the function to return the result of the + from the plugins directory by using + load_filter() function or by + setting + $autoload_filters + variable. Smarty will pass the compiled template code as the first + argument, and expect the function to return the result of the processing. @@ -1046,7 +1180,7 @@ $smarty->display("index.tpl"); <?php // put this in your application -function add_header_comment($tpl_source) +function add_header_comment($tpl_source, &$smarty) { return "<?php echo \"<!-- Created by Smarty! -->\n\" ?>\n".$tpl_source; } @@ -1062,6 +1196,49 @@ $smarty->display("index.tpl"); + + Output Filters + + When the template is invoked via display() or fetch(), its output can be + sent through one or more output filters. This differs from postfilters + because postfilters operate on compiled templates before they are saved to + the disk, and output filters operate on the template output when it is + executed. + + + + Output filters can be either + registered or loaded + from the plugins directory by using + load_filter() function or by + setting + $autoload_filters + variable. Smarty will pass the template output as the first argument, + and expect the function to return the result of the processing. + + + using a template outputfilter + +<?php +// put this in your application +function protect_email($tpl_output, &$smarty) +{ + $tpl_output = + preg_replace('!(\S+)@([a-zA-Z0-9\.\-]+\.([a-zA-Z]{2,3}|[0-9]{1,3}))!', + '$1%40$2', $tpl_output); + return $tpl_output; +} + +// register the outputfilter +$smarty->register_outputfilter("protect_email"); +$smarty->display("index.tpl"); + +// now any occurrence of an email address in the template output will have +// a simple protection against spambots +?> + + + Cache Handler Function @@ -1391,9 +1568,11 @@ $smarty->default_template_handler_func = 'make_template'; functions modifiers + block functions compiler functions prefilters postfilters + outputfilters resources inserts @@ -1409,17 +1588,16 @@ $smarty->default_template_handler_func = 'make_template'; How Plugins Work Plugins are always loaded on demand. Only the specific modifiers, - functions, resources, etc invoked in the templates or PHP scripts will - be loaded. Moreover, each plugin is loaded only once, even if you have + functions, resources, etc invoked in the templates scripts will be + loaded. Moreover, each plugin is loaded only once, even if you have several different instances of Smarty running within the same request. - Pre/post-filters are a bit of a special case. If a pre/post-filter - plugin is found in the plugins directory, it will always be loaded - because these filters are never explicitly mentioned in the template - language. This also means that the order in which multiple prefilters - or postfilters is executed depends on the way they are named - (basically, alphabetical order). + Pre/postfilters and output filters are a bit of a special case. Since + they are not mentioned in the templates, they must be registered or + loaded explicitly via API functions before the template is processed. + The order in which multiple filters of the same type are executed + depends on the order in which they are registered or loaded. There is only one plugins directory (for performance reasons). To @@ -1449,9 +1627,11 @@ $smarty->default_template_handler_func = 'make_template'; function modifier + block compiler prefilter postfilter + outputfilter resource insert @@ -1482,12 +1662,6 @@ $smarty->default_template_handler_func = 'make_template'; needs is not found, or if the file or the plugin function are named improperly. - - - Note that pre/postfilters still have to be correctly named even though - the names are not used for anything except their order of execution. - - @@ -1704,6 +1878,80 @@ function smarty_modifier_truncate($string, $length = 80, $etc = '...', + Block Functions + + + void smarty_function_name + array $params + mixed $content + object &$smarty + + + + Block functions are functions of the form: {func} .. {/func}. In other + words, they enclose a template block and operate on the contents of + this block. Block functions take precedence over custom functions of + the same name, that is, you cannot have both custom function {func} and + block function {func} .. {/func}. + + + Your function implementation is called twice by Smarty: + once for the opening tag, and once for the closing tag. + + + Only the opening tag of the block function may have attributes. All + attributes passed to template functions from the template are contained + in the $params as an associative array. You can + either access those values directly, e.g. + $params['start'] or use + extract($params) to import them into the symbol + table. The opening tag attributes are also accessible to your function + when processing the closing tag. + + + The value of $content variable depends on + whether your function is called for the opening or closing tag. In case + of the opening tag, it will be null, and in case of + the closing tag it will be the contents of the template block. + Note that the template block will have already been processed by + Smarty, so all you will receive is the template output, not the + template source. + + + If you have nested block functions, it's possible to find out what the + parent block function is by accessing + $smarty->_tag_stack variable. Just do a var_dump() + on it and the structure should be apparent. + + + See also: + register_block(), + unregister_block(). + + + block function + +<?php +/* + * Smarty plugin + * ------------------------------------------------------------- + * File: block.translate.php + * Type: block + * Name: translate + * Purpose: translate a block of text + * ------------------------------------------------------------- + */ +function smarty_block_eightball($params, $content, &$smarty) +{ + if ($content) { + $lang = $params['lang']; + // do some intelligent translation thing here with $content + echo $translation; + } +} + + + Compiler Functions Compiler functions are called only during compilation of the template. @@ -1843,6 +2091,46 @@ echo 'index.tpl compiled at 2002-02-20 20:02'; + Output Filters + + Output filter plugins operate on a template's output, after the + template is loaded and executed, but before the output is displayed. + + + + string smarty_outputfilter_name + string $template_output + object &$smarty + + + + The first parameter to the output filter function is the template + output that needs to be processed, and the second parameter is the + instance of Smarty invoking the plugin. The plugin is supposed to do + the processing and return the results. + + + output filter plugin + +/* + * Smarty plugin + * ------------------------------------------------------------- + * File: outputfilter.protect_email.php + * Type: outputfilter + * Name: protect_email + * Purpose: Converts @ sign in email addresses to %40 as + * a simple protection against spambots + * ------------------------------------------------------------- + */ + function smarty_outputfilter_protect_email($output, &$smarty) + { + return preg_replace('!(\S+)@([a-zA-Z0-9\.\-]+\.([a-zA-Z]{2,3}|[0-9]{1,3}))!', + '$1%40$2', $output); + } + + + + Resources Resource plugins are meant as a generic way of providing template