documentation/manual/ja/module_specs/Zend_Text_Table.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 20799 -->
   4 <sect1 id="zend.text.table.introduction">
   5     <title>Zend_Text_Table</title>
   6
   7     <para>
   8         <classname>Zend_Text_Table</classname> は、さまざまなデコレータを使用して
   9         テキストベースの表をその場で作成するためのコンポーネントです。
  10         これは、たとえばテキスト形式のメールで構造化されたデータを送信したい場合などに便利です。
  11         その場合は等幅フォントを使う必要があります。
  12         また、CLI アプリケーションで表形式の情報を表示する場合にも便利です。
  13         <classname>Zend_Text_Table</classname> は、複数行にわたるカラムやカラムの連結、
  14         テキストの配置の指定に対応しています。
  15     </para>
  16
  17     <note>
  18         <title>エンコーディング</title>
  19
  20         <para>
  21             <classname>Zend_Text_Table</classname> のデフォルトでは、文字列が
  22             UTF-8 でエンコードされていることを前提としています。
  23             もしそれ以外を使用している場合は、文字エンコーディングを
  24             コンストラクタあるいは <classname>Zend_Text_Table_Column</classname>
  25             の <code>setContent</code> メソッドのパラメータで指定します。
  26             もうひとつの方法として、もしそのエンコーディングをプロセス全体で使う場合には
  27             <methodname>Zend_Text_Table::setInputCharset($charset)</methodname>
  28             で標準の入力文字セットを定義できます。
  29             表を出力する際に別の文字セットを使用したい場合は、
  30             <methodname>Zend_Text_Table::setOutputCharset($charset)</methodname> で設定します。
  31         </para>
  32     </note>
  33
  34     <para>
  35         <classname>Zend_Text_Table</classname> オブジェクトは行の集まりで構成されており、
  36         行は列の集まりで構成されています。行と列を表すのが、それぞれ
  37         <classname>Zend_Text_Table_Row</classname> および
  38         <classname>Zend_Text_Table_Column</classname> です。
  39         表を作成する際に、表のオプションを配列で指定できます。
  40         指定できるオプションは次のとおりです。
  41
  42         <itemizedlist>
  43             <listitem>
  44                 <para>
  45                     <code>columnWidths</code> (必須):
  46                     配列で、すべてのカラムとその幅 (文字数) を指定します。
  47                 </para>
  48             </listitem>
  49
  50             <listitem>
  51                 <para>
  52                     <code>decorator</code>: テーブルの罫線に使用するデコレータ。
  53                     デフォルトは <code>unicode</code> ですが、<code>ascii</code>
  54                     あるいは独自のデコレータオブジェクトのインスタンスを指定することもできます。
  55                 </para>
  56             </listitem>
  57
  58             <listitem>
  59                 <para>
  60                     <code>padding</code>: カラムの左右の余白文字数。
  61                     デフォルトはゼロです。
  62                 </para>
  63             </listitem>
  64
  65             <listitem>
  66                 <para>
  67                     <code>AutoSeparate</code>: 各行を横線でどのように区切るかの方法。
  68                     デフォルトは、すべての行間を区切ります。これは、次の
  69                     <classname>Zend_Text_Table</classname> の定数のビットマスクで指定します。
  70
  71                     <itemizedlist>
  72                         <listitem>
  73                             <para><constant>Zend_Text_Table::AUTO_SEPARATE_NONE</constant></para>
  74                         </listitem>
  75
  76                         <listitem>
  77                             <para><constant>Zend_Text_Table::AUTO_SEPARATE_HEADER</constant></para>
  78                         </listitem>
  79
  80                         <listitem>
  81                             <para><constant>Zend_Text_Table::AUTO_SEPARATE_FOOTER</constant></para>
  82                         </listitem>
  83
  84                         <listitem>
  85                             <para><constant>Zend_Text_Table::AUTO_SEPARATE_ALL</constant></para>
  86                         </listitem>
  87                     </itemizedlist>
  88
  89                     ヘッダは常に最初の行、フッタは常に最後の行となります。
  90                 </para>
  91             </listitem>
  92         </itemizedlist>
  93     </para>
  94
  95     <para>
  96         表に行を追加するには、
  97         <classname>Zend_Text_Table_Row</classname> のインスタンスを作成して、それを
  98         <code>appendRow</code> メソッドで追加します。行自体には何もオプションはありません。
  99         配列を直接 <code>appendRow</code> メソッドに渡すこともできます。
 100         この場合は、複数の列オブジェクトからなる行オブジェクトに自動的に変換されます。
 101     </para>
 102
 103     <para>
 104         行に列を追加する方法も同じです。
 105         <classname>Zend_Text_Table_Column</classname> のインスタンスを作成し、
 106         列のオプションをコンストラクタで指定するか、あるいは後から
 107         <code>set*</code> メソッドで設定します。
 108         最初のパラメータは列の中身で、これは複数行にすることもできます。
 109         複数行にする場合は <code>\n</code> で行を区切ります。
 110         2 番目のパラメータは配置を指定します。デフォルトは左詰めで、
 111         <classname>Zend_Text_Table_Column</classname> のクラス定数のいずれかを指定できます。
 112
 113         <itemizedlist>
 114             <listitem>
 115                 <para>
 116                     <constant>ALIGN_LEFT</constant>
 117                 </para>
 118             </listitem>
 119
 120             <listitem>
 121                 <para>
 122                     <constant>ALIGN_CENTER</constant>
 123                 </para>
 124             </listitem>
 125
 126             <listitem>
 127                 <para>
 128                     <constant>ALIGN_RIGHT</constant>
 129                 </para>
 130             </listitem>
 131         </itemizedlist>
 132
 133         3 番目のパラメータは列の連結 (colspan) を指定します。
 134         たとえば、このパラメータに "2" を指定すると、
 135         表の中で 2 つの列が連結されるようになります。
 136         最後のパラメータは列の中身のエンコーディングです。
 137         ASCII および UTF-8 以外を使用する場合は必ず指定しなければなりません。
 138         行を列に追加するには、行オブジェクトの <code>appendColumn</code>
 139         のパラメータに列オブジェクトを指定してコールします。
 140         あるいは、文字列を直接 <code>appendColumn</code> メソッドに渡すこともできます。
 141     </para>
 142
 143     <para>
 144         最後に、表をレンダリングするには <code>render</code>
 145         メソッドを使用します。あるいは、
 146         <code>echo $table;</code> や <code>$tableString = (string) $table</code>
 147         などとしてマジックメソッド <code>__toString</code> を使用することもできます。
 148     </para>
 149
 150     <example id="zend.text.table.example.using">
 151         <title>Zend_Text_Table の使用例</title>
 152
 153         <para>
 154             この例では、<classname>Zend_Text_Table</classname>
 155             でシンプルな表を作成するための方法を示します。
 156         </para>
 157
 158         <programlisting language="php"><![CDATA[
 159 $table = new Zend_Text_Table(array('columnWidths' => array(10, 20)));
 160
 161 // シンプルな例
 162 $table->appendRow(array('Zend', 'Framework'));
 163
 164 // あるいは冗長な例
 165 $row = new Zend_Text_Table_Row();
 166
 167 $row->appendColumn(new Zend_Text_Table_Column('Zend'));
 168 $row->appendColumn(new Zend_Text_Table_Column('Framework'));
 169
 170 $table->appendRow($row);
 171
 172 echo $table;
 173 ]]></programlisting>
 174
 175         <para>
 176             この結果は次のようになります。
 177         </para>
 178
 179         <programlisting language="text"><![CDATA[
 180 ┌──────────┬────────────────────┐
 181 │Zend      │Framework           │
 182 └──────────┴────────────────────┘
 183 ]]></programlisting>
 184     </example>
 185 </sect1>
 186 <!--
 187 vim:se ts=4 sw=4 et:
 188 -->