documentation/manual/en/module_specs/Zend_Text_Table.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.text.table.introduction">
   4     <title>Zend_Text_Table</title>
   5
   6     <para>
   7         <classname>Zend_Text_Table</classname> is a component to create text based tables
   8         on the fly with different decorators. This can be helpful, if you either
   9         want to send structured data in text emails, which are used to have
  10         mono-spaced fonts, or to display table information in a CLI application.
  11         <classname>Zend_Text_Table</classname> supports multi-line columns, colspan and
  12         align as well.
  13     </para>
  14
  15     <note>
  16         <title>Encoding</title>
  17
  18         <para>
  19             <classname>Zend_Text_Table</classname> expects your strings to be UTF-8 encoded
  20             by default. If this is not the case, you can either supply the character
  21             encoding as a parameter to the <code>constructor</code> or the
  22             <code>setContent</code> method of <classname>Zend_Text_Table_Column</classname>.
  23             Alternatively if you have a different encoding in the entire
  24             process, you can define the standard input charset with
  25             <methodname>Zend_Text_Table::setInputCharset($charset)</methodname>. In
  26             case you need another output charset for the table, you can set
  27             this with <methodname>Zend_Text_Table::setOutputCharset($charset)</methodname>.
  28         </para>
  29     </note>
  30
  31     <para>
  32         A <classname>Zend_Text_Table</classname> object consists of rows, which contain
  33         columns, represented by <classname>Zend_Text_Table_Row</classname> and
  34         <classname>Zend_Text_Table_Column</classname>. When creating a table, you can
  35         supply an array with options for the table. Those are:
  36
  37         <itemizedlist>
  38             <listitem>
  39                 <para>
  40                     <code>columnWidths</code> (required): An array defining
  41                     all columns width their widths in characters.
  42                 </para>
  43             </listitem>
  44
  45             <listitem>
  46                 <para>
  47                     <code>decorator</code>: The decorator to use for the
  48                     table borders. The default is <code>unicode</code>, but
  49                     you may also specify <code>ascii</code> or give an instance
  50                     of a custom decorator object.
  51                 </para>
  52             </listitem>
  53
  54             <listitem>
  55                 <para>
  56                     <code>padding</code>: The left and right padding withing
  57                     the columns in characters. The default padding is zero.
  58                 </para>
  59             </listitem>
  60
  61             <listitem>
  62                 <para>
  63                     <code>AutoSeparate</code>: The way how the rows are
  64                     separated with horizontal lines. The default is a
  65                     separation between all rows. This is defined as a bitmask
  66                     containing one ore more of the following constants of
  67                     <classname>Zend_Text_Table</classname>:
  68
  69                     <itemizedlist>
  70                         <listitem>
  71                             <para><constant>Zend_Text_Table::AUTO_SEPARATE_NONE</constant></para>
  72                         </listitem>
  73
  74                         <listitem>
  75                             <para><constant>Zend_Text_Table::AUTO_SEPARATE_HEADER</constant></para>
  76                         </listitem>
  77
  78                         <listitem>
  79                             <para><constant>Zend_Text_Table::AUTO_SEPARATE_FOOTER</constant></para>
  80                         </listitem>
  81
  82                         <listitem>
  83                             <para><constant>Zend_Text_Table::AUTO_SEPARATE_ALL</constant></para>
  84                         </listitem>
  85                     </itemizedlist>
  86
  87                     Where header is always the first row, and the footer is
  88                     always the last row.
  89                 </para>
  90             </listitem>
  91         </itemizedlist>
  92     </para>
  93
  94     <para>
  95         Rows are simply added to the table by creating a new instance of
  96         <classname>Zend_Text_Table_Row</classname>, and appending it to the table via the
  97         <code>appendRow</code> method. Rows themselves have no options. You can also
  98         give an array to directly to the <code>appendRow</code> method, which then
  99         will automatically converted to a row object, containing multiple column
 100         objects.
 101     </para>
 102
 103     <para>
 104         The same way you can add columns to the rows. Create a new instance of
 105         <classname>Zend_Text_Table_Column</classname> and then either set the column
 106         options in the constructor or later with the <code>set*</code> methods.
 107         The first parameter is the content of the column which may have
 108         multiple lines, which in the best case are separated by just the
 109         <code>\n</code> character. The second parameter defines the align, which
 110         is <code>left</code> by default and can be one of the class constants of
 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         The third parameter is the colspan of the column. For example, when you
 134         choose "2" as colspan, the column will span over two columns of the table.
 135         The last parameter defines the encoding of the content, which should be
 136         supplied, if the content is neither ASCII nor UTF-8. To append the column
 137         to the row, you simply call <code>appendColumn</code> in your row object
 138         with the column object as parameter. Alternatively you can directly
 139         give a string to the <code>appendColumn</code> method.
 140     </para>
 141
 142     <para>
 143         To finally render the table, you can either use the <code>render</code>
 144         method of the table, or use the magic method <code>__toString</code>
 145         by doing <code>echo $table;</code> or <code>$tableString = (string) $table</code>.
 146     </para>
 147
 148     <example id="zend.text.table.example.using">
 149         <title>Using Zend_Text_Table</title>
 150
 151         <para>
 152             This example illustrates the basic use of <classname>Zend_Text_Table</classname>
 153             to create a simple table:
 154         </para>
 155
 156         <programlisting language="php"><![CDATA[
 157 $table = new Zend_Text_Table(array('columnWidths' => array(10, 20)));
 158
 159 // Either simple
 160 $table->appendRow(array('Zend', 'Framework'));
 161
 162 // Or verbose
 163 $row = new Zend_Text_Table_Row();
 164
 165 $row->appendColumn(new Zend_Text_Table_Column('Zend'));
 166 $row->appendColumn(new Zend_Text_Table_Column('Framework'));
 167
 168 $table->appendRow($row);
 169
 170 echo $table;
 171 ]]></programlisting>
 172
 173         <para>
 174             This will result in the following output:
 175         </para>
 176
 177         <programlisting language="text"><![CDATA[
 178 ┌──────────┬────────────────────┐
 179 │Zend      │Framework           │
 180 └──────────┴────────────────────┘
 181 ]]></programlisting>
 182     </example>
 183 </sect1>
 184 <!--
 185 vim:se ts=4 sw=4 et:
 186 -->