update documentation, changelog

NEWS

@@ -1,3 +1,5 @@
+    - added security features for third party template editing (Monte,Andrei)
+    - added assign custom function, documented (Monte)
     - fixed a problem with putting $ followed by numbers inside {strip} and
       {/strip} tags. (Andrei)
     - fixed Config_File class to allow empty config paths (defaults to current

Smarty.addons.php

@@ -208,18 +208,15 @@ function smarty_mod_default($string, $default="")
 function smarty_func_assign($vars,&$smarty_obj)
 {
 	extract($vars);
-	$smarty_obj->assign($var,$val);
+	if(empty($var)) {
-	return true;
+    	trigger_error("assign: missing 'var' parameter");
-}
+    	return;
-
+	}
-/*======================================================================*\
+	if(empty($value)) {
-    Function: smarty_func_unassign
+    	trigger_error("assign: missing 'value' parameter");
-    Purpose:  unassign a template variable
+    	return;
-\*======================================================================*/
+	}
-function smarty_func_unassign($vars,&$smarty_obj)
+	$smarty_obj->assign($var,$value);
-{
-	extract($vars);
-	$smarty_obj->clear_assign($var);
 	return true;
 }
 

Smarty.class.php

@@ -121,8 +121,7 @@ class Smarty
                                     'math'              => 'smarty_func_math',
                                     'fetch'             => 'smarty_func_fetch',
 									'counter'			=> 'smarty_func_counter',
-									'assign'			=> 'smarty_func_assign',
+									'assign'			=> 'smarty_func_assign'
-									'unassign'			=> 'smarty_func_unassign'
                                  );
     
     var $custom_mods     =  array(  'lower'             => 'strtolower',
@@ -245,7 +244,6 @@ class Smarty
                 unset($this->_tpl_vars[$curr_var]);
         else
             unset($this->_tpl_vars[$tpl_var]);
-		$this->_extract = true;
     }
 
     

docs.sgml

@@ -2523,9 +2523,65 @@ OUTPUT:
 	<sect1 id="custom.functions">
 		<title>Custom Functions</title>
 		<para>
-		Custom functions in Smarty work much the same as the built-in functions
+		Custom functions in Smarty work much the same as the built-in functions,
-		syntactically.
+		except that built-in functions cannot be modified. Custom functions are
+		located in Smarty.addons.php, built-in functions are not.
 		</para>
+		<sect2 id="custom.functions.assign">
+			<title>assign</title>
+            <informaltable frame=all>
+                <tgroup cols=3>
+                <colspec colname=param>
+                <colspec colname=type>
+                <colspec colname=required>
+                <colspec colname=default>
+                <colspec colname=desc>
+                <thead>
+                    <row>
+                        <entry>Attribute Name</entry>
+                        <entry>Type</entry>
+                        <entry>Required</entry>       
+                        <entry>Default</entry>
+                        <entry>Description</entry>
+                    </row>
+                </thead>
+                <tbody>
+                    <row>
+                        <entry>val</entry>
+                        <entry>string</entry>
+                        <entry>Yes</entry>
+                        <entry><emphasis>n/a</emphasis></entry>
+                        <entry>The name of the variable being assigned</entry>
+                    </row>
+                    <row>
+                        <entry>value</entry>
+                        <entry>string</entry>
+                        <entry>Yes</entry>
+                        <entry><emphasis>n/a</emphasis></entry>
+                        <entry>The value being assigned</entry>
+                    </row>
+                </tbody>
+                </tgroup>
+            </informaltable>
+			<para>
+			assign is used for assigning template variables during the execution
+			of the template. assign was added to Smarty 1.4.3.
+			</para>
+<example>
+<title>assign</title>
+<programlisting>
+
+{assign var="name" value="Bob"}
+
+The value of $name is {$name}.
+
+OUTPUT:
+
+The value of $name is Bob.
+
+</programlisting>
+</example>
+		</sect2>
 		<sect2>
 			<title>counter</title>
             <informaltable frame=all>
@@ -4176,6 +4232,27 @@ Parse error: parse error in /path/to/smarty/templates_c/index.tpl.php on line 75
 
 {$title|default:"&amp;nbsp;"}
 
+</programlisting>
+</example>
+	</sect1>
+	<sect1>
+		<title>Default Variable Handling</title>
+		<para>
+		If a variable is used frequently throughout your templates, applying
+		the default modifier every time it is mentioned can get a bit ugly. You
+		can remedy this by assigning the variable its default value with the
+		<link linkend="custom.functions.assign">assign</link> function.
+		</para>
+<example>
+<title>Assigning a template variable its default value</title>
+<programlisting>
+
+{* do this somewhere at the top of your template *}
+{assign var="title" value=$title|default:"no title"}
+
+{* if $title was empty, it now contains the value "no title" when you print it *}
+{$title}
+
 </programlisting>
 </example>
 	</sect1>

libs/Smarty.class.php

@@ -121,8 +121,7 @@ class Smarty
                                     'math'              => 'smarty_func_math',
                                     'fetch'             => 'smarty_func_fetch',
 									'counter'			=> 'smarty_func_counter',
-									'assign'			=> 'smarty_func_assign',
+									'assign'			=> 'smarty_func_assign'
-									'unassign'			=> 'smarty_func_unassign'
                                  );
     
     var $custom_mods     =  array(  'lower'             => 'strtolower',
@@ -245,7 +244,6 @@ class Smarty
                 unset($this->_tpl_vars[$curr_var]);
         else
             unset($this->_tpl_vars[$tpl_var]);
-		$this->_extract = true;
     }