CSV Chart Block

Caltech Sites now supports a new block called CSV Chart Block. Much like the CSV Table Block, it uses a CSV file to populate the data for a chart, which can be displayed in a variety of different formats. You can build the CSV file in Excel, then export it to CSV to use it as the data source for the chart. Here's how it works:

Creating Your CSV File

These instructions inform the reader of 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. You can then export that spreadsheet as a CSV file to use with CSV Chart block. 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 Chart Bock requires a specific format for the CSV file, to let it display the data properly. There are three types of lines that CSV Chart Block requires:

Header line: This is the first line in the CSV. It contains the titles of each axis in the chart, with the X-axis first and the Y-axis second. Column titles are optional, but this line must have two elements, even if they're both blank.
Format line: This line lets you specify what type of data is in each column. The details will be explained below.
Content lines: These are the actual chart data. Every Content line must have exactly two elements: the X-axis datum and the Y-axis datum. Blanks are allowed, but having a blank X-axis datum makes little sense.

A typical Header line looks like this:

Date, Tracked Value

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

type=datetime, type=numeric

This would make the Content rows get treated, in order, as: datetime, number

The Content rows themselves might look like this:

2023-02-09, 29
2023-02-10, 35
2023-02-11, 33
2023-02-12, 20

Format Options

The Format line lets you set the type of data in each column. The library we use to present the chart recognizes three data types:

datetime, numeric, category

Datetime columns can contain any data that's parseable as a Date value by Javascript. e.g. "2018-03-20 12:35:50 PST" or "2022-06-04".

Numeric columns can be any kind of number, e.g. 1, 3.4, 4.56e7, etc.

Category columns can be any string of characters. There's no need to specify this type, as it's the default.

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

Date, Tracked Value
type=datetime, type=numeric
2023-02-09, 29
2023-02-10, 35
2023-02-11, 33
2023-02-12, 20

Would render in CSV Chart Block like this when using the default block settings:

The CSV Table Block Form

To actually put a CSV Chart 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 click the + button and either scroll down to CSV Chart, or type "chart" into the "Search options..." field to filter the list of available blocks.

You'll then see this block form:

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

Chart Type determines how the data is presented. Currently, CSV Chart Block supports Vertical Bar charts and Line graphs.

The Color picker lets you choose a color for the bars/line. Here's a red line graph of the same example data seen above: