diff --git a/NEWS b/NEWS index 8e002e2b..39685eb7 100644 --- a/NEWS +++ b/NEWS @@ -1,9 +1,11 @@ + - documentation updates (Monte) - update fetch function to give proper warning when fetching a non-readable or non-existant file (Monte) - fixed problem with newline at the end of included templates (Monte, Andrei) - added feature to regenerate cache if compile_check is enabled and an involved template or config file gets modified (Monte) - - added DEBUG execution times to included files (Monte) + - added DEBUG execution times to included files: REQUIRES updated debug.tpl + file! (Monte) - added support for hidden config variables that cannot be read by templates. (Andrei) - added execution time to DEBUG console, total and inserts. (Monte) diff --git a/docs.sgml b/docs.sgml index 48abe829..4a5c2b17 100644 --- a/docs.sgml +++ b/docs.sgml @@ -146,14 +146,24 @@ every invocation, even within cached content. - TECHNICAL NOTE: Any time you change a template, change values in - config files or change the content that gets displayed in a - template, you must either clear the caches that are affected, or - wait for the cache to expire to see the results of the changes. You - can either do this manually by deleting files from the cache - directory, or programatically with clear_cache or clear_all_cache. + TECHNICAL NOTE: Any time you change a template, change values in + config files or change the content that gets displayed in a + template, you must turn on compile_check (new behavior in 1.4.6), + clear the caches that are affected, or wait for the cache to expire + to see the results of the changes. You can either do this manually + by deleting files from the cache directory, or programatically with + clear_cache or clear_all_cache. + + + TECHNICAL NOTE: As of Smarty 1.4.6, if you have caching enabled AND + you have compile_check enabled, the cached file will regenerate if + an involved template or config file has been modified, regardless + of the cache expire time. This results in a slight performance hit + since it has to check the templates and config files for + modification times. Therefore if you are not actively changing + templates or config files, it is advisable to leave compile_check + off. @@ -384,7 +394,7 @@ require_once(SMARTY_DIR."Smarty.class.php"); will *not* see the change since the template will not get recompiled. See $force_compile or clear_compiled_tpl. + linkend="api.clear.compiled.tpl">clear_compiled_tpl. @@ -1016,6 +1026,49 @@ $smarty->register_prefilter("remove_dw_comments"); $smarty->unregister_prefilter("imbed_asp_jokes"); + + + + + register_postfilter + + + void register_postfilter + string function_name + + + + Use this to dynamically register postfilters to run templates + through before they are compiled. See template postfilters for + more information on how to setup a postfiltering function. + + +register_postfilter + + +$smarty->register_postfilter("remove_dw_comments"); + + + + + + unregister_postfilter + + + void unregister_postfilter + string function_name + + + + Use this to dynamically unregister a postfilter. + + +unregister_postfilter + + +$smarty->unregister_postfilter("imbed_asp_jokes"); + @@ -1163,6 +1216,7 @@ var_dump($tpl_vars); void display string template string cache id + string compile id @@ -1172,6 +1226,12 @@ var_dump($tpl_vars); cache id. See the caching section for more information. + + As an optional third parameter, you can pass a compile id. This + is in the event that you want to compile different versions of + the same template, such as having separate templates compiled + for different languages. This was added to Smarty 1.4.5. + display @@ -1210,6 +1270,7 @@ $smarty->display("index.tpl"); string fetch string template [string cache_id] + [string compile_id] @@ -1220,6 +1281,12 @@ $smarty->display("index.tpl"); cache id. See the caching section for more information. + + As an optional third parameter, you can pass a compile id. This + is in the event that you want to compile different versions of + the same template, such as having separate templates compiled + for different languages. This was added to Smarty 1.4.5. + fetch @@ -1372,6 +1439,11 @@ $smarty->display("db:index.tpl"); first argument, an expect the function to return the resulting template source code. + + NOTE: As of Smarty 1.4.5, the Smarty object is passed as the second + argument. This way you can reference and modify information in the + Smarty object from within the prefilter function. + using a template prefilter @@ -1389,6 +1461,49 @@ $smarty->display("index.tpl"); {* from within Smarty template *} <!--# this line will get removed by the prefilter --> + + + + + + Template Postfilters + + Template postfilters are PHP functions that your templates are ran through + after they are compiled. Postfilters are processed in the order they are + registered. + + + Example of a Template Postfilter + + Create a function in your application that Smarty will use as a + template postfilter. Smarty will pass the template source code as the + first argument, an expect the function to return the resulting + template source code. + + + The Smarty object is passed as the second argument. This way you + can reference and modify information in the Smarty object from + within the prefilter function. + + + +using a template postfilter + + +// this program puts a +// put this in your application, or in Smarty.addons.php +function add_header_comment($tpl_source) { + return "\n\" ?>\n".$tpl_source; +} + +// register the postfilter +$smarty->register_postfilter("add_header_comments"); +$smarty->display("index.tpl"); + +{* from within Smarty template *} + +{* rest of template content... *} + @@ -1460,6 +1575,25 @@ zaphod@slartibartfast.com<br> + + + + + Array indexes + + You can reference arrays by their index, much like native PHP + syntax. + + +displaying arrays by index + + +{$Contacts[0]}<br> +{$Contacts[1]}<br> +{* you can print arrays of arrays as well *} +{$Contacts[0][0]}<br> +{$Contacts[0][1]}<br> + @@ -1702,6 +1836,15 @@ focus = "username" Intro = """This is a value that spans more than one line. you must enclose it in triple quotes.""" + +# hidden section +[.Database] +host=my.domain.com +db=ADDRESSBOOK +user=php-user +pass=foobar + + @@ -1726,6 +1869,15 @@ Intro = """This is a value that spans more Config files are loaded into templates with the built-in function called config_load. + + You can hide variables or entire sections by prepending the variable + name or section name with a period. This is useful if your + application reads the config files and gets sensitive data from them + that the template engine does not need. If you have third parties + doing template editing, you can be certain that they cannot read + sensitive data from the config file by loading it into the template. + This is new in Smarty 1.4.6. + Built-in Functions @@ -2054,6 +2206,11 @@ Intro = """This is a value that spans more pages. This works good for things like banners, polls, live weather, search results, user feedback areas, etc. + + NOTE: As of Smarty 1.4.5, the Smarty object is passed as the second + argument. This way you can reference and modify information in the + Smarty object from within the insert function. + if,elseif,else @@ -3100,6 +3257,10 @@ OUTPUT: selected by default as well. Required attributes are values and output, unless you use options instead. + + NOTE: As of Smarty 1.4.5, html_options now outputs xhtml compatible + code. + html_options @@ -3222,6 +3383,91 @@ OUTPUT: false whether or not to display the year as text + + reverse_years + boolean + No + false + display years in reverse order + + + field_array + string + No + null + + if a name is given, the select boxes will be drawn + such that the results will be returned to PHP in the + form of name[Day], name[Year], name[Month]. + + + + day_size + string + No + null + adds size attribute to select tag if given + + + month_size + string + No + null + adds size attribute to select tag if given + + + year_size + string + No + null + adds size attribute to select tag if given + + + all_extra + string + No + null + adds extra attributes to all select/input tags if + given + + + day_extra + string + No + null + adds extra attributes to select/input tags if + given + + + month_extra + string + No + null + adds extra attributes to select/input tags if + given + + + year_extra + string + No + null + adds extra attributes to select/input tags if + given + + + field_order + string + No + MDY + the order in which to display the fields + + + field_separator + string + No + \n + string printed between different fields + @@ -3229,6 +3475,11 @@ OUTPUT: html_select_date is a custom function that creates date dropdowns for you. It can display any or all of year, month, and day. + + NOTE: reverse_years, field_array, day_size, month_size, year_size, + all_extra, day_extra, month_extra, year_extra, field_order, + field_separator added in Smarty 1.4.5. + html_select_date @@ -4975,6 +5226,11 @@ s m o k e r s a r e p. . . NOTE: This feature was added to Smarty 1.4.3. + + NOTE: The load times of each template file and config file have been added to + the debug output in Smarty 1.4.6. This output is in seconds, or fractions + thereof. + Troubleshooting