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

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

    <para>
        <classname>Zend_Text_Table</classname> est un composant pour créer à la volée des
        tables de type texte avec différents décorateurs. Ceci peut être utile, si vous souhaitez
        soit envoyé des données structurées dans des emails textuels, qui sont sont utilisés pour
        leurs polices mono-espacés, ou pour afficher des informations sous forme de tableaux dans
        une application CLI. <classname>Zend_Text_Table</classname> supporte les colonnes
        multi-lignes, les fusions de colonnes ainsi que l'alignement.
    </para>

    <note>
        <title>Encodage</title>

        <para>
            <classname>Zend_Text_Table</classname> suppose que vos chaînes sont encodés en
            UTF-8 par défaut. Si ce n'est pas le cas, vous pouvez fournir l'encodage en tant que
            paramètre du constructeur ou à la méthode <code>setContent</code> de
            <classname>Zend_Text_Table_Column</classname>. Alternativement si vous avez un encodage
            différent dans le processus complet, vous pouvez définir l'encodage d'entrée ("input")
            standard avec <methodname>Zend_Text_Table::setInputCharset($charset)</methodname>. Dans le
            cas où vous avez besoin d'un autre encodage pour la sortie ("output") de la table, vous
            pouvez le paramétrer avec
            <methodname>Zend_Text_Table::setOutputCharset($charset)</methodname>.
        </para>
    </note>

    <para>
        Un objet <classname>Zend_Text_Table</classname> consiste en des lignes, qui
        contiennent des colonnes, représenté par <classname>Zend_Text_Table_Row</classname> et
        <classname>Zend_Text_Table_Column</classname>. Lors de la création d'une table, vous pouvez
        fournir un tableau avec les options pour la table. Celles-ci sont : <itemizedlist>
                <listitem>
                <para>
                    <code>columnWidths</code> (obligatoire) : un tableau définissant toutes
                    les largeurs de colonnes en nombre de caractères.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>decorator</code> : le décorateur à utiliser pour les bordures de la
                    table. Le défaut est <code>unicode</code>, mais vous pouvez aussi spécifier
                    <code>ascii</code> ou fournir une instance d'un objet décorateur
                    personnalisé.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>padding</code> : le remplissage gauche et droit de la colonne en
                    caractères. Le remplissage par défaut est zéro.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>AutoSeparate</code> : la manière comment les lignes sont séparées
                    avec des lignes horizontales. Par défaut, il y a une séparation entre chaque
                    ligne. Ceci est défini entant que bitmask contenant une ou plus des constantes
                    de <classname>Zend_Text_Table</classname> suivantes :<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> Où "header" est toujours la première ligne, et "footer" est
                    toujours la dernière.
                </para>
            </listitem>
            </itemizedlist>
        </para>

    <para>
        Les lignes sont simplement ajoutées à la table en créant une nouvelle instance de
        <classname>Zend_Text_Table_Row</classname>, et en l'ajoutant à la table via la méthode
        <code>appendRow</code>. Les lignes elle-même n'ont pas d'options. Vous pouvez aussi fournir
        un tableau directement à la méthode <code>appendRow</code>, qui le convertira
        automatiquement en des objets <code>Row</code>, contenant les multiples objets
        <code>Column</code>.
    </para>

    <para>
        De la même manière vous pouvez ajouter les colonnes aux lignes. Créez un instance de
        <classname>Zend_Text_Table_Column</classname> et ensuite paramétrer les options de colonnes
        soit dans le constructeur ou plus tard par les méthodes <code>set*</code>. Le premier
        paramètre est le contenu de la colonne qui peut avoir des lignes multiples, elles sont dans
        le meilleur des cas séparées par le caractère <code>\n</code>. Le second paramètre définit
        l'alignement, qui est <code>left</code> par défaut et peut être l'une des constantes de la
        classe <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>Le troisième paramètre est le colspan ("fusion") de la colonne. Par
        exemple, quand vous choisissez "2 comme colspan, la colonne va déborder sur deux colonnes de
        la table. Le dernier paramètre définit l'encodage du contenu, qui peut être fourni, si le
        contenu n'est ni de l'ASCII ni de l'UTF-8. Pour ajouter la colonne à la ligne, vous appelez
        simplement <code>appendColumn</code> dans votre objet <code>Row</code> avec l'objet
        <code>Column</code> en tant que paramètre. Alternativement vous pouvez directement fournir
        la chaîne à la méthode <code>appendColumn</code>.
    </para>

    <para>
        Pour finalement effectuer le rendu de la table, vous pouvez soit utiliser la méthode
        <code>render</code> de la table, ou utilisez la méthode magique <code>__toString</code> en
        faisant <code>echo $table;</code> ou <code>$tableString = (string) $table</code>.
    </para>

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

        <para>
            Cet exemple illustre un utilisation basique de
            <classname>Zend_Text_Table</classname> pour créer une table simple :
        </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>Ceci entraînera l'affichage suivant :</para>

        <programlisting language="text"><![CDATA[
┌──────────┬────────────────────┐
│Zend      │Framework           │
└──────────┴────────────────────┘
]]></programlisting>
    </example>
</sect1>