repo_zf1/documentation/manual/en/module_specs/Zend_Text_Table.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.text.table.introduction">
    <title>Zend_Text_Table</title>

    <para>
        <classname>Zend_Text_Table</classname> is a component to create text based tables
        on the fly with different decorators. This can be helpful, if you either
        want to send structured data in text emails, which are used to have
        mono-spaced fonts, or to display table information in a CLI application.
        <classname>Zend_Text_Table</classname> supports multi-line columns, colspan and
        align as well.
    </para>

    <note>
        <title>Encoding</title>

        <para>
            <classname>Zend_Text_Table</classname> expects your strings to be UTF-8 encoded
            by default. If this is not the case, you can either supply the character
            encoding as a parameter to the <methodname>constructor()</methodname> or the
            <methodname>setContent()</methodname> method of
            <classname>Zend_Text_Table_Column</classname>. Alternatively if you have a different
            encoding in the entire process, you can define the standard input charset with
            <methodname>Zend_Text_Table::setInputCharset($charset)</methodname>. In
            case you need another output charset for the table, you can set
            this with <methodname>Zend_Text_Table::setOutputCharset($charset)</methodname>.
        </para>
    </note>

    <para>
        A <classname>Zend_Text_Table</classname> object consists of rows, which contain
        columns, represented by <classname>Zend_Text_Table_Row</classname> and
        <classname>Zend_Text_Table_Column</classname>. When creating a table, you can
        supply an array with options for the table. Those are:

        <itemizedlist>
            <listitem>
                <para>
                    <property>columnWidths</property> (required): An array defining
                    all columns width their widths in characters.
                </para>
            </listitem>

            <listitem>
                <para>
                    <property>decorator</property>: The decorator to use for the
                    table borders. The default is <emphasis>unicode</emphasis>, but
                    you may also specify <emphasis>ascii</emphasis> or give an instance
                    of a custom decorator object.
                </para>
            </listitem>

            <listitem>
                <para>
                    <property>padding</property>: The left and right padding withing
                    the columns in characters. The default padding is zero.
                </para>
            </listitem>

            <listitem>
                <para>
                    <property>AutoSeparate</property>: The way how the rows are
                    separated with horizontal lines. The default is a
                    separation between all rows. This is defined as a bitmask
                    containing one ore more of the following constants of
                    <classname>Zend_Text_Table</classname>:

                    <itemizedlist>
                        <listitem>
                            <para><constant>Zend_Text_Table::AUTO_SEPARATE_NONE</constant></para>
                        </listitem>

                        <listitem>
                            <para><constant>Zend_Text_Table::AUTO_SEPARATE_HEADER</constant></para>
                        </listitem>

                        <listitem>
                            <para><constant>Zend_Text_Table::AUTO_SEPARATE_FOOTER</constant></para>
                        </listitem>

                        <listitem>
                            <para><constant>Zend_Text_Table::AUTO_SEPARATE_ALL</constant></para>
                        </listitem>
                    </itemizedlist>

                    Where header is always the first row, and the footer is
                    always the last row.
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        Rows are simply added to the table by creating a new instance of
        <classname>Zend_Text_Table_Row</classname>, and appending it to the table via the
        <methodname>appendRow()</methodname> method. Rows themselves have no options. You can also
        give an array to directly to the <methodname>appendRow()</methodname> method, which then
        will automatically converted to a row object, containing multiple column
        objects.
    </para>

    <para>
        The same way you can add columns to the rows. Create a new instance of
        <classname>Zend_Text_Table_Column</classname> and then either set the column
        options in the constructor or later with the <methodname>set*()</methodname> methods.
        The first parameter is the content of the column which may have
        multiple lines, which in the best case are separated by just the
        '\n' character. The second parameter defines the align, which
        is 'left' by default and can be one of the class constants of
        <classname>Zend_Text_Table_Column</classname>:

        <itemizedlist>
            <listitem>
                <para>
                    <constant>ALIGN_LEFT</constant>
                </para>
            </listitem>

            <listitem>
                <para>
                    <constant>ALIGN_CENTER</constant>
                </para>
            </listitem>

            <listitem>
                <para>
                    <constant>ALIGN_RIGHT</constant>
                </para>
            </listitem>
        </itemizedlist>

        The third parameter is the colspan of the column. For example, when you
        choose "2" as colspan, the column will span over two columns of the table.
        The last parameter defines the encoding of the content, which should be
        supplied, if the content is neither ASCII nor UTF-8. To append the column
        to the row, you simply call <methodname>appendColumn()</methodname> in your row object
        with the column object as parameter. Alternatively you can directly
        give a string to the <methodname>appendColumn()</methodname> method.
    </para>

    <para>
        To finally render the table, you can either use the <methodname>render()</methodname>
        method of the table, or use the magic method <methodname>__toString()</methodname>
        by doing <command>echo $table;</command> or
        <command>$tableString = (string) $table</command>.
    </para>

    <example id="zend.text.table.example.using">
        <title>Using Zend_Text_Table</title>

        <para>
            This example illustrates the basic use of <classname>Zend_Text_Table</classname>
            to create a simple table:
        </para>

        <programlisting language="php"><![CDATA[
$table = new Zend_Text_Table(array('columnWidths' => array(10, 20)));

// Either simple
$table->appendRow(array('Zend', 'Framework'));

// Or verbose
$row = new Zend_Text_Table_Row();

$row->appendColumn(new Zend_Text_Table_Column('Zend'));
$row->appendColumn(new Zend_Text_Table_Column('Framework'));

$table->appendRow($row);

echo $table;
]]></programlisting>

        <para>
            This will result in the following output:
        </para>

        <programlisting language="text"><![CDATA[
┌──────────┬────────────────────┐
│Zend      │Framework           │
└──────────┴────────────────────┘
]]></programlisting>
    </example>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->