Accessing the DataTable

CloudTables is built upon DataTables which provides an extremely rich API that can be used to access data from the table. As the CouldTable is a fully integrated part of your page, you can access the DataTables API to access the data. For example you might wish to use the data from the table in a charting library to visually represent the data.

Once embedded on your page two events will be triggered on the document:

• ct-ready triggered for each and every CloudTalble on the page
• ct-ready-{tableId} is triggered for each individual table (useful for listening for a specific CloudTable should you have multiple on the page).

You can listen for these events using document.addEventListener:

document.addEventListener('ct-ready', function (e) {
	let datasetId = e.datasetId;
	let domId = e.domId;
	let editor = e.editor;
	let table = e.table;

	// ...
});

If you wish to listen for a specific table, you can use the data-id attribute for the embed script, which will be used for the <table>'s id attribute and also fire this custom event - e.g.:

document.addEventListener('ct-ready-myId', function (e) {
	let datasetId = e.datasetId;
	let domId = e.domId;
	let editor = e.editor;
	let table = e.table;

	// ...
});

The event object passed in to the ct-ready* event handlers (e in the code above) has four custom properties:

• datasetId - The host data set's id
• domId - The ID of the <table> in the document - this can be specified by the data-id attribute used for the insert script. If not given it will automatically be assigned as ct-{datasetId}
• editor - The Editor API instance
• table - The DataTable API instance for the CloudTable in question

jQuery

If you have jQuery loaded on your page and would prefer to use a jQuery event listener, you can do so with:

$(document).on('ct-ready', function (e) {
	let datasetId = e.originalEvent.datasetId;
	let domId = e.originalEvent.domId;
	let editor = e.originalEvent.editor;
	let table = e.originalEvent.table;

	// ...
});

Note that when using jQuery, to access the custom properties datasetId, domId, editor and table, you will need to use the originalEvent parameter of the passed in object (since jQuery wraps it with its own object), as shown above. For example, e.originalEvent.table will give you the DataTable API instance.

Using the APIs

Both DataTables and Editor have a large number of API methods. Rather than attempting to re-document them here, please refer to their documentation for details:

• DataTables: Manual | Reference.
• Editor: Manual | Reference.

Example - Showing data in a chart

It can often be useful to show table information as a chart, so the end user can graphically interpret the data. There are many different charting libraries - in this example we'll make use of HighCharts. Please see the HighCharts documentation for full details and options.

A chart can be created using:

var myChart = Highcharts.chart('container', {
    chart: {
        type: 'pie',
    },
    title: {
        text: 'Staff Count Per Office',
    },
    series: [
        {
            data: [],
        },
    ],
});

Now we need to tie the data from our CloudTable into it - this can be done listening for the ct-ready event and then retrieving the display data from the DataTable with its cells().render() method:

// Listen for CloudTables being ready
document.addEventListener('ct-ready', function (e) {
	// On every draw of the DataTable, we re-chart the data
	e.table.on('draw', function () {
		let counts = {};
 
		// Bin the data for the third column in the table
		// (change as you need), using only the data
		// available when the search is applied.
		e.table
			.cells(null, 2, { search: 'applied' })
			.render('display')
			.each(function (val) {
				counts[val] = counts[val]
					? counts[val] + 1
					: 1;
			});
	
		// Map it to the format HighCharts uses
		let series = $.map(counts, function (val, key) {
			return {
				name: key,
				y: val,
			};
		});

		// Update the chart
		myChart.series[0].setData(series);
	});
});

The following JSFiddle shows the result from using the above CloudTables / ChartJS integration: