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
- defaults to
-
config.dataUrl
- The url from which you have the option of reloading the XPRMNTL configuration data.- defaults to
/xprmntl/xpr-data.json
- defaults to
-
config.defaultSave
- Setting this tofalse
will prevent creation ofxpr.saveExps
andxpr.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 callxpr.reload()