Dash-fu sources need to get their data somehow: enter Marios. Marios are the brave workers that go out and collect data from vaious data sources and report them back in the form of activities and metrics.

Setup

A Mario is setup in four steps. First, the display method returns an HTML form which will be displayed to the user. In fact, this method returns two values:

  • inputs – HTML input controls for setting up a new controller.

  • notes – Additional setup notes, e.g. other steps that need to be followed, what values to supply, etc.

Wrap input controls within the label and use the source notation for the name attribute. For example, for Twitter:

<label>Screen name <input type="text" name="source[screen_name]" size="30"></label>

When the form is filled, the setup method is called with a context and values from the form fields. Since the Mario needs to store state information, it uses the context for that. The context is a Hash that can store basic Ruby values (nil, String, boolean, Numeric, Array and Hash).

Some sources collect metrics. These sources must set three specific values (during setup):

  • metric.name – The name of the metric, e.g. Twitter source might use the name “Twitter mentions of @dash_fu”.

  • metric.columns – Specifies the columns (at least one) that make up this metric. The value if an array where each item describes a single column, see below for more details.

  • metric.totals – True if this metric collects totals (life-time values, e.g. downloads, user accounts), false if it only collects daily values (e.g. average response time, number of instances in cluster).

For metric.columns, each item can use the following keys:

  • id – Column identifier (if missing, derived from column name)

  • name – Column name (required)

Shortly after setup, the validate method is called with the same context. If it raises any exception, the error is displayed to the user and the source is discarded. Otherwise, register is called with a Webhook URL. Some Marios use that to register the Webhook with another service.

Updates

Periodically, the Mario will be asked to update the source by calling the update method. This method is called with the same context and a block. If data comes from a webhook, then the second argument to update is a Rack::Request object.

The block passed to update can be used to update the source by yielding to it with a hash of named arguments. A single update may yield any number of times with any combination of arguments.

The named arguments are:

  • set – Columns to set (metric). Records the most recent value for this metric. This is a hash where the keys are column ids (or indexes), the values are integers or floats.

  • inc – Columns to increment (metric). Records a change in value which may be positive or negative. This is a hash where the keys are column ids (or indexes), the values are integers or floats.

  • timestamp – The Time (if missing, uses the current system time).

  • activity – Activity to show in the stream. See below.

Activity can specify the following attributes:

  • uid – Unique identifier (within the scope of this source). For example, if activity is a release, this could be the version number.

  • html – HTML contents of the activity.

  • text – Text contents of the activity (can be used instead of html).

  • url – URL for original resource (e.g. blog post, tweet).

  • tags – Any number of tags for filtering activities like this (e.g. twitter, mention). Tags are lowercased and can contain alphanumeric, dashes and underscore.

  • person – Person who performed this activity. A hash with the (all optional) values :name, :email, :url and :photo.

  • timestamp – Timestamp activity occurred.

HTML can contain links (HTTP/S and email), images, bold, italics, paragraphs, block quotes, lists, tables, pre-formatted text, video and a few other elements. Scripts, objects, styles are obviously not allowed.

Occasionally, the meta method is called. This method is used to display meta-data from the most recent state (i.e. last update). It returns an array of fields, each being a hash with the following values:

  • title – Title for this field (not required)

  • text – Text to show as value of the field

  • url – Link (not required)

Teardown

Eventually the source is destroyed and the Webhook is unregistered by calling unregister.