smarty/docs/ja/designers/language-builtin-functions/language-function-foreach.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 1.11 Maintainer: takagi Status: ready -->
<!-- CREDITS: mat-sh,daichi,joe -->
<sect1 id="language.function.foreach">
 <title>{foreach},{foreachelse}</title>
  <para>
  <varname>{foreach}</varname> を使用して、
   <emphasis role="bold">１つの連想配列</emphasis> をループします。
   <link linkend="language.function.section"><varname>{section}</varname></link>
  のように、<emphasis role="bold">データの配列</emphasis> をループすることはありません。
   <varname>{foreach}</varname> の構文は
   <link linkend="language.function.section"><varname>{section}</varname></link>
   よりずっと簡単ですが、その代わりに <emphasis role="bold">１つの配列</emphasis>
   しか扱えません。すべての <varname>{foreach}</varname> タグは、
   終了タグ <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>属性名</entry>
     <entry>型</entry>
     <entry>必須</entry>
     <entry>デフォルト</entry>
     <entry>概要</entry>
    </row>
   </thead>
   <tbody>
    <row>
     <entry>from</entry>
     <entry>array</entry>
     <entry>Yes</entry>
     <entry><emphasis>n/a</emphasis></entry>
     <entry>ループに使用する配列</entry>
    </row>
    <row>
     <entry>item</entry>
     <entry>string</entry>
     <entry>Yes</entry>
     <entry><emphasis>n/a</emphasis></entry>
     <entry>現在の要素を示す変数の名前</entry>
    </row>
    <row>
     <entry>key</entry>
     <entry>string</entry>
     <entry>No</entry>
     <entry><emphasis>n/a</emphasis></entry>
     <entry>現在のキーを示す変数の名前</entry>
    </row>
    <row>
     <entry>name</entry>
     <entry>string</entry>
     <entry>No</entry>
     <entry><emphasis>n/a</emphasis></entry>
     <entry>foreach プロパティにアクセスするための foreach ループ名</entry>
    </row>
   </tbody>
  </tgroup>
 </informaltable>


   <itemizedlist>
   <listitem><para>
   必須の属性は <parameter>from</parameter> と <parameter>item</parameter> です。
   </para></listitem>

   <listitem><para>
   <varname>{foreach}</varname> ループの <parameter>name</parameter>
   は、英数字とアンダースコアを使用して自由に命名できます。これは
    <ulink url="&url.php-manual;language.variables">PHP の変数</ulink>
   と同じです。
   </para></listitem>

   <listitem><para>
   <varname>{foreach}</varname> ループはネスト可能で、ネストした
   <varname>{foreach}</varname> の name はお互いにユニークである必要があります。
   </para></listitem>

   <listitem><para>
   <parameter>from</parameter> 属性は、通常は値の配列で、
   <varname>{foreach}</varname> のループ回数を決定するために使われます。
   </para></listitem>

   <listitem><para>
   <varname>{foreachelse}</varname> は、
   <parameter>from</parameter> 変数の値が存在しない場合に実行されます。
   </para></listitem>

  <listitem><para>
      <varname>{foreach}</varname> ループは、プロパティを操作する変数を自身で持っています。
      これらは次のように表されます。
      <link linkend="language.variables.smarty.loops">
      <parameter>{$smarty.foreach.name.property}</parameter></link>
      ここで、<quote>name</quote> は
      <parameter>name</parameter> 属性の値となります。
      </para>
      <note>
      <title>注意</title>
      <para><parameter>name</parameter> 属性が必要となるのは
      <varname>{foreach</varname>} のプロパティにアクセスする必要がある場合のみです。
      これは <link linkend="language.function.section"><varname>{section}</varname></link>
      の場合とは異なります。<varname>{foreach}</varname> のプロパティに対して
      定義されていない <parameter>name</parameter> でアクセスしてもエラーは発生しませんが、
      結果は予測できない値になります。
      </para>
      </note>
  </listitem>

  <listitem><para>
    <varname>{foreach}</varname> のプロパティには
    <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><parameter>item</parameter> 属性</title>
  <programlisting role="php">
<![CDATA[
<?php
$arr = array(1000, 1001, 1002);
$smarty->assign('myArray', $arr);
?>
]]>
  </programlisting>
   <para><parameter>$myArray</parameter> を順序なしリストで出力するテンプレート</para>
  <programlisting>
<![CDATA[
<ul>
{foreach from=$myArray item=foo}
    <li>{$foo}</li>
{/foreach}
</ul>
]]>
  </programlisting>
  <para>
   出力
  </para>
  <screen>
<![CDATA[
<ul>
    <li>1000</li>
    <li>1001</li>
    <li>1002</li>
</ul>
]]>
  </screen>
 </example>

<example>
  <title><parameter>item</parameter> および <parameter>key</parameter> 属性の説明</title>
  <programlisting role="php">
<![CDATA[
<?php
$arr = array(9 => 'Tennis', 3 => 'Swimming', 8 => 'Coding');
$smarty->assign('myArray', $arr);
?>
]]>
  </programlisting>
   <para><parameter>$myArray</parameter> を キー/値 のペアで出力するテンプレート。
   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>
   出力
  </para>
  <screen>
<![CDATA[
<ul>
    <li>9: Tennis</li>
    <li>3: Swimming</li>
    <li>8: Coding</li>
</ul>
]]>
  </screen>
 </example>


 <example>
  <title>{foreach} で連想配列の <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><parameter>$items</parameter> と
   <parameter>$myId</parameter> を 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>
   出力
  </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} で <parameter>item</parameter> と <parameter>key</parameter> をネストする例</title>
  <para>配列を Smarty に割り当てます。key にはループする値のキーが含まれます。</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><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>
   出力
  </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>データベースを使用する {foreachelse} の例</title>
  <para>データベース (PEAR や ADODB など) を検索する例で、クエリの結果を 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>結果がない場合に、<varname>{foreachelse}</varname>
  を使用して <quote>見つかりません</quote> と表示するテンプレート</para>
  <programlisting>
<![CDATA[
{foreach key=cid item=con from=$results}
    <a href="contact.php?contact_id={$cid}">{$con.name} - {$con.nick}</a><br />
{foreachelse}
    検索結果が見つかりませんでした
{/foreach}
]]>
  </programlisting>
 </example>


 <sect2 id="foreach.property.index">
  <title>.index</title>
  <para>
   <parameter>index</parameter> には、現在の配列のインデックスをゼロから数えた値が含まれます。
  </para>
  <example>
  <title><parameter>index</parameter> の例</title>

<programlisting role="php">
<![CDATA[
{* ヘッダブロックを５行おきに出力します *}
<table>
{foreach from=$items key=myId item=i name=foo}
  {if $smarty.foreach.foo.index % 5 == 0}
     <tr><th>タイトル</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> は現在のループが反復された回数を表示します。
   <link linkend="foreach.property.index"><parameter>index</parameter></link>
   とは異なり、常に 1 から始まります。
   各ループごとに 1 ずつ加算されます。
  </para>
 <example>
  <title><parameter>iteration</parameter> および <parameter>index</parameter> の例</title>
<programlisting role="php">
<![CDATA[
{* この出力は 0|1, 1|2, 2|3, ... のようになります *}
{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> は、現在の <varname>{foreach}</varname>
   の反復が最初のものであるときに &true; となります。
  </para>
  <example>
  <title><parameter>first</parameter> プロパティの例</title>
<programlisting role="php">
<![CDATA[
{* 最初の項目には「最新」、それ以外は id を表示します *}
<table>
{foreach from=$items key=myId item=i name=foo}
<tr>
  <td>{if $smarty.foreach.foo.first}最新{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> は、現在の <varname>{foreach}</varname>
   の反復が最後のものであるときに &true; となります。
  </para>
   <example>
  <title><parameter>last</parameter> プロパティの例</title>
<programlisting role="php">
<![CDATA[
{* 一覧の最後に横罫線を追加します *}
{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}
  ... コンテンツ ...
{/foreach}
]]>
  </programlisting>
  </example>
 </sect2>

 <sect2 id="foreach.property.show">
  <title>.show</title>
  <para>
   <parameter>show</parameter> は <varname>{foreach}</varname> のパラメータとして使用します。
   <parameter>show</parameter> は boolean 値です。
   &false; の場合は <varname>{foreach}</varname> は表示されず、
   もし <varname>{foreachelse}</varname> が存在すれば、それが代わりに表示されます。
  </para>

 </sect2>
 <sect2 id="foreach.property.total">
  <title>.total</title>
  <para>
   <parameter>total</parameter> には、
   <varname>{foreach}</varname> がループするトータル回数が含まれます。
   これは、<varname>{foreach}</varname> の内部だけではなく
   ループを抜けた後でも使用できます。
  </para>
     <example>
  <title><parameter>total</parameter> プロパティの例</title>
<programlisting role="php">
<![CDATA[
{* 返された行の総数を最後に表示します *}
{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}
 ... 別の内容 ...
{/foreach}
]]>
  </programlisting>
  </example>

  <para>
   <link linkend="language.function.section"><varname>{section}</varname></link>
   および  <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
-->