CSV Table Block

For tables with lots and lots of data, you may prefer the CSV Table Block over the Table Block. It allows you to build the table data in a CSV file (or in Excel, and then export it to CSV), which will then be used as the source of the table's content. Here's how it works:

Creating Your CSV File

The instructions below talk about the detailed CSV text format, which you can create using a text editor like Notepad or Sublime Text. But the most natural way to create your CSV file is to use a spreadsheet program like Excel or Google Sheets. This will allow you to see roughly what your table will look like. Then, export that spreadsheet as a CSV file. Excel or Google Sheet's export function will generate all the formatting for you. That way you won't have to worry about getting the number of commas right or dealing with multi-line data in individual cells. Please do not use a word processor like Microsoft Word, because such programs don't save raw text files.

To export a single Excel spreadsheet page as a CSV file, use the File -> Save As... menu. Then, from the File Format dropdown in the save dialog, choose the CSV UTF-8 (Comma delimited) (.csv) option. Then choose a location and filename, and save the file.

To export a single Google Sheet page as a CSV file, use the File -> Download -> Comma Separated Values (.csv) menu. This will download the CSV file to your default download location, with a filename matching the Sheet's title and the name of the current page.

The CSV Format

CSV Table Bock requires a specific format for the CSV file, to let it display the data properly. There are three types of lines that CSV Table Block requires:

Header line: This is the first line in the CSV. It contains the titles of each column. Every column must have a title. Titles don't have to be unique within the same table, but uniqueness is strongly encouraged.
Format line: This line lets you specify what type of data is in each column, and how to format it for display. The details will be explained below.
Content lines: These are the actual table data. Every single Content line must have exactly as many pieces of content as the Header line, though blanks are allowed.

A typical Header line looks like this:

Name, Position, Salary, Hire Date, Age

And a Format line that might correspond to those titles would be:

, options=filter, datatype=currency, datatype=date, datatype=number;alignment=right

This would make the Content rows get treated, in order, as: default text, filterable text, money, dates, integers

The Content rows themselves might look like this:

John Smith, Software Engineer, 75000, 2020-10-09, 29
Julie Shapiro, Sales Associate, 90000, 2015-03-15, 35
Joe Samson, Software Engineer, 80000, 2018-05-26, 33
Max Carnage, Obliterator, , 2021-10-14, 2001

Format Options

The Format line offers a wide variety of options to apply to each column. Some add functionality, like options=filter. Some specify the data type, like datatype=currency, so that numbers in the CSV are displayed as dollar values in the table. Here's all the Format options, what they do, and how to combine them:

datatype

This can be any one of the following: text, number, currency, date, or datetime. Text is the default.

alignment

This can be any one of the following: left, center, or right. Left is the default.

options

CSV Table Block currently supports three options, and multiple can be included simultaneously, by using a colon to separate them. E.g. options=filter:nowrap:

filter: This option adds a UI control to the table that allows visitors to filter the table to show only those rows which match a single unique value from that column.
hidden: This option hides the column by default. Visitors can hide and unhide columns manually using a UI control.
nowrap: This option forces the content of the row to render on a single line, even if it would normally break across multiple lines.

To specify multiple format objectives for the same column, separate them with semicolons like so:

datatype=text; alignment=center; options=filter:nowrap

Bringing it all together, the earlier examples for full Header, Format, and Content lines:

Name, Position, Salary, Hire Date, Age
, options=filter, datatype=currency, datatype=date, datatype=number;alignment=right
John Smith, Software Engineer, 75000, 2020-10-09, 29
Julie Shapiro, Sales Associate, 90000, 2015-03-15, 35
Joe Samson, Software Engineer, 80000, 2018-05-26, 33
Max Carnage, Obliterator, , 2021-10-14, 2001

Would render in CSV Table Block like this:

So that's how you get basic text and simple dates, currency, and numbers to display nicely. But CSV Table Block supports complex text, as well. To include things like multiple paragraphs, links, bold and italic formatting, and linebreaks, you can use the Markdown language in your text columns.

CSV Table Block doesn't support the entire language, for security and simplicity reasons, but it does support most of the features you'll find useful in tabular data. Here's how to format each thing the block supports:

Links

[This is a link](https://www.caltech.edu), isn't it great?

Displays as: This is a link, isn't it great?

Bold and Italic

This word is **bold**, while this one is _italic_.

Displays as: This word is bold, while this one is italic.

Paragraphs

These are a tad trickier, as you need to use two newlines to represent a paragraph break in Markdown. In a CSV file, this means the entire value will need to be wrapped in double-quotes, so that the CSV treats it as a single column of the current line, rather than multiple lines. Like so:

Max Carnage, "Master of all things explosive.

Do not mess with him", , 2021-10-14, 2001

That single row of CSV data will render like this in a CSV Table Block:

Linebreaks

Linebreaks are like paragraphs, but they put less space between the above and below line of text. They're a tad awkward to document, though, as Markdown's code for linebreak is difficult to express in a webpage. What you need to do is end the first line with two spaces, then press enter, then type the second line. I'll use <space> as a visual indicator. Don't actually type that.

Max Carnage, "Master of all things explosive.<space><space>
Do not mess with him", , 2021-10-14, 2001

This text will render like this in a CSV Table Block:

The CSV Table Block Form

To actually put a CSV Table block into your page, choose a supported Layout Block (Right or Left Sidebar block's content area, Two Column Block, or the top level of the StreamField), then Add a "CSV Table" using the Add Block UI:

You'll then see this block form:

The Document field is what lets you choose the .csv file from your site's Documents list.

Page Size determines the default number of rows that will be displayed at one time. CSV Table Block is paginated by default, and writers can choose to display 10, 25, 50, or 100 rows at a time by default. Visitors can change this value to suit their own preferences when they view the page.

The Striped checkbox lets you decide if you want your table to have alternative background colors per row. It looks like this:

The CSV Table Block view

Visitors who view a CSV Table Block will have several ways to interact with the table, mostly for searching and filtering purposes.

Columns

The Columns control allows users to hide or show columns at will. Click the "Columns" button next to Table Controls to bring it up:

This screenshot shows the Salary column having been manually hidden.

Filters

Filtering by a single column can be done by opening the "Filter By" table control:

Notice that if we choose "Software Engineer" from the Filter By: Position dropdown, the table will collapse down to just the two rows with have Software Engineer as the "Position" column.

And finally, there's the Search field in the upper right. Visitors can search for whatever they like in this field, and the table will be immediately filtered to show the results as they type.

Searches are done against the filtered results from the Filter By control, so be sure to turn that off before you search, if you don't want the extra filtering.