/documentation/fr/designers/language-builtin-functions/language-function-foreach.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- $Revision: 2972 $ -->
<!-- EN-Revision: 1.11 Maintainer: gerald Status: ready -->

<sect1 id="language.function.foreach">
 <title>{foreach},{foreachelse}</title>
 <para>
  <varname>{foreach}</varname> est utilisé pour parcourir un
  <emphasis role="bold">simple tableau associatif</emphasis>,
  contrairement à <link linkend="language.function.section"><varname>{section}</varname></link>
  qui effectue une boucle sur les <emphasis role="bold">tableaux de données</emphasis>.
  La synthaxe pour
  <varname>{foreach}</varname> est plus simple que
  <link linkend="language.function.section"><varname>{section}</varname></link>,
  mais <emphasis role="bold">ne peut être utilisé que pour des tableau simple</emphasis>.
  Chaque <varname>{foreach}</varname> doit aller de paire avec une balise fermante 
  <varname>{/foreach}</varname>.
 </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>Nom attribut</entry>
     <entry>Type</entry>
     <entry>Requis</entry>
     <entry>Defaut</entry>
     <entry>Description</entry>
    </row>
   </thead>
   <tbody>
    <row>
     <entry>from</entry>
     <entry>tableau</entry>
     <entry>oui</entry>
     <entry><emphasis>n/a</emphasis></entry>
     <entry>Le tableau à parcourir</entry>
    </row>
    <row>
     <entry>item</entry>
     <entry>chaîne de caractère</entry>
     <entry>Oui</entry>
     <entry><emphasis>n/a</emphasis></entry>
     <entry>Le nom de la variable "élément courant"</entry>
    </row>
    <row>
     <entry>key</entry>
     <entry>chaîne de caractère</entry>
     <entry>Non</entry>
     <entry><emphasis>n/a</emphasis></entry>
     <entry>Le nom de la variable représentant la clef courante.</entry>
    </row>
    <row>
     <entry>name</entry>
     <entry>chaîne de caractère</entry>
     <entry>Non</entry>
     <entry><emphasis>n/a</emphasis></entry>
     <entry>Le nom de la boucle foreach, qui nous permettra
      d'accéder à ses propriétés.</entry>
    </row>
   </tbody>
  </tgroup>
 </informaltable>
 
 
 <itemizedlist>
  <listitem><para>
    Required attributes are <parameter>from</parameter> and <parameter>item</parameter>.
   </para></listitem>
  
  <listitem><para>
    The <parameter>name</parameter> of the <varname>{foreach}</varname> loop 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>
    <varname>{foreach}</varname> loops can be nested, and the nested
    <varname>{foreach}</varname> names must be unique from each other.
   </para></listitem>
  
  <listitem><para>
    The <parameter>from</parameter> attribute, usually an array of values,
    determines the number of times <varname>{foreach}</varname> will loop.
   </para></listitem>
  
  <listitem><para>
    <varname>{foreachelse}</varname> is executed when there are no
    values in the <parameter>from</parameter> variable.
   </para></listitem>
  
  <listitem><para>
    <varname>{foreach}</varname> loops also have their own variables that handle properties.
    These are accessed with:
    <link linkend="language.variables.smarty.loops">
     <parameter>{$smarty.foreach.name.property}</parameter></link> with
    <quote>name</quote> being the
    <parameter>name</parameter> attribute.
   </para>
   <note>
    <title>Note</title>
    <para>The <parameter>name</parameter> attribute is only required when
     you want to access a <varname>{foreach</varname>} property, unlike
     <link linkend="language.function.section"><varname>{section}</varname></link>.
     Accessing a <varname>{foreach}</varname> property with <parameter>name</parameter>
     undefined does not throw an error, but leads to unpredictable results instead.
    </para>
   </note>
  </listitem>
  
  <listitem><para>
    <varname>{foreach}</varname> properties are
    <link linkend="foreach.property.index"><parameter>index</parameter></link>,
    <link linkend="foreach.property.iteration"><parameter>iteration</parameter></link>,
    <link linkend="foreach.property.first"><parameter>first</parameter></link>,
    <link linkend="foreach.property.last"><parameter>last</parameter></link>,
    <link linkend="foreach.property.show"><parameter>show</parameter></link>,
    <link linkend="foreach.property.total"><parameter>total</parameter></link>.
   </para></listitem>
 </itemizedlist>

 <example>
  <title>L'attribut <parameter>item</parameter></title>
  <programlisting role="php">
<![CDATA[
<?php
$arr = array(1000, 1001, 1002);
$smarty->assign('myArray', $arr);
?>
]]>
  </programlisting>
  <para>
   Template pour afficher <parameter>$myArray</parameter> dans une liste non-ordonnée.
  </para>
  <programlisting>
<![CDATA[
<ul>
 {foreach from=$myArray item=foo}
 <li>{$foo}</li>
 {/foreach}
</ul>
]]>
  </programlisting>
  <para>
   L'exemple ci-dessus affichera :
  </para>
  <screen>
<![CDATA[
<ul>
 <li>1000</li>
 <li>1001</li>
 <li>1002</li>
</ul>
]]>
  </screen>
 </example>

 <example>
  <title>Utilisation des attributs <parameter>item</parameter> et <parameter>key</parameter></title>
  <programlisting role="php">
<![CDATA[
<?php
$arr = array(9 => 'Tennis', 3 => 'Natation', 8 => 'Programmation');
$smarty->assign('myArray', $arr);
?>
]]>
  </programlisting>
  <para>
   Le template affiche le tableau <parameter>$myArray</parameter> comme paire clé/valeur,
   comme la fonction PHP
   <ulink url="&url.php-manual;foreach"><varname>foreach</varname></ulink>.
  </para>
  <programlisting>
<![CDATA[
<ul>
 {foreach from=$myArray key=k item=v}
 <li>{$k}: {$v}</li>
 {/foreach}
</ul>
]]>
  </programlisting>
  <para>
   L'exemple ci-dessus affichera :
  </para>
  <screen>
<![CDATA[
<ul>
 <li>9: Tennis</li>
 <li>3: Natation</li>
 <li>8: Programmation</li>
</ul>
]]>
  </screen>
 </example>

 <example>
  <title>{foreach} avec un attribut associatif <parameter>item</parameter></title>
  <programlisting role="php">
<![CDATA[
<?php
$items_list = array(23 => array('no' => 2456, 'label' => 'Salad'),
    96 => array('no' => 4889, 'label' => 'Cream')
);
$smarty->assign('items', $items_list);
?>
]]>
  </programlisting>
  <para>
   Le template affiche <parameter>$items</parameter> avec
   <parameter>$myId</parameter> dans l'URL.
  </para>
  <programlisting>
<![CDATA[
<ul>
 {foreach from=$items key=myId item=i}
 <li><a href="item.php?id={$myId}">{$i.no}: {$i.label}</li>
  {/foreach}
 </ul>
 ]]>
  </programlisting>
  <para>
   L'exemple ci-dessus affichera :
  </para>
  <screen>
<![CDATA[
<ul>
<li><a href="item.php?id=23">2456: Salad</li>
<li><a href="item.php?id=96">4889: Cream</li>
</ul>
]]>
  </screen>
 </example>

 <example>
  <title>{foreach} avec <parameter>item</parameter> et <parameter>key</parameter></title>
  <para>Assigne un tableau à Smarty, la clé contient la clé pour chaque valeur de la boucle.</para>
  <programlisting role="php">
<![CDATA[
<?php
$smarty->assign('contacts', array(
array('phone' => '1',
         'fax' => '2',
         'cell' => '3'),
         array('phone' => '555-4444',
         'fax' => '555-3333',
         'cell' => '760-1234')
));
?>
]]>
  </programlisting>
  <para>Le template affiche <parameter>$contact</parameter>.</para>
  <programlisting>
<![CDATA[
{foreach name=outer item=contact from=$contacts}
    <hr />
    {foreach key=key item=item from=$contact}
        {$key}: {$item}<br />
    {/foreach}
{/foreach}
]]>
  </programlisting>
  <para>
   L'exemple ci-dessus affichera :
  </para>
  <screen>
<![CDATA[
<hr />
phone: 1<br />
fax: 2<br />
cell: 3<br />
<hr />
phone: 555-4444<br />
fax: 555-3333<br />
cell: 760-1234<br />
]]>
  </screen>
 </example>

 <example>
  <title>Exemple d'une base de données avec {foreachelse}</title>
  <para>Exemple d'un script de recherche dans une base de données (e.g. PEAR ou ADODB),
   le résultat de la requête est assigné à Smarty.</para>
  <programlisting role="php">
<![CDATA[
<?php
$search_condition = "where name like '$foo%' ";
$sql = 'select contact_id, name, nick from contacts '.$search_condition.' order by name';
$smarty->assign('results', $db->getAssoc($sql) );
?>
]]>
  </programlisting>
  <para>Le template qui affiche <quote>None found</quote>
   si aucun résultat avec <varname>{foreachelse}</varname>.</para>
  <programlisting>
<![CDATA[
{foreach key=cid item=con from=$results}
<a href="contact.php?contact_id={$cid}">{$con.name} - {$con.nick}</a><br />
{foreachelse}
Aucun élément n'a été trouvé dans la recherche
{/foreach}
]]>
   </programlisting>
  </example>

  <sect2 id="foreach.property.index">
   <title>.index</title>
   <para>
    <parameter>index</parameter> contient l'index courant du tableau, en commançant par zéro.
   </para>
   <example>
    <title>Exemple avec <parameter>index</parameter></title>
    <programlisting role="php">
 <![CDATA[
 {* L'en-tête du block est affiché toutes les 5 lignes *}
<table>
 {foreach from=$items key=myId item=i name=foo}
 {if $smarty.foreach.foo.index % 5 == 0}
 <tr><th>Title</th></tr>
 {/if}
 <tr><td>{$i.label}</td></tr>
 {/foreach}
</table>
]]>
  </programlisting>
 </example>
</sect2>

<sect2 id="foreach.property.iteration">
 <title>.iteration</title>
 <para>
  <parameter>iteration</parameter> contient l'itération courante de la boucle et commence
  toujours à 1, contrairement à
  <link linkend="foreach.property.index"><parameter>index</parameter></link>.
  Il est incrémenté d'un, à chaque itération.
 </para>
 <example>
  <title>Exemple avec <parameter>iteration</parameter> et <parameter>index</parameter></title>
  <programlisting role="php">
<![CDATA[
{* this will output 0|1, 1|2, 2|3, ... etc *}
{foreach from=$myArray item=i name=foo}
{$smarty.foreach.foo.index}|{$smarty.foreach.foo.iteration},
{/foreach}
]]>
  </programlisting>
 </example>
</sect2>
<sect2 id="foreach.property.first">
  <title>.first</title>
  <para>
   <parameter>first</parameter> vaut &true; si l'itération courante de
   <varname>{foreach}</varname> est l'initial.
  </para>
  <example>
   <title>Exemple avec <parameter>first</parameter></title>
   <programlisting role="php">
<![CDATA[
 {* affiche LATEST sur le premier élément, sinon, l'id *}
 <table>
  {foreach from=$items key=myId item=i name=foo}
  <tr>
  <td>{if $smarty.foreach.foo.first}LATEST{else}{$myId}{/if}</td>
  <td>{$i.label}</td>
 </tr>
 {/foreach}
</table>
]]>
  </programlisting>
 </example>
</sect2>
<sect2 id="foreach.property.last">
 <title>.last</title>
 <para>
  <parameter>last</parameter> est défini à &true; si l'itération courante de
  <varname>{foreach}</varname> est la dernière.
 </para>
 <example>
  <title>Exemple avec <parameter>last</parameter></title>
  <programlisting role="php">
<![CDATA[
{* Ajout une barre horizontale à la fin de la liste *}
{foreach from=$items key=part_id item=prod name=products}
<a href="#{$part_id}">{$prod}</a>{if $smarty.foreach.products.last}<hr>{else},{/if}
{foreachelse}
... contenu ...
{/foreach}
]]>
  </programlisting>
 </example>
</sect2>
<sect2 id="foreach.property.show">
 <title>.show</title>
 <para>
  <parameter>show</parameter> est utilisé en tant que paramètre à <varname>{foreach}</varname>.
  <parameter>show</parameter> est une valeur booléenne. S'il vaut
  &false;, <varname>{foreach}</varname> ne sera pas affiché.
  S'il y a un <varname>{foreachelse}</varname>, il sera affiché alternativement.
 </para>
</sect2>

<sect2 id="foreach.property.total">
 <title>.total</title>
 <para>
  <parameter>total</parameter> contient le nombre d'itérations que cette boucle
  <varname>{foreach}</varname> effectuera.
  Il peut être utilisé dans ou après un <varname>{foreach}</varname>.
 </para>
 <example>
  <title>Exemple avec <parameter>total</parameter></title>
  <programlisting role="php">
<![CDATA[
{* affiche les lignes retournées à la fin *}
{foreach from=$items key=part_id item=prod name=foo}
{$prod.name><hr/>
{if $smarty.foreach.foo.last}
<div id="total">{$smarty.foreach.foo.total} items</div>
{/if}
{foreachelse}
... quelque chose d'autre ...
{/foreach}
]]>
 </programlisting>
</example>

  <para>
   Voir aussi
   <link linkend="language.function.section"><varname>{section}</varname></link>
   et <link linkend="language.variables.smarty.loops"><parameter>$smarty.foreach</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
-->