MODULES Uize.Templates.Text.ProgressBar
1. Introduction
The Uize.Templates.Text.ProgressBar module is a JavaScript Template module, used for generating a text progress bar string that can be used when outputting to logs, consoles, terminals, etc.
DEVELOPERS: Chris van Rensburg
1.1. In a Nutshell
The Uize.Templates.Text.ProgressBar module is a simple template module that can be useful in situations where you need to display a visual progress or level indicator using purely text characters.
For instance, you may wish to display progress updates in a console or terminal window for an automation script that may be long-running, such as a build script. In a console you have only plain text at your disposal. The following example illustrates the possible console output from a hypothetical build script that processes a set of files and builds a package archive file...
LOG OUTPUT EXAMPLE
|█░░░░░░░░░| Prepared job, 8 files to process under ~/files |▓█░░░░░░░░| Processed file: ~/files/foo.txt |▓▓█░░░░░░░| Processed file: ~/files/bar.txt |▓▓▓█░░░░░░| Processed file: ~/files/baz.txt |▓▓▓▓█░░░░░| Processed file: ~/files/qux.txt |▓▓▓▓▓█░░░░| Processed file: ~/files/more/foo.txt |▓▓▓▓▓▓█░░░| Processed file: ~/files/more/bar.txt |▓▓▓▓▓▓▓█░░| Processed file: ~/files/more/baz.txt |▓▓▓▓▓▓▓▓█░| Processed file: ~/files/more/qux.txt |▓▓▓▓▓▓▓▓▓█| Processed 8 files and built package ~/files.zip
As the build script progresses through its steps, it uses the Uize.Templates.Text.ProgressBar module when constructing the progress update messages it outputs to the console.
1.1.1. Examples
The following examples demonstrate the various ways that output from the Uize.Templates.Text.ProgressBar.process method can be customized by using the different properties supported by its inputOBJ argument.
1.1.1.1. Indicating a Progress of 0%
A progress of 0% can be indicated by specifying the value 0 for the progress property of the inputOBJ argument.
EXAMPLE
Uize.Templates.Text.ProgressBar.process ({progress:0});
OUTPUT
|█░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░|
1.1.1.2. Indicating a Progress of 50%
A progress of 50% can be indicated by specifying the value .5 for the progress property of the inputOBJ argument.
EXAMPLE
Uize.Templates.Text.ProgressBar.process ({progress:.5});
OUTPUT
|▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█░░░░░░░░░░░░░░░░░░░░░░░░|
1.1.1.3. Indicating a Progress of 100%
A progress of 100% can be indicated by specifying the value 1 for the progress property of the inputOBJ argument.
EXAMPLE
Uize.Templates.Text.ProgressBar.process ({progress:.5});
OUTPUT
|▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█|
1.1.1.4. Specifying a Custom Track Length
A custom track length can be achieved by specifying the desired track length (measured in characters) for the trackLength property of the inputOBJ argument.
EXAMPLE
Uize.Templates.Text.ProgressBar.process ({trackLength:10,progress:.5});
OUTPUT
|▓▓▓▓▓█░░░░|
1.1.1.5. Specifying Custom Characters
The appearance of the progress bar can be controlled by specifying values for the endsChar, fullHeadChar, and emptyChar properties of the inputOBJ argument.
EXAMPLE
Uize.Templates.Text.ProgressBar.process ({
endsChar:'|',
fullHeadChar:'#',
fullChar:'=',
emptyChar:'-',
trackLength:20,
progress:.75
});
OUTPUT
|==============#-----|
1.2. Examples
There are no dedicated showcase example pages for the Uize.Templates.Text.ProgressBar module.
SEARCH FOR EXAMPLES
Use the link below to search for example pages on the UIZE Web site that reference the Uize.Templates.Text.ProgressBar module...
SEARCH
1.3. Implementation Info
The Uize.Templates.Text.ProgressBar module defines the Uize.Templates.Text.ProgressBar package under the Uize.Templates.Text namespace.
1.3.1. Features Introduced in This Module
The features listed in this section have been introduced in this module.
STATIC METHODS
Uize.Templates.Text.ProgressBar.process
STATIC PROPERTIES
Uize.Templates.Text.ProgressBar.input | Uize.Templates.Text.ProgressBar.moduleName | Uize.Templates.Text.ProgressBar.pathToResources
1.3.2. Features Overridden in This Module
No features have been overridden in this module.
1.3.3. Features Inherited From Other Modules
This module has no inherited features.
1.3.4. Modules Directly Under This Namespace
There are no modules directly under this namespace.
1.3.5. Unit Tests
The Uize.Templates.Text.ProgressBar module is unit tested by the Uize.Test.Uize.Templates.Text.ProgressBar test module.
2. Static Methods
2.1. Uize.Templates.Text.ProgressBar.process
Returns a string, being the generated text progress bar.
SYNTAX
textProgressBarSTR = Uize.Templates.Text.ProgressBar.process (inputOBJ);
2.1.1. inputOBJ
The object specified for the inputOBJ parameter may contain the following properties...
2.1.1.1. endsChar
An optional string, specifying the characters(s) that should be used for the left and right ends of the text progress bar.
NOTES
| the value for this property may be more than one character in length | |
| the value of this property is defaulted to the "|" (pipe) character |
2.1.1.2. trackLength
An optional number, specifying the desired length (in characters) of the track for the text progress bar.
NOTES
the value of this property is defaulted to 50 |
2.1.1.3. fullChar
An optional string, specifying the character that should be used for the full portion of the track of the text progress bar.
NOTES
| the value for this property should be exactly one character in length | |
| the value of this property is defaulted to the "▓" (dark shaded block) character |
2.1.1.4. fullHeadChar
An optional string, specifying the characters(s) that should be used for the head of the full portion of the track of the text progress bar.
The head of the full portion of the progress bar essentially demarcates the progress position.
NOTES
| the value for this property may be more than one character in length | |
| the value of this property is defaulted to the "█" (solid block) character | |
| if an empty string is specified for this property, then the full portion of the text progress bar will not have a head |
2.1.1.5. emptyChar
An optional string, specifying the character that should be used for the empty portion of the track of the text progress bar.
NOTES
| the value for this property should be exactly one character in length | |
| the value of this property is defaulted to the "░" (light shaded block) character |
2.1.1.6. progress
A floating point number in the range of 0 to 1, indicating the progress that should be displayed in the text progress bar.
A progress value of 0 indicates 0% progress, a value of .5 indicates 50% progress, and a value of 1 indicates 100% progress.
NOTES
the value of this property is defaulted to 0 |
IMPLEMENTATION INFO
| this feature was introduced in this module |
3. Static Properties
3.1. Uize.Templates.Text.ProgressBar.input
An object, describing the allowed properties of the inputOBJ parameter of the Uize.Templates.Text.ProgressBar.process static method.
IMPLEMENTATION INFO
| this feature was introduced in this module |
3.2. Uize.Templates.Text.ProgressBar.moduleName
IMPLEMENTATION INFO
| this feature was introduced in this module |
3.3. Uize.Templates.Text.ProgressBar.pathToResources
IMPLEMENTATION INFO
| this feature was introduced in this module |