adhonorem 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9f326114945fed6499e4985c361ccea8375f8116
-  data.tar.gz: c2b90be5a62154750813b7d03fad2406040ad3bd
+  metadata.gz: e7e951e1aa1ee4f829618f394cf7f709a3b8ef33
+  data.tar.gz: 477be5b21e10e849b473903ca9ffff9500aa719a
 SHA512:
-  metadata.gz: 685fc34c29a634a9685728168c89344d63f6bf88b555f78fcdbea9460183ca1fb190e33096c76fa5800ca79dd209a647f526ce85d8b7b63ca7e8118e6085b079
-  data.tar.gz: d6e57fceb122c8e2557ce35b8c4bc5b32bcfa8897c0102f3b792d2bd252c95e071ed58add556b46cb3211df585612902bedccb64d79be84577e91a6bab080c80
+  metadata.gz: e4a7b733539dd2b5ae32059d5f6c8183bcb38cf2794cc6619220f7d8a3b5d6ad3628897ed2c8e2cced4256d6f45f7d3aea7ae923ba6cecf9359ccbf96d4e33db
+  data.tar.gz: bec3c2836d0f394d3c77f5e6f25de0ce84ca05fd9db4101df39686be963af44a282c26c2d0326be322f4d57a419ab7eacbc2b9fab35095b760444bc486f8cda1

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright 2016 Hugo Chevalier
+Copyright 2017 Hugo Chevalier
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -1,6 +1,227 @@
 = AdHonorem
 
-1. Ensure you have a User model (name as you want)
-2. rails g adhonorem:initializer
-2. rails g adhonorem:migrations
-3. rake db:migrate
+{<img src="https://badge.fury.io/rb/adhonorem.svg" alt="Gem Version" />}[https://badge.fury.io/rb/adhonorem] {<img src="https://codeclimate.com/github/hchevalier/adhonorem/badges/gpa.svg" />}[https://codeclimate.com/github/hchevalier/adhonorem] {<img src="https://codeclimate.com/github/hchevalier/adhonorem/badges/coverage.svg" />}[https://codeclimate.com/github/hchevalier/adhonorem/coverage] {<img src="https://travis-ci.org/hchevalier/adhonorem.svg?branch=master" alt="Build Status" />}[https://travis-ci.org/hchevalier/adhonorem]
+
+AdHonorem assumes that you want to manage the gamification of your Rails application code-side, using Ruby files to represent your badges rather than depending on entries stored in a database.
+
+This way, your badges are never to be altered by error, can be under revision control and, most of all, can be covered by your tests suite before they are deployed.
+
+== Installation
+
+Add this to your Gemfile:
+
+  gem 'adhonorem'
+
+and run the bundle install command.
+
+Ensure you already have an ActiveRecord model representing your users before executing the following commands:
+
+  # Generate initializer with AdHonorem settings
+  rails g adhonorem:initializer
+
+  # Generate migrations for progress-tracking and achievement ActiveRecord models
+  rails g adhonorem:migrations
+
+  # Execute the migrations
+  rake db:migrate
+
+=== How to use
+
+==== The base class
+
+AdHonorem::Badge is the main class that your own badges will have to inherit from.
+
+It uses static-record gem to provide an ActiveRecord-like query interface allowing you to query over the filesystem Ruby files. For the moment, no path setting is possible and your badge files are expected to be saved under /app/models/badges/ folder. You can create subfolders if you want.
+
+Documentation for static-record's query interface can be found here: https://github.com/hchevalier/static_record
+
+==== Your badge files
+
+A simple badge file looks like this:
+
+  class SimpleBadge < AdHonorem::Badge
+    # The slug allows to reference the badge and must be unique
+    attribute :slug,          'simple_badge'
+    # The following attributes can be displayed to your users when needed
+    attribute :name,          'Simple badge'
+    attribute :description,   'This is a simple badge'
+    attribute :category,      'General'
+    # Point are not used yet.
+    # In a near future, a migration will add a new column to your users table and grant them points
+    attribute :points,        10
+    # The following attributes can be displayed to your users when needed
+    attribute :icon_locked,   Rails.root.join('public', 'badges', 'locked', 'simple.png')
+    attribute :icon_unlocked, Rails.root.join('public', 'badges', 'unlocked', 'simple.png')
+    # The 'legacy' attribute allow you to defined when a badge cannot be obtained anymore
+    attribute :legacy,        false
+
+    def initialize
+      # Important, do not forget to call super
+      super
+
+      # Parameter 1: checker method called when the objective is triggered.
+      # The user progress will increase by 1 if the method returns true
+      # It won't increase if the method returns false
+      # Parameter 2: The name of the objective. Can be displayed to your users when needed
+      # Parameter 3: The description of the objective. Can be displayed to your users when needed
+      # Parameter 4: Optional, defaults to 1. Defines how many times the objective must be
+      # successfully triggered to be completed
+      add_objective(:trigger_me, 'Pull the trigger', 'Trigger the objective to unlock the badge', 3)
+    end
+
+    def trigger_me(user, params)
+      true
+    end
+  end
+
+Let's say that this file is saved in /app/models/badges/general/simple.rb
+
+All attributes are mandatory for the moment, I'll try to make some of them have a default value as soon as possible.
+
+The #initialize method is used to add as many objectives as you want or to add sub-badges (see 'Meta Badge')
+
+You can see that for this badge, a user will have to successfully trigger the 'Pull the trigger' objective 3 times to unlock the badge.
+
+==== Triggering
+
+To trigger an objective, you'll have to call it from where you want in your code (model, controller, whatever...)
+
+  AdHonorem::Badge.find('simple_badge').set_context(current_user).trigger(:trigger_me)
+
+Note that current_user is used for the example, you can use any user here.
+
+This line of code will call the checker with the same name (which always return true in our example), which will lead to the user progression over this specific objective.
+
+You can trigger an objective several times in a row with
+
+  AdHonorem::Badge.find('simple_badge').set_context(current_user).trigger(:trigger_me, amount: 5)
+
+The 'Pull the trigger' objective will be successfully triggered 5 times, resulting in the user being granted the SimpleBadge.
+
+As you may have noticed, checker methods always receive 2 parameters:
+- The user specified with #set_context
+- A 'params' object
+
+Params can be passed to checkers using a 'data' attribute when calling #trigger
+
+  params = { ammos_left: @ammos }
+  AdHonorem::Badge.find('simple_badge').set_context(current_user).trigger(:trigger_me, amount: 5, data: params)
+
+Now you can access everything in the checker
+
+  def trigger_me(user, params)
+    user.alive? && !params[:ammos_left].zero?
+  end
+
+==== Result
+
+The #trigger method will return the command result as a symbol:
+- :legacy_badge when the badge cannot be unlocked anymore
+- :already_done if the badge is already unlocked or if the objective is already fulfilled
+- :failed_check when the checker method returns false
+- :completed_badge when the user just unlocked the badge
+- :completed_step when the user fulfilled the objective but not the whole badge (still have other objectives to complete)
+- :triggered when the checker method returns true but it's not enough to complete the objective (still have some successful triggers to perform)
+
+==== Progress and completion
+
+Several methods allow you to give your users informations about their progression:
+
+  # Get progression for a specific badge
+  badge = AdHonorem::Badge.find('simple_badge')
+  badge.complete? # check if every objective is complete
+  badge.complete?(:trigger_me) # check if a single objective is complete
+  badge.progress # list completion for each objective
+    => Pull the trigger: 0/1
+  badge.progress(:step) # Same as above, :step being the default parameter
+  badge.progress(:global) # Returns the percentage of completion
+    => 78.0
+
+  # Get progression for a specific objective
+  progression = AdHonorem::Progress.find_by(user: current_user, badge_static_record_type: 'SimpleBadge', objective_slug: 'trigger_me')
+  progression.progress(:percentage)
+    => 33.3
+  progression.progress(:stringified)
+    => 1/3
+  progression.done?
+    => false
+
+  # Get unlocked badges for a specific user
+  unlocked_badges = AdHonorem::Achievement.find_by(user: current_user, state: :done)
+  unlocked_badges.first.badge # returns an instance of the first unlocked badge
+    => #<SimpleBadge:0x007fcfe9c7cf48>
+
+==== Events and hooks
+
+As manually triggering every badge won't be relevant if several badges can be unlocked through the same piece of code, AdHonorem provides an event/hook system.
+
+Under the attributes of your badge, just before the initialize method, add the following:
+  hook :<event_name>, to: [:<responder_one>, :<responder_two>]
+
+Where <event_name> is an arbitrary event name and where <responder_one> and <responder_two> are checker methods of your badge.
+
+Several badges can hook a similar event name.
+
+In your models or controllers (or whatever), you can raise an event with
+
+  AdHonorem::Badge.dispatch(current_user, :<event_name>, params)
+
+'params' is optional and works the same as for the #trigger method, for instance
+
+  { amount: 1, data: { called_from_file: __FILE__ } }
+
+The event will bubble to all the badges that have a hook for it and will try to triggers the responder(s) as if they had been called through #trigger
+
+==== Meta Badge
+
+Here is an example of a meta badge
+
+  class MetaBadge < AdHonorem::Badge
+    attribute :slug,          'meta_badge'
+    attribute :name,          'Meta badge'
+    #### truncated for the sake of the example, other attributes are still mandatory ####
+
+    def initialize
+      super
+
+      add_sub_badge(:sub_badge_one)
+      add_sub_badge(:sub_badge_two)
+    end
+  end
+
+As you can see, we defined sub-badges in the initialize method instead of objectives.
+
+Each time this badge will be triggered for an objective, it will bubble it to all of its sub-badges (except for those already unlocked by the user).
+
+Meta badges respond to the #complete? method with true when all their sub-badges are complete too, though they don't unlock. You won't find an AdHonorem::Achievement for meta badges. It allows you to add an harder to get sub-badge to an existing meta later if you want.
+
+Important: Your sub-badges should not declare event hooks directly! Instead, hook the events to your meta badge this way:
+
+  class MetaBadge < AdHonorem::Badge
+    attribute :slug,          'meta_badge'
+    attribute :name,          'Meta badge'
+    #### truncated for the sake of the example, other attributes are still mandatory ####
+
+    hook :level_up, to: :level_up
+
+    def initialize
+      super
+
+      add_sub_badge(:sub_badge_one)
+      add_sub_badge(:sub_badge_two)
+    end
+  end
+
+  # Each time AdHonorem::Badge.dispatch(current_user, :level_up) is called, the level_up method of both sub_badge_one and sub_badge_two badges will be triggered
+
+== Questions?
+
+If you have any question or doubt regarding StaticRecord which you cannot find the solution to in the documentation, you can send me an email. I'll try to answer in less than 24 hours.
+
+== Bugs?
+
+If you find a bug please add an issue on GitHub or fork the project and send a pull request.
+
+== Future
+
+AdHonorem is in active development, so be ready for leaderboards, sample apps with ready-to-use partials and JS/CSS to provide you with a badge-list interface, better badge category support, possibility to order your categories and badge inside them easily, etc...

data/lib/adhonorem/concerns/hooking_concern.rb

@@ -0,0 +1,46 @@
+module AdHonorem
+  # Handle event and hook system
+  module HookingConcern
+    extend ActiveSupport::Concern
+
+    module ClassMethods # :nodoc:
+      # After all badges loading, @@hooks will look like
+      # {
+      #   master_a_weapon: {
+      #     'ParameteredBadge' => [:checker_one, :checker_two],
+      #     'LegacyBadge' => [:a_checker],
+      #   },
+      #   other_event: {
+      #     'OtherBadgeResponder' => [:other_checker]
+      #   }
+      # }
+      @@hooks = {}
+
+      def dispatch(user, event, params = nil)
+        params ||= {}
+        result = {}
+
+        @@hooks[event] ||= {}
+        @@hooks[event].each do |responder, registered_checkers|
+          badge = find_by(klass: responder).set_context(user)
+          registered_checkers.each do |checker|
+            res = badge.trigger(checker, params)
+            result[res] ||= []
+            result[res] << "#{responder}##{checker}"
+          end
+        end
+
+        result
+      end
+
+      protected
+
+      def hook(event, params = nil)
+        params ||= {}
+        @@hooks[event] ||= {}
+        @@hooks[event][name] ||= []
+        @@hooks[event][name] += [params[:to] || []].flatten.uniq
+      end
+    end
+  end
+end

data/lib/adhonorem/concerns/meta_concern.rb

@@ -0,0 +1,59 @@
+module AdHonorem
+  # Concerning meta badges
+  module MetaConcern
+    extend ActiveSupport::Concern
+
+    def meta?
+      !@sub_badges.empty?
+    end
+
+    protected
+
+    def add_sub_badge(badge_slug)
+      @sub_badges << badge_slug
+    end
+
+    private
+
+    def trigger_meta(objective_slug, params)
+      @sub_badges.each do |sub_slug|
+        sub_badge = AdHonorem::Badge.find(sub_slug).set_context(@user)
+        next if sub_badge.complete? || !sub_badge.respond_to?(objective_slug)
+        sub_badge.trigger(objective_slug, params)
+      end
+    end
+
+    def complete_meta?
+      check_context
+      progress_meta(:global) == 100.0
+    end
+
+    def progress_meta(progress_type = :step)
+      check_context
+
+      res = @sub_badges.map do |sub_slug|
+        sub_badge = AdHonorem::Badge.find(sub_slug)
+        sub_badge.set_context(@user).progress(progress_type)
+      end
+
+      case progress_type
+      when :step
+        res
+      when :global
+        res.sum / @sub_badges.size
+      end
+    end
+
+    def next_sub_badge
+      @sub_badges.each do |sub_slug|
+        sub = AdHonorem::Badge.find(sub_slug).set_context(@user)
+        return sub unless sub.complete?
+      end
+      last_sub_badge
+    end
+
+    def last_sub_badge
+      AdHonorem::Badge.find(@sub_badges.last).set_context(@user)
+    end
+  end
+end

data/lib/adhonorem/concerns/objective_concern.rb

@@ -0,0 +1,18 @@
+module AdHonorem
+  # Contains objective-related methods
+  module ObjectiveConcern
+    extend ActiveSupport::Concern
+
+    attr_reader :objectives
+
+    def add_objective(slug, name, description, amount_needed = 1)
+      # prevent crash when Badges are initialized before migrations were applied
+      return unless defined?(AdHonorem::Objective)
+      @objectives[slug] = AdHonorem::Objective.new(slug, name, description, amount_needed)
+    end
+
+    def objectives_count
+      objectives.keys.count
+    end
+  end
+end

data/lib/adhonorem/concerns/reward_concern.rb

@@ -0,0 +1,15 @@
+module AdHonorem
+  # Contains reward-related methods
+  module RewardConcern
+    extend ActiveSupport::Concern
+
+    def add_reward; end
+
+    private
+
+    def reward
+      # @rewards.each do |reward|
+      # end
+    end
+  end
+end

data/lib/adhonorem/concerns/user_contexted_concern.rb

@@ -0,0 +1,22 @@
+module AdHonorem
+  module UserContextedConcern # :nodoc:
+    extend ActiveSupport::Concern
+
+    attr_reader :user
+
+    def set_context(user)
+      @user = user
+      self
+    end
+
+    def reload_context!
+      check_context
+      @user = AdHonorem.configuration.user_class.constantize.find(@user.id)
+      self
+    end
+
+    def check_context
+      raise AdHonorem::NoContext, 'No context User has been set' unless @user
+    end
+  end
+end

data/lib/adhonorem/generators/adhonorem_generator.rb

@@ -4,8 +4,10 @@ module Adhonorem
 
     def copy_files
       time = Time.zone.now.strftime('%Y%m%d%H%M')
-      template 'progress_migration.rb', "db/migrate/#{time}00_create_adhonorem_progress.rb"
-      template 'achievement_migration.rb', "db/migrate/#{time}01_create_adhonorem_achievement.rb"
+      progress_mig = "db/migrate/#{time}00_create_adhonorem_progress.rb"
+      achievement_mig = "db/migrate/#{time}01_create_adhonorem_achievement.rb"
+      template 'progress_migration.rb', progress_mig
+      template 'achievement_migration.rb', achievement_mig
     end
   end
 

data/lib/adhonorem/models/badge.rb

@@ -1,24 +1,16 @@
 module AdHonorem
   # AdHonorem core class, must be inherited from
   class Badge < ::StaticRecord::Base
+    include AdHonorem::UserContextedConcern
+    include AdHonorem::ObjectiveConcern
+    include AdHonorem::HookingConcern
+    include AdHonorem::MetaConcern
+    include AdHonorem::RewardConcern
+
     table       :badges
     path        Rails.root.join('app', 'models', 'badges', '**', '*.rb')
     primary_key :slug
 
-    attr_reader :objectives, :user
-
-    # After all badges loading, @@hooks will look like
-    # {
-    #   master_a_weapon: {
-    #     'ParameteredBadge' => [:checker_one, :checker_two],
-    #     'LegacyBadge' => [:a_checker],
-    #   },
-    #   other_event: {
-    #     'OtherBadgeResponder' => [:other_checker]
-    #   }
-    # }
-    @@hooks = {}
-
     def initialize
       super
 
@@ -27,29 +19,6 @@ module AdHonorem
       @objectives = {}
     end
 
-    def set_context(user)
-      @user = user
-      self
-    end
-
-    def reload_context!
-      check_context
-      @user = AdHonorem.configuration.user_class.constantize.find(@user.id)
-      self
-    end
-
-    def add_reward; end
-
-    def add_objective(slug, name, description, amount_needed = 1)
-      # prevent crash when Badges are initialized before migrations were applied
-      return unless defined?(AdHonorem::Objective)
-      @objectives[slug] = AdHonorem::Objective.new(slug, name, description, amount_needed)
-    end
-
-    def objectives_count
-      objectives.keys.count
-    end
-
     def progress(progress_type = :step)
       check_context
       return progress_meta(progress_type) if meta?
@@ -69,23 +38,6 @@ module AdHonorem
       legacy || false
     end
 
-    def self.dispatch(user, event, params = nil)
-      params ||= {}
-      result = {}
-
-      @@hooks[event] ||= {}
-      @@hooks[event].each do |responder, registered_checkers|
-        badge = find_by(klass: responder).set_context(user)
-        registered_checkers.each do |checker|
-          res = badge.trigger(checker, params)
-          result[res] ||= []
-          result[res] << "#{responder}##{checker}"
-        end
-      end
-
-      result
-    end
-
     def trigger(objective_slug, params = nil)
       return trigger_meta(objective_slug, params || {}) if meta?
 
@@ -113,33 +65,13 @@ module AdHonorem
       objective = objective_slug
       unless objective.is_a?(AdHonorem::Objective)
         objective = objectives[objective_slug]
-        raise ObjectiveNotFound, "Objective #{objective_slug} could not be found" unless objective
+        err = "Objective #{objective_slug} could not be found"
+        raise ObjectiveNotFound, err unless objective
       end
 
       objective
     end
 
-    def meta?
-      !@sub_badges.empty?
-    end
-
-    class << self
-      protected
-
-      def hook(event, params = nil)
-        params ||= {}
-        @@hooks[event] ||= {}
-        @@hooks[event][name] ||= []
-        @@hooks[event][name] += [params[:to] || []].flatten.uniq
-      end
-    end
-
-    protected
-
-    def add_sub_badge(badge_slug)
-      @sub_badges << badge_slug
-    end
-
     private
 
     def proceed(objective_slug, params)
@@ -180,54 +112,6 @@ module AdHonorem
       achievement.done!
     end
 
-    def trigger_meta(objective_slug, params)
-      @sub_badges.each do |sub_slug|
-        sub_badge = AdHonorem::Badge.find(sub_slug).set_context(@user)
-        next if sub_badge.complete? || !sub_badge.respond_to?(objective_slug)
-        sub_badge.trigger(objective_slug, params)
-      end
-    end
-
-    def complete_meta?
-      check_context
-      progress_meta(:global) == 100.0
-    end
-
-    def progress_meta(progress_type = :step)
-      check_context
-
-      case progress_type
-      when :step
-        @sub_badges.map { |sub_slug| AdHonorem::Badge.find(sub_slug).set_context(@user).progress(progress_type) }
-      when :global
-        res = @sub_badges.map do |sub_slug|
-          AdHonorem::Badge.find(sub_slug).set_context(@user).progress(progress_type)
-        end
-        res.sum / @sub_badges.size
-      end
-    end
-
-    def next_sub_badge
-      @sub_badges.each do |sub_slug|
-        sub = AdHonorem::Badge.find(sub_slug).set_context(@user)
-        return sub unless sub.complete?
-      end
-      last_sub_badge
-    end
-
-    def last_sub_badge
-      AdHonorem::Badge.find(@sub_badges.last).set_context(@user)
-    end
-
-    def reward
-      # @rewards.each do |reward|
-      # end
-    end
-
-    def check_context
-      raise AdHonorem::NoContext, 'No context User has been set' unless @user
-    end
-
     columns slug:             :string,
             name:             :string,
             description:      :string,

data/lib/adhonorem/railtie.rb

@@ -4,6 +4,12 @@ class Railtie < Rails::Railtie # :nodoc:
       require 'adhonorem/models/objective'
       require 'adhonorem/models/achievement'
       require 'adhonorem/models/progress'
+
+      require 'adhonorem/concerns/user_contexted_concern'
+      require 'adhonorem/concerns/objective_concern'
+      require 'adhonorem/concerns/hooking_concern'
+      require 'adhonorem/concerns/meta_concern'
+      require 'adhonorem/concerns/reward_concern'
       require 'adhonorem/models/badge'
 
       ActiveSupport.run_load_hooks(:adhonorem, AdHonorem::Badge)

data/lib/adhonorem/version.rb

@@ -1,3 +1,3 @@
 module AdHonorem
-  VERSION = '1.0.0'.freeze
+  VERSION = '1.0.1'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: adhonorem
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Hugo Chevalier
@@ -136,7 +136,11 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.46.0
-description: A complete gamification gem designed for Ruby on Rails
+description: |2
+      A complete gamification gem designed for Ruby on Rails.
+      AdHonorem assumes that you want to manage the gamification of your
+      Rails application code-side, using Ruby files to represent your badges
+      rather than depending on entries stored in a database.
 email:
 - drakhaine@gmail.com
 executables: []
@@ -152,6 +156,11 @@ files:
 - app/views/layouts/adhonorem/application.html.erb
 - config/routes.rb
 - lib/adhonorem.rb
+- lib/adhonorem/concerns/hooking_concern.rb
+- lib/adhonorem/concerns/meta_concern.rb
+- lib/adhonorem/concerns/objective_concern.rb
+- lib/adhonorem/concerns/reward_concern.rb
+- lib/adhonorem/concerns/user_contexted_concern.rb
 - lib/adhonorem/engine.rb
 - lib/adhonorem/exceptions.rb
 - lib/adhonorem/generators/adhonorem_generator.rb
@@ -205,7 +214,7 @@ files:
 - spec/test_app/db/migrate/20170103065400_create_adhonorem_progress.rb
 - spec/test_app/db/migrate/20170103065401_create_adhonorem_achievement.rb
 - spec/test_app/db/schema.rb
-homepage: http://rubygems.org/gems/adhonorem
+homepage: https://github.com/hchevalier/adhonorem
 licenses:
 - MIT
 metadata: {}