image representing the current explore topic

Data Tables

How to use the Data Tables Plugin

The data tables plugin is a fast track to displaying a small to medium sized data set within a table. Tables cells can be populated with plain text, links, or markdown. 

 

Uploading Data 

Before attempting to upload your data be sure it matches the data schema outlined below. 

 

Once your data is in the proper format you can open the structure view (button top right) on a page using the Resource List template, and do the following:

  1. Click the + button and add a data table

  2. Click the Choose File button

  3. Upload your formatted data file

  4. Hit save

At this point if your json matches the schema you'll see a table containing your data!

Data Schema

The schema for the data tables takes in a json object with three properties `order-by`, `data`, and `schema`. The order-by` property defines which of your data fields to use when ordering the table rows, the `schema` defines which data properties map to which column of the table, and `data` is an array  containing all of your row content.

 

{
    "schema": [],
    "data": [],
    "order-by": ""
}

 

Defining Table Columns

`Schema` is an array filled with several objects, each object represents a column in your table, and will be displayed in the order provided. Each column requires three properties (four for links) `column`, `type`, and `key`. The `column` property is the name of your column and will show up in the table header, `type` is one of the three available data types (string, markdown, or link), and `key` is a property in your data.

Lets say we want to create a table of books and authors like so:

Book Author About
Dune Frank Herbert Scifi, Book 1 of the Dune Saga
SevenEves Neal Stevenson Scifi, Standalone
The Sparrow Maria Doria Russel Scifi, Standalone

 

The `schema` property for this table would look like so:

{ 
    "schema": [
        { 
            "column": "Book",
            "type": "string", 
            "key": "book" 
        },
        {
            "column": "Author", 
            "type": "link", 
            "text-key": "author_name", 
            "url-key": "author_url"
        },
        {
            "column": "About",
            "type": "markdown",
            "key": "about_copy"
        }
    ],
    "data" : [{
          "book": "Dune",
          "author_name": "Frank Herbert",
          "author_url": "https://en.wikipedia.org/wiki/Frank_Herbert",
          "about_copy": "Scifi, book 1 of the [Dune Sage](https://en.wikipedia.org/wiki/Dune_(franchise))",
          "extra-column": "I won't be rendered"
    }],
    "order-by": ""
}

 

The first column "Book" is defined in the first `schema` object. It's name defined by the `column` property, it's `type` defined as `string` and the `key` is pointing to the `book` property of the row data. So while `schema` defines the columns of your table, `data` provides the rows, but row properties aren't used unless one of the `schema` columns points to it. The `extra-column` in the above data will never be displayed in our table, because it's not referenced in the schema.

 

When defining your data types you are always limited to the following.

Type Usage
`string` Content will be dropped into the cell as is. Things like html will not be rendered, rather it will be displayed as text for the user to read.
`link` This allows you to point to two fields in your data, one for the link text ("text-key"), and one for the url ("url-key")
`markdown` This allows you to insert markdown in a cell. You can find the markdown schema on Daring Fireball

 

 

Providing Row Data

The data property is an array containing some number of objects, these objects represent a single row in your table. Keep in mind that you must add an entry in the schema for each column you'd like to display, any property without an associated column in the schema will not be displayed. 

This is what two rows of data might look like:

"data":[{
    "my-data": "42",
    "transgenic_line": "Snap25-LSL-F2A-GFP",
    "knock_in_locus": "Snap25"
 }, 
 {
     "my-data": "42",
     "transgenic_line": "Ai57(RCFL-Jaws)",
     "knock_in_locus": "ROSA26"
 }]

 

Returning to the books table example, if we wanted to create the following table we need to define each of the properties referenced in our schema. 

 

Book Author About
Dune Frank Herbert Scifi, Book 1 of the Dune Saga
SevenEves Neal Stevenson Scifi, Standalone
The Sparrow Maria Doria Russel Scifi, Standalone

 

Which makes our json look like this:

{ 
    "schema": [
        { 
            "column": "Book",
            "type": "string", 
            "key": "book" 
        },
        {
            "column": "Author", 
            "type": "link", 
            "text-key": "author_name", 
            "url-key": "author_url"
        },
        {
            "column": "About",
            "type": "markdown",
            "key": "about_copy"
        }
    ],
    "data" : [
      {
          "book": "Dune",
          "author_name": "Frank Herbert",
          "author_url": "https://en.wikipedia.org/wiki/Frank_Herbert",
          "about_copy": "Scifi, book 1 of the [Dune Sage](https://en.wikipedia.org/wiki/Dune_(franchise))"
      },
      {
          "book": "SevenEves",
          "author_name": "Neal Stevenson",
          "author_url": "https://en.wikipedia.org/wiki/Neal_Stephenson",
          "about_copy": "Scifi, standalone"
      },
      {
          "book": "The Sparrow",
          "author_name": "Maria Doria Russel",
          "author_url": "https://en.wikipedia.org/wiki/Mary_Doria_Russell",
          "about_copy": "Scifi, standalone"
      }
    ],
}

 

That's it. You know have a table containing some great authors and some of thier best works.

 

Row Ordering

The last and probably easiest part of all this is the `order-by` property. This lets you choose a single property from your data rows and render the rows in descending order based on that property. Returning once more to our example, if you wanted to order the rows by author name you could simply do the following:

{
    "order-by": "author_name",
    "schema": [ ... ],
    "data": [ ... ]
}

 

Real World Example

File:

cell_lines.json

Result: