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

<!-- EN-Revision: 13910 -->
<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
        <classname>Zend_Text_Table::setInputCharset($charset)</classname>. Dans le cas où vous avez besoin d'un autre encodage
        pour la sortie ("output") de la table, vous pouvez le paramétrer avec
        <classname>Zend_Text_Table::setOutputCharset($charset)</classname>.</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><code>ALIGN_LEFT</code></para>
            </listitem>

            <listitem>
                <para><code>ALIGN_CENTER</code></para>
            </listitem>

            <listitem>
                <para><code>ALIGN_RIGHT</code></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 role="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 role="text"><![CDATA[
┌──────────┬────────────────────┐
│Zend      │Framework           │
└──────────┴────────────────────┘
]]></programlisting>
    </example>
</sect1>