documentation/manual/fr/module_specs/Zend_Text_Table.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 20799 -->
   3 <!-- Reviewed: no -->
   4 <sect1 id="zend.text.table.introduction">
   5     <title>Zend_Text_Table</title>
   6
   7     <para>
   8         <classname>Zend_Text_Table</classname> est un composant pour créer à la volée des
   9         tables de type texte avec différents décorateurs. Ceci peut être utile, si vous souhaitez
  10         soit envoyé des données structurées dans des emails textuels, qui sont sont utilisés pour
  11         leurs polices mono-espacés, ou pour afficher des informations sous forme de tableaux dans
  12         une application CLI. <classname>Zend_Text_Table</classname> supporte les colonnes
  13         multi-lignes, les fusions de colonnes ainsi que l'alignement.
  14     </para>
  15
  16     <note>
  17         <title>Encodage</title>
  18
  19         <para>
  20             <classname>Zend_Text_Table</classname> suppose que vos chaînes sont encodés en
  21             UTF-8 par défaut. Si ce n'est pas le cas, vous pouvez fournir l'encodage en tant que
  22             paramètre du constructeur ou à la méthode <code>setContent</code> de
  23             <classname>Zend_Text_Table_Column</classname>. Alternativement si vous avez un encodage
  24             différent dans le processus complet, vous pouvez définir l'encodage d'entrée ("input")
  25             standard avec <methodname>Zend_Text_Table::setInputCharset($charset)</methodname>. Dans le
  26             cas où vous avez besoin d'un autre encodage pour la sortie ("output") de la table, vous
  27             pouvez le paramétrer avec
  28             <methodname>Zend_Text_Table::setOutputCharset($charset)</methodname>.
  29         </para>
  30     </note>
  31
  32     <para>
  33         Un objet <classname>Zend_Text_Table</classname> consiste en des lignes, qui
  34         contiennent des colonnes, représenté par <classname>Zend_Text_Table_Row</classname> et
  35         <classname>Zend_Text_Table_Column</classname>. Lors de la création d'une table, vous pouvez
  36         fournir un tableau avec les options pour la table. Celles-ci sont : <itemizedlist>
  37                 <listitem>
  38                 <para>
  39                     <code>columnWidths</code> (obligatoire) : un tableau définissant toutes
  40                     les largeurs de colonnes en nombre de caractères.
  41                 </para>
  42             </listitem>
  43
  44             <listitem>
  45                 <para>
  46                     <code>decorator</code> : le décorateur à utiliser pour les bordures de la
  47                     table. Le défaut est <code>unicode</code>, mais vous pouvez aussi spécifier
  48                     <code>ascii</code> ou fournir une instance d'un objet décorateur
  49                     personnalisé.
  50                 </para>
  51             </listitem>
  52
  53             <listitem>
  54                 <para>
  55                     <code>padding</code> : le remplissage gauche et droit de la colonne en
  56                     caractères. Le remplissage par défaut est zéro.
  57                 </para>
  58             </listitem>
  59
  60             <listitem>
  61                 <para>
  62                     <code>AutoSeparate</code> : la manière comment les lignes sont séparées
  63                     avec des lignes horizontales. Par défaut, il y a une séparation entre chaque
  64                     ligne. Ceci est défini entant que bitmask contenant une ou plus des constantes
  65                     de <classname>Zend_Text_Table</classname> suivantes :<itemizedlist>
  66                             <listitem>
  67                                 <para><classname>Zend_Text_Table::AUTO_SEPARATE_NONE</classname></para>
  68                             </listitem>
  69
  70                             <listitem>
  71                                 <para><classname>Zend_Text_Table::AUTO_SEPARATE_HEADER</classname></para>
  72                             </listitem>
  73
  74                             <listitem>
  75                                 <para><classname>Zend_Text_Table::AUTO_SEPARATE_FOOTER</classname></para>
  76                             </listitem>
  77
  78                             <listitem>
  79                                 <para><classname>Zend_Text_Table::AUTO_SEPARATE_ALL</classname></para>
  80                             </listitem>
  81                         </itemizedlist> Où "header" est toujours la première ligne, et "footer" est
  82                     toujours la dernière.
  83                 </para>
  84             </listitem>
  85             </itemizedlist>
  86         </para>
  87
  88     <para>
  89         Les lignes sont simplement ajoutées à la table en créant une nouvelle instance de
  90         <classname>Zend_Text_Table_Row</classname>, et en l'ajoutant à la table via la méthode
  91         <code>appendRow</code>. Les lignes elle-même n'ont pas d'options. Vous pouvez aussi fournir
  92         un tableau directement à la méthode <code>appendRow</code>, qui le convertira
  93         automatiquement en des objets <code>Row</code>, contenant les multiples objets
  94         <code>Column</code>.
  95     </para>
  96
  97     <para>
  98         De la même manière vous pouvez ajouter les colonnes aux lignes. Créez un instance de
  99         <classname>Zend_Text_Table_Column</classname> et ensuite paramétrer les options de colonnes
 100         soit dans le constructeur ou plus tard par les méthodes <code>set*</code>. Le premier
 101         paramètre est le contenu de la colonne qui peut avoir des lignes multiples, elles sont dans
 102         le meilleur des cas séparées par le caractère <code>\n</code>. Le second paramètre définit
 103         l'alignement, qui est <code>left</code> par défaut et peut être l'une des constantes de la
 104         classe <classname>Zend_Text_Table_Column</classname> :<itemizedlist>
 105                 <listitem>
 106                     <para><constant>ALIGN_LEFT</constant></para>
 107                 </listitem>
 108
 109                 <listitem>
 110                     <para><constant>ALIGN_CENTER</constant></para>
 111                 </listitem>
 112
 113                 <listitem>
 114                     <para><constant>ALIGN_RIGHT</constant></para>
 115                 </listitem>
 116             </itemizedlist>Le troisième paramètre est le colspan ("fusion") de la colonne. Par
 117         exemple, quand vous choisissez "2 comme colspan, la colonne va déborder sur deux colonnes de
 118         la table. Le dernier paramètre définit l'encodage du contenu, qui peut être fourni, si le
 119         contenu n'est ni de l'ASCII ni de l'UTF-8. Pour ajouter la colonne à la ligne, vous appelez
 120         simplement <code>appendColumn</code> dans votre objet <code>Row</code> avec l'objet
 121         <code>Column</code> en tant que paramètre. Alternativement vous pouvez directement fournir
 122         la chaîne à la méthode <code>appendColumn</code>.
 123     </para>
 124
 125     <para>
 126         Pour finalement effectuer le rendu de la table, vous pouvez soit utiliser la méthode
 127         <code>render</code> de la table, ou utilisez la méthode magique <code>__toString</code> en
 128         faisant <code>echo $table;</code> ou <code>$tableString = (string) $table</code>.
 129     </para>
 130
 131     <example id="zend.text.table.example.using">
 132         <title>Utilisation de Zend_Text_Table</title>
 133
 134         <para>
 135             Cet exemple illustre un utilisation basique de
 136             <classname>Zend_Text_Table</classname> pour créer une table simple :
 137         </para>
 138
 139         <programlisting language="php"><![CDATA[
 140 $table = new Zend_Text_Table(array('columnWidths' => array(10, 20)));
 141
 142 // Either simple
 143 $table->appendRow(array('Zend', 'Framework'));
 144
 145 // Or verbose
 146 $row = new Zend_Text_Table_Row();
 147
 148 $row->appendColumn(new Zend_Text_Table_Column('Zend'));
 149 $row->appendColumn(new Zend_Text_Table_Column('Framework'));
 150
 151 $table->appendRow($row);
 152
 153 echo $table;
 154 ]]></programlisting>
 155
 156         <para>Ceci entraînera l'affichage suivant :</para>
 157
 158         <programlisting language="text"><![CDATA[
 159 ┌──────────┬────────────────────┐
 160 │Zend      │Framework           │
 161 └──────────┴────────────────────┘
 162 ]]></programlisting>
 163     </example>
 164 </sect1>