Text tables generated by the Uize.Templates.Text.ProgressBar module do not need to contain a title.

A table without a table can be generated by specifying no title property in the input object, or by specifying the value '' (empty string), null, or undefined for the title property.

EXAMPLE

Uize.Templates.Text.Table.process ({
  columns:[
    {title:'Column 1'},
    {title:'Column 2'}
  ],
  rows:[
    ['foo','bar'],
    ['baz','qux']
  ]
});

OUTPUT

+---------------------+
| Column 1 | Column 2 |
|----------+----------|
| foo      | bar      |
|----------+----------|
| baz      | qux      |
+---------------------+

When a title is specified, it is always center-aligned in the generated text table.

EXAMPLE

Uize.Templates.Text.Table.process ({
  title:'Foo Table',
  columns:[
    {title:'Column 1'},
    {title:'Column 2'}
  ],
  rows:[
    ['foo','bar'],
    ['baz','qux']
  ]
});

OUTPUT

+---------------------+
|      Foo Table      |
+---------------------+
| Column 1 | Column 2 |
|----------+----------|
| foo      | bar      |
|----------+----------|
| baz      | qux      |
+---------------------+

The value specified for the columns property should be an array, where each element is a column description object of the form...

{
  title:titleSTR,                // the display title for the column (required)
  align:alignSTRorFLOAT,         // the alignment of values in the column (optional)
  formatter:formatterFUNCorSTR,  // a value transformer for formatting column values (optional)
  minValue:minValueNUM,          // the lower end of the column's value range (optional)
  maxValue:maxValueNUM           // the upper end of the column's value range (optional)
}

Titles are specified for columns using the title property of the column description object.

Column titles are required, unlike other properties of the column description object. Column titles are always displayed center-aligned when the calculated column width is greater than the column title width.

EXAMPLE

Uize.Templates.Text.Table.process ({
  title:'Foo Table',
  columns:[
    {title:'Column 1'},
    {title:'Column 2'}
  ],
  rows:[
    ['this is a wide value','another wide value'],
    ['yet another wide value','the final wide value']
  ]
});

OUTPUT

+-----------------------------------------------+
|                   Foo Table                   |
+-----------------------------------------------+
|        Column 1        |       Column 2       |
|------------------------+----------------------|
| this is a wide value   | another wide value   |
|------------------------+----------------------|
| yet another wide value | the final wide value |
+-----------------------------------------------+

Alignment of values can be specified for columns using the align property of the column description object.

Column values can be left aligned by specifying the value 'left' or 0, center-aligned by specifying the value 'center' or .5, or right-aligned by specifying the value 'right' or 1.

EXAMPLE

Uize.Templates.Text.Table.process ({
  title:'Foo Table',
  columns:[
    {title:'Column 1',align:'left'},
    {title:'Column 2',align:'center'},
    {title:'Column 3',align:'right'}
  ],
  rows:[
    ['ABC','ABC','ABC'],
    ['ABCDEFG','ABCDEFG','ABCDEFG'],
    ['ABCDEFGHIJK','ABCDEFGHIJK','ABCDEFGHIJK'],
    ['ABCDEFGHIJKLMNO','ABCDEFGHIJKLMNO','ABCDEFGHIJKLMNO'],
    ['ABCDEFGHIJKLMNOPQRS','ABCDEFGHIJKLMNOPQRS','ABCDEFGHIJKLMNOPQRS']
  ]
});

OUTPUT

+-----------------------------------------------------------------+
|                            Foo Table                            |
+-----------------------------------------------------------------+
|      Column 1       |      Column 2       |      Column 3       |
|---------------------+---------------------+---------------------|
| ABC                 |         ABC         |                 ABC |
|---------------------+---------------------+---------------------|
| ABCDEFG             |       ABCDEFG       |             ABCDEFG |
|---------------------+---------------------+---------------------|
| ABCDEFGHIJK         |     ABCDEFGHIJK     |         ABCDEFGHIJK |
|---------------------+---------------------+---------------------|
| ABCDEFGHIJKLMNO     |   ABCDEFGHIJKLMNO   |     ABCDEFGHIJKLMNO |
|---------------------+---------------------+---------------------|
| ABCDEFGHIJKLMNOPQRS | ABCDEFGHIJKLMNOPQRS | ABCDEFGHIJKLMNOPQRS |
+-----------------------------------------------------------------+

1.1.3.3.1. Left-aligned, by Default

Uize.Templates.Text.Table.process ({
  title:'Foo Table',
  columns:[
    {title:'Column 1'},
    {title:'Column 2',align:'right'}
  ],
  rows:[
    ['ABC','ABC'],
    ['ABCDEFG','ABCDEFG'],
    ['ABCDEFGHIJK','ABCDEFGHIJK']
  ]
});

+---------------------------+
|         Foo Table         |
+---------------------------+
|  Column 1   |  Column 2   |
|-------------+-------------|
| ABC         |         ABC |
|-------------+-------------|
| ABCDEFG     |     ABCDEFG |
|-------------+-------------|
| ABCDEFGHIJK | ABCDEFGHIJK |
+---------------------------+

1.1.3.3.2. Fractional Alignment

Uize.Templates.Text.Table.process ({
  title:'Foo Table',
  columns:[
    {title:'Column 1',align:0},
    {title:'Column 2',align:.25},
    {title:'Column 3',align:.5},
    {title:'Column 4',align:.75},
    {title:'Column 5',align:1}
  ],
  rows:[
    ['ABC','ABC','ABC','ABC','ABC'],
    ['ABCDEFG','ABCDEFG','ABCDEFG','ABCDEFG','ABCDEFG'],
    ['ABCDEFGHIJK','ABCDEFGHIJK','ABCDEFGHIJK','ABCDEFGHIJK','ABCDEFGHIJK'],
    ['ABCDEFGHIJKLMNO','ABCDEFGHIJKLMNO','ABCDEFGHIJKLMNO','ABCDEFGHIJKLMNO','ABCDEFGHIJKLMNO']
  ]
});

+-----------------------------------------------------------------------------------------+
|                                        Foo Table                                        |
+-----------------------------------------------------------------------------------------+
|    Column 1     |    Column 2     |    Column 3     |    Column 4     |    Column 5     |
|-----------------+-----------------+-----------------+-----------------+-----------------|
| ABC             |    ABC          |       ABC       |          ABC    |             ABC |
|-----------------+-----------------+-----------------+-----------------+-----------------|
| ABCDEFG         |   ABCDEFG       |     ABCDEFG     |       ABCDEFG   |         ABCDEFG |
|-----------------+-----------------+-----------------+-----------------+-----------------|
| ABCDEFGHIJK     |  ABCDEFGHIJK    |   ABCDEFGHIJK   |    ABCDEFGHIJK  |     ABCDEFGHIJK |
|-----------------+-----------------+-----------------+-----------------+-----------------|
| ABCDEFGHIJKLMNO | ABCDEFGHIJKLMNO | ABCDEFGHIJKLMNO | ABCDEFGHIJKLMNO | ABCDEFGHIJKLMNO |
+-----------------------------------------------------------------------------------------+

Values for a column can optionally be formatted by specifying a formatter function or expression for the formatter property of the column description object.

EXAMPLE

Uize.Templates.Text.Table.process ({
  title:'2013 Food Prices in the UK',
  columns:[
    {title:'Description'},
    {
      title:'Price',
      align:'right',
      formatter:function (value) {
        return value < 1 ? (value * 100).toFixed (0) + "p" : "£" + value.toFixed (2);
      }
    }
  ],
  rows:[
    ['Loaf of bread',1.30],
    ['Apples, per kg',2.02],
    ['Pint of milk',.46],
    ['Sausages, per kg',4.84],
    ['Carrots, per kg',.91],
    ['Sugar, per kg',.93],
    ['Dozen eggs',2.78]
  ]
});

In the above example, a column formatter function is being specified for the price column. The formatter function is passed a price in pounds and returns a formatted value that is expressed in pence if the value is below 1 pound, and pounds if the value is 1 pound or greater.

OUTPUT

+----------------------------+
| 2013 Food Prices in the UK |
+----------------------------+
|    Description    | Price  |
|-------------------+--------|
| Loaf of bread     |  £1.30 |
|-------------------+--------|
| Apples, per kg    |  £2.02 |
|-------------------+--------|
| Pint of milk      |    46p |
|-------------------+--------|
| Sausages, per kg  |  £4.84 |
|-------------------+--------|
| Carrots, per kg   |    91p |
|-------------------+--------|
| Sugar, per kg     |    93p |
|-------------------+--------|
| Dozen eggs        |  £2.78 |
+----------------------------+

1.1.3.4.1. Column Formatter String Expression

Uize.Templates.Text.Table.process ({
  title:'2013 Food Prices in the UK',
  columns:[
    {title:'Description'},
    {
      title:'Price',
      align:'right',
      formatter:'value < 1 ? (value * 100).toFixed (0) + "p" : "£" + value.toFixed (2)'
    }
  ],
  rows:[
    ['Loaf of bread',1.30],
    ['Apples, per kg',2.02],
    ['Pint of milk',.46],
    ['Sausages, per kg',4.84],
    ['Carrots, per kg',.91],
    ['Sugar, per kg',.93],
    ['Dozen eggs',2.78]
  ]
});

+----------------------------+
| 2013 Food Prices in the UK |
+----------------------------+
|    Description    | Price  |
|-------------------+--------|
| Loaf of bread     |  £1.30 |
|-------------------+--------|
| Apples, per kg    |  £2.02 |
|-------------------+--------|
| Pint of milk      |    46p |
|-------------------+--------|
| Sausages, per kg  |  £4.84 |
|-------------------+--------|
| Carrots, per kg   |    91p |
|-------------------+--------|
| Sugar, per kg     |    93p |
|-------------------+--------|
| Dozen eggs        |  £2.78 |
+----------------------------+

The Uize.Templates.Text.Table module will compute min and max values for each column, unless values are specified explicitly for the minValue and maxValue properties in the column description object.

Specifically, if no minValue property is present in the column description object for a column, then a min value will be computed from all the values of the column, and this value will be set on the minValue property. Similarly, if no maxValue property is present in the column description object, then a max value will be computed from the column's values, and this value will be set on the maxValue property.

Because a column formatter is called as an instance method on the column description object when formatting a value for a column, the formatter can access the values of the minValue and maxValue properties and use these values to affect the formatted value. One way that this feature can be used is to add level indicator bars in columns to indicate where the current value falls in the range of values for the column across all rows of the table.

Consider the following example...

EXAMPLE

Uize.Templates.Text.Table.process ({
  title:'2013 Food Prices in the UK',
  columns:[
    {title:'Description'},
    {
      title:'Price',
      align:'right',
      formatter:function (value) {
        return (
          (value < 1 ? (value * 100).toFixed (0) + "p" : "£" + value.toFixed (2)) + ' ' +
          Uize.Templates.Text.ProgressBar.process ({
            progress:(value - this.minValue) / (this.maxValue - this.minValue),
            trackLength:20,
            endsChar:''
          })
        );
      }
    }
  ],
  rows:[
    ['Loaf of bread',1.30],
    ['Apples, per kg',2.02],
    ['Pint of milk',.46],
    ['Sausages, per kg',4.84],
    ['Carrots, per kg',.91],
    ['Sugar, per kg',.93],
    ['Dozen eggs',2.78]
  ]
});

In the above example, the Uize.Templates.Text.ProgressBar template module is being used to add a level indicator alongside the formatted price for the values in the price column. This level indicator provides a quick visual cue as to where a price falls in the range of prices for the foods listed in the table.

Now, the column description object for the price column does not specify values for the minValue and maxValue properties, so valuaes for these properties are computed from the values in the column. The formatter function for the column can then access the computed values using the this keyword, since the formatter is called as an instance method on the column description object.

From the above example, we get the following output...

OUTPUT

+-----------------------------------------------+
|          2013 Food Prices in the UK           |
+-----------------------------------------------+
|   Description    |           Price            |
|------------------+----------------------------|
| Loaf of bread    | £1.30 ▓▓▓▓█░░░░░░░░░░░░░░░ |
|------------------+----------------------------|
| Apples, per kg   | £2.02 ▓▓▓▓▓▓▓█░░░░░░░░░░░░ |
|------------------+----------------------------|
| Pint of milk     |   46p █░░░░░░░░░░░░░░░░░░░ |
|------------------+----------------------------|
| Sausages, per kg | £4.84 ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█ |
|------------------+----------------------------|
| Carrots, per kg  |   91p ▓▓█░░░░░░░░░░░░░░░░░ |
|------------------+----------------------------|
| Sugar, per kg    |   93p ▓▓█░░░░░░░░░░░░░░░░░ |
|------------------+----------------------------|
| Dozen eggs       | £2.78 ▓▓▓▓▓▓▓▓▓▓█░░░░░░░░░ |
+-----------------------------------------------+

If the table title is wider than the sum of all the calculated column widths and column separators, then the difference will be distributed as padding evenly across the columns.

EXAMPLE

Uize.Templates.Text.Table.process ({
  title:'This is an extremely long title for this table',
  columns:[
    {title:'Col 1'},
    {title:'Col 2'},
    {title:'Col 3'}
  ],
  rows:[
    ['Foo 1','Foo 2','Foo 3'],
    ['Bar 1','Bar 2','Bar 3'],
    ['Baz 1','Baz 2','Baz 3'],
    ['Qux 1','Qux 2','Qux 3']
  ]
});

In the above example, the table's title is wider than the sum of the column widths (as calculated from the column values and column titles) and column separators. The number of characters by which the title is wider is distributed as padding spaces evenly across the three columns.

OUTPUT

+------------------------------------------------+
| This is an extremely long title for this table |
+------------------------------------------------+
|     Col 1     |     Col 2      |     Col 3     |
|---------------+----------------+---------------|
| Foo 1         | Foo 2          | Foo 3         |
|---------------+----------------+---------------|
| Bar 1         | Bar 2          | Bar 3         |
|---------------+----------------+---------------|
| Baz 1         | Baz 2          | Baz 3         |
|---------------+----------------+---------------|
| Qux 1         | Qux 2          | Qux 3         |
+------------------------------------------------+