UIZE JavaScript Framework

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