diff --git a/NEWS b/NEWS index 55756922..b7b1a34c 100644 --- a/NEWS +++ b/NEWS @@ -1,14 +1,15 @@ - - added trusted_dir functionality. (Monte) - - consolidated security tests to one function. (Monte) + - added trusted_dir functionality, documented. (Monte) + - consolidated secure_dir tests to one function. (Monte) - prepend SMARTY_DIR to default directories in class constructor. (Monte, Ricard Pillosu) - append _smarty_ to variable names in fetch() class function to avoid namespace conflicts. (Monte) - introduced $compile_id class variable that can be used to set persistent - compile identifier across multiple display calls. (Andrei) + compile identifier across multiple display calls, documented. (Andrei) - fixed bug with concatenated null cache and compile identifiers. (Andrei) - - added $smarty.section.* syntax for accessing section properties. (Andrei) - - added custom cache handling function ability. (Monte) + - added $smarty.section.* syntax for accessing section properties, + documented. (Andrei) + - added custom cache handling function ability, documented. (Monte) - added assign attribute to insert, fetch, math, and counter functions, documented. (Monte) - fixed bug with fetch testing for local file when http address. (Monte) @@ -16,14 +17,14 @@ - made {config_load ...} merge globals from each config file only once per scope, thus avoiding several problems. (Andrei) - added {foreach ...} tag that can be used to iterate through - non-sequential and associative arrays. (Andrei) + non-sequential and associative arrays, documented. (Andrei) - speeded up section property access a bit. (Andrei) - removed $smarty variable from storage used by normal template variables, to prevent any problems. (Andrei) - fixed a bug that could cause parse error with quotes inside literal blocks. (Andrei, Alexander Belonosov) - - added 'field_array' attribute to html_select_time function. (Andrei, - Michael Caplan) + - added 'field_array' attribute to html_select_time function, documented. + (Andrei, Michael Caplan) - documented {section} "max" attribute. (Monte) - fixed notice message in Smarty_Compiler.class.php. (Monte) - fixed bug with clear_cache introduced in 1.4.6, third parameter should diff --git a/docs.sgml b/docs.sgml index ceb9bc62..83c37c24 100644 --- a/docs.sgml +++ b/docs.sgml @@ -496,21 +496,6 @@ require_once(SMARTY_DIR."Smarty.class.php"); NOTE: $tpl_file_ext is no longer needed in 1.4.0. This is kept for backward compatability. - - - $allow_php - - Whether or not to allow PHP code in the templates. If set to - false, PHP code is escaped and not interpreted. Embedding PHP - code into templates is not recommended. Use custom functions or modifiers instead. Default - is "false". - - - NOTE: $allow_php was removed in 1.3.0, and replaced with - $php_handling. - $php_handling @@ -590,6 +575,16 @@ require_once(SMARTY_DIR."Smarty.class.php"); PHP functions used as variable modifiers. + + $trusted_dir + + $trusted_dir is only for use when $security is enabled. + This is an array of all directories that are considered + trusted. When a directory is considered trusted, $security is + temporarily disabled while any templates from here are + included. New in Smarty 1.5.0. + + $left_delimiter @@ -628,7 +623,14 @@ require_once(SMARTY_DIR."Smarty.class.php"); $show_info_header Shows an HTML comment at the beginning of the templates output, - displaying smarty version and date generated. Default is true. + displaying smarty version and date generated. Default is false. + + + + $show_info_include + + Shows an HTML comment before and after each included template. + Default is false. @@ -639,6 +641,41 @@ require_once(SMARTY_DIR."Smarty.class.php"); advanced users only. + + $resource_funcs + + An array of functions that resource handlers are mapped to. + + + + $prefilter_funcs + + An array of functions that templates are filtered through before + compilation. + + + + $postfilter_funcs + + An array of functions that templates are filtered through after + compilation. + + + + $request_vars_order + + The order in which request variables are registered, similar to + variables_order in php.ini + + + + $compile_id + + Persistant compile identifier. As an alternative to passing the + same compile_id to each and every function call, you can set this + compile_id and it will be used implicitly thereafter. + + @@ -1545,6 +1582,143 @@ $smarty->display("index.tpl"); {* rest of template content... *} + + + + + + Template Cache Handling Function + + As an alternative to using the default file-based caching mechanism, you + can specify a custom cache handling function that will be used to read, + write and clear cached files. + + + Example of a Template Cache Handling Function + + Create a function in your application that Smarty will use as a + cache handler. Set the name of it in the $cache_handler_func class + variable. Smarty will now use this to handle cached data. The first + argument is the action, which will be one of 'read', 'write' and + 'clear'. The second parameter is the smarty object. The third + parameter is the cached content. Upon a write, Smarty passed th + cached content in this paramters. Upon a 'read', Smarty expects + your function to pass this by reference and populate it with the + cached data. Upon a 'clear', pass a dummy variable here since it is + not used. The fourth parameter is the name of the template file + (needed for read/write), the fifth parameter is the cache_id + (optional), and the sixth is the compile_id (optional) + + + +example using MySQL as a cache source + + +<?php + +/* + +example usage: + +include('Smarty.class.php'); +include('mysql_cache_handler.php'); + +$smarty = new Smarty; +$smarty->cache_handler_func='mysql_cache_handler'; + +$smarty->display('index.tpl'); + + +mysql database is expected in this format: + +create database SMARTY_CACHE; + +create table CACHE_PAGES( +CacheID char(32) PRIMARY KEY, +CacheContents MEDIUMTEXT NOT NULL +); + +*/ + +function mysql_cache_handler($action, &$smarty_obj, &$cache_content, $tpl_file=null, $cache_id=null, $compile_id=null) { + // set db host, user and pass here + $db_host = 'localhost'; + $db_user = 'myuser'; + $db_pass = 'mypass'; + $db_name = 'SMARTY_CACHE'; + $use_gzip = false; + + // create unique cache id + $CacheID = md5($tpl_file.$cache_id.$compile_id); + + if(! $link = mysql_pconnect($db_host, $db_user, $db_pass)) { + $smarty_obj->_trigger_error_msg("cache_handler: could not connect to database"); + return false; + } + mysql_select_db($db_name); + + switch ($action) { + case 'read': + // save cache to database + $results = mysql_query("select CacheContents from CACHE_PAGES where CacheID='$CacheID'"); + if(!$results) { + $smarty_obj->_trigger_error_msg("cache_handler: query failed."); + } + $row = mysql_fetch_array($results,MYSQL_ASSOC); + + if($use_gzip && function_exists("gzuncompress")) { + $cache_contents = gzuncompress($row["CacheContents"]); + } else { + $cache_contents = $row["CacheContents"]; + } + $return = $results; + break; + case 'write': + // save cache to database + + if($use_gzip && function_exists("gzcompress")) { + // compress the contents for storage efficiency + $contents = gzcompress($cache_content); + } else { + $contents = $cache_content; + } + $results = mysql_query("replace into CACHE_PAGES values( + '$CacheID', + '".addslashes($contents)."') + "); + if(!$results) { + $smarty_obj->_trigger_error_msg("cache_handler: query failed."); + } + $return = $results; + break; + case 'clear': + // clear cache info + if(empty($cache_id) && empty($compile_id) && empty($tpl_file)) { + // clear them all + $results = mysql_query("delete from CACHE_PAGES"); + } else { + $results = mysql_query("delete from CACHE_PAGES where CacheID='$CacheID'"); + } + if(!$results) { + $smarty_obj->_trigger_error_msg("cache_handler: query failed."); + } + $return = $results; + break; + default: + // error, unknown action + $smarty_obj->_trigger_error_msg("cache_handler: unknown action \"$action\""); + $return = false; + break; + } + mysql_close($link); + return $return; + +} + +?> + + + @@ -3009,6 +3183,126 @@ e-mail: jane@mydomain.com<p> + + foreach,foreachelse + + + + + + + + + + Attribute Name + Type + Required + Default + Description + + + + + from + string + Yes + n/a + The name of the array you are looping through + + + item + string + Yes + n/a + The name of the variable that is the current + element + + + key + string + No + n/a + The name of the variable that is the current key + + + name + string + No + n/a + The name of the foreach loop for accessing + foreach properties + + + + + + foreach loops are an alternative to + section loops. foreach is + used to loop over a single associative array. The syntax for + foreach is much easier than + section, but as a tradeoff it can only be used + for a single array. foreach tags must be + paired with /foreach tags. Required parameters + are from and item. The + name of the foreach loop can be anything you like, made up of + letters, numbers and underscores. foreach + loops can be nested, and the nested foreach names must be unique + from each other. The from variable (usually an + array of values) determines the number of times + foreach will loop. + foreachelse is executed when there are no + values in the from variable. + + +foreach + + + +{* this example will print out all the values of the $custid array *} +{foreach from=$custid item=curr_id} + id: {$curr_id}<br> +{/foreach} + +OUTPUT: + +id: 1000<br> +id: 1001<br> +id: 1002<br> + + + + + +foreach key + + +{* The key contains the key for each looped value + +assignment looks like this: + +$smarty->assign("contacts", array(array("phone" => "1", "fax" => "2", "cell" => "3"), + array("phone" => "555-4444", "fax" => "555-3333", "cell" => "760-1234"))); + +*} + +{foreach name=outer item=contact from=$contacts} + {foreach key=key item=item from=$smarty.foreach.outer} + {$key}: {$item}<br> + {/foreach} +{/foreach} + +OUTPUT: + +phone: 1<br> +fax: 2<br> +cell: 3<br> +phone: 555-4444<br> +fax: 555-3333<br> +cell: 760-1234<br> + + + + strip @@ -3767,6 +4061,13 @@ OUTPUT: 1 number interval in second dropdown + + field_array + string + No + n/a + outputs values to array of this name +