diff --git a/docs/en/designers/language-builtin-functions/language-function-section.xml b/docs/en/designers/language-builtin-functions/language-function-section.xml index 8b9655e9..d1944d9f 100644 --- a/docs/en/designers/language-builtin-functions/language-function-section.xml +++ b/docs/en/designers/language-builtin-functions/language-function-section.xml @@ -3,22 +3,15 @@ {section},{sectionelse} - Template sections are used for looping over - arrays of data - (just like {foreach}). All - {section} tags must be paired with - {/section} tags. Required parameters are - name and loop. The name - of the {section} can be anything you like, made up of letters, - numbers and underscores. Sections can be nested, and the nested - section names must be unique from each other. The loop variable - (usually an array of values) determines the number of times the - section will loop. When printing a variable within a section, the - section name must be given next to variable name within brackets - []. {sectionelse} is - executed when there are no values in the loop variable. - - + A {section} + is for looping over arrays of data, + unlike {foreach} + which is used to loop over a + single associative array. + Every {section} tag must be paired with + a closing {/section} tag. + + @@ -85,26 +78,81 @@ show boolean No - true + &true; determines whether or not to show this section - - {section} + + + Required attributes are name and loop. + + + The name of the {section} can be + anything you like, made up of letters, numbers and underscores, like + PHP variables. + + + + Sections can be nested, and the nested + {section} names must be unique from each other. + + + + The loop attribute, + usually an array of values, determines the number of times the + {section} will loop. + + + When printing a variable within a {section}, the + {section} name must be given next + to variable name within [brackets]. + + + + {sectionelse} is + executed when there are no values in the loop variable. + + + + A {section} also has its own variables that handle + {section} properties. + These properties are accessible as: + {$smarty.section.name.property} + where name is the attribute name. + + + + {section} properties are + index, + index_prev, + index_next, + iteration, + first, + last, + rownum, + loop, + show, + total. + + + + + + Looping a simple array with {section} +assign() an array to Smarty from the php script assign('custid',$data); - ?> ]]> +The template that outputs the array id: 1000
]]> - - Another couple of examples without an assigned array. - + + + + + {section} without an assigned array 20 18 16 14 12 10 ]]> - + + + Naming a {section} + The name of the {section} can be anything + you like, see PHP variables. + It is used to reference the data within the {section}. + + + + + + - {section} loop variable + Looping an associative array's with {section} + This is an example of printing an associative array + of data within a {section}. Following is the php script to assign the + $contacts array to Smarty. + + 'John Smith', 'home' => '555-555-5555', + 'cell' => '666-555-5555', 'email' => 'john@myexample.com'), + array('name' => 'Jack Jones', 'home' => '777-555-5555', + 'cell' => '888-555-5555', 'email' => 'jack@myexample.com'), + array('name' => 'Jane Munson', 'home' => '000-555-5555', + 'cell' => '123456', 'email' => 'jane@myexample.com') + ); +$smarty->assign('contacts',$data); +?> +]]> + + +The template to output $contacts + + + name: {$contacts[customer].name}
+ home: {$contacts[customer].home}
+ cell: {$contacts[customer].cell}
+ e-mail: {$contacts[customer].email} +

+{/section} +]]> + + + The above example will output: + + + + name: John Smith
+ home: 555-555-5555
+ cell: 666-555-5555
+ e-mail: john@myexample.com +

+

+ name: Jack Jones
+ home phone: 777-555-5555
+ cell phone: 888-555-5555
+ e-mail: jack@myexample.com +

+

+ name: Jane Munson
+ home phone: 000-555-5555
+ cell phone: 123456
+ e-mail: jane@myexample.com +

+]]> + + + + + {section} demonstrating the <varname>loop</varname> variable + This example assumes that $custid, $name + and $address are all + arrays containing the same number of values. First the php script that assign's the + arrays to Smarty. assign('custid',$id); $fullnames = array('John Smith','Jack Jones','Jane Munson'); $smarty->assign('name',$fullnames); -$addr = array('253 N 45th', '417 Mulberry ln', '5605 apple st'); +$addr = array('253 Abbey road', '417 Mulberry ln', '5605 apple st'); $smarty->assign('address',$addr); ?> ]]> +The loop variable only determines the number of times to loop. + You can access ANY variable from the template within the {section} id: {$custid[customer]}
@@ -202,7 +330,7 @@ $smarty->assign('address',$addr);

id: 1000
name: John Smith
- address: 253 N 45th + address: 253 Abbey road

id: 1001
@@ -218,27 +346,15 @@ $smarty->assign('address',$addr); - - {section} naming - - - id: {$custid[anything]}
- name: {$name[anything]}
- address: {$address[anything]} -

-{/section} -]]> - - + - nested sections + Nested {section}'s + + Sections can be nested as deep as you like. With nested sections, + you can access complex data structures, such as multi-dimensional + arrays. This is a php script thats assign's the arrays. + assign('contact_info', $info); ?> ]]> +In this template, $contact_type[customer] is an array of + contact types for the current customer. id: {$custid[customer]}
@@ -315,85 +427,22 @@ $smarty->assign('contact_info', $info); - - sections and associative arrays - - 'John Smith', 'home' => '555-555-5555', - 'cell' => '666-555-5555', 'email' => 'john@myexample.com'), - array('name' => 'Jack Jones', 'home' => '777-555-5555', - 'cell' => '888-555-5555', 'email' => 'jack@myexample.com'), - array('name' => 'Jane Munson', 'home' => '000-555-5555', - 'cell' => '123456', 'email' => 'jane@myexample.com') - ); -$smarty->assign('contacts',$data); - -?> -]]> - - - - - name: {$contacts[customer].name}
- home: {$contacts[customer].home}
- cell: {$contacts[customer].cell}
- e-mail: {$contacts[customer].email} -

-{/section} -]]> - - - The above example will output: - - - - name: John Smith
- home: 555-555-5555
- cell: 666-555-5555
- e-mail: john@myexample.com -

-

- name: Jack Jones
- home phone: 777-555-5555
- cell phone: 888-555-5555
- e-mail: jack@myexample.com -

-

- name: Jane Munson
- home phone: 000-555-5555
- cell phone: 123456
- e-mail: jane@myexample.com -

-]]> - - - Database example (eg using Pear or Adodb) + +Database example with a {sectionelse} + Results of a database search (eg ADODB or PEAR) are assigned to Smarty assign('contacts',$db->getAll($sql) ); - +$sql = 'select id, name, home, cell, email from contacts ' + ."where name like '$foo%' "; +$smarty->assign('contacts', $db->getAll($sql)); ?> ]]> - +The template to output the database result in a HTML table  Name>HomeCellEmail {section name=co loop=$contacts} @@ -404,60 +453,42 @@ $smarty->assign('contacts',$db->getAll($sql) ); {$contacts[co].cell} {$contacts[co].email} +{sectionelse} + No items found {/section} ]]> - - {sectionelse} - - -{sectionelse} - there are no values in $custid. -{/section} -]]> - - - - Sections also have their own variables that handle section properties. - These are indicated like so: - {$smarty.section.sectionname.varname} - - - - As of Smarty 1.5.0, the syntax for section property variables has - changed from {%sectionname.varname%} to - {$smarty.section.sectionname.varname}. The old syntax is still - supported, but you will only see examples of the new syntax. - - + - index + .index - index is used to display the current array index, starting with zero - (or the start attribute if given), and incrementing by one (or by - the step attribute if given.) + index contains the current array index, starting with zero + or the start attribute if given It increments by one or by + the step attribute if given. Technical Note - If the step and start section properties are not + If the step and start + properties are not modified, then this works the same as the iteration section - property, except it starts at 0 instead of 1. + linkend="section.property.iteration">iteration + property, except it starts at zero instead of one. -{section} property index +{section} <varname>index</varname> property + +FYI +$custid[customer.index] and $custid[customer] + are identical in meaning. + + {/section} @@ -478,48 +509,47 @@ $smarty->assign('contacts',$db->getAll($sql) ); - index_prev + .index_prev - index_prev is used to display the previous loop index. - on the first loop, this is set to -1. + index_prev is the previous loop index. + On the first loop, this is set to -1. - index_next + .index_next - index_next is used to display the next loop index. On the last - loop, this is still one more than the current index (respecting the - setting of the step attribute, if given.) + index_next is the next loop index. On the last + loop, this is still one more than the current index, respecting the + setting of the step attribute, if given. -{section} property index_next and index_prev +<varname>index</varname>, <varname>index_next</varname> + and <varname>index_prev</varname> properties assign('custid',$data); - +$smarty->assign('rows',$data); ?> ]]> +Template to output the above array in a table indexid index_prevprev_id index_nextnext_id -{section name=cus loop=$custid} +{section name=row loop=$rows} - {$smarty.section.cus.index}{$custid[cus]} - {$smarty.section.cus.index_prev}{$custid[cus.index_prev]} - {$smarty.section.cus.index_next}{$custid[cus.index_next]} + {$smarty.section.row.index}{$rows[row]} + {$smarty.section.row.index_prev}{$rows[row.index_prev]} + {$smarty.section.row.index_next}{$rows[row.index_next]} {/section} @@ -543,35 +573,37 @@ index id index_prev prev_id index_next next_id - iteration + .iteration - iteration is used to display the current loop iteration. + iteration contains the current loop iteration and starts at one. - This is not affected by the section properties start, step and - max, unlike the index - property. Iteration also starts with 1 instead of 0 like index. rownum is an alias to iteration, - they work identical. + This is not affected by the {section} properties + start, step and max, + unlike the index + property. iteration also starts with one instead of zero + unlike index. rownum is an alias to + iteration, they are identical. -{section} property iteration +A section's <varname>iteration</varname> property assign('custid',$id); - +$smarty->assign('arr',$id); ?> ]]> +Template to output every other element of the $arr +array as step=2 @@ -592,14 +624,14 @@ iteration=6 index=15 id=3015
]]> - This example uses the iteration property to - output a table header block every five rows - (uses {if} - with the mod operator). + Another example uses the iteration property to + output a table header block every five rows and + uses {if} + with the mod operator. + {section name=co loop=$contacts} {if $smarty.section.co.iteration % 5 == 1} @@ -620,29 +652,27 @@ iteration=6 index=15 id=3015
- first + .first - first is set to true if the current section iteration is the first - one. + first is set to &true; if the current {section} + iteration is the initial one. - last + .last - last is set to true if the current section iteration is the last - one. + last is set to &true; + if the current section iteration is the final one. - {section} property first and last + {section} property <varname>first</varname> and <varname>last</varname> - This example loops the $customers array; + This example loops the $customers array, outputs a header block on the first iteration and - on the last outputs the footer block - (uses section total property) + on the last outputs the footer block. Also uses the + total property. - rownum + .rownum - rownum is used to display the current loop iteration, + rownum contains the current loop iteration, starting with one. It is an alias to iteration, they work - identically. + linkend="section.property.iteration">iteration, + they work identically. + - loop + .loop - loop is used to display the last index number that this section - looped. This can be used inside or after the section. - + loop contains the last index number + that this {section} + looped. This can be used inside or after the {section}. + - {section} property index + {section} property <varname>loop</varname>s {/section} - -There were {$smarty.section.customer.loop} customers shown above. +There are {$smarty.section.customer.loop} customers shown above. ]]> @@ -702,30 +733,28 @@ There were {$smarty.section.customer.loop} customers shown above. 0 id: 1000
1 id: 1001
2 id: 1002
- -There were 3 customers shown above. +There are 3 customers shown above. ]]> + - show + .show - show is used as a parameter to section. - show is a boolean value, true or false. If - false, the section will not be displayed. If there is a {sectionelse} - present, that will be alternately displayed. + show is used as a parameter to section. + show is a boolean value, &true; or &false;. If + &false;, the section will not be displayed. If there is a + {sectionelse} present, that will be alternately displayed. - {section} attribute show + <varname>show</varname> property + Boolean $show_customer_info has been passed from the PHP + application, to regulate whether or not this section shows. +{section name=customer loop=$customers show=$show_customer_info} + {$smarty.section.customer.rownum} id: {$customers[customer]}
{/section} {if $smarty.section.customer.show} @@ -749,35 +778,24 @@ the section was shown. + - total + .total - total is used to display the number of iterations that this section - will loop. This can be used inside or after the section. + total contains the number of iterations that this + {section} will loop. This can be used inside or after a + {section}. - {section} property total + <varname>total</varname> property example {/section} - - There were {$smarty.section.customer.total} customers shown above. + There are {$smarty.section.customer.total} customers shown above. ]]> - - The above example will output: - - - -2 id: 1002
-4 id: 1004
- -There were 3 customers shown above. -]]> - See also {foreach}
 Name>HomeCellEmail