The flocc.TableRenderer class (from here on, just TableRenderer) writes agent data into rows of an HTML table or a list of comma-separated values (CSV). While not a visualization of data, this can be useful for showing exact, discrete values and for exporting or analyzing data.

Instantiating

A TableRenderer requires an Environment to render:

const environment = new Environment();
const renderer = new TableRenderer(environment);

Before a TableRenderer will render anything, you also need to set its columns. The columns of a table should be the names of agent data (the key in key-value pairs), and are set as an array of strings on the table’s columns value.

const renderer = new TableRenderer(environment);
renderer.columns = ["x", "y", "color"];

A TableRenderer can also be instantiated with configuration options that let you filter, sort, and limit the rows that are rendered.

const opts = {
    filter: Function,
    limit: number,
    order: 'asc' | 'desc' = 'desc',
    refresh: number = 500,
    sortKey: string,
    type: 'csv' | 'table' = 'table'
};
const renderer = new TableRenderer(environment, opts);

filter

You can pass in a function that takes an agent as its only parameter and returns a boolean value (to say whether or not to include this row in the output). For example, if you only want to include agents with an x value greater than 100:

const renderer = new TableRenderer(environment, {
  filter: agent => {
    return agent.get('x') > 100;
  }
});

limit

By setting a number for a limit, the table will write at most this many rows (not including the header row, which simply writes the column names). If you use the limit option alongside filter, the limit will be applied after data has been filtered.

order

This option is only relevant when using a sortKey to sort data. Set this to "asc" to have data be listed in ascending order, and "desc" to have it in descending order.

refresh

Environments and other renderers (e.g. CanvasRenderer) typically redraw very quickly. However, this experience is extremely jarring and unhelpful in a TableRenderer. The refresh option lets you control how often the table should be re-rendered with updated data by specifying the number of milliseconds that should elapse between re-rendering.

.mount(selector or element)

Calling .mount specifies where on the page the TableRenderer should render. If passed a CSS selector (like #id or .class), the renderer will look for the first matching element on the page, and use that as a container. If passed an element directly, the renderer will use that element as a container.

<div id="some-element"></div>

renderer.mount('#some-element');
// or...
const element = document.getElementById('some-element');
renderer.mount(element);

.render()

Renders Environment‘s agent data into a table inside the HTML element that was mounted previously.

.output()

Returns the outer HTML of the table or the CSV data as a string. This can be useful for exporting data, particularly in a Node.js environment as opposed to in a browser. For instance, in a Node.js script, you could write the CSV data to a file as follows:

const fs = require('fs'); // import the file system module
const environment = new Environment();
for (let i = 0; i < 3; i++) environment.addAgent(new Agent({ i }));
const renderer = new TableRenderer(environment, { type: 'csv' });
renderer.columns = ['i'];
// write the TableRenderer's output to a CSV file named data.csv
fs.writeFileSync('./data.csv', renderer.output());