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
│ │ ├── index => control table index
│ │ ├── size => size of table xs-lg
│ │ └── 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
│ │ └── 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.
Size
The table size can be one of four size, small, medium, large and auto.
The small sizes align with the corresponding e-mail sizes with small being 400, medium being 600 and large being 900. Auto adjusts to the available space.
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.
Thea 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 .
Here we use theslicers 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 (IMPLEMENT/DOCUMENT)
TODO: COMPLETE The format file consists of a newline seprated list of formatting instructions controlling the cell number/date formatting.
Things we want to show:
- Numeric Bn, Mn, K, thousands separator, decimals, percentage
- Date and time support (year, months, days, time hh:mm:ss, sub seconds etc)
- Just text
- Wrap/truncate
Text 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:
- Truncation - the removal of the excess contet
- Wrap - the splitting of content across multiple lines
There is no best practice for chosing either or, by default novem truncates overflowing text with the ellipis charracter, but this can be overriden with format instructions.
https://docs.python.org/3/library/string.html#format-specification-mini-language
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)
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