meta_events 1.0.1

data/lib/meta_events/controller_methods.rb

@@ -0,0 +1,43 @@
+require 'active_support'
+
+module MetaEvents
+  # This module defines methods that we add to ActionController::Base if we're being used with Rails.
+  module ControllerMethods
+    # We use this for the #included block, below.
+    extend ActiveSupport::Concern
+
+    # Declares a new "frontend event". A frontend event is, at its core, a binding from a name to (an event name,
+    # a set of properties to fire with that event); by default, the name used is just the event name, without its
+    # normal prefix (_i.e._, +foo_bar+, not +ab1_foo_bar+).
+    #
+    # You declare the frontend event here, on the server side; the server renders into the page this very binding,
+    # and the frontend JavaScript (+meta_events.js.erb+) can pick up that data and expose it by very easy-to-use
+    # JavaScript functions.
+    #
+    # +category+ is the category for your event;
+    def meta_events_define_frontend_event(category, event, properties = { }, options = { })
+      options.assert_valid_keys(:name, :tracker)
+
+      name = (options[:name] || "#{category}_#{event}").to_s
+      tracker = options[:tracker] || meta_events_tracker
+
+      @_meta_events_registered_clientside_events ||= { }
+      @_meta_events_registered_clientside_events[name] = tracker.effective_properties(category, event, properties)
+    end
+
+    # Returns the set of defined frontend events.
+    def meta_events_defined_frontend_events
+      @_meta_events_registered_clientside_events || { }
+    end
+
+    def meta_events_tracker
+      raise "You must implement the method #meta_events_tracker on your controllers for this method to work; it should return the MetaEvents::Tracker instance (ideally, cached, using just something like @tracker ||=) that you want to use."
+    end
+
+    # When we get included into a controller, declare these methods as helper methods, so they're available to views,
+    # too.
+    included do
+      helper_method :meta_events_define_frontend_event, :meta_events_defined_frontend_events, :meta_events_tracker
+    end
+  end
+end

data/lib/meta_events/definition/category.rb

@@ -0,0 +1,78 @@
+require "meta_events"
+require "meta_events/definition/event"
+require "active_support/core_ext"
+
+module MetaEvents
+  module Definition
+    # A Category is the middle level of hierarchy in the MetaEvents DSL. Child of a Version and parent of an Event, it
+    # groups together a set of Events that logically belong together. Programmatically, it serves no purpose other than
+    # to group together related events, so that the namespace of events doesn't get enormous.
+    #
+    class Category
+      class << self
+        # Normalizes the name of a category, so that we don't run into crazy Symbol-vs.-String bugs.
+        def normalize_name(name)
+          raise ArgumentError, "Must supply a name for a category, not: #{name.inspect}" if name.blank?
+          name.to_s.strip.downcase.to_sym
+        end
+      end
+
+      attr_reader :version, :name
+
+      # Creates a new instance. +version+ must be the ::MetaEvents::Definition::Version to which this Category should belong;
+      # +name+ is the name of the category. +options+ can contain:
+      #
+      # [:retired_at] If passed, this must be a String that can be parsed by Time.parse; it indicates the time at which
+      #               this category was retired, meaning that it no longer can be used to fire events. (The code does
+      #               not actually care about the value of this Time; that's used only for record-keeping purposes --
+      #               rather, it's used simply as a flag indicating that the category has been retired, and events in
+      #               it should no longer be allowed to be fired.)
+      #
+      # The block passed to this constructor is evaluated in the context of this object; this is how we build our
+      # DSL.
+      def initialize(version, name, options = { }, &block)
+        raise ArgumentError, "You must pass a Version, not: #{version.inspect}" unless version.kind_of?(::MetaEvents::Definition::Version)
+
+        @version = version
+        @name = self.class.normalize_name(name)
+        @events = { }
+
+        options.assert_valid_keys(:retired_at)
+
+        @retired_at = Time.parse(options[:retired_at]) if options[:retired_at]
+
+        instance_eval(&block) if block
+      end
+
+      # Declares a new event. +name+ is the name of the event; all additional arguments are passed to the constructor
+      # of ::MetaEvents::Definition::Event. It is an error to try to define two events with the same name.
+      def event(name, *args, &block)
+        event = ::MetaEvents::Definition::Event.new(self, name, *args, &block)
+        raise ArgumentError, "Category #{self.name.inspect} already has an event named #{event.name.inspect}" if @events[event.name]
+        @events[event.name] = event
+      end
+
+      # Returns the full prefix that events of this Category should use.
+      def prefix
+        "#{version.prefix}#{name}_"
+      end
+
+      # Retrieves an event with the given name; raises +ArgumentError+ if there is no such event.
+      def event_named(name)
+        name = ::MetaEvents::Definition::Event.normalize_name(name)
+        @events[name] || raise(ArgumentError, "#{self} has no event named #{name.inspect}; it has: #{@events.keys.sort_by(&:to_s).inspect}")
+      end
+
+      # Returns the effective time at which this category was retired, or +nil+ if it is not retired. This is the
+      # earliest of the time at which this category was retired and the time at which the version was retired.
+      def retired_at
+        [ @retired_at, version.retired_at ].compact.min
+      end
+
+      # Override #to_s, for a cleaner view.
+      def to_s
+        "<Category #{name.inspect} of #{version}>"
+      end
+    end
+  end
+end

data/lib/meta_events/definition/definition_set.rb

@@ -0,0 +1,122 @@
+require "meta_events"
+require "meta_events/definition/version"
+
+module MetaEvents
+  module Definition
+    # A DefinitionSet is the root of the MetaEvents DSL. Generally speaking, any application will have exactly one
+    # DefinitionSet, which contains the definition of every event it currently or has ever fired.
+    #
+    # The only reason a DefinitionSet is not a singleton object (or just class methods) is that it is extremely
+    # useful for testing to be able to use a separate DefinitionSet.
+    #
+    # A single DefinitionSet has a +global_events_prefix+, which is prepended to every event fired. This can be used
+    # to easily distinguish events that come through this system from events before it was introduced, or versus events
+    # fired by some other system entirely.
+    class DefinitionSet
+      class BaseError < StandardError; end
+      class RetiredEventError < BaseError; end
+
+      class << self
+        # Creates an MetaEvents::Definition::DefinitionSet. +source+ can be one of:
+        #
+        # * An MetaEvents::Definition::DefinitionSet; we simply return it. This can seem a little redundant (and it is), but
+        #   it helps us write much cleaner code in other classes (like MetaEvents::Tracker).
+        # * An IO (or StringIO, which doesn't actually inherit from IO but effectively is one); or
+        # * A path to a File.
+        #
+        # In both of the last two cases, we interpret the contents of the file as Ruby code in the context of the new
+        # DefinitionSet -- in other words, it should look something like:
+        #
+        #     global_events_prefix :mp
+        #
+        #     version 1, '2014-01-01' do
+        #       category :foo do
+        #         event :bar, '2014-01-16', 'this is great'
+        #       end
+        #     end
+        def from(source)
+          source = new(:definition_text => source) unless source.kind_of?(self)
+          source
+        end
+      end
+
+      # Creates a new instance. +global_events_prefix+ must be a String or Symbol; it will be prepended to the name
+      # of every event fired. You can pass the empty string if you want.
+      #
+      # The block passed to this constructor is evaluated in the context of this object; this is how we build our
+      # DSL.
+      def initialize(options = { }, &block)
+        @global_events_prefix = nil
+        @versions = { }
+
+        options.assert_valid_keys(:global_events_prefix, :definition_text)
+
+        global_events_prefix options[:global_events_prefix] if options[:global_events_prefix]
+
+        @source_description = "passed-in data/block"
+
+        if (source = options[:definition_text])
+          if source.kind_of?(String)
+            File.open(File.expand_path(source)) { |f| read_from(f) }
+          else
+            read_from(source)
+          end
+        end
+
+        instance_eval(&block) if block
+
+        if global_events_prefix.blank?
+          raise ArgumentError, "When reading events from #{@source_description}: you must declare a global_events_prefix, or else pass one to the constructor"
+        end
+      end
+
+      # Sets the +global_events_prefix+ -- the string that will be prepended (with the version) to every single
+      # event fired through this DefinitionSet.
+      def global_events_prefix(prefix = nil)
+        if prefix
+          @global_events_prefix = prefix.to_s
+        else
+          @global_events_prefix
+        end
+      end
+
+      # Declares a new version. The +number+ is required and must be unique. For +introduced+ and +options+, see the
+      # constructor of ::MetaEvents::Definition::Version.
+      #
+      # The block passed is evaluated in the context of the new Version; this is how we build our DSL.
+      def version(number, introduced, options = { }, &block)
+        version = ::MetaEvents::Definition::Version.new(self, number, introduced, options, &block)
+        raise "There is already a version #{version.number.inspect}" if @versions[version.number]
+        @versions[version.number] = version
+      end
+
+      # Returns the Version object for the given number, or raises an exception if there is none.
+      def fetch_version(number)
+        @versions[number] || raise(ArgumentError, "No such version #{number.inspect}; I have: #{@versions.keys.sort_by(&:to_s).inspect}")
+      end
+
+      # Fetches an ::MetaEvents::Definition::Event object directly, by version number, category, and event.
+      def fetch_event(version_num, category_name, event_name)
+        fetch_version(version_num).fetch_event(category_name, event_name)
+      end
+
+      private
+      def read_from(source)
+        # StringIO is, really annoyingly, *not* an actual subclass of IO.
+        raise ArgumentError, "Invalid source: #{source.inspect}" unless source.kind_of?(IO) || source.kind_of?(StringIO)
+        args = [ source.read ]
+
+        if source.respond_to?(:path) && source.respond_to?(:lineno) && source.path && source.lineno
+          args += [ source.path, source.lineno ]
+          @source_description = "#{source.path}:#{source.lineno}"
+        end
+
+        begin
+          instance_eval(*args)
+        rescue Exception => e
+          raise "When reading event definitions from #{@source_description}, we got an exception: (#{e.class.name}) #{e.message}\n    #{e.backtrace.join("\n    ")}"
+        end
+      end
+    end
+  end
+end

data/lib/meta_events/definition/event.rb

@@ -0,0 +1,163 @@
+require "meta_events"
+
+# An ::MetaEvents::Definition::Event is the lowest level of the MetaEvents DSL. It belongs to a Category (which, in turn,
+# belongs to a Version), and should represent a single, consistent "thing that happened" that you want to track.
+# The name of an Event must be unique within its Category and Version.
+#
+# The definition of "single, consistent" depends very much on your context and the scope of what you're tracking,
+# and will require significant judgement calls. For example, if your event is +:signup+ (in category +:user+), and
+# you change from a lengthy, complex, demanding signup process to Facebook signup -- with an optional form of all the
+# lengthy information later -- is that the same event? It depends greatly on how you think of it; you could keep it
+# the same event, or introduce a new +:simple_signup+ event -- it depends on how you want to track it.
+module MetaEvents
+  module Definition
+    class Event
+      attr_reader :category, :name
+
+      class << self
+        # Normalizes the name of an Event, so that we don't run into crazy Symbol-vs.-String bugs.
+        def normalize_name(name)
+          raise ArgumentError, "Must supply a name for an event, not: #{name.inspect}" if name.blank?
+          name.to_s.strip.downcase.to_sym
+        end
+      end
+
+      # Creates a new instance. +category+ must be the ::MetaEvents::Definition::Category that this event is part of; +name+
+      # must be the name of the event.
+      #
+      # In order to create a new instance, you must also supply a description for the instance and indicate when it was
+      # introduced; this is part of the required record-keeping that makes the MetaEvents DSL useful. You can do this in one
+      # of several ways (expressed as it would look in the DSL):
+      #
+      #    category :user do
+      #      event :signup, "2014-01-01", "a new user we've never heard of before signs up"
+      #    end
+      #
+      # or:
+      #
+      #    category :user do
+      #      event :signup, :introduced => "2014-01-01", :desc => "a new user we've never heard of before signs up"
+      #    end
+      #
+      # or:
+      #
+      #    category :user do
+      #      event :signup do
+      #        introduced "2014-01-01"
+      #        desc "a new user we've never heard of before signs up"
+      #      end
+      #    end
+      #
+      # You can also combine these in any way you want; what's important is just that they get set, or else you'll get an
+      # exception at definition time.
+      def initialize(category, name, *args, &block)
+        raise ArgumentError, "Must supply a Category, not #{category.inspect}" unless category.kind_of?(::MetaEvents::Definition::Category)
+
+        @category = category
+        @name = self.class.normalize_name(name)
+        @notes = [ ]
+
+        apply_options!(args.extract_options!)
+        args = apply_args!(args)
+
+        raise ArgumentError, "Too many arguments: don't know what to do with #{args.inspect}" if args.present?
+
+        instance_eval(&block) if block
+
+        ensure_complete!
+      end
+
+      # Given a set of properties, validates this event -- that is, either returns without doing anything if everything is
+      # OK, or raises an exception if the event should not be allowed to be fired. Currently, all we do is fail if the
+      # event has been retired (directly, or via its Category or Version); however, this could easily be extended to
+      # provide for required properties, property validation, or anything else.
+      def validate!(properties)
+        if retired_at
+          raise ::MetaEvents::Definition::DefinitionSet::RetiredEventError, "Event #{full_name} was retired at #{retired_at.inspect} (or its category or version was); you can't use it any longer."
+        end
+      end
+
+      # Returns, or sets, the description for an event.
+      def desc(text = nil)
+        @description = text if text
+        @description
+      end
+
+      # Returns, or sets, the introduced-at time for an event.
+      def introduced(time = nil)
+        @introduced = Time.parse(time) if time
+        @introduced
+      end
+
+      # Returns the name of the category for an event.
+      def category_name
+        category.name
+      end
+
+      # Returns the full name of an event, including all prefixes.
+      def full_name
+        "#{category.prefix}#{name}"
+      end
+
+      # Returns the time at which this event has been retired, if any -- this is the earliest time from its category
+      # (which, in turn, is the earliest of the category and the version), and this event. If an event has been retired,
+      # then #validate! will fail.
+      def retired_at(value = nil)
+        @retired_at = Time.parse(value) if value
+        [ @retired_at, category.retired_at ].compact.min
+      end
+
+      # Adds a note to this event. Notes are simply metadata right now -- useful for indicating what the history of an
+      # event is, significant changes in its meaning, and so on.
+      def note(when_left, who, text)
+        raise ArgumentError, "You must specify when this note was left" if when_left.blank?
+        when_left = Time.parse(when_left)
+        raise ArgumentError, "You must specify who left this note" if who.blank?
+        raise ArgumentError, "You must specify an actual note" if text.blank?
+
+        @notes << { :when_left => when_left, :who => who, :text => text }
+      end
+
+      # Returns all notes associated with this event, as an array of Hashes.
+      def notes
+        @notes
+      end
+
+      # Override for clearer data.
+      def to_s
+        "<Event #{name.inspect} of #{category}>"
+      end
+
+      private
+      # Called at the very end of the constructor, to ensure that you have declared all required properties for this
+      # event.
+      def ensure_complete!
+        raise ArgumentError, "You must specify a description for event #{full_name}, either as an argument, in the options, or using 'desc'" if @description.blank?
+        raise ArgumentError, "You must record when you introduced event #{full_name}, either as an argument, in the options, or using 'introduced'" if (! @introduced)
+      end
+
+      # Called with the set of options (which can be empty) supplied in the constructor; responsible for applying those
+      # to the object properly.
+      def apply_options!(options)
+        options.assert_valid_keys(:introduced, :desc, :description, :retired_at)
+
+        introduced options[:introduced] if options[:introduced]
+        desc options[:desc] if options[:desc]
+        desc options[:description] if options[:description]
+
+
+        @retired_at = Time.parse(options[:retired_at]) if options[:retired_at]
+      end
+
+      # Called with the arguments (past the category and event name) supplied to the constructor; responsible for
+      # applying those to the object properly.
+      def apply_args!(args)
+        intro = args.shift
+        d = args.shift
+        introduced intro if intro
+        desc d if d
+        args
+      end
+    end
+  end
+end

data/lib/meta_events/definition/version.rb

@@ -0,0 +1,89 @@
+require "meta_events"
+require "meta_events/definition/category"
+
+module MetaEvents
+  module Definition
+    # A Version is the common top level of hierarchy in the MetaEvents DSL. A Version represents a version of your
+    # application's _entire_ event hierarchy -- that is, you should create a new Version if (and only if) you decide
+    # to rearrange major parts of, or all of, your event hierarchy. (This is something that, in my experience, happens
+    # more often than you'd imagine. ;)
+    #
+    # A Version belongs to a DefinitionSet; it has a +number+, which is just an integer (that you'll probably be
+    # happier with if you make sequential, but no such requirement is imposed), the date (and possibly time) that it
+    # was introduced (for record-keeping purposes). Additionally, you can mark a version as _retired_, which means that
+    # it is still accessible for record-keeping purposes but will not allow any of its events to actually be fired.
+    class Version
+      attr_reader :definition_set, :number, :introduced
+
+      # Creates a new instance. +definition_set+ is the MetaEvents::Definition::DefinitionSet to which this Version belongs;
+      # +number+ is an integer telling you, well, which version this is -- it must be unique within the DefinitionSet.
+      # +introduced+ is a String that must be parseable using Time.parse; this should be the date (and time, if you
+      # really want to be precise) that the Version was first used, for record-keeping purposes.
+      #
+      # Currently, +options+ can contain:
+      #
+      # [:retired_at] If present, must be a String representing a date and/or time (as parseable by Time.parse); its
+      #               presence indicates that this version is _retired_, meaning that you will not be allowed to fire
+      #               events from this version. (The date and time itself is present for record-keeping purposes.)
+      #               Set this if (and only if) this version should no longer be in use, presumably because it has
+      #               been superseded by another version.
+      #
+      # Note that neither the introduction time nor retired-at time are actually compared with +Time.now+ in any way;
+      # the introduction time is not used in the event mechanism at all, and the +retired_at+ time is treated as a
+      # simple boolean flag (if present, you can't fire events from this version).
+      #
+      # The block passed to this constructor is evaluated in the context of this object; this is how we build our
+      # DSL.
+      def initialize(definition_set, number, introduced, options = { }, &block)
+        raise ArgumentError, "You must pass a DefinitionSet, not #{definition_set.inspect}" unless definition_set.kind_of?(::MetaEvents::Definition::DefinitionSet)
+        raise ArgumentError, "You must pass a version, not #{number.inspect}" unless number.kind_of?(Integer)
+
+        @definition_set = definition_set
+        @number = number
+        @introduced = Time.parse(introduced)
+        @categories = { }
+
+        options.assert_valid_keys(:retired_at)
+
+        @retired_at = Time.parse(options[:retired_at]) if options[:retired_at]
+
+        instance_eval(&block) if block
+      end
+
+      # Returns the prefix that all events in this version should have -- something like "st1", for example.
+      def prefix
+        "#{definition_set.global_events_prefix}#{number}_"
+      end
+
+      # Declares a category within this version; this is part of our DSL. See the constructor of
+      # ::MetaEvents::Definition::Category for more information about the arguments.
+      def category(name, options = { }, &block)
+        category = ::MetaEvents::Definition::Category.new(self, name, options, &block)
+        raise ArgumentError, "There is already a category named #{name.inspect}" if @categories[category.name]
+        @categories[category.name] = category
+      end
+
+      # Returns the Category with the given name, or raises ArgumentError if there is no such category.
+      def category_named(name)
+        name = ::MetaEvents::Definition::Category.normalize_name(name)
+        @categories[name] || raise(ArgumentError, "#{self} has no category #{name.inspect}; it has: #{@categories.keys.sort_by(&:to_s).inspect}")
+      end
+
+      # Returns the ::MetaEvents::Definition::Event object for the given category and event name, or raises
+      # ArgumentError if no such category or event exists.
+      def fetch_event(category_name, event_name)
+        category_named(category_name).event_named(event_name)
+      end
+
+      # Returns the Time at which this version was retired, or +nil+ if it is still active.
+      def retired_at
+        @retired_at
+      end
+
+      # Override #to_s, for a cleaner view.
+      def to_s
+        "<Version #{number}>"
+      end
+    end
+  end
+end

data/lib/meta_events/engine.rb

@@ -0,0 +1,6 @@
+require 'rails'
+
+module MetaEvents
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/meta_events/helpers.rb

@@ -0,0 +1,114 @@
+require 'json'
+
+module MetaEvents
+  # This module gets included as a Rails helper module, if Rails is available. It defines methods that are usable
+  # by views to do tracking from the front-end -- both auto-tracking and frontend events.
+  module Helpers
+    class << self
+      # Defines (or returns) the prefix we use for our class and data attributes; this just needs to be unique enough
+      # that we are highly unlikely to collide with any other attributes.
+      def meta_events_javascript_tracking_prefix(prefix = nil)
+        if prefix == nil
+          @_meta_events_javascript_tracking_prefix
+        else
+          if (prefix.kind_of?(String) || prefix.kind_of?(Symbol)) && prefix.to_s.strip.length > 0
+            @_meta_events_javascript_tracking_prefix = prefix.to_s.strip
+            @_meta_events_javascript_tracking_prefix = $1 if @_meta_events_javascript_tracking_prefix =~ /^([^_]+)_+$/i
+          else
+            raise ArgumentError, "Must supply a String or Symbol, not: #{prefix.inspect}"
+          end
+        end
+      end
+    end
+
+    # The default prefix we use.
+    meta_events_javascript_tracking_prefix "mejtp"
+
+    # PRIVATE (though there's no point to declaring something private in a helper; everything's being called from the
+    # same object anyway). Simply prepends our prefix, plus an underscore, to whatever's passed in.
+    def meta_events_prefix_attribute(name)
+      "#{MetaEvents::Helpers.meta_events_javascript_tracking_prefix}_#{name}"
+    end
+
+    # Given a Hash of attributes for an element -- and, optionally, a MetaEvents::Tracker instance to use; we default
+    # to using the one exposed by the +meta_events_tracker+ method -- extracts a +:meta_event+ property, if present,
+    # and turns it into exactly the attributes that +meta_events.js.erb+ can use to detect that this is an element
+    # we want to track (and thus correctly return it from its +forAllTrackableElements+ method). If no +:meta_event+
+    # key is present on the incoming set of attributes, simply returns exactly its input.
+    #
+    # The +:meta_event+ property must be a Hash, containing:
+    #
+    # [:category] The name of the category of the event;
+    # [:event] The name of the event within the category;
+    # [:properties] Any additional properties to fire with the event; this is optional.
+    def meta_events_tracking_attributes_for(input_attributes, event_tracker = meta_events_tracker)
+      # See if we've even got an event...
+      return input_attributes unless input_attributes && (input_attributes[:meta_event] || input_attributes['meta_event'])
+
+      # If so, let's start populating our set of output attributes.
+      # #with_indifferent_access dups the Hash even if it already has indifferent access, which is important here
+      output_attributes = input_attributes.with_indifferent_access
+      event_data = output_attributes.delete(:meta_event)
+
+      # A little error-checking...
+      unless event_data.kind_of?(Hash)
+        raise ArgumentError, ":meta_event must be a Hash, not: #{event_data.inspect}"
+      end
+
+      event_data.assert_valid_keys(%w{category event properties})
+
+      # Grab our event data...
+      category = event_data[:category]
+      event = event_data[:event]
+      properties = event_data[:properties] || { }
+
+      unless category && event
+        raise ArgumentError, "You must supply :category and :event in your :meta_event attributes, not: #{event_data.inspect}"
+      end
+
+      # Ask the Tracker to compute the set of properties we should be firing with this event...
+      props_data = event_tracker.effective_properties(category, event, properties)
+
+      # Add our class to the +:class+ attribute -- Rails supports declaring +:class+ as an Array, and so we'll use
+      # that here. It works fine even if +:class+ is a string of space-separated class names.
+      classes = Array(output_attributes.delete(:class) || [ ])
+      classes << meta_events_prefix_attribute("trk")
+      output_attributes[:class] = classes
+
+      # Set the data attributes we'll be looking for...
+      output_attributes["data-#{meta_events_prefix_attribute('evt')}"] = props_data[:event_name]
+      output_attributes["data-#{meta_events_prefix_attribute('prp')}"] = props_data[:properties].to_json
+
+      # And we're done!
+      output_attributes
+    end
+
+    # This works exactly like Rails' built-in +link_to+ method, except that it takes a +:meta_event+ property in
+    # +html_options+ and turns the link into a tracked link, using #meta_events_tracking_attributes_for, above.
+    #
+    # The +:meta_event+ property is actually required; this is because, presumably, you're calling this method exactly
+    # because you want to track something, and if you didn't pass +:meta_event+, you probably misspelled or forgot
+    # about it.
+    #
+    # Obviously, feel free to create a shorter alias for this method in your application; we give it a long, unique
+    # name here so that we don't accidentally collide with another helper method in your project.
+    def meta_events_tracked_link_to(name = nil, options = nil, html_options = nil, &block)
+      unless html_options && html_options[:meta_event]
+        raise ArgumentError, "You asked for a tracked link, but you didn't provide a :meta_event: #{html_options.inspect}"
+      end
+
+      link_to(name, options, meta_events_tracking_attributes_for(html_options, meta_events_tracker), &block)
+    end
+
+
+    # Returns a JavaScript string that, when placed on a page into which +meta_events.js.erb+ has been included, sets
+    # up all defined front-end events so that they can be fired by that JavaScript.
+    def meta_events_frontend_events_javascript
+      out = ""
+      (meta_events_defined_frontend_events || { }).each do |name, properties|
+        out << "MetaEvents.registerFrontendEvent(#{name.to_json}, #{properties.to_json});\n"
+      end
+      out.html_safe
+    end
+  end
+end

data/lib/meta_events/railtie.rb

@@ -0,0 +1,29 @@
+module MetaEvents
+  class Railtie < Rails::Railtie
+    def say(x)
+      ::Rails.logger.info "MetaEvents: #{x}"
+    end
+
+    initializer "meta_events.configure_rails_initialization" do
+      ::ActiveSupport.on_load(:action_view) do
+        include ::MetaEvents::Helpers
+      end
+
+      ::ActiveSupport.on_load(:action_controller) do
+        include ::MetaEvents::ControllerMethods
+      end
+
+      return if ::MetaEvents::Tracker.default_definitions
+
+      config_meta_events = File.expand_path(File.join(::Rails.root, 'config', 'meta_events.rb'))
+      if File.exist?(config_meta_events)
+        ::MetaEvents::Tracker.default_definitions = config_meta_events
+        say "Loaded event definitions from #{config_meta_events.inspect}"
+
+        if defined?(::Spring)
+          Spring.watch config_meta_events
+        end
+      end
+    end
+  end
+end