tweek

docs/en/designers/language-builtin-functions.xml

@@ -3,11 +3,20 @@
 <chapter id="language.builtin.functions">
  <title>Built-in Functions</title>
  <para>
-  Smarty comes with several built-in functions. Built-in functions
-  are integral to the template language. You cannot create custom
-  functions with the same names, nor can you modify built-in functions.
+  Smarty comes with several built-in functions. These built-in functions 
+  are the integral part of the smarty template engine. You cannot create your own
+  <link linkend="language.custom.functions">custom functions</linkend>
+  with the same name; and you  should  not need to 
+  modify the built-in functions.
+ </para>
+ <para>
+ A few on these functions have an <emphasis role="bold">assign</emphasis> 
+ attribute which collects
+ the result the function to a named variable within a template instead of being output;
+ much like the <link linkend="language.function.assign">{assign}</link> function.
  </para>
 
+ 
  &designers.language-builtin-functions.language-function-capture;
  &designers.language-builtin-functions.language-function-config-load;
  &designers.language-builtin-functions.language-function-foreach;

docs/en/designers/language-builtin-functions/language-function-capture.xml

@@ -4,15 +4,17 @@
  <title>{capture}</title>
  
   <para>
-   {capture} is used to collect the output of the template into a
+   {capture} is used to collect the output of the template between the tags into a
    variable instead of displaying it. Any content between {capture
-   name="foo"} and {/capture} is collected into the variable specified
-   in the name attribute. The captured content can be used in the
-   template from the special variable <link
+   name='foo'} and {/capture} is collected into the variable specified
+   in the name attribute. 
+   </para>
+   <para>The captured content can be used in the
+   template from the variable <link
     linkend="language.variables.smarty.capture">$smarty.capture.foo</link>
    where "foo" is the value passed in the name attribute. If you do not
-   supply a name attribute, then "default" will be used as the name. All {capture}
-   commands must be paired with {/capture}. You can nest capture commands.
+   supply a name attribute, then "default" will be used as in $smarty.capture.default. 
+   You can nest capture commands.
  </para>
  
  
@@ -66,39 +68,33 @@
  </caution>
  <para>
   <example>
-   <title>capturing template content</title>
+   <title>{capture} with a the name attribute</title>
    <programlisting>
 <![CDATA[
-{* we don't want to print a table row unless content is displayed *}
+{* we don't want to print a div tag unless content is displayed *}
 {capture name=banner}
   {include file='get_banner.tpl'}
 {/capture}
 
 {if $smarty.capture.banner ne ''}
-<table>
-<tr>
-  <td>
-   {$smarty.capture.banner}
-  </td>
-</tr>
-</table>
+<div id="banner">{$smarty.capture.banner}</div>
 {/if}
 ]]>
    </programlisting>
   </example>
   
     <example>
-     <title>capturing content to a variable</title>
+     <title>{capture} into a template variable</title>
      <para>This example also demonstrates the 
      <link linkend="language.function.popup">{popup}</link> 
      function</para>
      <programlisting>
 <![CDATA[
 {capture name=some_content assign=popText}
-.... some popup content ....
+The server is {$smarty.server.SERVER_NAME|upper} at {$smarty.server.SERVER_ADDR}<br>
+Your ip is {$smarty.server.REMOTE_ADDR}.
 {/capture}
-
-<a href="#" {popup caption='Help' text=$popText}>help</a>
+<a href="#" {popup caption='Server Info' text=$popText}>help</a>
 ]]>
      </programlisting>
   </example>

docs/en/designers/language-custom-functions/language-function-assign.xml

@@ -5,7 +5,7 @@
   <para>
    {assign} is used for assigning template variables
    <emphasis role="bold">during the execution
-   of the template</emphasis>.
+   of a template</emphasis>.
  </para>
  
  <informaltable frame="all">
@@ -76,7 +76,7 @@ The value of $name is Bob.
  <example>
   <title>Accessing {assign} variables from a PHP script.</title>
   <para>
-  To access {assign} variables from php use
+  To access {assign} variables from the php script use
     <link linkend="api.get.template.vars">get_template_vars()</link>.
     However, the variables are only available after/during template execution
   as in the following example

docs/en/designers/language-modifiers.xml

@@ -45,6 +45,11 @@
 
 {* php's shuffle on servers's ip *}
 {$smarty.server.SERVER_ADDR|shuffle}
+
+(* this will uppercase and truncate the whole array *}
+<select name="name_id">
+{html_options output=$myArray|upper|truncate:20}
+</select>
 ]]>
   </programlisting>
  </example>

docs/en/designers/language-modifiers/language-modifier-default.xml

@@ -7,6 +7,14 @@
      is empty or unset, the given default value is printed instead.
      Default takes one argument.
   </para>
+     <para>
+     <note>
+      <para>
+       With error_reporting(E_ALL), undeclared variables will always throw an error within the template. This function
+       is useful for replacing null or zero length strings. 
+    </para>
+    </note>
+    </para>
   
   <informaltable frame="all">
    <tgroup cols="5">

docs/en/designers/language-modifiers/language-modifier-escape.xml

@@ -3,9 +3,8 @@
  <sect1 id="language.modifier.escape">
   <title>escape</title>
     <para>
-     This is used to html escape, url escape, escape single quotes on a
-     variable not already escaped, hex escape, hexentity or javascript escape.
-     By default, the variable is html
+     This is used to encode/escape and a variable to html url single quotes, hex escape, hexentity, javascript and mail escape.
+     By default its html
      escaped.
   </para>
   
@@ -69,12 +68,12 @@ $smarty->assign('EmailAddress','smarty@example.com');
 <![CDATA[
 {$articleTitle}
 {$articleTitle|escape}
-{$articleTitle|escape:"html"}    {* escapes  & " ' < > *}
-{$articleTitle|escape:"htmlall"} {* escapes ALL html entities *}
-{$articleTitle|escape:"url"}
-{$articleTitle|escape:"quotes"}
+{$articleTitle|escape:'html'}    {* escapes  & " ' < > *}
+{$articleTitle|escape:'htmlall'} {* escapes ALL html entities *}
+{$articleTitle|escape:'url'}
+{$articleTitle|escape:'quotes'}
 <a href="mailto:{$EmailAddress|escape:"hex"}">{$EmailAddress|escape:"hexentity"}</a>
-{$EmailAddress|escape:'mail'}
+{$EmailAddress|escape:'mail'}    {* this converts to email to text *}
 ]]>
    </programlisting>
    <para>
@@ -92,19 +91,28 @@ $smarty->assign('EmailAddress','smarty@example.com');
 smarty [AT] example [DOT] com
 ]]>
    </screen>
-   <para>Remember that native PHP functions can be used as modifiers so this will work</para>
+   <para>Note that native PHP functions can be used as modifiers so this will work</para>
    <screen>
 <![CDATA[
 {* rewind get var registers the current location *}
 <a href="{$SCRIPT_NAME}?page=foo&rewind={$smarty.server.REQUEST_URI|urlencode}">click here</a>
 ]]>
-   </screen>   
+   </screen>
+      <para>And this is very useful for emails but see also 
+      <link linkend="language.function.mailto">{mailto}</link></para>
+      <screen>
+   <![CDATA[
+   {* email address mangled *}
+   <a href="mailto:{$EmailAddress|escape:'hex'}">{$EmailAddress:escape'mail'}</a>
+   ]]>
+   </screen>  
   </example>
   
   
   
   <para>
-   See also <link linkend="language.escaping">Escaping Smarty Parsing</link>
+   See also <link linkend="language.escaping">Escaping Smarty Parsing</link>,
+   <link linkend="language.function.mailto">{mailto}</link>
    and <link linkend="tips.obfuscating.email">Obfuscating E-mail Addresses</link>.
   </para>
  </sect1>