Skip to content

Make your own

Clément Geiger edited this page Aug 19, 2014 · 16 revisions

Summary: this page will explain how to extend Datastringer:

If you don't know what use-cases and stringers are, please refer to the architecture page.

Since it's significantly easier to make new use-cases for existing stringers than to make new stringers, let's start with that.

#Use-case

Datastringer stores its list of use-cases in ~/.local/share/datastringer/stringers_use_cases.json. Inside, you will find an array of use-cases: just append a new one at the end, or edit an existing one.

##Anatomy of a use-case

A use-case presents two fields:

  • stringer is the name of the JS file where the stringer for that use-case is written.
  • parameters is an array holding all the parameters the stringer needs to run, except the callback. These parameters are stringer-dependant: one may need two strings, another one four ints... It depends. Hopefully, the stringer you want to use comes with some documentation, and that's where you will find this info.

##For example:

Let's add a use-case for local-police.js. This stringer monitors any changes in information about local police teams (people, events, priorities). It just needs two parameters: the force to which the team is attached (metropolitan, leicestershire, etc.) and the team's code in that force (boring looking IDs such as 00AMGF, A01, ...)

Here we want to monitor changes for the team C01 from leicestershire force. We'll just write that:

{
  "stringer": "local-police.js",
  "parameters": ["leicestershire", "C01"]
}

at the end of the array in ~/.local/share/datastringer/stringers_use_cases.json and Datastringer will start using this new use case at its next run!

#Stringer

In Datastringer, stringers are functions living in JS file. There is one file per stringer. Let's see what's inside local-police-stringer.js:

var fs = require('fs');
// import whatever modules you want

function stringer(force, neighbourhood, triggerAlertCallback) {
  // stuff and stuff and stuff
  // eventually, call the triggerAlertCallback if there is an alert.
  if (alert) {
    triggerAlertCallback('Local Police Stringer', 'there is a new bobby in the team: John Layman');
  }
}

module.exports = stringer;

We can note some important things:

  • Datastringer relies on nodejs, so you can require modules.
  • For the same reason, a stringer is exported in a module. When requireing a stringer file, Datastringer expects to get a single function, which is the actual stringer function. So be sure to put module.exports = myStringerFunction at the end of your file.
  • The stringer function accepts as much parameters as it needs to fetch data and determine whether there's an alert but its last parameter must always be a callback. The stringer function must call that callback when it wants to signal an alert.
  • That callback will take two parameters: the stringer's name, and the reason for the alert. Both are strings.

##Your stringer made easy Datastringer ships with some utilities to help you writing stringers. All of them are located in the utils.js module. Let's review them!

###getTheJSON We made quite a heavy usage of GET requests to API to fetch JSON files, so we decided to write this simple helper. It's quite straight forward, as you can see:

var utils = require('./utils.js');
utils.getTheJSON('the/json/url', function(err, jsonData) {
  if (!err) {
    console.log('we got some JSON: ', jsonData);
  }
});

###readAsset, writeAsset When writing a stringer dealing with history ("Is this data different than the previous one?"), you will want to store the current data to refer to it later. And later you will want to read that stored data. Thus, readAsset and writeAsset, thin wrappers around readFile and writeFile. Essentially, they make sure you read and write from and to the ~/.local/share/datastringer folder. If you write in unexisting folders, they will be created along.

var utils = require('./utils.js');

writeAsset('myfolder/hello.json', 'hello there', function(err) {
  if (err) {
    console.log(err);
  }
});
// you just wrote 'hello there' in ~/.local/share/datastringer/myfolder/hello.json.
// if ~/.local/share/datastringer/myfolder didn't exist, it has been created.

readAsset('myfolder/hello.json', function(err, data) {
  if (!err) {
    console.log('read some data: ' + data); // read some data: hello there
  }
});
You can’t perform that action at this time.