Retracked draft

README.md

Retracked wraps your event recording system in an API optimized for React components.

Usage

Setup

Somewhere early in execution:

# set the recording function
retracked.setup(myTrackingSystem.push);

In a parent component to set tracking context:

  childContextTypes: {
    track: React.PropTypes.func,
  },

  getChildContext: function() {
    return {
      track: Retracked.makeTracker({
        namespace: 'course.welcome_page',
        include: {
          'course_id': () => this.props.course.get('id'),
          'course_slug': () => this.props.course.get('slug'),
        }
      })
    };
  },

Then when you want to track events:

    render() {
      this.context.track('Foo_rendered');

or for a handler:

      <a
        onClick={this.context.track.handle('instructor_link.click', {'instructor_id': instructor.id})}

retracked.js

/**
 * Retracked wraps your event recording system in an API optimized for React components.
 *
 * .track(key, values) records an event immediately. (values are optional)
 *
 * .track.handle(key, values) returns a function that records the event when evaluated.
 */

var _ = require('underscore');

var _recordEvent = function() {
  throw new Error('Retracked setup() must first be called with an event recording function.');
};

exports.setup = function(recordEventFn) {
  _recordEvent = recordEventFn;
};

exports.makeTracker = function(config) {

  var include = config.include || {};

  var event = function(eventKey, moreValues) {
    var fullEventKey = config.namespace ? config.namespace + '.' + eventKey : eventKey;

    // keys map to values or functions
    var includeValues = _(_(include).map(function(valOrFunc, key) {
      return [key, _(include).result(key)];
    })).object();

    var values = _({}).extend(includeValues, moreValues);

    _recordEvent(fullEventKey, values);
  };

  // curried form returns function that calls event with the same args
  event.handle = function(eventKey, moreValues) {
    return event.bind(null, eventKey, moreValues);
  };

  return event;
};