Embedding CloudTables

The whole point of CloudTables is to let you quickly and easily define the structure of your data and then embed it seamlessly into your web application / page. As such we have two methods that can be used to perform the embedding:

• Securely with server-side API key
• With an API key client-side

Which one is the most appropriate will depend upon the context in which you are using CloudTables. For example, you might wish to publish a table as read only available to the general public without needing to use a sever-side action, while still having full read / write access in your own admin portal.

Securely with server-side API key

The recommended way to embed a CloudTable in your application is to request an access token based on an API key. That access token gives the same access rights as the API key, but it is time limited and is available for use by one client session only. Any other clients attempting to access the embedded table using the same access token would receive an access error.

The best way to get an access token is through one of our supported libraries - please see the documentation for the platform you are using. If we don't yet provide a library for your platform, or you wish to create your own, see the HTTP REST API documentation for the access route.

Once you have the access token, you embed the CloudTable into your page using a <script> tag with the data-token attribute set to the value of the token retrieved from the API.

<script
	src="https://sub-domain.cloudtables.io/loader/:datasetId/table/d"
	data-token=":accessToken"
></script>

where:

• :accessToken is the access token retrieved from the above HTTP request.
• :datasetId - the ID of the data set you'd like to show (see the data set Embed tab for this information)

The <script> tag should be inserted into your HTML where you want the CloudTable to be shown.

With an API key client-side (Serverless)

This method will expose your API key in web-browsers and as such should not be used for sensitive data or with an API key that has write access in a context where you do not want to expose that functionality.

Having given you that warning, the advantage of using this method to embed a table is that it is very easy. You can place it directly into HTML without need for any server-side script contacting CloudTables before serving the client's request.

To embed the data set in your HTML page where you want the CloudTable to appear use:

<script
	src="https://sub-domain.cloudtables.io/loader/:datasetId/table/d"
	data-apiKey=":apiKey"
	data-clientId=":clientId"
></script>

where:

• :apiKey - the API key which will allow access (and thus assign the roles that can be used for access).
• :clientId - a unique id for the client accessing the table on your system. This is optional, but useful for tracking requests in CloudTables' analytics. For example you might use web as the id if you embed it in a public web-page, or an id specific to that page. A data-clientName parameter can also be specified, but that is more useful for the server-side API key interaction detailed above when you are using a user login system.
• :datasetId - the ID of the data set you'd like to show (see the data set Embed tab for this information)

Additional options

The embed script can also be given a number of custom attributes to effect its behavior. These are discussed below.

Custom ID

At times you might wish to interact with the DataTable that is embedded into the page by CloudTables. That can be done through the ct-ready event. If you are working with multiple CloudTables on a single page you might wish to be able to tell them apart to work with their APIs. The data-id attribute can be used for this to assign the DataTable a specific ID as well as triggering a custom ct-ready-* event.

<script
	src="https://sub-domain.cloudtables.io/loader/:datasetId/table/d"
	data-token=":accessToken"
	data-id="employees"
></script>

You can then use the following to know when the table is available (for more information see the documentation for accessing the table):

document.addEventListener('ct-ready-employees', function (e) {
	// ...
});

Positioning

A data-insert attribute can be used to tell CloudTables where to insert the table into the page. By default it will place the table immediately after the <script> tag used to embed it, but you may wish it to go somewhere else (for example if you need to have all <script> tags in your <head>). The value given in data-insert will be matched to another element which has a data-ct-insert attribute with the same value - e.g. this could be an empty <div>:

<script
	src="https://sub-domain.cloudtables.io/loader/:datasetId/table/d"
	data-token=":accessToken"
	data-insert="cloudtable"
></script>

<div data-ct-insert="cloudtable"></div>

It is inside this matching element that the CloudTable will be inserted.