survey 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 88c7e715f08bd4533d85638100a971c263eac2c5
+  data.tar.gz: e944022847b8b42b9ac60a5e9ceaf3d22bfbc20d
+SHA512:
+  metadata.gz: 33b982f786f59f8d90d9f1322d86fa4869dc1d8027a09014b515555c3617fdced414247e30baa55e59168699257695a82e74fb772395110077aa0ce069939736
+  data.tar.gz: 5c58ab3d53e5969e3dce66ada574cfe2b22dad1ac7217904a289176415162c6e8ff61fff63d7969e465f3c577288082fad68c55b42a140582a26cd42b628a69b

data/Gemfile

@@ -0,0 +1,9 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem "rdoc"
+
+group :test do
+  gem 'sqlite3'
+end

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 Runtime Revolution
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,194 @@
+# Survey
+
+[![Build Status](https://travis-ci.org/runtimerevolution/survey.png?branch=master)](https://travis-ci.org/runtimerevolution/survey)
+[![Code Climate](https://codeclimate.com/github/runtimerevolution/survey.png)](https://codeclimate.com/github/runtimerevolution/survey)
+### Surveys on Rails...
+
+Survey is a Rails Engine that brings quizzes, surveys and contests into your Rails
+application. Survey models were designed to be flexible enough in order to be extended and
+integrated with your own models. Survey was initially extracted from a real application that handles contests and quizzes.
+
+## Documentation
+
+You can view the Survey documentation in RDoc format here:
+
+http://rubydoc.info/github/runtimerevolution/survey/frames
+
+## Main Features:
+ - Surveys can limit the number of attempts for each participant
+ - Questions can have multiple answers
+ - Answers can have different weights
+ - Base Scaffold Support for Active Admin, Rails Admin and default Rails Controllers
+ - Base calculation for scores
+ - Easy integration with your project
+
+## Installation
+
+Add survey to your Gemfile:
+```ruby
+gem 'survey', :git => 'git://github.com/runtimerevolution/survey.git'
+
+```
+Then run bundle to install the Gem:
+```sh
+bundle install
+```
+Now generate and run migrations:
+```sh
+rails generate survey:install
+
+bundle exec rake db:migrate
+```
+
+## Getting started with Survey
+
+## Survey inside your models
+To make a model aware of you just need to add `has_surveys` on it:
+```ruby
+class User < ActiveRecord::Base
+  has_surveys
+
+  #... (your code) ...
+end
+```
+There is the concept of participant, in our example we choose the User Model.
+Every participant can respond to surveys and every response is registered as a attempt.
+By default, survey logic assumes an infinite number of attempts per participant
+but if your surveys need to have a maximum number of attempts
+you can pass the attribute `attempts_number` when creating them.
+```ruby
+# Each Participant can respond 4 times this survey
+Survey::Survey.new(:name => "Star Wars Quiz", :description => "A quiz about Star Wars", :attempts_number => 4)
+```
+## Surveys used in your controllers
+In this example we are using the current_user helper
+but you can do it in the way you want.
+
+```ruby
+class ContestsController < ApplicationController
+
+  helper_method :survey, :participant
+
+  # create a new attempt to this survey
+  def new
+    @attempt = survey.attempts.new
+    # build a number of possible answers equal to the number of options
+    survey.questions.size.times { @attempt.answers.build }
+  end
+
+  # create a new attempt in this survey
+  # an attempt needs to have a participant assigned
+  def create
+    @attempt = survey.attempts.new(params[:attempt])
+    # ensure that current user is assigned with this attempt
+    @attempt.participant = participant
+    if @attempt.valid? and @attempt.save
+      redirect_to contests_path
+    else
+      render :action => :new
+    end
+  end
+
+  def participant
+    @participant ||= current_user
+  end
+
+  def survey
+    @survey ||= Survey::Survey.active.first
+  end
+end
+```
+
+## Survey inside your Views
+
+### Controlling Survey avaliability per participant
+To control which page participants see you can use method `avaliable_for_participant?`
+that checks if the participant already spent his attempts.
+```erb
+<% if @survey.avaliable_for_participant?(@participant) %>
+  <%= render 'form' %>
+<% else %>
+  Uupss, <%= @participant.name %> you have reach the maximum number of
+  attempts for <%= @survey.name %>
+<% end %>
+
+<% # in _form.html.erb %>
+<%= form_for [:contests, @attempt] do |f| %>
+  <%= f.fields_for :answers do |builder| %>
+    <ul>
+      <% @survey.questions.each do |question| %>
+        <li>
+          <p><%= question.text %></p>
+          <%= builder.hidden_field :question_id, :value => question.id %>
+          <% question.options.each do |option| %>
+            <%= builder.check_box :option_id, {}, option.id, nil %>
+            <%= option.text %> <br/ >
+          <% end -%>
+        </li>
+      <% end -%>
+    </ul>
+  <% end -%>
+  <%= f.submit "Submit" %>
+<% end -%>
+```
+
+### Scaffolds and CRUD frameworks
+If you are using Rails Admin or Active Admin, you can generate base CRUD screens for Survey with:
+```sh
+rails generate survey active_admin
+
+rails generate survey rails_admin
+```
+If you want a simple way to get started you can use the `plain` option which is a simple Rails scaffold to generate the controller and views related with survey logic.
+By default when you type `rails g survey plain` it generates a controller in the `admin` namespace but you can choose your own namespace as well:
+```sh
+rails generate survey plain namespace:contests
+```
+
+By default when you generates your controllers using the `plain` command the task
+generates the associated routes as well.
+Afterwards if you want to generate more routes, you can using the command:
+
+```sh
+rails generate survey routes namespace:admin
+```
+
+## How to use it
+Every user has a collection of attempts for each survey that he respond to. Is up to you to
+make averages and collect reports based on that information.
+What makes Survey useful is that all the logic behind surveys is now abstracted and well integrated,
+making your job easier.
+
+## Hacking with Survey through your Models:
+
+```ruby
+# select the first active Survey
+survey = Survey::Survey.active.first
+
+# select all the attempts from this survey
+survey_answers = survey.attempts
+
+# check the highest score for current user
+user_highest_score  = survey_answers.for_participant(@user).high_score
+
+#check the highest score made for this survey
+global_highest_score = survey_answers.high_score
+```
+# Compability
+### Rails
+Survey supports Rails 3 and 4. For use in Rails 4. Rails 4 support is recent, so some minor issues may still be present,
+please report them.
+
+### Active Admin
+Only support versions of Active Admin higher than 0.3.1.
+
+# Roadmap
+
+- Add a form builder or a helper to improve the creation of Survey forms.
+- Add polymorphic relations to help the survey be extended with subclasses.
+- Allow adding new fields without breaking the existent logic.
+
+# License
+Copyright © 2013 [Runtime Revolution](http://www.runtime-revolution.com), released under the MIT license.
+
+[![githalytics.com alpha](https://cruel-carlota.pagodabox.com/59be37fe81712a1a4dadc798325a30ee "githalytics.com")](http://githalytics.com/runtimerevolution/survey)

data/Rakefile

@@ -0,0 +1,30 @@
+# encoding: UTF-8
+require 'rubygems'
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rake'
+require 'rdoc/task'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+task :default => :test
+
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Survey'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_files.include('app/**/*.rb')
+end

data/app/models/survey/answer.rb

@@ -0,0 +1,34 @@
+class Survey::Answer < ActiveRecord::Base
+
+  self.table_name = "survey_answers"
+
+  acceptable_attributes :attempt, :option, :correct, :option_id, :question, :question_id
+
+  # associations
+  belongs_to :attempt
+  belongs_to :option
+  belongs_to :question
+
+  # validations
+  validates :option_id, :question_id, :presence => true
+  validates :option_id, :uniqueness => { :scope => [:attempt_id, :question_id] }
+
+  # callbacks
+  after_create :characterize_answer
+
+  def value
+    points = (self.option.nil? ? Survey::Option.find(option_id) : self.option).weight
+    correct?? points : - points
+  end
+
+  def correct?
+    self.correct ||= self.option.correct?
+  end
+
+  private
+
+  def characterize_answer
+    update_attribute(:correct, option.correct?)
+  end
+
+end

data/app/models/survey/attempt.rb

@@ -0,0 +1,60 @@
+class Survey::Attempt < ActiveRecord::Base
+
+  self.table_name = "survey_attempts"
+
+  acceptable_attributes :winner, :survey, :survey_id,
+    :participant,
+    :participant_id,
+    :answers_attributes => ::Survey::Answer::AccessibleAttributes
+
+  # relations
+  belongs_to :survey
+  belongs_to :participant, :polymorphic => true
+  has_many :answers, :dependent => :destroy
+  accepts_nested_attributes_for :answers,
+    :reject_if => ->(q) { q[:question_id].blank? || q[:option_id].blank? }
+
+  # validations
+  validates :participant_id, :participant_type, :presence => true
+  validate :check_number_of_attempts_by_survey
+
+  #scopes
+  scope :wins,   -> { where(:winner => true) }
+  scope :looses, -> { where(:winner => false) }
+  scope :scores, -> { order("score DESC") }
+  scope :for_survey, ->(survey) { where(:survey_id => survey.id) }
+  scope :exclude_survey,  ->(survey) { where("NOT survey_id = #{survey.id}") }
+  scope :for_participant, ->(participant) {
+    where(:participant_id => participant.try(:id), :participant_type => participant.class)
+  }
+
+  # callbacks
+  before_create :collect_scores
+
+  def correct_answers
+    return self.answers.where(:correct => true)
+  end
+
+  def incorrect_answers
+    return self.answers.where(:correct => false)
+  end
+
+  def self.high_score
+    return scores.first.score
+  end
+
+  private
+
+  def check_number_of_attempts_by_survey
+    attempts = self.class.for_survey(survey).for_participant(participant)
+    upper_bound = self.survey.attempts_number
+
+    if attempts.size >= upper_bound && upper_bound != 0
+      errors.add(:survey_id, "Number of attempts exceeded")
+    end
+  end
+
+  def collect_scores
+    self.score = self.answers.map(&:value).reduce(:+) || 0
+  end
+end

data/app/models/survey/option.rb

@@ -0,0 +1,34 @@
+class Survey::Option < ActiveRecord::Base
+
+  self.table_name = "survey_options"
+
+  acceptable_attributes :text, :correct, :weight
+
+  #relations
+  belongs_to :question
+
+  # validations
+  validates :text, :presence => true, :allow_blank => false
+
+  # scopes
+  scope :correct,   -> { where(:correct => true)  }
+  scope :incorrect, -> { where(:correct => false) }
+
+  # callbacks
+  before_create :default_option_weight
+
+  def to_s
+    return self.text
+  end
+
+  def correct?
+    return (self.correct == true)
+  end
+
+  private
+
+  def default_option_weight
+    self.weight = 1 if correct? && self.weight == 0
+  end
+
+end

data/app/models/survey/question.rb

@@ -0,0 +1,24 @@
+class Survey::Question < ActiveRecord::Base
+
+  self.table_name = "survey_questions"
+
+  acceptable_attributes :text, :survey, :options_attributes => Survey::Option::AccessibleAttributes
+
+  # relations
+  belongs_to :survey
+  has_many   :options, :dependent => :destroy
+  accepts_nested_attributes_for :options,
+    :reject_if => ->(a) { a[:text].blank? },
+    :allow_destroy => true
+
+  # validations
+  validates :text, :presence => true, :allow_blank => false
+
+  def correct_options
+    return options.correct
+  end
+
+  def incorrect_options
+    return options.incorrect
+  end
+end

data/app/models/survey/survey.rb

@@ -0,0 +1,49 @@
+class Survey::Survey < ActiveRecord::Base
+
+  self.table_name = "survey_surveys"
+
+  acceptable_attributes :name, :description,
+    :finished,
+    :active,
+    :attempts_number,
+    :questions_attributes => Survey::Question::AccessibleAttributes
+
+  # relations
+  has_many :attempts,  :dependent => :destroy
+  has_many :questions, :dependent => :destroy
+  accepts_nested_attributes_for :questions,
+    :reject_if => ->(q) { q[:text].blank? },
+    :allow_destroy => true
+
+  # scopes
+  scope :active,   -> { where(:active => true) }
+  scope :inactive, -> { where(:active => false) }
+
+  # validations
+  validates :attempts_number, :numericality => { :only_integer => true, :greater_than => -1 }
+  validates :description, :name, :presence => true, :allow_blank => false
+  validate  :check_active_requirements
+
+  # returns all the correct options for current surveys
+  def correct_options
+    return self.questions.map(&:correct_options).flatten
+  end
+
+  # returns all the incorrect options for current surveys
+  def incorrect_options
+    return self.questions.map(&:incorrect_options).flatten
+  end
+
+  def avaliable_for_participant?(participant)
+    current_number_of_attempts = self.attempts.for_participant(participant).size
+    upper_bound = self.attempts_number
+    return !((current_number_of_attempts >= upper_bound) && (upper_bound != 0))
+  end
+
+  private
+
+  # a surveys only can be activated if has one or more questions
+  def check_active_requirements
+    errors.add(:active, "Survey without questions cannot be activated") if self.active && self.questions.empty?
+  end
+end