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>
 <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>
 <para>
  Template sections are used for looping over
  <emphasis role="bold">arrays of data</emphasis>
  (just like <link linkend="language.function.foreach">{foreach}</link>). All
  <emphasis>{section}</emphasis> tags must be paired with
  <emphasis>{/section}</emphasis> tags. Required parameters are
  <emphasis>name</emphasis> and <emphasis>loop</emphasis>. 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
  []. <emphasis>{sectionelse}</emphasis> is
  executed when there are no values in the loop variable.
 </para>
 <example>
  <title>{section}</title>

<programlisting role="php">
<![CDATA[
<?php

$data = array(1000,1001,1002);
$smarty->assign('custid',$data);

?>
]]>
</programlisting>
  <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>
  <para>
  Another couple of examples without an assigned array.
  </para>
<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>{section} loop variable</title>
<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);

?>
]]>
</programlisting>
  <programlisting>
<![CDATA[
{*
  the loop variable only determines the number of times to loop.
  you can access any variable from the template within the section.
  This example assumes that $custid, $name and $address are all
  arrays containing the same number of values
*}
{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 N 45th
</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>{section} naming</title>
  <programlisting>
<![CDATA[
{*
  the name of the section can be anything you like,
  as it is used to reference the data within the section
*}
{section name=anything loop=$custid}
<p>
  id: {$custid[anything]}<br />
  name: {$name[anything]}<br />
  address: {$address[anything]}
</p>
{/section}
]]>
  </programlisting>
 </example>

 <example>
  <title>nested sections</title>
  <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>
  <programlisting>
<![CDATA[
{*
  sections can be nested as deep as you like. With nested sections,
  you can access complex data structures, such as multi-dimensional
  arrays. In this example, $contact_type[customer] is an array of
  contact types for the current customer.
*}
{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>sections and associative arrays</title>
  <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>

  <programlisting>
<![CDATA[
{*
   This is an example of printing an associative array
   of data within a section
*}
{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>

  <para>Database example (eg using Pear or Adodb)</para>
    <programlisting role="php">
  <![CDATA[
<?php

$sql = 'select id, name, home, cell, email from contacts';
$smarty->assign('contacts',$db->getAll($sql) );

?>
]]>
</programlisting>

  <programlisting>
<![CDATA[
{*
   output database result in a table
*}
<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>
{/section}
</table>
]]>
</programlisting>
 </example>

 <example>
  <title>{sectionelse}</title>
  <programlisting>
<![CDATA[
{* sectionelse will execute if there are no $custid values *}
{section name=customer loop=$custid}
  id: {$custid[customer]}<br />
{sectionelse}
  there are no values in $custid.
{/section}
]]>
  </programlisting>
 </example>
 <para>
  Sections also have their own variables that handle section properties.
  These are indicated like so:
  <link linkend="language.variables.smarty.loops">{$smarty.section.sectionname.varname}</link>
 </para>
 <note>
  <para>
   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.
  </para>
 </note>
 <sect2 id="section.property.index">
  <title>index</title>
  <para>
   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.)
  </para>
  <note>
   <title>Technical Note</title>
   <para>
    If the step and start section properties are not
    modified, then this works the same as the <link
    linkend="section.property.iteration">iteration</link> section
    property, except it starts at 0 instead of 1.
   </para>
  </note>
  <example>
<title>{section} property index</title>
   <programlisting>
<![CDATA[
{* FYI, $custid[customer.index] and $custid[customer] are identical in meaning *}

{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>
   index_prev is used to display 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>
   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.)
  </para>

  <example>
<title>{section} property index_next and index_prev</title>
<programlisting role="php">
<![CDATA[
<?php

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

?>
]]>
</programlisting>
   <programlisting>
<![CDATA[
{* FYI, $custid[cus.index] and $custid[cus] 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=cus loop=$custid}
  <tr>
    <td>{$smarty.section.cus.index}</td><td>{$custid[cus]}</td>
    <td>{$smarty.section.cus.index_prev}</td><td>{$custid[cus.index_prev]}</td>
    <td>{$smarty.section.cus.index_next}</td><td>{$custid[cus.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>
   iteration is used to display the current loop iteration.
  </para>
  <note>
   <para>
    This is not affected by the section properties start, step and
    max, unlike the <link linkend="section.property.index">index</link>
    property. Iteration also starts with 1 instead of 0 like index. <link
    linkend="section.property.rownum">rownum</link> is an alias to iteration,
    they work identical.
   </para>
  </note>
  <example>
<title>{section} property iteration</title>
<programlisting role="php">
<![CDATA[
<?php

// array of 3000 to 3015
$id = range(3000,3015);
$smarty->assign('custid',$id);

?>
]]>
</programlisting>
   <programlisting>
<![CDATA[
{section name=cu loop=$custid 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>
   This  example  uses the iteration property to
   output a table header block every five rows
   (uses <link linkend="language.function.if">{if}</link>
   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>
   first is set to true if the current section <link
   linkend="section.property.iteration">iteration</link> is the first
   one.
  </para>
 </sect2>


 <sect2 id="section.property.last">
  <title>last</title>
  <para>
   last is set to true if the current section <link
   linkend="section.property.iteration">iteration</link> is the last
   one.
  </para>
  <example>
   <title>{section} property first and last</title>
   <para>
   This example loops the $customers array;
   outputs a header block on the first iteration and
   on the last outputs the footer block
   (uses section <link linkend="section.property.total">total</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>
   rownum is used to display the current loop iteration,
   starting with one. It is an alias to <link
   linkend="section.property.iteration">iteration</link>, they work
   identically.
  </para>
 </sect2>
 <sect2 id="section.property.loop">
  <title>loop</title>
  <para>
   loop is used to display the last index number that this section
   looped. This can be used inside or after the section.
  </para>
  <example>
   <title>{section} property index</title>
   <programlisting>
<![CDATA[
{section name=customer loop=$custid}
  {$smarty.section.customer.index} id: {$custid[customer]}<br />
{/section}

There were {$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 were 3 customers shown above.
]]>
   </screen>
  </example>
 </sect2>
 <sect2 id="section.property.show">
  <title>show</title>
  <para>
   <emphasis>show</emphasis> is used as a parameter to section.
   <emphasis>show</emphasis> 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.
  </para>
  <example>
   <title>{section} attribute show</title>
   <programlisting>
<![CDATA[
{*
  $show_customer_info (true/false) may have been passed from the PHP
  application, to regulate whether or not this section shows
*}
{section name=customer loop=$custid show=$show_customer_info}
  {$smarty.section.customer.rownum} id: {$custid[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>
   total is used to display the number of iterations that this section
   will loop. This can be used inside or after the section.
  </para>
  <example>
   <title>{section} property total</title>
   <programlisting>
<![CDATA[
{section name=customer loop=$custid step=2}
  {$smarty.section.customer.index} id: {$custid[customer]}<br />
{/section}

    There were {$smarty.section.customer.total} customers shown above.
]]>
  </programlisting>
  <para>
   The above example will output:
  </para>
  <screen>
<![CDATA[
0 id: 1000<br />
2 id: 1002<br />
4 id: 1004<br />

There were 3 customers shown above.
]]>
   </screen>
  </example>
  <para>
   See also <link linkend="language.function.foreach">{foreach}</link>
   and <link linkend="language.variables.smarty.loops">$smarty.section</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
-->