Getting Started Guide - pvande/Tranquil GitHub Wiki

By now, you've heard or seen that Tranquil is a great tool for building dynamic tools for reporting information. Fortunately, it's also very easy to get started with!

For this demo, we'll be working with the version of Tranquil hosted on Heroku - you can get there by visiting http://tranquil.heroku.com/ in Chrome.

The page we're looking at is using the default configuration; that's not particularly useful to us, but it does tell us how we can supply our own configuration file. Let's start by building our own config file, and putting it somewhere our browser can read it.

I've opted to use Github Gists for this, because they're an easy way to publish (and edit!) simple files on the Internet. If we click the raw link for that file, we have a link that serves us specifically just the contents for that file.

We can take that link, then, and supply it as the value to the config parameter for Tranquil.

Let's talk a little bit about that config file format. The file itself is JSON, which is simply a formal way of talking about a Javascript object literal.

{ ... }

That config object has a key, layout, that holds an array.

{
  "layout": [ ... ]
}

That layout array contains the description of each row of the status board. In this case, we have a single row containing a widget with a type of static.

{
  "layout": [
    { "type": "static", ... }
  ]
}

Each widget is a Javascript object with a type field describing what kind of widget it is. Any additional fields used by the widget are described by the type itself. All of the core types will be documented on the project's wiki page here. In this case, looking at the documentation for the Static type, we can see that it takes a template object with a content string that dictates what gets rendered.

{
  "layout": [
    {
      "type": "static",
      "template": {
        "content": "Getting Started with Tranquil!"
      }
    }
  ]
}

If we want to add another row, we can do that easily by appending a new widget object to the layout array.

{
  "layout": [
    {
      "type": "static",
      "template": {
        "content": "Getting Started with Tranquil!"
      }
    },
    {
      "type": "static",
      "template": {
        "content": "Second row!"
      }
    }
  ]
}

This ends up looking something like...

I mentioned earlier that each element of the layout array described a row on the status board, but so far we've only seen rows that contained a single widget. In actuality, we've been using a shorthand: the layout value is best described as an array of arrays of widgets. Tranquil is giving us a hand and automatically converting those bare widgets into single element arrays. If we want a row with more than one widget, we should wrap those widgets in an array.

{
  "layout": [
    {
      "type": "static",
      "template": {
        "content": "Getting Started with Tranquil!"
      }
    },
    [
      {
        "type": "static",
        "template": {
          "content": "Second row!"
        }
      },
      {
        "type": "static",
        "template": {
          "content": "Second column!"
        }
      },
    ]
  ]
}

So far, everything we've done has been using the simple Static type, but if we're building a status board, we probably have data we want to present. The most straightforward way to do that is to use the Dynamic widget type.

{
  "layout": [
    {
      "type": "dynamic",
      "data": {},
      "template": {
        "content": "Dynamic Templates in Tranquil!"
      }
    }
  ]
}

This new widget type (and all of the dynamic core types) introduces a bunch of new parameters, including url, interval, filter, and data. The url parameter is for specifying the remote data source we should fetch data from, and interval describes how often (in milliseconds) we should poll for updates. The filter parameter is used to name a function that will take that data and coerce it into a format that is more easily consumed by the widget. The data parameter gives us the ability to test the widget, without requiring remote connections.

In this case, we've specified an empty data object, and our content template is just static text. All of the dynamic core types use Mustache to handle data interpolation. Let's try a more interesting data object and template.

{
  "layout": [
    {
      "type": "dynamic",
      "data": {
        "data": { "full_name": 'some/repo', "watchers": 5, "open_issues": 0 }
      },
      "template": {
        "content": "<h3>{{data.full_name}}</h3> ({{data.watchers}} watchers, {{data.open_issues}} issues)"
      }
    }
  ]
}

This gives us a reasonable approximation of how this widget will look when we've got it attached to real data, and as it turns out, our fixture data object contains a subset of the data of Github's Repo API. So at this point, we can replace our fixture data with the URL on Github and see this work with real data.

{
  "layout": [
    {
      "type": "dynamic",
      "url": "https://api.github.com/repos/pvande/Tranquil?callback=?",
      "template": {
        "content": "<h3>{{data.full_name}}</h3> ({{data.watchers}} watchers, {{data.open_issues}} issues)"
      }
    }
  ]
}

The Dynamic type is about as flexible as you can get, but it's certainly less convenient than it might be. For more specialized visualizations, you'll probably want to use a more specific type. There are a number of built-in types you can leverage, and writing your own is reasonably easy. Play around with it, and above all -- have fun!