gamifier 1.0.3

data/lib/gamifier/dsl/site.rb

@@ -0,0 +1,134 @@
+module Gamifier
+  module DSL
+    class Site
+      attr_reader :behaviors
+      attr_reader :units
+      attr_reader :rewards
+      attr_reader :missions
+      attr_reader :tracks
+      attr_reader :source
+
+      def initialize(*args)
+        @source = ::Gamifier::Site.new(*args)
+        @behaviors = []
+        @units = []
+        @rewards = []
+        @missions = []
+        @tracks = []
+      end
+
+      def engine
+        source.engine
+      end
+
+      def behavior(name, &block)
+        new_behavior = engine.activity_definitions.build(:name => name)
+        behaviors.push new_behavior
+
+        DSL.eval_with_context(new_behavior, &block)
+      end
+
+      def reward(name, &block)
+        new_reward = engine.reward_definitions.build(:name => name)
+        rewards.push new_reward
+
+        DSL.eval_with_context(new_reward, &block)
+      end
+
+      def unit(name, &block)
+        new_unit = engine.units.build(:name => name)
+        units.push new_unit
+
+        DSL.eval_with_context(new_unit, &block)
+      end
+
+      def mission(name, &block)
+        new_mission = engine.groups.build(:name => name)
+        missions.push new_mission
+
+        DSL.eval_with_context(new_mission, &block)
+      end
+
+      def track(name, &block)
+        new_track = engine.tracks.build(:label => name)
+        tracks.push new_track
+
+        DSL.eval_with_context(new_track, &block)
+      end
+
+      def save
+        if super
+          save_units!
+          save_behaviors!
+          save_rewards!
+          save_missions!
+          save_tracks!
+        else
+          raise Error, "Can't save #{self}"
+        end
+      end
+
+      def save_units!
+        units.each do |unit|
+          Gamifier.logger.info "Saving units..."
+          unit.site = self.url
+          if gunit = engine.send(unit.class.path).find_by_name(unit.name, :site => unit.site)
+            unit._id = gunit._id
+            # FIXME: once Badgeville returns the unit _id in the
+            # response, remove the next line:
+            next
+          end
+          unit.save || raise(Error, "Can't save #{unit}")
+        end
+      end
+
+      def save_behaviors!
+        behaviors.each do |behavior|
+          Gamifier.logger.info "Saving behaviors..."
+          behavior.site_id = self._id
+          if gbehavior = engine.send(behavior.class.path).find_by_name(behavior.name, :site => self.url)
+            behavior._id = gbehavior._id
+          end
+          behavior.save || raise(Error, "Can't save #{behavior}")
+        end
+      end
+
+      def save_rewards!
+        rewards.each do |reward|
+          Gamifier.logger.info "Saving rewards..."
+          reward.site_id = self._id
+          if greward = engine.send(reward.class.path).find_by_name(reward.name, :site => self.url)
+            reward._id = greward._id
+          end
+          reward.save || raise(Error, "Can't save #{reward}")
+        end
+      end
+
+      def save_missions!
+        missions.each do |mission|
+          Gamifier.logger.info "Saving missions..."
+          mission.site_id = self._id
+          if gmission = engine.send(mission.class.path).find_by_name(mission.name, :site => self.url)
+            mission._id = gmission._id
+          end
+          mission.save || raise(Error, "Can't save #{mission}")
+        end
+      end
+
+      def save_tracks!
+        tracks.each do |track|
+          Gamifier.logger.info "Saving tracks..."
+          track.site_id = self._id
+          if gtrack = engine.send(track.class.path).find_by_label(track.label, :site => self.url)
+            track._id = gtrack._id
+          end
+          track.save || raise(Error, "Can't save #{track}")
+        end
+      end
+
+      def method_missing(*args, &block)
+        source.send(*args, &block)
+      end
+    end
+  end
+end

data/lib/gamifier/dsl.rb

@@ -0,0 +1,24 @@
+require 'gamifier/dsl/network'
+require 'gamifier/dsl/site'
+
+module Gamifier
+  module DSL
+    class << self
+      def eval_with_context(new_context, &block)
+        new_context.extend DSL
+        if block
+          new_context.instance_eval(&block)
+        end
+        new_context
+      end
+    end
+    
+    def set(key, *args, &block)
+      if block
+        self.send("#{key}=".to_sym, block)
+      else
+        self.send("#{key}=".to_sym, *args)
+      end
+    end
+  end
+end

data/lib/gamifier/engine.rb

@@ -0,0 +1,84 @@
+require 'faraday'
+require 'gamifier/collection'
+require 'json'
+require 'rack/utils'
+
+module Gamifier
+  class Engine
+    MODELS = %w{Activity ActivityDefinition Group Player Reward RewardDefinition Site Track Unit User}
+
+    attr_accessor :connection
+    attr_writer :config
+
+    def initialize(opts = {})
+      opts.each{|k,v| config[k.to_sym] = v}
+      raise ArgumentError, "Please configure a :uri and :key first." unless ok?
+      @connection = Faraday::Connection.new(:url => uri_to) do |builder|
+        builder.use Faraday::Adapter::NetHttp     # make http requests with Net::HTTP
+      end
+    end
+
+    def config
+      @config ||= Gamifier.config.dup
+    end
+
+    def ok?
+      !config.values_at(:key, :uri).any?{|k| k.nil? || k.empty?}
+    end
+
+    # Sends an HTTP request corresponding to +method+, on +path+, with
+    # any options given in +opts+:
+    # +query+:: a hash of query parameters to pass with the request
+    # +head+:: a hash of HTTP headers to pass with the request
+    # +body+:: the body to send with the request. If you pass a Ruby
+    #          object, it will be automatically converted into
+    #          x-www-form-urlencoded by default.
+    def transmit(method, path, opts = {})
+      res = connection.send(method) do |req|
+        req.url [path, "json"].join("."), (opts[:query] || {})
+        (opts[:head] || {}).each do |k,v|
+          req.headers[k] = v
+        end
+        req.headers['Content-Type'] ||= 'application/x-www-form-urlencoded'
+        req.body = self.class.encode_www_form(opts[:body]) unless opts[:body].nil?
+        Gamifier.logger.debug "#{method.to_s.upcase} #{req.inspect}"
+      end
+      Gamifier.logger.debug "#{res.inspect}"
+      body = JSON.parse(res.body) rescue res.body
+      case res.status
+      when 204
+        true
+      when 200...300
+        body
+      when 404
+        nil
+      when 422
+        # Badgeville returns 422 when an entry already exists or is not valid
+        [:get, :head].include?(method) ? nil : false
+      when 400...500
+        raise HTTPClientError, body
+      when 500...600
+        raise HTTPServerError, body
+      else
+        raise HTTPError, body
+      end
+    end
+
+    def uri_to(path = "")
+      URI.join(File.join(::Gamifier.config[:uri], ::Gamifier.config[:key], ""), path)
+    end
+    
+    MODELS.each do |model|
+      underscored = Gamifier.underscore(model)
+      require "gamifier/models/#{underscored}"
+      klass = Gamifier.const_get(model)
+      define_method(klass.path.to_sym) do
+        Collection.new(self, klass)
+      end
+    end
+    
+    def self.encode_www_form(enum)
+      Rack::Utils.build_nested_query(enum)
+    end
+  end
+end

data/lib/gamifier/errors.rb

@@ -0,0 +1,6 @@
+module Gamifier
+  class Error < StandardError; end
+  class HTTPError < Error; end
+  class HTTPServerError < HTTPError; end
+  class HTTPClientError < HTTPError; end
+end

data/lib/gamifier/model.rb

@@ -0,0 +1,212 @@
+require 'ostruct'
+
+module Gamifier
+  class Model < OpenStruct
+    attr_writer :engine
+
+    # The engine to use when creating or updating records. Default to
+    # the global Gamifier engine if not set via <tt>#engine=</tt>
+    # method.
+    def engine
+      @engine ||= Gamifier.engine
+    end
+
+    def attributes; @table.dup; end
+
+    def save
+      new? ? create : update
+    end
+
+    # Allow to update only the specific attributes given in the +opts+ Hash.
+    def update_attributes(opts = {})
+      raise Error, "Can't update an object if it has not been saved yet" if new?
+      update(opts)
+    end
+
+    def payload_for_submission(opts = {})
+      attr_to_keep = opts.empty? ? attributes : opts
+
+      attr_to_keep = attr_to_keep.reject{|k,v|
+        self.class.special_attributes.include?(k.to_sym) || (
+          !self.class.mutable_attributes.empty? && !self.class.mutable_attributes.include?(k.to_sym)
+        )
+      }
+
+      # Nested hashes are dumped as JSON payload.
+      attr_to_keep.each do |k,v|
+        attr_to_keep[k] = encode(k.to_sym,v) || case v
+        when Hash
+          JSON.dump(v)
+        # Lazyloaded attributes
+        when Proc
+          v.call
+        else
+          v.to_s
+        end
+      end
+
+      h = { self.class.container => attr_to_keep }
+
+      self.class.special_attributes.each do |key|
+        h[key] = send(key)
+      end
+
+      h
+    end
+
+    # Overwrite in descendants to specifically encode a key/value pair.
+    def encode(key, value)
+      return nil
+    end
+
+    def _id
+      super || attributes[:id]
+    end
+
+    def destroy
+      return true if new?
+      engine.transmit :delete, path
+    end
+
+    def replace_if_successful(response)
+      if response.kind_of?(Hash)
+        response.each{|k,v| send("#{k}=".to_sym, v)}
+        self
+      else
+        response
+      end
+    end
+
+    # Returns true if the current object does not exist on the server.
+    def new?
+      self._id.nil?
+    end
+
+    def path
+      [self.class.path, self._id || "undefined"].join("/")
+    end
+
+    # To be included  as instance methods into the Collection class used
+    # to instantiate and find objects. Add more in descendants if you
+    # want to add more methods. See Gamifier::Player for an example.
+    module FinderMethods
+      # Fetch all the records according to the given query parameters.
+      # If a block is given, it will automatically lazy-load all the
+      # pages and yield each entry, until all the items have been
+      # loaded, or until the user returns from the block.
+      def all(params = {}, &block)
+        params[:page] ||= 1
+        params[:per_page] ||= 50
+        res = engine.transmit(:get, path, :query => params)
+        if res.kind_of?(Hash)
+          entries = res['data'].map{|h| build(h)}
+          if block
+            # Lazy load all the pages
+            entries.each{|entry| yield(entry)}
+            params[:page] += 1
+            all(params, &block) unless res['paging'].empty? || res['data'].empty?
+          end
+          entries
+        else
+          res
+        end
+      end
+
+      def find_by(key, value, params = {})
+        all(params) do |entry|
+          return entry if entry.respond_to?(key) && entry.send(key) == value.to_s
+        end
+        return nil
+      end
+
+      def find_by_name(name, params = {})
+        find_by(:name, name, params)
+      end
+
+      def find_by_label(label, params = {})
+        find_by(:label, label, params)
+      end
+
+      def find(key, params = {})
+        res = engine.transmit(:get, [path, key].join("/"), :query => params)
+        select_first_entry_if_any(res)
+      end
+
+      def find_or_create(key, params = {})
+        find(key, params) || build(params).save
+      end
+
+      protected
+      # Selects the first entry out of a data array, or out of a single
+      # data entry.
+      def select_first_entry_if_any(response)
+        if response.kind_of?(Hash) && response.has_key?('data')
+          entry = [response['data']].flatten[0]
+          return nil if entry.nil?
+          build(entry)
+        else
+          response
+        end
+      end
+    end
+
+    module ClassMethods
+      def reset!
+        @path = nil
+      end
+
+      # Sets or retrieve the path to use to access the resource on the
+      # remote server. By default the path will be the pluralized
+      # container name (naive pluralization: container+s).
+      def path(value = nil)
+        if value.nil?
+          @path ||= container+"s"
+        else
+          @path = value
+        end
+      end
+
+      # Declare attributes that must be submitted outside the default
+      # container.
+      def special_attributes *values
+        store_or_get("@special_attributes", values)
+      end
+
+      # Define the attributes that will be sent when creating or
+      # updating a model.
+      def mutable_attributes *values
+        store_or_get("@mutable_attributes", values)
+      end
+
+      def store_or_get(variable, values)
+        if values.empty?
+          v = instance_variable_get(variable)
+          v ||= []
+        else
+          instance_variable_set(variable, values.map{|v| v.to_sym})
+        end
+      end
+      # Returns the container to use when submitting data. E.g. when
+      # submitting user attributes as user[email]=xxx, the container is
+      # 'user'. Basically, this is the underscored class name.
+      def container
+        Gamifier.underscore(name)
+      end
+    end
+
+    extend ClassMethods
+
+    protected
+
+    def create
+      res = engine.transmit :post, self.class.path, :body => payload_for_submission
+      replace_if_successful(res)
+    end
+
+    def update(opts = {})
+      res = engine.transmit :put, path, :body => payload_for_submission(opts)
+      replace_if_successful(res)
+    end
+  end
+
+end

data/lib/gamifier/models/activity.rb

@@ -0,0 +1,8 @@
+require 'gamifier/model'
+
+module Gamifier
+  class Activity < Model
+    path "activities"
+    special_attributes :player_id, :site, :email
+  end
+end

data/lib/gamifier/models/activity_definition.rb

@@ -0,0 +1,6 @@
+require 'gamifier/model'
+
+module Gamifier
+  class ActivityDefinition < Model
+  end
+end

data/lib/gamifier/models/group.rb

@@ -0,0 +1,6 @@
+require 'gamifier/model'
+
+module Gamifier
+  class Group < Model
+  end
+end

data/lib/gamifier/models/player.rb

@@ -0,0 +1,20 @@
+require 'gamifier/model'
+
+module Gamifier
+  class Player < Model
+
+    special_attributes :email, :site
+    mutable_attributes :first_name, :last_name, :nickname, :display_name, :picture_url, :admin
+
+    module FinderMethods
+      def find_by_site_and_email(site, email, params = {})
+        res = engine.transmit(:get, path, :query => params.merge({:site => site, :email => email}))
+        select_first_entry_if_any(res)
+      end
+    end
+
+    def credit(verb, metadata = {})
+      engine.activities.build(metadata.merge({:player_id => _id, :verb => verb})).save
+    end
+  end
+end

data/lib/gamifier/models/reward.rb

@@ -0,0 +1,6 @@
+require 'gamifier/model'
+
+module Gamifier
+  class Reward < Model
+  end
+end

data/lib/gamifier/models/reward_definition.rb

@@ -0,0 +1,14 @@
+require 'gamifier/model'
+
+module Gamifier
+  class RewardDefinition < Model
+    def encode(key, value)
+      case key
+      when :components
+        JSON.dump(value)
+      else
+        super(key,value)
+      end
+    end
+  end
+end

data/lib/gamifier/models/site.rb

@@ -0,0 +1,6 @@
+require 'gamifier/model'
+
+module Gamifier
+  class Site < Model
+  end
+end

data/lib/gamifier/models/track.rb

@@ -0,0 +1,6 @@
+require 'gamifier/model'
+
+module Gamifier
+  class Track < Model
+  end
+end

data/lib/gamifier/models/unit.rb

@@ -0,0 +1,16 @@
+require 'gamifier/model'
+
+module Gamifier
+  class Unit < Model
+    special_attributes :site, :type
+    mutable_attributes :name, :label, :abbreviation
+
+    def initialize(*args)
+      super
+    end
+
+    def type
+      "point"
+    end
+  end
+end

data/lib/gamifier/models/user.rb

@@ -0,0 +1,6 @@
+require 'gamifier/model'
+
+module Gamifier
+  class User < Model
+  end
+end

data/lib/gamifier/version.rb

@@ -0,0 +1,3 @@
+module Gamifier
+  VERSION = "1.0.3" unless defined?(Gamifier::VERSION)
+end

data/lib/gamifier.rb

@@ -0,0 +1,76 @@
+require 'logger'
+require "gamifier/version"
+require 'gamifier/errors'
+
+module Gamifier
+  class << self
+    attr_writer :logger
+
+    # Sets a configuration option. The keys will be symbolized.
+    def set(key, opts = nil)
+      if opts.nil?
+        key.each do |k,v|
+          config[k.to_sym] = v
+        end
+      else
+        config[key.to_sym] = opts
+      end
+    end
+
+    # Returns the configuration Hash.
+    def config
+      @config ||= {}
+    end
+
+    # Returns the global Engine. If you need multiple engine with
+    # different API keys and/or URIs, you should create a new engine
+    # directly with Gamifier::Engine.new
+    def engine(&block)
+      @engine ||= Engine.new
+      block.call(@engine) if block
+      @engine
+    end
+
+    # Creates and returns a new DSL::Network object. The given block
+    # will be evaluated in the context of the network object.
+    # 
+    # Usage:
+    # 
+    #   network = Gamifier.dsl do
+    #     site 'my-site' do
+    #       set :url, 'my-site.com'
+    #       ...
+    #     end
+    #   end
+    def dsl(&block)
+      network = DSL::Network.new
+      network.instance_eval(&block)
+      network
+    end
+
+    def logger
+      @logger ||= begin
+        l = Logger.new(STDERR)
+        l.level = Logger::WARN
+        l
+      end
+    end
+
+    def reset!
+      @engine = nil
+      config.clear
+    end
+
+    def underscore(camel_cased_word)
+      camel_cased_word.to_s.gsub(/::/, '/').
+        gsub("Gamifier/", '').
+        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+        gsub(/([a-z\d])([A-Z])/,'\1_\2').
+        tr("-", "_").
+        downcase
+    end
+  end
+end
+
+require 'gamifier/engine'
+require 'gamifier/dsl'