README

XPR-Toggle.js

This is a Node.js plugin for XPRMNTL feature-client. It adds a new express4 middleware (featureClient.toggle) that serves client-side javascript for toggling features via the browser.

This library requires a .features object to exist on the express req object, as supplied by xpr-express and the default update of feature data is by serialization matching the same. If you have your own user->feature serialization/deserialization, you will need to configure both.

Installation

$ npm install xpr-toggle

API

Server

var featureClient = require('feature-client');
var xprExpress = require('xpr-express');
var xprToggle = require('xpr-toggle');

featureClient.use(xprExpress());
featureClient.use(xprToggle());

app.use(featureClient.express);
app.use(featureClient.toggle);

Client

<script src="/xprmntl/xpr-toggle.js"></script>

Toggles

To show the toggles, you must have the script tag on the page, and you may either:

Add a new query parameter of "listEx"

[url]/[path]/?listEx
[url]/[path]/?listEx#/some/spa/stuff
[url]/[path]/?query=val&query2=val&listEx

From the JavaScript console, you may call xpr.listEx()

Reload

If at any time, you want to refetch your user's xpr data, you may call xpr.reload() which will refresh that data via an xhr request.

Events

For integration into external libraries, you may listen for updates.

xpr.on('update', function(e, xprData) {
  // `e` is a JS CustomEvent
  // `xprData` is the current configuration.
});

Configuration

You may pass in a config object during initalization:

  featureClient.use(xprExpress(config));

config.scriptUrl - The url from which you want to serve the client component
- defaults to /xprmntl/xpr-toggle.js
config.dataUrl - The url from which you have the option of reloading the XPRMNTL configuration data.
- defaults to /xprmntl/xpr-data.json
config.defaultSave - Setting this to false will prevent creation of xpr.saveExps and xpr.clearExps on the client.
- This will cause errors if you have not filled this gap properly.
- xpr.saveExps shall be a function that accepts a userID, and an object in Experiment Format and is called when a toggle is changed:
```
{
  userID: userID,
  bucket: bucketNumber, // 0-99
  app: {
    userID: userID,
    bucket: bucketNumber, // May be different
    stamp: someHash, // Used to determine when out-of-date
    features: {}, // Key,value of what is already used for this user
    dirtyFeatures: {}, // Used to override library experiments with `this.features`
  },
  shared: {} // Same format as `this.app`
}
```
- xpr.clearExps accepts a callback and is called when "Reset" is clicked. If you do not want the page to reload do not call the callback, but probably do immediately call xpr.reload()

Usage no npm install needed!