= Merit Rails Gem

Define reputation for users and data on your application.

http://i567.photobucket.com/albums/ss118/DeuceBigglebags/th_nspot26_300.jpg


= Installation

1. Add 'merit' to your Gemfile
2. Run +rails+ +g+ +merit+:+install+
3. Run +rails+ +g+ +merit+ +MODEL_NAME+
4. Run +rake+ +db+:+migrate+
5. Configure reputation rules for your application


= Defining badge rules

You may give badges to any resource on your application if some condition
holds. Badges may have levels, and may be temporary.

Define rules on +app/models/merit_badge_rules.rb+:

+grant_on+ accepts:
* +controller+#+action+ string (similar to Rails routes)
* :+badge+ for badge name
* :+level+ for badge level
* :+to+: method name over target_object which obtains user to badge.
* :+model_name+ (string): when controller's name differs from the model being
  worked (like RegistrationsController for User model).
* :+temporary+ (boolean): if the condition doesn't hold and the receiver had
  the badge, it gets removed. +false+ by default (badges are kept forever).
* &+block+
  * empty (always grants)
  * a block which evaluates to boolean (recieves target object as parameter)
  * a block with a hash composed of methods to run on the target object with
    expected values

== Examples

    grant_on 'comments#vote', :badge => 'relevant-commenter', :to => :user do
      { :votes => 5 }
    end

    grant_on ['users#create', 'users#update'], :badge => 'autobiographer', :temporary => true do |user|
      user.name.present? && user.address.present?
    end


= Defining point rules

Points are a simple integer value which are given to "meritable" resources.
They are given on actions-triggered, either to the action user or to the
method (or array of methods) defined in the +:to+ option.

Define rules on +app/models/merit_point_rules.rb+:

== Examples

    score 10, :on => [
      'users#update'
    ]

    score 15, :on => 'reviews#create', :to => [:reviewer, :reviewed]

    score 20, :on => [
      'comments#create',
      'photos#create'
    ]


= Defining rank rules

Rankings are very similar to badges. They give "badges" which have a hierarchy
defined by +level+'s lexicografical order (greater is better). If a rank is
granted, lower level ranks are taken off. 5 stars is a common ranking use
case.

They are not given at specified actions like badges, you should define a cron
job to test if ranks are to be granted.

Define rules on +app/models/merit_rank_rules.rb+:

+set_rank+ accepts:
* +badge_name+ name of this ranking
* :+level+ ranking level (greater is better)
* :+to+ model or scope to check if new rankings apply

Check for rules on a rake task executed in background like:
    task :cron => :environment do
      MeritRankRules.new.check_rank_rules
    end


== Examples

    set_rank :stars, :level => 2, :to => Commiter.active do |commiter|
      commiter.branches > 1 && commiter.followers >= 10
    end

    set_rank :stars, :level => 3, :to => Commiter.active do |commiter|
      commiter.branches > 2 && commiter.followers >= 20
    end


= Grant manually

You may also add badges/rank "by hand" from controller actions:
   Badge.find(3).grant_to(current_user)


= Upgrade to 0.2.0

Added +had_errors+ boolean attribute to +merit_actions+ table.


= Test application

To run the test application inside this gem follow:
  cd test/dummy
  rails g merit:install
  rails g merit user
  rake db:migrate ; rake db:seed
  rails s


= To-do list

* Test points granting with different options.
* Test model_name attribute for badge_rules.
* Add model_name option on rank and point rules.
* Ranking should not be badges, so .badges doesn't return them (2-stars shouldn't be badge).
* grep -r 'FIXME\|TODO' .
* :value parameter (for star voting for example) should be configurable (depends
  on params[:value] on the controller).
* Make fixtures for integration testing (now creating objects on test file!).