smarty/docs/en/designers/language-builtin-functions/language-function-section.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<sect1 id="language.function.section">
 <title>{section},{sectionelse}</title>
  <para>
  A <varname>{section}</varname>
  is for looping over <emphasis role="bold">arrays of data</emphasis>,
  unlike <link linkend="language.function.foreach"><varname>{foreach}</varname></link>
  which is used to loop over a
   <emphasis role="bold">single associative array</emphasis>.
  Every <varname>{section}</varname> tag must be paired with
   a closing <varname>{/section}</varname> tag.
   </para>

 <informaltable frame="all">
  <tgroup cols="5">
   <colspec colname="param" align="center" />
   <colspec colname="type" align="center" />
   <colspec colname="required" align="center" />
   <colspec colname="default" align="center" />
   <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>name</entry>
     <entry>string</entry>
     <entry>Yes</entry>
     <entry><emphasis>n/a</emphasis></entry>
     <entry>The name of the section</entry>
    </row>
    <row>
     <entry>loop</entry>
     <entry>mixed</entry>
     <entry>Yes</entry>
     <entry><emphasis>n/a</emphasis></entry>
     <entry>Value to determine the number of loop iterations</entry>
    </row>
    <row>
     <entry>start</entry>
     <entry>integer</entry>
     <entry>No</entry>
     <entry><emphasis>0</emphasis></entry> <entry>The index
      position that the section will begin looping. If the
      value is negative, the start position is calculated
      from the end of the array. For example, if there are
      seven values in the loop array and start is -2, the
      start index is 5. Invalid values (values outside of the
      length of the loop array) are automatically truncated
      to the closest valid value.</entry>
    </row>
    <row>
     <entry>step</entry>
     <entry>integer</entry>
     <entry>No</entry>
     <entry><emphasis>1</emphasis></entry>
     <entry>The step value that will be used to traverse the
      loop array. For example, step=2 will loop on index
      0,2,4, etc. If step is negative, it will step through
      the array backwards.</entry>
    </row>
    <row>
     <entry>max</entry>
     <entry>integer</entry>
     <entry>No</entry>
     <entry><emphasis>n/a</emphasis></entry>
     <entry>Sets the maximum number of times the section
      will loop.</entry>
    </row>
    <row>
     <entry>show</entry>
     <entry>boolean</entry>
     <entry>No</entry>
     <entry><emphasis>&true;</emphasis></entry>
     <entry>Determines whether or not to show this section</entry>
    </row>
   </tbody>
  </tgroup>
 </informaltable>

 <itemizedlist>
   <listitem><para>
   Required attributes are <parameter>name</parameter> and <parameter>loop</parameter>.
   </para></listitem>

   <listitem><para>
    The <parameter>name</parameter> of the <varname>{section}</varname> can be
    anything you like,  made up of letters,  numbers and underscores, like
    <ulink url="&url.php-manual;language.variables">PHP variables</ulink>.
    </para></listitem>

    <listitem><para>
    {section}'s can be nested, and the nested
   <varname>{section}</varname> names must be unique from each other.
   </para></listitem>

   <listitem><para>
   The <parameter>loop</parameter> attribute,
   usually an array of values, determines the number of times the
   <varname>{section}</varname> will loop.
   </para></listitem>

   <listitem><para>When printing a variable within a <varname>{section}</varname>, the
   <varname>{section}</varname> <parameter>name</parameter> must be given next
   to variable name within [brackets].
   </para></listitem>

   <listitem><para>
   <varname>{sectionelse}</varname> is
   executed when there are no values in the loop variable.
 	</para></listitem>

  <listitem><para>
  A <varname>{section}</varname> also has its own variables that handle
  <varname>{section}</varname> properties.
  These properties are accessible as: <link linkend="language.variables.smarty.loops">
  <parameter>{$smarty.section.name.property}</parameter></link>
  where <quote>name</quote> is the attribute <parameter>name</parameter>.
  </para></listitem>

  <listitem><para>
  <varname>{section}</varname> properties are
  <link linkend="section.property.index"><parameter>index</parameter></link>,
  <link linkend="section.property.index.prev"><parameter>index_prev</parameter></link>,
  <link linkend="section.property.index.next"><parameter>index_next</parameter></link>,
  <link linkend="section.property.iteration"><parameter>iteration</parameter></link>,
  <link linkend="section.property.first"><parameter>first</parameter></link>,
  <link linkend="section.property.last"><parameter>last</parameter></link>,
  <link linkend="section.property.rownum"><parameter>rownum</parameter></link>,
  <link linkend="section.property.loop"><parameter>loop</parameter></link>,
  <link linkend="section.property.show"><parameter>show</parameter></link>,
  <link linkend="section.property.total"><parameter>total</parameter></link>.
  </para></listitem>
</itemizedlist>

 <example>
  <title>Looping a simple array with {section}</title>
<para>
<link linkend="api.assign"><varname>assign()</varname></link> an array to Smarty
</para>
<programlisting role="php">
<![CDATA[
<?php
$data = array(1000,1001,1002);
$smarty->assign('custid',$data);
?>
]]>
</programlisting>
<para>The template that outputs the array</para>
  <programlisting>
<![CDATA[
{* this example will print out all the values of the $custid array *}
{section name=customer loop=$custid}
  id: {$custid[customer]}<br />
{/section}
<hr />
{*  print out all the values of the $custid array reversed *}
{section name=foo loop=$custid step=-1}
  {$custid[foo]}<br />
{/section}
]]>
  </programlisting>
  <para>
   The above example will output:
  </para>
  <screen>
<![CDATA[
id: 1000<br />
id: 1001<br />
id: 1002<br />
<hr />
id: 1002<br />
id: 1001<br />
id: 1000<br />
]]>
  </screen>
  </example>


   <example>
  <title>{section} without an assigned array</title>
<programlisting>
<![CDATA[
{section name=foo start=10 loop=20 step=2}
  {$smarty.section.foo.index}
{/section}
<hr />
{section name=bar loop=21 max=6 step=-2}
  {$smarty.section.bar.index}
{/section}
]]>
</programlisting>
<para>
  The above example will output:
</para>
<screen>
  <![CDATA[
10 12 14 16 18
<hr />
20 18 16 14 12 10
]]>
  </screen>
 </example>


<example>
  <title>Naming a {section}</title>
  <para>The <parameter>name</parameter> of the <varname>{section}</varname> can be anything
  you like, see <ulink url="&url.php-manual;language.variables">PHP variables</ulink>.
  It is used to reference the data within the <varname>{section}</varname>.</para>
  <programlisting>
<![CDATA[
{section name=anything loop=$myArray}
  {$myArray[anything].foo}
  {$name[anything]}
  {$address[anything].bar}
{/section}
]]>
  </programlisting>
 </example>


 <example>
  <title>Looping an associative array with {section}</title>
  <para>This is an example of printing an associative array
   of data with a <varname>{section}</varname>. Following is the php script to assign the
   <parameter>$contacts</parameter> array to Smarty.</para>
  <programlisting role="php">
  <![CDATA[
<?php
$data = array(
          array('name' => '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);
?>
]]>
  </programlisting>

<para>The template to output <parameter>$contacts</parameter></para>
  <programlisting>
<![CDATA[
{section name=customer loop=$contacts}
<p>
  name: {$contacts[customer].name}<br />
  home: {$contacts[customer].home}<br />
  cell: {$contacts[customer].cell}<br />
  e-mail: {$contacts[customer].email}
</p>
{/section}
]]>
  </programlisting>
  <para>
   The above example will output:
  </para>
  <screen>
<![CDATA[
<p>
  name: John Smith<br />
  home: 555-555-5555<br />
  cell: 666-555-5555<br />
  e-mail: john@myexample.com
</p>
<p>
  name: Jack Jones<br />
  home phone: 777-555-5555<br />
  cell phone: 888-555-5555<br />
  e-mail: jack@myexample.com
</p>
<p>
  name: Jane Munson<br />
  home phone: 000-555-5555<br />
  cell phone: 123456<br />
  e-mail: jane@myexample.com
</p>
]]>
  </screen>
</example>

 <example>
  <title>{section} demonstrating the <varname>loop</varname> variable</title>
  <para>This example assumes that <parameter>$custid</parameter>, <parameter>$name</parameter>
  and <parameter>$address</parameter> are all
  arrays containing the same number of values. First the php script that assign's the
  arrays to Smarty.</para>
<programlisting role="php">
<![CDATA[
<?php

$id = array(1001,1002,1003);
$smarty->assign('custid',$id);

$fullnames = array('John Smith','Jack Jones','Jane Munson');
$smarty->assign('name',$fullnames);

$addr = array('253 Abbey road', '417 Mulberry ln', '5605 apple st');
$smarty->assign('address',$addr);

?>
]]>
</programlisting>
<para>The <parameter>loop</parameter> variable only determines the number of times to loop.
  You can access ANY variable from the template within the <varname>{section}</varname></para>
  <programlisting>
<![CDATA[
{section name=customer loop=$custid}
<p>
  id: {$custid[customer]}<br />
  name: {$name[customer]}<br />
  address: {$address[customer]}
</p>
{/section}
]]>
  </programlisting>
  <para>
   The above example will output:
  </para>
  <screen>
<![CDATA[
<p>
  id: 1000<br />
  name: John Smith<br />
  address: 253 Abbey road
</p>
<p>
  id: 1001<br />
  name: Jack Jones<br />
  address: 417 Mulberry ln
</p>
<p>
  id: 1002<br />
  name: Jane Munson<br />
  address: 5605 apple st
</p>
]]>
  </screen>
 </example>



 <example>
  <title>Nested {section}'s</title>
  <para>
  {section}'s can be nested as deep as you like. With nested {section}'s,
  you can access complex data structures, such as multi-dimensional
  arrays. This is an example <filename>.php</filename> script thats assign's the arrays.
  </para>
  <programlisting role="php">
<![CDATA[
<?php

$id = array(1001,1002,1003);
$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');
$smarty->assign('address',$addr);

$types = array(
           array( 'home phone', 'cell phone', 'e-mail'),
           array( 'home phone', 'web'),
           array( 'cell phone')
         );
$smarty->assign('contact_type', $types);

$info = array(
           array('555-555-5555', '666-555-5555', 'john@myexample.com'),
           array( '123-456-4', 'www.example.com'),
           array( '0457878')
        );
$smarty->assign('contact_info', $info);

?>
  ]]>
</programlisting>
<para>In this template, <emphasis>$contact_type[customer]</emphasis> is an array of
  contact types for the current customer.</para>
  <programlisting>
<![CDATA[
{section name=customer loop=$custid}
<hr>
  id: {$custid[customer]}<br />
  name: {$name[customer]}<br />
  address: {$address[customer]}<br />
  {section name=contact loop=$contact_type[customer]}
    {$contact_type[customer][contact]}: {$contact_info[customer][contact]}<br />
  {/section}
{/section}
]]>
  </programlisting>
  <para>
   The above example will output:
  </para>
  <screen>
<![CDATA[
<hr>
  id: 1000<br />
  name: John Smith<br />
  address: 253 N 45th<br />
    home phone: 555-555-5555<br />
    cell phone: 666-555-5555<br />
    e-mail: john@myexample.com<br />
<hr>
  id: 1001<br />
  name: Jack Jones<br />
  address: 417 Mulberry ln<br />
    home phone: 123-456-4<br />
    web: www.example.com<br />
<hr>
  id: 1002<br />
  name: Jane Munson<br />
  address: 5605 apple st<br />
    cell phone: 0457878<br />
]]>
  </screen>
 </example>


<example>
<title>Database example with a {sectionelse}</title>
  <para>Results of a database search (eg ADODB or PEAR) are assigned to Smarty</para>
    <programlisting role="php">
  <![CDATA[
<?php
$sql = 'select id, name, home, cell, email from contacts '
      ."where name like '$foo%' ";
$smarty->assign('contacts', $db->getAll($sql));
?>
]]>
</programlisting>
<para>The template to output the database result in a HTML table</para>
  <programlisting>
<![CDATA[
<table>
<tr><th>&nbsp;</th><th>Name></th><th>Home</th><th>Cell</th><th>Email</th></tr>
{section name=co loop=$contacts}
  <tr>
    <td><a href="view.php?id={$contacts[co].id}">view<a></td>
    <td>{$contacts[co].name}</td>
    <td>{$contacts[co].home}</td>
    <td>{$contacts[co].cell}</td>
    <td>{$contacts[co].email}</td>
  <tr>
{sectionelse}
  <tr><td colspan="5">No items found</td></tr>
{/section}
</table>
]]>
</programlisting>
 </example>


 <sect2 id="section.property.index">
  <title>.index</title>
  <para>
   <parameter>index</parameter> contains the current array index, starting with zero
   or the <parameter>start</parameter> attribute if given. It increments by one or by
   the <parameter>step</parameter> attribute if given.
  </para>
  <note>
   <title>Technical Note</title>
   <para>
    If the <parameter>step</parameter> and <parameter>start</parameter>
     properties are not
    modified, then this works the same as the <link
    linkend="section.property.iteration"><parameter>iteration</parameter></link>
    property, except it starts at zero instead of one.
   </para>
  </note>
  <example>
<title>{section} <varname>index</varname> property</title>
<para>
<note><title>FYI</title>
<para><literal>$custid[customer.index]</literal> and
<literal>$custid[customer]</literal> are identical.</para>
</note>
</para>
   <programlisting>
<![CDATA[
{section name=customer loop=$custid}
  {$smarty.section.customer.index} id: {$custid[customer]}<br />
{/section}
]]>
  </programlisting>
  <para>
   The above example will output:
  </para>
  <screen>
<![CDATA[
0 id: 1000<br />
1 id: 1001<br />
2 id: 1002<br />
]]>
   </screen>
  </example>
 </sect2>


 <sect2 id="section.property.index.prev">
  <title>.index_prev</title>
  <para>
   <parameter>index_prev</parameter> is the previous loop index.
   On the first loop, this is set to -1.
  </para>
 </sect2>

 <sect2 id="section.property.index.next">
  <title>.index_next</title>
  <para>
   <parameter>index_next</parameter> is  the next loop index. On the last
   loop, this is still one more than the current index, respecting the
   setting of the <parameter>step</parameter> attribute, if given.
  </para>

  <example>
<title><varname>index</varname>, <varname>index_next</varname>
 and <varname>index_prev</varname> properties </title>
<programlisting role="php">
<![CDATA[
<?php
$data = array(1001,1002,1003,1004,1005);
$smarty->assign('rows',$data);
?>
]]>
</programlisting>
<para>Template to output the above array in a table</para>
   <programlisting>
<![CDATA[
{* $rows[row.index] and $rows[row] are identical in meaning *}
<table>
  <tr>
    <th>index</th><th>id</th>
    <th>index_prev</th><th>prev_id</th>
    <th>index_next</th><th>next_id</th>
  </tr>
{section name=row loop=$rows}
  <tr>
    <td>{$smarty.section.row.index}</td><td>{$rows[row]}</td>
    <td>{$smarty.section.row.index_prev}</td><td>{$rows[row.index_prev]}</td>
    <td>{$smarty.section.row.index_next}</td><td>{$rows[row.index_next]}</td>
  </tr>
{/section}
</table>
]]>
  </programlisting>
  <para>
 The above example will output a table containing the  following:
  </para>
  <screen>
<![CDATA[
index  id    index_prev prev_id index_next next_id
0      1001  -1	                1          1002
1      1002  0          1001    2          1003
2      1003  1          1002    3          1004
3      1004  2          1003    4          1005
4      1005  3          1004    5
]]>
   </screen>
  </example>
 </sect2>


 <sect2 id="section.property.iteration">
  <title>.iteration</title>
  <para>
   <parameter>iteration</parameter> contains the current loop iteration and starts at one.
  </para>
  <note>
   <para>
    This is not affected by the <varname>{section}</varname> properties
    <parameter>start</parameter>, <parameter>step</parameter> and <parameter>max</parameter>,
     unlike the <link linkend="section.property.index"><parameter>index</parameter></link>
    property. <parameter>iteration</parameter> also starts with one instead of zero
    unlike <parameter>index</parameter>. <link
    linkend="section.property.rownum"><parameter>rownum</parameter></link> is an alias to
    <parameter>iteration</parameter>,  they are identical.
   </para>
  </note>
  <example>
<title>A section's <varname>iteration</varname> property </title>
<programlisting role="php">
<![CDATA[
<?php
// array of 3000 to 3015
$id = range(3000,3015);
$smarty->assign('arr',$id);
?>
]]>
</programlisting>
<para>Template to output every other element of the <literal>$arr</literal>
array as <literal>step=2</literal></para>
   <programlisting>
<![CDATA[
{section name=cu loop=$arr start=5 step=2}
  iteration={$smarty.section.cu.iteration}
  index={$smarty.section.cu.index}
  id={$custid[cu]}<br />
{/section}
]]>
  </programlisting>
  <para>
   The above example will output:
  </para>
  <screen>
<![CDATA[
iteration=1 index=5 id=3005<br />
iteration=2 index=7 id=3007<br />
iteration=3 index=9 id=3009<br />
iteration=4 index=11 id=3011<br />
iteration=5 index=13 id=3013<br />
iteration=6 index=15 id=3015<br />
]]>
   </screen>
  <para>
   Another example that uses the <parameter>iteration</parameter> property to
   output a table header block every five rows.
   Uses the <link linkend="language.function.if"><varname>{if}</varname></link>
   function with the mod operator.
  </para>
   <programlisting>
<![CDATA[
<table>
{section name=co loop=$contacts}
  {if $smarty.section.co.iteration % 5 == 1}
    <tr><th>&nbsp;</th><th>Name></th><th>Home</th><th>Cell</th><th>Email</th></tr>
  {/if}
  <tr>
    <td><a href="view.php?id={$contacts[co].id}">view<a></td>
    <td>{$contacts[co].name}</td>
    <td>{$contacts[co].home}</td>
    <td>{$contacts[co].cell}</td>
    <td>{$contacts[co].email}</td>
  <tr>
{/section}
</table>
]]>
  </programlisting>
</example>
 </sect2>


 <sect2 id="section.property.first">
  <title>.first</title>
  <para>
   <parameter>first</parameter> is set to &true; if the current
   <varname>{section}</varname> iteration is the initial one.
  </para>
 </sect2>


 <sect2 id="section.property.last">
  <title>.last</title>
  <para>
   <parameter>last</parameter> is set to &true;
   if the current section iteration is the final one.
  </para>
  <example>
   <title>{section} property <varname>first</varname> and <varname>last</varname></title>
   <para>
   This example loops the <varname>$customers</varname> array,
   outputs a header block on the first iteration and
   on the last outputs the footer block. Also uses the
   <link linkend="section.property.total"><parameter>total</parameter></link> property.
   </para>
   <programlisting>
<![CDATA[
{section name=customer loop=$customers}
  {if $smarty.section.customer.first}
    <table>
    <tr><th>id</th><th>customer</th></tr>
  {/if}

  <tr>
    <td>{$customers[customer].id}}</td>
    <td>{$customers[customer].name}</td>
  </tr>

  {if $smarty.section.customer.last}
    <tr><td></td><td>{$smarty.section.customer.total} customers</td></tr>
    </table>
  {/if}
{/section}
]]>
  </programlisting>
  </example>
 </sect2>


 <sect2 id="section.property.rownum">
  <title>.rownum</title>
  <para>
   <parameter>rownum</parameter> contains the current loop iteration,
   starting with one. It is an alias to <link
   linkend="section.property.iteration"><parameter>iteration</parameter></link>,
   they work identically.
  </para>
 </sect2>

 <sect2 id="section.property.loop">
  <title>.loop</title>
  <para>
   <parameter>loop</parameter> contains the last index number
   that this {section}
   looped. This can be used inside or after the <varname>{section}</varname>.
     </para>
  <example>
   <title>{section} property <varname>loop</varname></title>
   <programlisting>
<![CDATA[
{section name=customer loop=$custid}
  {$smarty.section.customer.index} id: {$custid[customer]}<br />
{/section}
There are {$smarty.section.customer.loop} customers shown above.
]]>
  </programlisting>
  <para>
   The above example will output:
  </para>
  <screen>
<![CDATA[
0 id: 1000<br />
1 id: 1001<br />
2 id: 1002<br />
There are 3 customers shown above.
]]>
   </screen>
  </example>
 </sect2>

 <sect2 id="section.property.show">
  <title>.show</title>
  <para>
   <parameter>show</parameter> is used as a parameter to section and is
   a boolean value. If
   &false;, the section will not be displayed. If there is a
   <varname>{sectionelse}</varname>  present, that will be alternately displayed.
  </para>
  <example>
   <title><varname>show</varname> property </title>
   <para>Boolean <varname>$show_customer_info</varname> has been passed from the PHP
  application, to regulate whether or not this section shows.</para>
   <programlisting>
<![CDATA[
{section name=customer loop=$customers show=$show_customer_info}
  {$smarty.section.customer.rownum} id: {$customers[customer]}<br />
{/section}

{if $smarty.section.customer.show}
  the section was shown.
{else}
  the section was not shown.
{/if}
]]>
  </programlisting>
  <para>
   The above example will output:
  </para>
  <screen>
<![CDATA[
1 id: 1000<br />
2 id: 1001<br />
3 id: 1002<br />

the section was shown.
]]>
   </screen>
  </example>
 </sect2>

 <sect2 id="section.property.total">
  <title>.total</title>
  <para>
   <parameter>total</parameter> contains the number of iterations that this
   <varname>{section}</varname> will loop. This can be used inside or after a
   <varname>{section}</varname>.
  </para>
  <example>
   <title><varname>total</varname> property example</title>
   <programlisting>
<![CDATA[
{section name=customer loop=$custid step=2}
  {$smarty.section.customer.index} id: {$custid[customer]}<br />
{/section}
   There are {$smarty.section.customer.total} customers shown above.
]]>
  </programlisting>
  </example>
  <para>
   See also <link linkend="language.function.foreach"><varname>{foreach}</varname></link>
   and
   <link linkend="language.variables.smarty.loops"><parameter>$smarty.section</parameter></link>.
  </para>
 </sect2>
</sect1>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->