From eea494dcd21cde3dea8006fc2f7582e37af84091 Mon Sep 17 00:00:00 2001 From: nlopess Date: Sun, 5 Jun 2005 15:47:25 +0000 Subject: [PATCH] more examples, WS and linking from Peter. Thanks :) --- docs/en/appendixes/tips.xml | 160 +++++++++++------- docs/en/appendixes/troubleshooting.xml | 109 +++++++++++- .../language-modifier-date-format.xml | 8 +- .../language-variables-smarty.xml | 7 +- .../programmers/api-functions/api-fetch.xml | 72 ++++---- .../api-functions/api-load-filter.xml | 3 +- .../api-register-compiler-function.xml | 36 ++-- .../api-functions/api-register-function.xml | 37 ++-- .../api-functions/api-register-modifier.xml | 35 ++-- .../api-functions/api-register-object.xml | 5 +- .../api-register-outputfilter.xml | 42 +++-- .../api-functions/api-register-postfilter.xml | 42 +++-- .../api-functions/api-register-prefilter.xml | 49 +++--- .../api-functions/api-template-exists.xml | 49 ++++++ .../variable-autoload-filters.xml | 11 +- .../api-variables/variable-cache-dir.xml | 11 +- .../api-variables/variable-caching.xml | 3 +- .../api-variables/variable-compile-dir.xml | 8 +- .../api-variables/variable-config-dir.xml | 7 +- .../api-variables/variable-debug-tpl.xml | 3 +- .../api-variables/variable-php-handling.xml | 6 +- .../api-variables/variable-plugins-dir.xml | 38 ++++- .../api-variables/variable-template-dir.xml | 9 +- .../api-variables/variable-use-sub-dirs.xml | 5 +- .../programmers/caching/caching-cacheable.xml | 31 ++-- docs/en/programmers/smarty-constants.xml | 5 +- 26 files changed, 541 insertions(+), 250 deletions(-) diff --git a/docs/en/appendixes/tips.xml b/docs/en/appendixes/tips.xml index f458f4f6..f0c6f613 100644 --- a/docs/en/appendixes/tips.xml +++ b/docs/en/appendixes/tips.xml @@ -12,7 +12,9 @@ table backgrounds work properly. Many would use an {if} statement to handle this, but there is a shorthand way with Smarty, using the - default variable modifier. + default + variable modifier. Printing   when a variable is empty @@ -69,53 +71,71 @@ Passing variable title to header template When the majority of your templates use the same headers and footers, it - is common to split those out into their own templates and include them. + is common to split those out into their own templates and + {include} them. But what if the header needs to have a different title, depending on what page you are coming from? You can pass the title to the header when it is included. - + + Passing the title variable to the header template + + + mainpage.tpl + + - -archives.tpl ------------- + + archives.tpl + + + - -{$title|default:"BC News"} - - - - -footer.tpl ----------- - - ]]> - + + + header.tpl + + + + +{$title|default:"BC News"} + + +]]> + + + + footer.tpl + + + + +]]> + + + When the main page is drawn, the title of "Main Page" is passed to the - header.tpl, and will subsequently be used as the title. When the + header.tpl, and will subsequently be used as the title. When the archives page is drawn, the title will be "Archives". Notice in the - archive example, we are using a variable from the archives_page.conf + archive example, we are using a variable from the + archives_page.conf file instead of a hard coded variable. Also notice that "BC News" is printed if the $title variable is not set, using the default @@ -191,7 +211,7 @@ Jan 4, 2001 $startDate = makeTimeStamp($startDate_Year, $startDate_Month, $startDate_Day); -function makeTimeStamp($year="", $month="", $day="") +function makeTimeStamp($year='', $month='', $day='') { if(empty($year)) { $year = strftime("%Y"); @@ -222,22 +242,27 @@ function makeTimeStamp($year="", $month="", $day="") WAP/WML - WAP/WML templates require a php Content-Type header to be passed along + WAP/WML templates require a php + Content-Type header + to be passed along with the template. The easist way to do this would be to write a custom - function that prints the header. If you are using caching, that won't - work so we'll do it using the insert tag (remember insert tags are not - cached!) Be sure that there is nothing output to the browser before the + function that prints the header. If you are using + caching, that won't + work so we'll do it using the + {insert} + tag; remember {insert} tags are not + cached! Be sure that there is nothing output to the browser before the template, or else the header may fail. - using insert to write a WML Content-Type header + using {insert} to write a WML Content-Type header - + + - - - - - - - -

+ + + + + + + +

Welcome to WAP with Smarty! - Press OK to continue... -

- - - -

+ Press OK to continue... +

+ + + +

Pretty easy isn't it? -

- +

+ ]]> @@ -289,8 +314,8 @@ function insert_header($params) Traditionally, programming templates into your applications goes as follows: First, you accumulate your variables within your PHP application, (maybe with database queries.) Then, you instantiate your - Smarty object, assign the variables and - display the template. So lets + Smarty object, assign() the variables and + display() the template. So lets say for example we have a stock ticker on our template. We would collect the stock data in our application, then assign these variables in the template and display it. Now wouldn't it be nice if you could @@ -303,35 +328,39 @@ function insert_header($params) componentized template + + function.load_ticker.php - + drop file in + $plugins directory + assign($params['assign'], $ticker_info); } ?> ]]> + + index.tpl + {mailto} plugin. Example of Obfuscating an E-mail Address @@ -369,11 +399,13 @@ Send inquiries to Technical Note This method isn't 100% foolproof. A spammer could conceivably program his - e-mail collector to decode these values, but not likely. + e-mail collector to decode these values, but not likely....hopefully. - See also escape. + See also escape + and + {mailto}. diff --git a/docs/en/appendixes/troubleshooting.xml b/docs/en/appendixes/troubleshooting.xml index abb15311..1bd8f800 100644 --- a/docs/en/appendixes/troubleshooting.xml +++ b/docs/en/appendixes/troubleshooting.xml @@ -27,7 +27,7 @@ Fatal error: Smarty: [in index.tpl line 28]: syntax error: missing section name After that, the error consists of the actual line number in the Smarty class that the error occured. - + There are certain errors that Smarty cannot catch, such as missing close tags. These types of errors usually end up in PHP compile-time @@ -42,7 +42,7 @@ Parse error: parse error in /path/to/smarty/templates_c/index.tpl.php on line 75 ]]> - + When you encounter a PHP parsing error, the error line number will correspond to the compiled PHP script, not the template itself. Usually @@ -55,6 +55,110 @@ Parse error: parse error in /path/to/smarty/templates_c/index.tpl.php on line 75 go to the line number to figure out where the corresponding error is in the template. + + + + Other common errors + + + + + + + + + + + The $template_dir + is incorrect, doesn't exist or + the file index.tpl is not in the + templates/ directory + + + + + A {config_load} + function is within a template (or + config_load() + has been called) and either + $config_dir + is incorrent , does not exist or + site.conf is not in the directory. + + + + + + + + + + + + + Either the + $compile_dir + is incorrectly set, the directory does not exist, + or templates_c is a + file and not a directory. + + + + + + + The $compile_dir + is not writable by the web server. See the bottom of the + installing smarty page + for permissions. + + + + + + + + + This means that + $caching is enabled and either; + the + $cache_dir + is incorrectly set, the directory does not exist, + or cache is a + file and not a directory. + + + + + + + + + This means that + $caching is enabled and the + $cache_dir + is not writable by the web server. See the bottom of the + installing smarty page + for permissions. + + + + + See also debugging, @@ -84,3 +188,4 @@ vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 --> + diff --git a/docs/en/designers/language-modifiers/language-modifier-date-format.xml b/docs/en/designers/language-modifiers/language-modifier-date-format.xml index 12bbdda9..07ec0454 100644 --- a/docs/en/designers/language-modifiers/language-modifier-date-format.xml +++ b/docs/en/designers/language-modifiers/language-modifier-date-format.xml @@ -44,9 +44,9 @@ or any string made up of month day year, parsable by strtotime(). Designers can then use date_format to have complete control of the - formatting of the date. If the date passed to date_format is empty - and a second parameter is passed, that will be used as the date to - format. + formatting of the date. If the date passed to + date_format is empty and a second parameter is passed, + that will be used as the date to format. date_format @@ -60,7 +60,7 @@ $smarty->assign('yesterday', strtotime('-1 day')); ]]> - Where template is: + Where template is (uses $smarty.now): {$smarty} reserved variable - The reserved {$smarty} variable can be used to access several + The PHP reserved {$smarty} variable can be used to access several special template variables. The full list of them follows. @@ -12,7 +12,10 @@ The request variables such as $_GET, $_POST, $_COOKIE, $_SERVER, $_ENV and $_SESSION - can be accessed as demonstrated in the examples below: + (see $request_vars_order + and $request_use_auto_globals + ) can be accessed as demonstrated in the examples below: displaying request variables diff --git a/docs/en/programmers/api-functions/api-fetch.xml b/docs/en/programmers/api-functions/api-fetch.xml index 6d75dcab..b7acc03b 100644 --- a/docs/en/programmers/api-functions/api-fetch.xml +++ b/docs/en/programmers/api-functions/api-fetch.xml @@ -25,10 +25,10 @@ ¶meter.compileid; - - -fetch() - + + + fetch() + fetch('index.tpl'); echo $output; ?> ]]> - - - - - - -Using fetch() to send an email - - The email_body.txt template + + - + + + + Using fetch() to send an email + + The email_body.tpl template + + - - - The email_disclaimer.txt template - - + + + The email_disclaimer.tpl template which uses the + {textformat} modifier. + + - - - and the php script using the PHP - mail() function - - + + + and the php script using the PHP + mail() function + + getRow($sql); $smarty->assign('contact', $contact); -mail($contact['email'], 'Subject', $smarty->fetch('email_body.txt')); +mail($contact['email'], 'Subject', $smarty->fetch('email_body.tpl')); ?> ]]> - - - - + + + See also @@ -150,5 +154,3 @@ vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 --> - - diff --git a/docs/en/programmers/api-functions/api-load-filter.xml b/docs/en/programmers/api-functions/api-load-filter.xml index 328c109f..bac7590e 100644 --- a/docs/en/programmers/api-functions/api-load-filter.xml +++ b/docs/en/programmers/api-functions/api-load-filter.xml @@ -41,7 +41,8 @@ $smarty->load_filter('output', 'compress'); See also register_prefilter(), register_postfilter(), - register_outputfilter() + register_outputfilter(), + $autoload_filters and Advanced features. diff --git a/docs/en/programmers/api-functions/api-register-compiler-function.xml b/docs/en/programmers/api-functions/api-register-compiler-function.xml index 5eda172d..16f3a193 100644 --- a/docs/en/programmers/api-functions/api-register-compiler-function.xml +++ b/docs/en/programmers/api-functions/api-register-compiler-function.xml @@ -21,24 +21,30 @@ The php-function callback impl can be either: - - (a) a string containing the function name - - (b) an array of the form array(&$object, $method) with - &$object being a reference to an - object and $method being a string - containing the mehod-name - - (c) an array of the form - array(&$class, $method) with - $class being a classname and - $method being a class method of that - class. - + + + + a string containing the function name + + + an array of the form array(&$object, $method) with + &$object being a reference to an + object and $method being a string + containing the mehod-name + + + an array of the form + array(&$class, $method) with + $class being a classname and + $method being a class method of that + class. + + + cacheable can be omitted in most cases. See Controlling - Cacheability of Plugins' Output on how to it properly. + Cacheability of Plugins' Output on how to use it properly. diff --git a/docs/en/programmers/api-functions/api-register-function.xml b/docs/en/programmers/api-functions/api-register-function.xml index b383a6b6..5225f928 100644 --- a/docs/en/programmers/api-functions/api-register-function.xml +++ b/docs/en/programmers/api-functions/api-register-function.xml @@ -22,22 +22,29 @@ The php-function callback impl can be either - - (a) a string containing the function name + + + + a string containing the function name + + + + an array of the form + array(&$object, $method) with + &$object being a reference to an + object and $method being a string + containing the mehod-name + + + + an array of the form array(&$class, $method) + with $class being a classname and + $method being a class method of that + class. - - (b) an array of the form - array(&$object, $method) with - &$object being a reference to an - object and $method being a string - containing the mehod-name - - - (c) an array of the form array(&$class, $method) - with $class being a classname and - $method being a class method of that - class. - + + + cacheable and cache_attrs can be omitted in most cases. See - The php-function callback impl can be either (a) a string - containing the function name or (b) an array of the form - array(&$object, $method) with - &$object being a reference to an - object and $method being a string - containing the mehod-name or (c) an array of the form - array(&$class, $method) with - $class being a classname and - $method being a class method of that - class. + The php-function callback impl can be either + + + a string containing the function name + + + an array of the form array(&$object, + $method) with &$object + being a reference to an + object and $method being a string + containing the mehod-name + + + + an array of the form + array(&$class, $method) with + $class being a classname and + $method being a class method of that + class. + + + + register_modifier() @@ -59,7 +72,7 @@ $smarty->register_modifier('sslash', 'stripslashes'); modifiers, Extending Smarty with plugins and - Plugin modifiers, + Creating Plugin modifiers, diff --git a/docs/en/programmers/api-functions/api-register-object.xml b/docs/en/programmers/api-functions/api-register-object.xml index 9d301ff0..69c4bc18 100644 --- a/docs/en/programmers/api-functions/api-register-object.xml +++ b/docs/en/programmers/api-functions/api-register-object.xml @@ -22,7 +22,10 @@ for examples. - See also unregister_object(). + See also + get_registered_object(), + and + unregister_object(). diff --git a/docs/en/programmers/api-functions/api-register-outputfilter.xml b/docs/en/programmers/api-functions/api-register-outputfilter.xml index 3fcd5a1f..363e5afa 100644 --- a/docs/en/programmers/api-functions/api-register-outputfilter.xml +++ b/docs/en/programmers/api-functions/api-register-outputfilter.xml @@ -23,30 +23,36 @@ The php-function callback function can be either - - (a) a string - containing the function name - - - (b) an array of the form - array(&$object, $method) with - &$object being a reference to an - object and $method being a string - containing the mehod-name - - - (c) an array of the form - array(&$class, $method) with - $class being a classname and - $method being a class method of that - class. - + + + + a string containing the function name + + + + an array of the form + array(&$object, $method) with + &$object being a reference to an + object and $method being a string + containing the mehod-name + + + + an array of the form + array(&$class, $method) with + $class being a classname and + $method being a class method of that + class. + + + See also unregister_outputfilter(), register_prefilter(), register_postfilter(), load_filter(), +$autoload_filters and template output filters. diff --git a/docs/en/programmers/api-functions/api-register-postfilter.xml b/docs/en/programmers/api-functions/api-register-postfilter.xml index 2281e027..4d92801e 100644 --- a/docs/en/programmers/api-functions/api-register-postfilter.xml +++ b/docs/en/programmers/api-functions/api-register-postfilter.xml @@ -20,31 +20,37 @@ The php-function callback function can be either + + + + + a string containing the function name - - (a) a string containing the function name - - - (b) an array of the form - array(&$object, $method) with - &$object being a reference to an - object and $method being a string - containing the mehod-name - - - (c) an array of the form - array(&$class, $method) with - $class being a classname and - $method being a class method of that - class. - - + + + an array of the form + array(&$object, $method) with + &$object being a reference to an + object and $method being a string + containing the mehod-name + + + + an array of the form + array(&$class, $method) with + $class being a classname and + $method being a class method of that + class. + + + See also unregister_postfilter(), register_prefilter(), register_ouputfilter(), load_filter(), + $autoload_filters and template output filters. diff --git a/docs/en/programmers/api-functions/api-register-prefilter.xml b/docs/en/programmers/api-functions/api-register-prefilter.xml index 9a94babc..18008a3e 100644 --- a/docs/en/programmers/api-functions/api-register-prefilter.xml +++ b/docs/en/programmers/api-functions/api-register-prefilter.xml @@ -18,37 +18,46 @@ linkend="advanced.features.prefilters">template prefilters for more information on how to setup a prefiltering function. + - The php-function callback function can be either - - - (a) a string - containing the function name - - - (b) an array of the form - array(&$object, $method) with - &$object being a reference to an - object and $method being a string - containing the mehod-name - - - (c) an array of the form - array(&$class, $method) with - $class being a classname and - $method being a class method of that - class. + The php-function callback function can be either + + + + a string containing the function name + + + + an array of the form + array(&$object, $method) with + &$object being a reference to an + object and $method being a string + containing the mehod-name + + + + an array of the form + array(&$class, $method) with + $class being a classname and + $method being a class method of that + class. + + + + See also unregister_prefilter(), register_postfilter(), register_ouputfilter(), load_filter(), + $autoload_filters and template output filters. - + + + diff --git a/docs/en/programmers/api-variables/variable-caching.xml b/docs/en/programmers/api-variables/variable-caching.xml index 1b431afe..b7b784f7 100644 --- a/docs/en/programmers/api-variables/variable-caching.xml +++ b/docs/en/programmers/api-variables/variable-caching.xml @@ -3,7 +3,8 @@ $caching - This tells Smarty whether or not to cache the output of the templates. + This tells Smarty whether or not to cache the output of the templates + to the $cache_dir. By default this is set to 0, or disabled. If your templates generate redundant content, it is advisable to turn on $caching. This will result in significant performance gains. You can also have diff --git a/docs/en/programmers/api-variables/variable-compile-dir.xml b/docs/en/programmers/api-variables/variable-compile-dir.xml index 33eebb72..898ea80f 100644 --- a/docs/en/programmers/api-variables/variable-compile-dir.xml +++ b/docs/en/programmers/api-variables/variable-compile-dir.xml @@ -4,10 +4,14 @@ $compile_dir This is the name of the directory where compiled templates are - located. By default this is "./templates_c", meaning that it + located. By default this is + "./templates_c" + , meaning that it will look for the compile directory in the same directory as the executing php script. This directory must - be writeable by the web server. See also + be writeable by the web server + (see install). + Also $use_sub_dirs. diff --git a/docs/en/programmers/api-variables/variable-config-dir.xml b/docs/en/programmers/api-variables/variable-config-dir.xml index a204b84a..5920a662 100644 --- a/docs/en/programmers/api-variables/variable-config-dir.xml +++ b/docs/en/programmers/api-variables/variable-config-dir.xml @@ -6,9 +6,10 @@ This is the directory used to store config files used in the - templates. Default is "./configs", meaning that it will look - for the configs directory in the same directory as the - executing php script. + templates. Default is + "./configs", meaning that + Smarty will look for the configs directory in the same directory + as the executing php script. Technical Note diff --git a/docs/en/programmers/api-variables/variable-debug-tpl.xml b/docs/en/programmers/api-variables/variable-debug-tpl.xml index 2e093460..7c070b41 100644 --- a/docs/en/programmers/api-variables/variable-debug-tpl.xml +++ b/docs/en/programmers/api-variables/variable-debug-tpl.xml @@ -4,7 +4,8 @@ $debug_tpl This is the name of the template file used for the debugging console. By - default, it is named debug.tpl and is located in the debug.tpl and is + located in the SMARTY_DIR. diff --git a/docs/en/programmers/api-variables/variable-php-handling.xml b/docs/en/programmers/api-variables/variable-php-handling.xml index 8ba38878..86061054 100644 --- a/docs/en/programmers/api-variables/variable-php-handling.xml +++ b/docs/en/programmers/api-variables/variable-php-handling.xml @@ -8,7 +8,7 @@ SMARTY_PHP_PASSTHRU. Note that this does NOT affect php code within {php}{/php} tags in the template. - + SMARTY_PHP_PASSTHRU - Smarty echos tags as-is. SMARTY_PHP_QUOTE - Smarty quotes the tags as @@ -21,8 +21,8 @@ Embedding PHP code into templates is highly discouraged. - Use custom functions or - modifiers instead. + Use custom functions or + modifiers instead. diff --git a/docs/en/programmers/api-variables/variable-plugins-dir.xml b/docs/en/programmers/api-variables/variable-plugins-dir.xml index be4baae9..4fe58e4a 100644 --- a/docs/en/programmers/api-variables/variable-plugins-dir.xml +++ b/docs/en/programmers/api-variables/variable-plugins-dir.xml @@ -4,7 +4,8 @@ $plugins_dir This is the directory (or directories) where Smarty will look for the - plugins that it needs. Default is "plugins" under the + plugins that it needs. Default is + "plugins" under the SMARTY_DIR. If you supply a relative path, Smarty will first look under the SMARTY_DIR, then @@ -13,14 +14,33 @@ search for your plugin in each plugin directory in the order they are given. - - Technical Note - - For best performance, do not setup your plugins_dir to have to use the - PHP include path. Use an absolute pathname, or a path relative to - SMARTY_DIR or the cwd. - - + + Technical Note + + For best performance, do not setup your $plugins_dir to have to use + the PHP include path. Use an absolute pathname, or a path relative + to SMARTY_DIR or the cwd. + + + + + multiple $plugins_dir + +plugins_dir = array( + 'plugins', // the default under SMARTY_DIR + '/path/to/shared/plugins', + '../../includes/my/plugins' + ); + +?> + +]]> + + + Controlling Cacheability of Plugins' Output - + Since Smarty-2.6.0 plugins the cacheability of plugins can be declared - when registering them. The third parameter to register_block, - register_compiler_function and register_function is called + when registering them. The third parameter to + register_block(), + register_compiler_function() + and + register_function() is called $cacheable and defaults to true which is also the behaviour of plugins in Smarty versions before 2.6.0 + - When registering a plugin with $cacheable=false the plugin is + When registering a plugin with $cacheable=false the plugin is called everytime the page is displayed, even if the page comes from the cache. The plugin function behaves a little like an insert function. - In contrast to {insert} + In contrast to insert the attributes to the plugins are not cached by default. They can be - declared to be cached with the fourth parameter + declared to be cached with the fourth parameter $cache_attrs. $cache_attrs - is an array of attribute-names that should be cached, so the - plugin-function get value as it was the time the page was written + is an array of attribute-names that should be cached, so the + plugin-function get value as it was the time the page was written to cache everytime it is fetched from the cache. @@ -65,7 +70,7 @@ Time Remaining: {remaining endtime=$obj->endtime} The number of seconds till the endtime of $obj is reached changes on - each display of the page, even if the page is cached. Since the + each display of the page, even if the page is cached. Since the endtime attribute is cached the object only has to be pulled from the database when page is written to the cache but not on subsequent requests of the page. @@ -109,16 +114,16 @@ Now is: {"0"|date_format:"%D %H:%M:%S"} ]]> - + When reloading the page you will notice that both dates differ. One - is "dynamic" one is "static". You can do everything between + is "dynamic" one is "static". You can do everything between {dynamic}...{/dynamic} and be sure it will not be cached like the rest of the page. - + - +