Skip to content

Fix invalid ProgressBar message examples #7251

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jan 24, 2017
Merged

Fix invalid ProgressBar message examples #7251

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
771f952
Fix invalid ProgressBar message examples
Jean85 Dec 13, 2016
89a2843
Fix explanation of custom placeholder
Jean85 Dec 13, 2016
da7fd2d
Reworded some explanations and expanded examples
javiereguiluz Jan 16, 2017
File filter

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 19 additions & 27 deletions components/console/helpers/progressbar.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,6 @@ current progress of the bar. Here is a list of the built-in placeholders:
* ``remaining``: The remaining time to complete the task (not available if no max is defined);
* ``estimated``: The estimated time to complete the task (not available if no max is defined);
* ``memory``: The current memory usage;
* ``message``: The current message attached to the progress bar.

For instance, here is how you could set the format to be the same as the
``debug`` one::
Expand All @@ -186,20 +185,6 @@ Notice the ``:6s`` part added to some placeholders? That's how you can tweak
the appearance of the bar (formatting and alignment). The part after the colon
(``:``) is used to set the ``sprintf`` format of the string.

The ``message`` placeholder is a bit special as you must set the value
yourself::

$bar->setMessage('Task starts');
$bar->start();

$bar->setMessage('Task in progress...');
$bar->advance();

// ...

$bar->setMessage('Task is finished');
$bar->finish();

Instead of setting the format for a given instance of a progress bar, you can
also define global formats::

Expand Down Expand Up @@ -313,25 +298,32 @@ that displays the number of remaining steps::
Custom Messages
~~~~~~~~~~~~~~~

The ``%message%`` placeholder allows you to specify a custom message to be
displayed with the progress bar. But if you need more than one, just define
your own::
If you want to show some fixed text or generic message, you can define custom
placeholders in a custom format to be displayed with the progress bar, and use
them afterwards.

$bar->setMessage('Task starts');
$bar->setMessage('', 'filename');
$bar->start();
By default, the ``setMessage()`` method implies ``message`` as the name of the
placeholder, but if you need more than one, you have just to define your own::

$progressBar = new ProgressBar($output, 100);
$progressBar->setFormatDefinition('custom', ' %current%/%max% -- %message% %filename%');
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should describe which placeholders one can use here.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you mean? Something like

[...] but if you need more than one, you have just to define your own; in the example below, we added the message and filename placeholders:

is enough?
$progressBar->setFormat('custom');
$progressBar->setMessage('Start');

$progressBar->start();
// 0/100 -- Start

$progressBar->advance();
$progressBar->setMessage('Task is in progress...');
// 1/100 -- Task is in progress...

$bar->setMessage('Task is in progress...');
while ($file = array_pop($files)) {
$bar->setMessage($filename, 'filename');
$bar->advance();
// 2/100 -- Task is in progress... $filename
}

$bar->setMessage('Task is finished');
$bar->setMessage('', 'filename');
$bar->finish();

For the ``filename`` to be part of the progress bar, just add the
``%filename%`` placeholder in your format::

$bar->setFormat(" %message%\n %current%/%max%\n Working on %filename%");
// 100/100 -- Task is finished