meta_events 1.0.1

data/vendor/assets/javascripts/meta_events.js.erb

@@ -0,0 +1,154 @@
+var MetaEvents = window.MetaEvents || {};
+/**
+ * Defines the MetaEvents JavaScript module. This provides client-side functions that support MetaEvents'
+ * auto-tracking and frontend events systems; see README.md for more information.
+ */
+MetaEvents = (function() {
+  var out = {}; // The public object that we'll return.
+  var createDomIdUniqueId = 0; // Helps us ensure we generate truly unique DOM IDs.
+  // See MetaEvents::Helpers.meta_events_javascript_tracking_prefix for more details; just copies that string.
+  var trackingPrefix = <%= MetaEvents::Helpers.meta_events_javascript_tracking_prefix.to_json %>;
+
+  /**
+   * Given a DOM element, ensures that it has a DOM ID on it. Returns its unique DOM ID -- either the one it already
+   * had, or the newly-generated synthetic ID.
+   *
+   * @param element - The DOM element that you want to make sure has an ID.
+   */
+  var getOrCreateDomId = function(element) {
+    var theId = element.id;
+
+    if (theId == null || theId == "") {
+      theId = "metaEventsSyntheticDomId" + createDomIdUniqueId++;
+      element.id = theId;
+    }
+
+    return theId;
+  };
+
+  /**
+   * Given a DOM element that should be used with auto-tracking, calls a specified function, passing in the unique
+   * DOM ID of the element (which will be generated if necessary), the element itself, the name of the event that
+   * should be fired, and the set of properties that should be fired with that event.
+   *
+   * After the specified function is called and returns successfully, the element is marked (via a jQuery data
+   * attribute) so that it will never again have that function called.
+   *
+   * @param element - The element that we should use
+   * @param applyFunction - The function that we'll call on that element, unless it has already been called
+   */
+  var registerTrackableElement = function(element, applyFunction) {
+    var registeredPropertyName = trackingPrefix + "_reg";
+    var registered = $(element).data(registeredPropertyName);
+
+    if (registered != null) {
+      return;
+    }
+
+    var theId = getOrCreateDomId(element);
+    var eventName = $(element).data(trackingPrefix + "_evt");
+    var eventProperties = $(element).data(trackingPrefix + "_prp");
+
+    if (! (eventName == null || eventName == "" || eventProperties == null)) {
+      applyFunction(theId, element, eventName, eventProperties);
+      <% if Rails.env.development? %>
+    } else {
+      $(element).data(registeredPropertyName, true);
+      throw "No Mixpanel event name or event properties on element that has class '." + trackingPrefix + "_trk', which tags it for tracking. Element: " + element;
+      <% end %>
+    }
+
+    $(element).data(registeredPropertyName, true);
+  };
+
+  /**
+   * Given a DOM element to start with and a function, finds all elements underneath that DOM element that have been
+   * enabled for auto-tracking (using #meta_events_tracking_attributes_for or #meta_events_tracked_link_to), and
+   * calls the given function on each one, in turn.
+   *
+   * The function will never be called twice for the same element (since the element is marked as having been passed to
+   * the function once it's done); this means that it's safe to call as often as you want -- for example, when the
+   * DOM changes.
+   *
+   * The function passed should accept the following parameters, in this order:
+   *    id - the DOM ID of the element; one will be generated for it and assigned to it if not already present
+   *    element - the element itself
+   *    eventName - the name of the event that this DOM element should fire
+   *    eventProperties - an object containing the properties that should be included with that event
+   *
+   * @param startingElement - The element under which we should search
+   * @param applyFunction - The function we should call on each element
+   */
+  out.forAllTrackableElements = function(startingElement, applyFunction) {
+    $(startingElement).find("." + trackingPrefix + "_trk").each(function(index, element) {
+      registerTrackableElement(element, applyFunction);
+    });
+  };
+
+  var events = { };
+
+  /**
+   * Called to register a frontend event that was defined server-side.
+   *
+   * @param name - The name that we'll use to access this event, using 'event', below; this is different from the name
+   *               of the actual event that will be fired and need not have any correlation;
+   * @param eventData - The data for the event; this must be an object containing 'event_name', which is the name of
+   *                    the event to fire, and 'properties', the set of properties to fire with that event.
+   */
+  out.registerFrontendEvent = function(name, eventData) {
+    events[name] = eventData;
+  };
+
+  /**
+   * Fires a frontend event. Accepts the name (alias) that we use to access the event, and zero or more objects; all
+   * properties of those objects are merged together (with later objects overriding earlier ones) and then merged into
+   * the properties the server told us to fire with the event (again, with our properties overriding it), and then the
+   * event is fired by calling the current handler function set by 'setEventHandler', below (which, by default, calls
+   * Mixpanel).
+   *
+   * @param eventAlias - The alias for the event to fire, which must match a call to registerFrontendEvent(), above;
+   *                     this is typically created by the +meta_events_frontend_events_javascript+ method in
+   *                     MetaEvents::Helpers that's called Rails-side to generate appropriate JavaScript code in the
+   *                     page somewhere.
+   */
+  out.event = function(eventAlias) {
+    var eventData = events[eventAlias];
+
+    if (eventData == null) {
+      <% if Rails.env.development? %>
+      throw "No front-end event has been registered named '" + name + "'. Did you forget to call meta_events_define_frontend_event on the server?";
+      <% end %>
+      return;
+    }
+
+    var effectiveProperties = { };
+    $.extend(effectiveProperties, eventData.properties);
+
+    for (var i = 1; i < arguments.length; ++i) {
+      $.extend(effectiveProperties, arguments[i]);
+    }
+
+    this.eventHandler(eventData.event_name, effectiveProperties);
+  };
+
+  /**
+   * The default event handler that we use if you haven't called setEventHandler(), below.
+   */
+  out.mixpanelEventHandler = function(eventName, properties) {
+    mixpanel.track(eventName, properties);
+  };
+
+  /**
+   * When a frontend event is fired, there's a function, at the bottom, that actually fires the event; it gets passed
+   * two parameters -- the name of the event, and properties to pass with it. By default, we use mixpanelEventHandler,
+   * above, which, well, calls Mixpanel. This function allows you to change that to any function you want, in case you
+   * want to do something different.
+   */
+  out.setEventHandler = function(eventHandler) {
+    this.eventHandler = eventHandler;
+  };
+
+  out.setEventHandler(out.mixpanelEventHandler);
+
+  return out;
+}());

metadata

@@ -0,0 +1,154 @@
+--- !ruby/object:Gem::Specification
+name: meta_events
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Andrew Geweke
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-02-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - <=
+      - !ruby/object:Gem::Version
+        version: 4.99.99
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - <=
+      - !ruby/object:Gem::Version
+        version: 4.99.99
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.14'
+description: 
+email:
+- ageweke@swiftype.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .travis.yml
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/meta_events.rb
+- lib/meta_events/controller_methods.rb
+- lib/meta_events/definition/category.rb
+- lib/meta_events/definition/definition_set.rb
+- lib/meta_events/definition/event.rb
+- lib/meta_events/definition/version.rb
+- lib/meta_events/engine.rb
+- lib/meta_events/helpers.rb
+- lib/meta_events/railtie.rb
+- lib/meta_events/test_receiver.rb
+- lib/meta_events/tracker.rb
+- lib/meta_events/version.rb
+- meta_events.gemspec
+- spec/meta_events/controller_methods_and_helpers_spec.rb
+- spec/meta_events/definition/category_spec.rb
+- spec/meta_events/definition/definition_set_spec.rb
+- spec/meta_events/definition/event_spec.rb
+- spec/meta_events/definition/version_spec.rb
+- spec/meta_events/tracker_spec.rb
+- vendor/assets/javascripts/meta_events.js.erb
+homepage: http://www.github.com/swiftype/meta_events
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.1
+signing_key: 
+specification_version: 4
+summary: Structured, documented, powerful event emitting library for Mixpanel and
+  other such systems.
+test_files:
+- spec/meta_events/controller_methods_and_helpers_spec.rb
+- spec/meta_events/definition/category_spec.rb
+- spec/meta_events/definition/definition_set_spec.rb
+- spec/meta_events/definition/event_spec.rb
+- spec/meta_events/definition/version_spec.rb
+- spec/meta_events/tracker_spec.rb
+has_rdoc: