Permalink
Browse files

feature #3627 added docs for the new Table console helper (fabpot)

This PR was merged into the master branch.

Discussion
----------

added docs for the new Table console helper

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes (symfony/symfony#10365)
| Applies to    | 2.5+
| Fixed tickets | n/a

Commits
-------

bd9cd26 added docs for the new Table console helper
  • Loading branch information...
weaverryan committed Mar 12, 2014
2 parents 876a55d + bd9cd26 commit df63740960702ab41bfd20a5c1f01e182a9b9702
@@ -11,6 +11,7 @@ The Console Helpers
formatterhelper
progressbar
progresshelper
table
tablehelper
The Console component comes with some useful helpers. These helpers contain
@@ -2,4 +2,5 @@
* :doc:`/components/console/helpers/formatterhelper`
* :doc:`/components/console/helpers/progressbar`
* :doc:`/components/console/helpers/progresshelper`
* :doc:`/components/console/helpers/table`
* :doc:`/components/console/helpers/tablehelper`
@@ -0,0 +1,144 @@
.. index::
single: Console Helpers; Table
Table
=====
.. versionadded:: 2.5
The ``Table`` class was introduced in Symfony 2.5 as a replacement for the
:doc:`Table Helper </components/console/helpers/tablehelper>`.
When building a console application it may be useful to display tabular data:
.. code-block:: text
+---------------+--------------------------+------------------+
| ISBN | Title | Author |
+---------------+--------------------------+------------------+
| 99921-58-10-7 | Divine Comedy | Dante Alighieri |
| 9971-5-0210-0 | A Tale of Two Cities | Charles Dickens |
| 960-425-059-0 | The Lord of the Rings | J. R. R. Tolkien |
| 80-902734-1-6 | And Then There Were None | Agatha Christie |
+---------------+--------------------------+------------------+
To display a table, use :class:`Symfony\\Component\\Console\\Helper\\Table`,
set the headers, set the rows and then render the table::
use Symfony\Component\Helper\Table;
$table = new Table($output);
$table
->setHeaders(array('ISBN', 'Title', 'Author'))
->setRows(array(
array('99921-58-10-7', 'Divine Comedy', 'Dante Alighieri'),
array('9971-5-0210-0', 'A Tale of Two Cities', 'Charles Dickens'),
array('960-425-059-0', 'The Lord of the Rings', 'J. R. R. Tolkien'),
array('80-902734-1-6', 'And Then There Were None', 'Agatha Christie'),
))
;
$table->render();
You can add a table separator anywhere in the output by passing an instance of
:class:`Symfony\\Component\\Console\\Helper\\TableSeparator` as a row::
use Symfony\Component\Helper\TableSeparator;
$table->setRows(array(
array('99921-58-10-7', 'Divine Comedy', 'Dante Alighieri'),
array('9971-5-0210-0', 'A Tale of Two Cities', 'Charles Dickens'),
new TableSeparator(),
array('960-425-059-0', 'The Lord of the Rings', 'J. R. R. Tolkien'),
array('80-902734-1-6', 'And Then There Were None', 'Agatha Christie'),
));
.. code-block:: text
+---------------+--------------------------+------------------+
| ISBN | Title | Author |
+---------------+--------------------------+------------------+
| 99921-58-10-7 | Divine Comedy | Dante Alighieri |
| 9971-5-0210-0 | A Tale of Two Cities | Charles Dickens |
+---------------+--------------------------+------------------+
| 960-425-059-0 | The Lord of the Rings | J. R. R. Tolkien |
| 80-902734-1-6 | And Then There Were None | Agatha Christie |
+---------------+--------------------------+------------------+
The table style can be changed to any built-in styles via
:method:`Symfony\\Component\\Console\\Helper\\Table::setStyle`::
// same as calling nothing
$table->setStyle('default');
// changes the default style to compact
$table->setStyle('compact');
$table->render();
This code results in:
.. code-block:: text
ISBN Title Author
99921-58-10-7 Divine Comedy Dante Alighieri
9971-5-0210-0 A Tale of Two Cities Charles Dickens
960-425-059-0 The Lord of the Rings J. R. R. Tolkien
80-902734-1-6 And Then There Were None Agatha Christie
You can also set the style to ``borderless``::
$table->setStyle('borderless');
$table->render();
which outputs:
.. code-block:: text
=============== ========================== ==================
ISBN Title Author
=============== ========================== ==================
99921-58-10-7 Divine Comedy Dante Alighieri
9971-5-0210-0 A Tale of Two Cities Charles Dickens
960-425-059-0 The Lord of the Rings J. R. R. Tolkien
80-902734-1-6 And Then There Were None Agatha Christie
=============== ========================== ==================
If the built-in styles do not fit your need, define your own::
.. code-block:: php
use Symfony\Component\Helper\TableStyle;
// by default, this is based on the default style
$style = new TableStyle();
// customize the style
$style
->setHorizontalBorderChar('<fg=magenta>|</>')
->setVerticalBorderChar('<fg=magenta>-</>')
->setCrossingChar(' ')
;
// use the style for this table
$table->setStyle($style);
Here is a full list of things you can customize:
* :method:`Symfony\\Component\\Console\\Helper\\TableStyle::setPaddingChar`
* :method:`Symfony\\Component\\Console\\Helper\\TableStyle::setHorizontalBorderChar`
* :method:`Symfony\\Component\\Console\\Helper\\TableStyle::setVerticalBorderChar`
* :method:`Symfony\\Component\\Console\\Helper\\TableStyle::setCrossingChar`
* :method:`Symfony\\Component\\Console\\Helper\\TableStyle::setCellHeaderFormat`
* :method:`Symfony\\Component\\Console\\Helper\\TableStyle::setCellRowFormat`
* :method:`Symfony\\Component\\Console\\Helper\\TableStyle::setBorderFormat`
* :method:`Symfony\\Component\\Console\\Helper\\TableStyle::setPadType`
.. tip::
You can also register a style globally::
// register the style under the colorful name
Table::setStyleDefinition('colorful', $style);
// use it for a table
$table->setStyle('colorful');
This method can also be used to override a built-in style.
@@ -7,6 +7,13 @@ Table Helper
.. versionadded:: 2.3
The ``table`` helper was added in Symfony 2.3.
.. caution::
The Table Helper was deprecated in Symfony 2.5 and will be removed in
Symfony 3.0. You should now use the
:doc:`Table </components/console/helpers/table>` class instead which is
more powerful.
When building a console application it may be useful to display tabular data:
.. image:: /images/components/console/table.png

0 comments on commit df63740

Please sign in to comment.