Plugin Architecture

The official documentation has been moved to http://wiki.sarah.encausse.net/

.
.
.
.
.
.
.
.

This page describe some getting started infos with plugin architecture. (All edited files should be in UTF-8 to handle accent)

see also: Mon Premier Module

Properties

Plugins must provide a JSON configuration file named {plugin}.prop. This file contains data to be used by plugin and overrided by users.

{
  "modules" : { 
    "myplugin"  : {
      "description": "Description of My Demo Plugin",
      "version"    : "0.1",
      "token"      : "secret token",
      "param"      : "some sample value"
    }
  }
}

Configuration

Plugin's configuration must be edited online (http://127.0.0.1:8080). It will be saved and merged in custom.prop. So secret token stay stored in custom.prop of user's install.

Note: Plugin's properties can also set x, y, w, h to layout portlets

JavaScript

Plugins must provide a JS file named {plugin}.js. This file contains the code to run for each HTTP request to: http://127.0.0.1:8080/sarah/{plugin}?{param}={value}

The plugin must expose the following function:

exports.action = function(data, callback, config, SARAH){

  // Narrow to plugiin's config
  var config = config.modules.myplugin;
  
  // >>> your code here <<<

  callback({'tts' : 'text to speech'});
}

Here is a description of function's parameters:

Params	Description
data	JSON object with HTTP request parameters
callback	A function that MUST be called ONCE to release the request
config	The JSON config file
SARAH	The Singleton entry to API

Callback

The callback function MUST be called ONCE to release the HTTP request. The parameter is a JSON object that will be forward to caller and following plugins (using Rule Engine).

If the caller is an HTTP request the parameter tts will be sent back and vocalized.

Scope

The plugin can declare variable and utility function outside the export. It helps to get a more readable code.

exports.action = function(data, callback, config, SARAH){
  var value = yourcodehere();
  callback(value);
}

var yourcodehere = function(){
  // your code here
  cache = 'something';
}

var cache; // some data to store in memory

The scope of cache and yourcodehere() is only visible to this plugin and stored in memory. If the plugin's file is modified, it is reloaded and memory is wiped.

Exports (hooks)

Hooks are function a plugin can provide to hack default behavior.

Initialization

An initialization function can be called:

• When the server starts
• When the plugin is reloded

exports.init = function(SARAH){
  // your code here
}

This function can be used to initialize data, setup a server, etc ...

Speak

A plugin can provide speak() function to override default tts or find an other way to perform text to speech. If tts is false then speech is canceled. If async the function is called twice. The second call async=false.

exports.speak = function(tts, async, SARAH){
  // your code here
  return tts;
}

Params	Description
tts	The text to speech
async	True if async, False if sync or end of speech
SARAH	Singleton API

Motion / StandBy

A plugin can provide standBy() function to handle motion/standby state of clients.

exports.standBy = function(motion, data, SARAH){
  // motion is a boolean true/false
}

CRON

CRON plugins works like modules but are called at a given time schedule. A plugin can handle both.

{
  "cron" : {
    "myplugin" :   { 
      "name"       : "myplugin",
      "description": "Description of My Demo Plugin",
      "time"       : "0 */5 * * * *",
      "token"      : "secret token",
      "param"      : "some sample value"
    }
  }
}

The time parameter is a CRON notation. To call the following function:

exports.cron = function(callback, task, SARAH){
  // >>> your code here <<<
  callback({'tts' : 'text to speech'});
}

The task parameter is a JSON object of the plugin's cron config.

PhantomJS

PhantomJS plugins works like modules but are executed by PhantomJS to scrap a webpage. The URL to call that plugin is: http://127.0.0.1:8080/sarah/phantom/{plugin}?{param}={value}

see also: How to: Scraping with Cheerio or PhantomJS

{
  "phantoms" : { 
    "myplugin"  : {
      "description": "Description of My Demo Plugin",
      "version"    : "0.1"
    }
  }
}

Remember this file is called by PhantomJS not NodeJS.

// Inject helper
phantom.injectJs("../../script/lib/scraper.js");

// Merge default options with querystring
var options = {};
scraper.setOptions(options);

var url = 'http://path.to/page/to/scrap.php';

// Scrap
scraper.scrap(url, options, function(options, results) {
   // >>> Your code here <<<
   // >>> It is run into the webpage with jQuery <<<
   var items = $('body').text() ; 
   results.tts = items; // The object to return in callback()
});

The result can also be processed by NodeJS if a file {plugin}.node.js is provided.

exports.after = function(options, results){
  // >>> Your code here <<<
}