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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 15157 -->
<!-- Reviewed: no -->
<sect1 id="zend.text.table.introduction">
    <title>Zend_Text_Table</title>
    <para>
        <classname>Zend_Text_Table</classname> ist eine Komponente für die Erstellung von Text-basierenden Tabellen
        welche mit unterschiedlichen Dekoratoren arbeitet. Das kann hilfreich sein, wenn man entweder
        strukturierte Daten in einer Textemail verwenden will, welche normalerweise mit monospaced Schriftarten
        geschrieben sind, oder um Tabelleninformationen in einer CLI Anwendung darzustellen.
        <classname>Zend_Text_Table</classname> unterstützt mehrzeilige Spalten, Colspan und auch Ausrichtung.
    </para>
    <note>
        <title>Kodierung</title>
        <para>
            <classname>Zend_Text_Table</classname> erwartet die Strings standardmäßig als UTF-8 kodiert. Wenn das nicht
            der Fall ist, kann entweder die Zeichenkodierung als Parameter an den <code>Constructor</code>
            übergeben werden, oder an die <code>setContent</code> Methode von <classname>Zend_Text_Table_Column</classname>.
            Wenn man im kompletten Prozess eine andere Kodierung verwendet, kann man die standardmäßige
            Eingabekodierung mit <classname>Zend_Text_Table::setInputCharset($charset)</classname> setzen.
            Im Fall, das man eine andere Ausgabekodierung für die Tabelle benötigt, kann diese mit
            <classname>Zend_Text_Table::setOutputCharset($charset)</classname> gesetzt werden.
        </para>
    </note>
    <para>
        Ein <classname>Zend_Text_Table</classname> Objekt besteht aus Zeilen, die Spalten enthalten, repräsentiert durch
        <classname>Zend_Text_Table_Row</classname> und <classname>Zend_Text_Table_Column</classname>. Wenn eine Tabelle erstellt
        wird, kann ein Array mit Optionen für die Tabelle angegeben werden: Diese sind:

        <itemizedlist>
            <listitem>
                <para>
                    <code>columnWidths</code> (required): Ein Array das alle Spalten mit Ihrer Breite in Zeichen
                    definiert.
                </para>
            </listitem>
            <listitem>
                <para>
                    <code>decorator</code>: Der Dekorator der für die Tabellenränder verwendet wird. Der
                    Standard ist <code>unicode</code>, aber man kann auch <code>ascii</code> spezifizieren,
                    oder eine Instanz eines eigenen Dekoratorobjekts angeben.
                </para>
            </listitem>
            <listitem>
                <para>
                    <code>padding</code>: Die linke und rechte Füllung innerhalb der Spalten in Zeichen. Die
                    Standardfüllung ist Null.
                </para>
            </listitem>
            <listitem>
                <para>
                    <code>AutoSeparate</code>: Der Weg auf dem Zeilen mit horizontalen Linien getrennt werden.
                    Der Standard ist eine Trennung zwischen allen Zeilen. Das ist als Bitmaske definiert die
                    ein oder mehrere der folgenden Konstanten von <classname>Zend_Text_Table</classname> haben kann:
                    <itemizedlist>
                        <listitem>
                            <para><classname>Zend_Text_Table::AUTO_SEPARATE_NONE</classname></para>
                        </listitem>
                        <listitem>
                            <para><classname>Zend_Text_Table::AUTO_SEPARATE_HEADER</classname></para>
                        </listitem>
                        <listitem>
                            <para><classname>Zend_Text_Table::AUTO_SEPARATE_FOOTER</classname></para>
                        </listitem>
                        <listitem>
                            <para><classname>Zend_Text_Table::AUTO_SEPARATE_ALL</classname></para>
                        </listitem>
                    </itemizedlist>
                    Wobei der Tabellenheader immer die erste Zeile ist, und der Tabellenfooter immer die letzte
                    Zeile.
                </para>
            </listitem>
        </itemizedlist>
    </para>
    <para>
        Zeilen werden zur Tabelle einfach hinzugefügt indem eine neue Instanz von <classname>Zend_Text_Table_Row</classname>
        erstellt, und der Tabelle über die <code>appendRow</code> Methode angehängt wird. Zeilen selbst haben
        keine Optionen. Man kann der <code>appendRow</code> Methode auch direkt auch ein Array geben, welches
        dann automatisch in ein Zeilenobjekt konvertiert wird, welches mehrere Spaltenobjekte enthält.
    </para>
    <para>
        Auf dem gleichen Weg kann man Spalten zu Zeilen hinzufügen. Man erstellt eine neue Instanz von
        <classname>Zend_Text_Table_Column</classname> und setzt dann entweder die Zeilenoptionen im Constructor, oder
        später mit den <code>set*</code> Methoden. Der erste Parameter ist der Inhalt der Spalte, welcher
        mehrere Zeilen haben kann, welche im besten Fall einfach durch das <code>\n</code> Zeichen getrennt
        sind. Der zweite Parameter definiert die Ausrichtung, welche standardmäßig <code>left</code> ist, und
        eine der Klassenkonstanten von <classname>Zend_Text_Table_Column</classname> sein kann:

        <itemizedlist>
            <listitem>
                <para>
                    <code>ALIGN_LEFT</code>
                </para>
            </listitem>
            <listitem>
                <para>
                    <code>ALIGN_CENTER</code>
                </para>
            </listitem>
            <listitem>
                <para>
                    <code>ALIGN_RIGHT</code>
                </para>
            </listitem>
        </itemizedlist>

        Der dritte Parameter ist die Colspan der Zeile. Wenn man, zum Beispiel, "2" als Colspan definiert,
        wird die Spalte über 2 Spalten der Tabelle gespannt. Der letzt Parameter definiert die Kodierung
        des Inhalts, welche angegeben werden sollte, wenn der Inhalt weder ASCII noch UTF-8 ist. Um die
        Spalte zur Zeile hinzuzufügen, muß einfach <code>appendColumn</code> im Zeilenobjekt, mit dem
        Spaltenobjekt als Parameter, aufgerufen werden. Alternativ kann ein String direkt an die
        <code>appendColumn</code> Methode übergeben werden.
    </para>
    <para>
        Um die Tabelle letztendlich darzustellen, kann man entweder die <code>render</code> Methode der
        Tabelle verwenden, oder die magische <code>__toString</code> Methode der Tabelle, indem man
        <code>echo $table;</code> oder <code>$tableString = (string) $table</code> ausführt.
    </para>
    <example id="zend.text.table.example.using">
        <title>Verwenden von Zend_Text_Table</title>
        <para>
            Ein Beispiel zeigt die grundsätzliche Verwendung von <classname>Zend_Text_Table</classname> um eine einfache
            Tabelle zu erstellen:
        </para>
        <programlisting role="php"><![CDATA[
$table = new Zend_Text_Table(array('columnWidths' => array(10, 20)));

// Entweder Einfach
$table->appendRow(array('Zend', 'Framework'));

// Oder wortreich
$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>
            Das führt zur folgenden Ausgabe:
        </para>
        <programlisting role="text"><![CDATA[
┌──────────┬────────────────────┐
│Zend      │Framework           │
└──────────┴────────────────────┘
]]></programlisting>
    </example>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->