Guide to using Custom Widgets

Try our Datasets API

We encourage you to try our Datasets API for the most simple, powerful way to access your most important data with Geckoboard.

This article outlines how to get data from an external API into Geckoboard. You might choose this method of getting data into Geckoboard when the integration you would like is not already available, such as from your company’s own API.

The process explained

This diagram explains the flow of data from the its source to your dashboard.

Data source

The data you want to see on your dashboard. This can be your own systems and databases, or a third-party/external API.

Your App

In order to use Custom Widgets, you need to develop an app that requests the data from the data source, transforms it to meet the format Geckoboard expects, and then sends this data to Geckoboard.

Output

Your application needs to format the data from the data source into the format the widget expects. Each widget type has a format defined in the Developer Documentation.

Your Dashboard

Your app then either sends the data directly to Geckoboard, or responds to a request from Geckoboard for the data that you want in the widget.

Push vs. Poll

There are two ways Custom Widgets can receive data: Push and Poll methods.

The Push method means that your app sends the data directly to Geckoboard’s API. You are given a URL to send your widget data to.

The Poll method means that Geckoboard will send a request to the link that you give it, and expects your app to respond with the data for the widget.

Tip

The biggest advantage of the Push method is that you can send data whenever you’re ready. For example, if you need to perform a long running task in order to get your data ready, using the Push method is best so that Geckoboard doesn’t time out waiting for the data (with the Poll method).

You can also use a service like Dropbox to host your data or your own website. The widget just needs to be able to access a link that hosts a file with data feed.

Once you've saved the Gist, you'll now want to have a URL you can add to the widget that'll take it directly to the data.

In Github, Click the Raw button. Now copy the URL in the address bar. This is the link you'll need from the widget to work.

Return to the Line Chart configuration screen in Geckoboard. Paste the URL from in the URL Date Feed field.

Set a Reload Time that makes sense for your widget.

When you've finished configuring your widget, click Add widget.

You'll now be taken back to your dashboard complete with your new widget.

Note

This example of a simple widget will need to be updated manually. To experience the full potential of Custom Widgets it might be necessary for you to create scripts to programmatically update the widgets for you.

Important note

If you're using a Windows machine you'll need to escape all the quotes.

If all is correct, you'll receive a reply in your terminal client confirming that the push has been successful.

Note

This example of a simple widget will need to be updated manually. To experience the full potential of Custom Widgets it might be necessary for you to create scripts to programmatically update the widgets for you.