Table
This document teaches you how to style and format your novem tables.
The table folder consists of several endpoints related to the formatting of
your novem table or mtable visualisations.
Structure
plot_name => Name
├── config => Configuration options
...
│ ├── table => table specific settings
│ │ └── cell => Format table cells
│ │ ├── border => control table borders
│ │ ├── text => Font information (weight, style, color)
│ │ ├── align => Number alignment
│ │ ├── format => Number and text format
│ │ ├── padding => Intra cell padding
│ │ ├── width => Fixed column width
│ │ ├── overflow => Text overflow control
│ │ ├── priority => Responsive design control
│ │ └── merge => Set cell min/max width
...
Table options
Cell options
The cell folder contains a collection of files which controls the formatting of the individual cells in the table. Each file consists of a set of instructions, separated by newline, applied in order from first to last.
All instructions share a common structure consisting of space delimited options. Across all files the first two instructions are used to identify the rows and columns to be operated on. For more information see slicing.
Border
Novem tables offer extensive control over border formatting. Similar to other table formatting instructions the border format consist of row and table slicers follwed by position, size and color.
The slicing operations and colors are the same as for other novem table options, however the position and size instructions are unique to the border.
Size are simply a value between 1 and 5 denoting the thickness of the border, position is slighly more complex and encodes the position of the border relative to the cell. The available position options are as follows:
l -- add left border to cell
r -- add right border to cell
t -- add top border to cell
b -- add bottom border to cell
x -- add left and rigth border to cell
y -- add top and bottom border to cell
a -- add all borders to cell
We’ve included a few examples on how to use the border options below, feel free to follow the links and use the dropdown for more details on how the examples were created.
E-Mail table warning: Sometimes you might notice that certain cell borders are being prioritized over the ones you prefer (like a background grid taking presedence over a line). Unfortunately this is the result of how html tables work.
The easiest way to avoid this is by being more explicit in your instructions to avoid drawing multiple borders next to each other. It’s also helpful to know that larger borders are prioritized over smaller, so if feasible, you can always increase the size.
For more information read about border conflict resolution over at the w3c.
Basic border
The below table shows one of the simplest border you can have, a plain grid with a soft shade of gray.
a operator adds borders to all sides of the cell and
the two slicers select the entire table. : : a 1 gray-400 -- add a gray grid of size 1 to all sides
Top and bottom
This example shows how to add a border to the top and bottom row of a table, this can look particularly nice when combined with bold text or custom color styles .
slicers to explicitly get the first (0) and
last row (-1).
To save some space we use the y instruction to add both top and bottom border
to the last row. We continue to add the gray background grid as well.Instructions are processed top to bottom, meaning later instructions override previous ones. You can see this above with the larger top and bottom borders overriding the previous background borders.
: : a 1 gray-400 -- add a gray grid of size 1 to all sides
0 : b 2 inverse -- select the first row and all columns
-- add a size 2 border to the bottom
-- using the inverse color (dark on light,
-- lgiht on dark)
-1 : y 2 inverse -- replicate the above instruction, but
-- add the border to the last row and
-- use the _y_ instruction to get both
-- top and bottom
Border size
Novem tables support up to five different border sizes denoted 1 through 5. 1 is the default and most common while 5 is the largets. It’s important to know that larger border takes priority over smaller ones where they intersect.
Even though we could have selected the rows and columns using our comma
operator 3,5,7,9,11 we have to use a line per instruction in this case.
This is because the size operator works on all the listed indices and
we want differnet size.
: : a 1 gray-300 -- continue our grid from above
-- but soften the color a bit
3 : b 1 inverse -- add a border to the bottom of all
5 : b 2 inverse -- columns for the given row and size
7 : b 3 inverse
9 : b 4 inverse
11 : b 5 inverse
: 3 r 1 inverse -- add a border to the left of all
: 5 r 2 inverse -- rows for the given row and size
: 7 r 3 inverse
: 9 r 4 inverse
: 11 r 5 inverse
Border colors
Novem has rich color support across all our visuals. In addition to the named colors and default themes, we also support custom color themes as well as explicit color codes. This is true for our borders just like anything else.
Below we’ve explicitly colored the the bottom borders using the 9 color custom scale. The reason we’ve only used 14 rows is to keep the example consistent with the other tables above. We’ve left a column in the middle empty for esthetic reasons.
0 :6 b 2 blue-100
1 :6 b 2 blue-300
2 :6 b 2 blue-400
3 :6 b 2 blue-500
4 :6 b 2 blue-600
5 :6 b 2 blue-700
6 :6 b 2 blue-800
7 :6 b 2 blue-900
8 :6 b 2 blue-800
9 :6 b 2 blue-700
10 :6 b 2 blue-600
11 :6 b 2 blue-500
12 :6 b 2 blue-400
13 :6 b 2 blue-300
0 8: b 2 green-100
1 8: b 2 green-300
2 8: b 2 green-400
3 8: b 2 green-500
4 8: b 2 green-600
5 8: b 2 green-700
6 8: b 2 green-800
7 8: b 2 green-900
8 8: b 2 green-800
9 8: b 2 green-700
10 8: b 2 green-600
11 8: b 2 green-500
12 8: b 2 green-400
13 8: b 2 green-300
Border position
Position referes to which side of the cell the border will be placed on. Picking the right side can be important to make sure you get the look you want. We’ve put together the below visualisation to show you how the different instrucitons lays out the borders.
As mentioned above novem borders support seven different position
instructions: lrtb xy a. The first four should be intuitive as the
letters represent left, right, top and bottom. x and y
represent the x (row) and y (column) axis and will place the
border on all sides in their respective direction. The last instruction
is a for all which will add border on all sides.
: : a 1 gray-300 -- continue our grid from above
-- create the first column - left both and right
0:3 0:3 l 2 inverse -- add border to the left side
5:8 0:3 x 2 inverse -- add border on all vertical (x/column) sides
10:13 0:3 r 2 inverse -- add border on the right side
-- create the second column - top both and bottom
0:3 5:9 t 2 inverse -- add border to the top side
5:8 5:9 y 2 inverse -- add border on all horizontal (y/row) sides
10:13 5:9 b 2 inverse -- add border on the bottom side
-- create the third column - all, outer and inner
0:3 11:14 a 2 inverse -- create a box with all sides drawn
-- our "outside" box
--5:8 11:14 o 2 inverse -- ideally we'd have an 8th instruction
-- "outside" drwaing only the outer border
-- unfortunately that's not implemented, so
-- instead each "outer" border has to be
-- drawn by hand
5 11:14 t 2 inverse -- top border
8 11:14 b 2 inverse -- bottom border
5:8 11 l 2 inverse -- left border
5:8 14 r 2 inverse -- right border
-- our "inside" box
--10:13 11:14 i 1 inverse -- perhpas a 9th instruction "inside"
10:13 11:13 r 2 inverse -- draw right border, one less than all
10:12 11:14 b 2 inverse -- draw bottom border, one less than all
Border Steps
In addition to start and end positions, the novem slice operator also
supports steps. This makes it easy to alternate colors
or group columns and rows into logical entities.
The table above shows alternating colors for every two rows and every three columns. This is done by a combination of using the step funciton of the slicer and offseting the starting point for the different colors.
: : a 1 gray-300 -- continue our grid from above
1:-1:4 : b 2 gray-500 -- color every 4th row
3:-1:4 : b 2 gray-700 -- repeat but start offset by 2
: 3:-1:6 l 2 gray-500 -- color every 6th column
: 6:-1:6 l 2 gray-700 -- repet, but start offset by 3
Border Combinations
Finally we have some examples combining all of the above operations in various ways. To save space we haven’t included the example code here, but feel free to click the links and read more on the individual chart pages.
Header, footer, indices and aggregates
Border art?
Text
The text file consists of a newline seprated list of formatting instructions controlling the cell text styles.
The novem text instruction has the following composition
row_slice col_slice text_style
The text style options are single charracter and as follows:
bfor boldifor italicsforstrikethroughrfor regular (no change)
0 : b -- bolden the first row
-1 : b -- bolden the last row
Bold
Align
It’s often easier to compare numbers and values when they are all aligned in a meaningful way. Novem tables support three styles of alignment, left, center and right. The alignment are applied to a subsection of the table defined by the standard slicing instructions. To instruct the alignment we use three glyphs:
< -- left align selection
- -- center align selection
> -- right align selection
It can be helpful to think of the symbols “pointing” in the direction of the alignment.
Left
Left alignment is the most common alignment and is the default if no instrucitons are given. That being said, some templates could have a different default direction, so the below example shows how to add a left align to the entire table.
All we need to do to left align the table is to create a global selector : :
and give it the < (left) instruciton.
: : < -- left align everything
Center
The next example shows how to center all columns in a table excep the left one. Often you’ll have index values or other information in the left column that you might feel look better left align.
Here we start by replicating the left align everything instruction, and then
providing a more specific center align - that centers the rest of the table.
: : < -- left align everything
: 1: - -- center everything except the first column
Right
Finally we have have what is probably the most common table alignment for numeric data. Below we have an example that left aligns the right most column, centers the remainder of the top row and right aligns all the numbers below.
Here we take advantage of the fact that our rules are processed in order, this allows us to first left align everything, then center everything excep the first column and then further right aligning all the numbers.
: : < -- left align everything
: 1: - -- center everything except the first column
1: 1: > -- align everything else to the right
Mix
This little alignment mix is more to show the flexibility of the slicers than any common alignment need. Hopefully this can serve as an inspiration to get your table looking just right.
The instructions below primarily does two things:
- left center and right align columns 2, 3 and 4
- create three different “snake” patterns for columns 5,6 and 7
Hopefully this helps illustrate that once can create complex formatting with rather few instructions.
: : < -- left align everything
: 1: > -- right align all rows and all columns staring
-- at column 2
0 1: - -- center top row starting at column 2
: 2 - -- center third column
: 3 < -- right align forth column
-- create the left "snake" in column five
4:-1 4 - -- center fifth column from fifth row and down
7:9 4 < -- override row 8-10 and left align
-- create the right "snake" in column seven
: 6 < -- left align column 7
4:-1 6 - -- center seventcolumn from fifth row and down
7:9 6 > -- override row 8-10 and right align
-- create the middle "snake" in column six
: 5 - -- start by centering column six
2:-1:4 5 < -- left align every forth row starting at row 3
4:-1:4 5 > -- left align every forth row starting at row 5
Padding (DOCUMENT)
Padding is the process of adding space on the inside of the cell. Novem supports adding padding in all the cardinal directions, top, down, left and right. The padding is provided as sizes between 1 and 5.
The instructions are similar to other novem plot with two slicers followed by direction and size. The direction codes are identical to the border direction codes and are as follows:
l -- add left padding to cell
r -- add right padding to cell
t -- add top padding to cell
b -- add bottom padding to cell
x -- add left and rigth padding to cell
y -- add top and bottom padding to cell
a -- add paddings to sides of the cell
No padding
- just an example with condensed numbers/text and superscripts
Breathing room
- Add extra space between text and border
- Combine with superscript for more clarity
Hierarchies
- Emulate a hierarchy structure by left padding
Setting Focus
- add lots of margin to one row to make it stand out
Format
The format file consists of a newline seprated list of formatting instructions controlling the cell number/text/date formatting.
TODO: EXPLAIN DEFAUL BEHAVIOR
Numeric
The novem platform supports a wider variety of number formatting rules, we actually support the entire python format mini-language. Number formatting works very similar to other novem formatting instructions, just slice out the part of the table you want to operate on and specify the formatting.
1:-1 1: ,.1% -- format everything except
-- first row and first column as pct
-1 1: ,.1% -- format last row as pct (skip first column)
Scientific
Novem extends the standard python library with basic support for scientific
notation by using the s suffix.
This supports a single integer precision before the s keyword
1:-1 1: 1s -- format everything except
-- first row and first column as pct
-1 1: 5s -- format last row as pct (skip first column)
Money
We further expand the standard formatting by offering a convenient
“money” format with the m suffix.
In additon to the precisoin integer of s, m also offer an optional
currency symbol between the precision and the m.
: 0 m -- just m, defeaults to precision of 1
: 1 .2m -- a double precision monetary value
: 2 $.3m -- add a usd `$` prefix
: 3 .4m$ -- add a usd `$` suffix
Dates
for details see the python format mini-language
Text
Markdown
Overflow
By default novem tries to assign width according to column content, however sometimes there just isn’t enough space. When that occurs one of two things can happen:
- Ellipsis
e- the substitution of the excess contet with ellipsis... - Truncation
t- the removal of the excess contet - Wrap
w- the splitting of content across multiple lines - Overflow
o- have the content spill across to the other cells
Ellipsis
The deafult behaviour is e (ellipsis) on overflow.
: : e -- the default overflow strategy
Truncation
Truncation simply cust of the words with no further indication to the user that information is missing. However, unlike ellipsis, words are never partially truncated but removed in full. The only exception is if there is only one word, in which case it will overflow.
: : t -- truncate the entire table
Wrap
Wrapping allows the text to continue to wrap onto the next line expanding the row until it shows all the text
: : t -- truncate the entire table
Overflow
The deafult behaviour is e (ellipsis) on overflow.
: 0 w -- wrap all rows the first column
: 1: t -- truncate the rest of the table
Width
Novem tables allow you specify column widths in “units”. You can think of units almost like pixels, except there is no guarantee that a unit is a 1:1 match against screen pixels. You can however assume that relative sizes given in units across novem endpoints is consistent. So a medium size table of 600 units can be properly divided into three columns of 200 units.
There are three types of widths you can assign to a column, min, max and
fixed shortened i,x and f respectively.
Width instructions follows a similar slicing syntax as other cell instructions,
but only column selectors are supplied, followed by width in units and then
type.
Max width
Max width x allows you to define the maximum width a column can have, this
means the column can be smaller, but never wider, than the supplied width.
: 0 x 200 -- give the first column a max width of 200
Min width
Minimum width i defines the smallest width a table column will have,
regardless of content the width of the column will neve be smaller than
the specified minimum width.
: 1 x 200 -- give the second column a min width of 200
Fixed width
Fixed width specifies that a column should never have any other size than the supplied width, all content larger than the width will be truncated according to formatting rules.
: 2 f 200 -- specify that the third column should be fixed to 200 units
Merge
Novem allows you to merge table cells together for more complex layout such as multi column or multi index views.
When merging cells the styling, formatting and content of the merged cell will be the value of the left, top most cell. Content and formatting of all the other cells in the merged set, except width, will be discarded.
The merging operation is the last operation applied to the dataset, meaning no other instructions will have to be adjusted to account for the merged layout.
Merging cells is similar to other novem slicing operations in that a slicing selector is created to define the cells to operate on. Unlike other table cell options the only action is to merge, so no further paratmers are needed.
In additon, as you can only merge a continous selection of cells, step operations are not allowed in novem merge selectors.
Creating category columns
A common way to use cell merges is to delineate different categories where a common set of sub-titles is shared amongst super titles.
Novem cell merging allows you to easily create these more complex layouts.
0 1:6 cat1 -- Merge category 1
0 7:12 cat2 -- Merge category 2
Creating a multi index (TODO)
A common way to use cell merges is to delineate
Priority
Novem tables are made to be shown on many different displays, from small cellphone widgets to landscape orientation documents.
To give the user better control over what information is to be included in the different views we support a priority syntax for rows and columns.
Priority is designated by regular slicing notation followed by a pririty integer
and a transformation option.
The lower the number the higher the priority, by deafult all cells start with
and equal priority of 0 and the option of collapsible.
N.B. mail tables mtable does not support priority
The mail table renderer does not have access to width information at run-time and as such cannot adjust to the display format. Please exercise care when designing for e-mails.
Hidden
Rows and columns given the hidden h attribute will simply dissapear if there
are not enough room to show them. The table will appear as if it only contains
the rows and columns the users can see in their current viewport.
: : 0 h
Collapsed
Collapsed columns and rows, designated with the c attribute, will give a
visual indication that one or more row/columns have been hidden in the user view.
: : 0 c