census 0.3.1 → 0.4.0

data/README.rdoc

@@ -3,3 +3,110 @@
 Census is a Rails plugin that collects searchable demographics data for each
 of your application's users. The data to be collected is defined using a simple
 admin interface that Census provides.
+
+== Setup
+
+After installing the Census gem, require it in your Rails app and run the census
+generator.
+
+In your config/environment.rb:
+
+  config.gem 'census'
+
+Run the generator and migrate your database:
+
+  script/generate census
+  rake db:migrate
+
+== Configuration
+	
+The generator creates a sample configuration file in config/initializers/census.rb.
+At the top of this file, you'll see a configuration option that allows you to
+restrict access to the Census admin user interface. You'll probably want to set
+this option, or anyone will be able to access the admin UI. Assuming your app has
+an authentication system that implements a current_user method, and that your user
+model has an admin? method, you could do something like this:
+
+  Census.configure do |config|
+    config.admin_role = 'current_user.admin?'
+  end
+	
+The remainder of the configuration file defines various data types that you can use
+for the data you'll be collecting. Census comes with a few data types already
+defined, and you can add additional types if needed. When defining a data type,
+you can provide various Ruby procs that are used to convert the data to and from
+a string representation that will be stored in the database. The procs you can
+provide are:
+
+* :sql_transform - returns a SQL fragment that will be used for comparing data when doing search queries
+
+* :format_data   - used to convert data from its string representation
+
+* :validate_data - used to validate form field submissions, and should return nil if the data is valid or an error message if it is invalid
+
+As an example, here's the data type definition for integer data:
+
+  Census::DataType.define(
+    "Number",
+    :sql_transform  => lambda {|column_name| "CAST(#{column_name} AS SIGNED INTEGER)"},
+    :format_data    => lambda {|data| data.to_i unless data.blank? },
+    :validate_data  => lambda {|data| "must be a number" unless data =~ /^\d*$/}
+  )
+
+== Defining Questions
+
+You can access the Census admin UI at /census/admin. You may want to add a link
+to census_admin_path somewhere in your app's administration interface. Using the
+admin interface, you'll be able to create questions and their optional
+multiple-choice answers. Questions are organized into data groups and can be
+reordered using drag and drop.
+
+You could also create DataGroup, Question, and Choice instances programatically
+if you'd prefer not to use the admin UI.
+
+== Allowing Users to Answer Your Questions
+
+Census provides a partial that you can include in a form that collects answers
+from your users. This partial assumes it's inside of a form_for(:user) block. It
+will render fields for each of the questions you've defined.
+
+ <%= render 'census/user_answers', :user => @user %>
+
+Data groups are rendered as fieldsets that contain a list of input fields, one
+for each question. If you take a look at the rendered HTML, you'll see several
+class and id attributes that you can use to style the form fields as needed.
+
+== Displaying a User's Answers
+
+Census provides a partial that you can use to display a user's answers.
+Somewhere in your app, probably in users/show.html.erb, add the following
+to render the partial:
+
+  <%= render 'census/user_answers', :user => @user %>
+
+== Searching
+
+Census provides a search interface for finding users whose answers match a list
+of search criteria. To perform a search, first create a Census::Search object,
+passing your search criteria as a hash of questions and values. We'll assume
+for this example that we have questions for "Hair Color" and "Age," and
+we'll look them up by name.
+
+  hair_color = Question.find_by_prompt('Hair Color')
+  age = Question.find_by_prompt('Age')
+  search = Census::Search.new(hair_color => 'Brown', age => 25)
+
+The search listed above will find all users who have brown hair and are 25 years
+old. You can also pass arrays or ranges, like this:
+
+  search = Census::Search.new(hair_color => ['Brown', 'Blond'], age => 25..30)
+
+That search will find all users between the ages of 25 and 30 that have either
+brown or blond hair. Once you've created the Search object, call its perform
+method to query the database and get back the list of matching users.
+
+  users = search.perform
+
+== Copyright
+
+Copyright (c) 2010 Envy Labs LLC. See LICENSE for details.

data/VERSION

@@ -1 +1 @@
-0.3.1
+0.4.0

data/app/controllers/census/data_groups_controller.rb

@@ -1,7 +1,9 @@
 class Census::DataGroupsController < ApplicationController
   
+  before_filter :restrict_access
+  
   def index
-    @data_groups = DataGroup.all(:order => :position)
+    @data_groups = DataGroup.all
   end
 
   def new
@@ -40,5 +42,22 @@ class Census::DataGroupsController < ApplicationController
     flash[:notice] = "Deleted #{@data_group.name}"
     redirect_to census_admin_path
   end
+  
+  def sort
+    group_positions = params[:data_group].to_a
+    DataGroup.all.each_with_index do |group, i|
+      group.position = group_positions.index(group.id.to_s) + 1
+      group.save
+    end
+    render :text => 'ok'
+  end
+  
+  
+  private
+  
+  
+  def restrict_access
+    render :text => 'Not authorized', :status => :unauthorized unless instance_eval(Census::configuration.admin_role.to_s)
+  end
 
 end

data/app/models/choice.rb

@@ -1,7 +1,7 @@
 class Choice < ActiveRecord::Base
 
   belongs_to :question, :inverse_of => :choices
-  acts_as_list :scope => :question
+  default_scope :order => :position
   
   validates_presence_of :value,
                         :question

data/app/models/data_group.rb

@@ -1,6 +1,7 @@
 class DataGroup < ActiveRecord::Base
 
   acts_as_list
+  default_scope :order => :position
 
   has_many :questions, :dependent => :destroy, :inverse_of => :data_group
   accepts_nested_attributes_for :questions, :reject_if => lambda { |a| a[:prompt].blank? }, :allow_destroy => true

data/app/models/question.rb

@@ -1,7 +1,7 @@
 class Question < ActiveRecord::Base
 
   belongs_to :data_group, :inverse_of => :questions
-  acts_as_list :scope => :data_group
+  default_scope :order => :position
   
   has_many :choices, :dependent => :destroy, :inverse_of => :question
   accepts_nested_attributes_for :choices, :reject_if => lambda { |a| a[:value].blank? }, :allow_destroy => true

data/app/views/census/data_groups/_choice_fields.html.erb

@@ -1,4 +1,5 @@
-<div class="fields">
+<div class="census_choice fields" id="choice-<%= form.object.id %>">
+  <%= form.hidden_field :position, :class => 'choice_position' %>
   <%= form.text_field :value %>
   <%= link_to_remove_fields "remove", form %>
 </div>

data/app/views/census/data_groups/_form.html.erb

@@ -2,10 +2,13 @@
 <div class="text_field">
   <%= form.label :name, "Group Name" %>
   <%= form.text_field :name %>
+  <label><span>Drag and drop questions and answer choices to rearrange them</span></label>
 </div>
-<% form.fields_for :questions do |builder| %>
-  <%= render "question_fields", :form => builder %>
-<% end %>
-<div>
-  <%= link_to_add_fields "Add Question", form, :questions %>
+<div class="census_question_list" id="<%= form.object.id %>">
+  <% form.fields_for :questions do |builder| %>
+    <%= render "question_fields", :form => builder %>
+  <% end %>
+  <p>
+    <%= link_to_add_fields "Add Question", form, :questions %>
+  </p>
 </div>

data/app/views/census/data_groups/_question_fields.html.erb

@@ -1,22 +1,24 @@
-<fieldset class="fields">
-  <legend>Question <%= form.object.position %></legend>
+<fieldset class="census_question fields" id="question-<%= form.object.id %>">
   <div class="question">
-    <%= form.label :prompt, "Label" %>
+    <%= form.hidden_field :position, :class => 'question_position' %>
+    <%= form.label :prompt, "Question" %>
     <%= form.text_field :prompt %>
     <%= link_to_remove_fields "remove", form %>
     <br/>
     <%= form.label :data_type %>
     <%= form.collection_select :data_type, Census::DataType.all, :name, :name %>
   </div>
-  <fieldset>
-    <legend>Answer Choices (leave empty to allow freeform text entry)</legend>
-    <% form.fields_for :choices do |builder| %>
-      <%= render 'choice_fields', :form => builder %>
-    <% end %>
-    <div>
-      <%= link_to_add_fields "Add Answer", form, :choices %>
+  <label>Answer Choices <span>Leave empty to allow freeform text entry</span></label>
+  <fieldset class="choices">
+    <div class="census_choice_list" id="<%= form.object.id %>">
+      <% form.fields_for :choices do |builder| %>
+        <%= render 'choice_fields', :form => builder %>
+      <% end %>
+      <div>
+        <%= link_to_add_fields "Add Answer", form, :choices %>
+        <%= form.check_box :multiple %>
+        <%= form.label :multiple, "Allow multiple selections" %>
+      </div>
     </div>
-    <%= form.check_box :multiple %>
-    <%= form.label :multiple, "Allow multiple selections" %>
   </fieldset>
 </fieldset>

data/app/views/census/data_groups/index.html.erb

@@ -1,8 +1,9 @@
 <h2>Census Data Groups</h2>
 <ul class="census_data_group_list">
   <% @data_groups.each do |group| %>
-    <li>
-      <%=link_to group.name, edit_census_data_group_path(group) %> 
+    <li class="census_data_group" id="data_group-<%= group.id %>">
+      <%=h group.name %>
+      <%=link_to 'edit', edit_census_data_group_path(group) %> 
     </li>
   <% end %>
 </ul>

data/config/routes.rb

@@ -1,7 +1,10 @@
 ActionController::Routing::Routes.draw do |map|
 
   map.namespace :census do |census|
-    census.resources :data_groups, :except => [:index, :show]
+    census.resources :data_groups,
+                     :except => [:index, :show],
+                     :collection => {:sort => :put}
+    
     census.admin 'admin', :controller => 'data_groups', :action => 'index'
   end
 

data/generators/census/census_generator.rb

@@ -10,6 +10,9 @@ class CensusGenerator < Rails::Generator::Base
       
       m.directory File.join("public", "javascripts")
       m.file "census.js", "public/javascripts/census.js"
+
+      m.directory File.join("public", "stylesheets")
+      m.file "census.css", "public/stylesheets/census.css"
       
       user_model = "app/models/user.rb"
       if File.exists?(user_model)

data/generators/census/templates/README

@@ -4,25 +4,33 @@
 Next:
 
 1. In order for the question admin views to work, you'll need to include both
-   jQuery and the census.js file in your application layout:
+   jQuery and the census.js file in your application layout. To enable drag-and-drop
+   sorting of questions and choices in the census admin, you'll also need to
+   include jQuery UI.
 
-     <%= javascript_include_tag 'http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js' %>
+     <%= javascript_include_tag 'http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js' %>
+     <%= javascript_include_tag 'http://ajax.googleapis.com/ajax/libs/jqueryui/1.7.2/jquery-ui.min.js' %>
      <%= javascript_include_tag 'census' %>
 
-2. Add a link to the question admin page somewhere in your app:
+2. If you'd like the Census admin pages to look nicer, include the provided census.css
+   file in your application layout.
+
+     <%= stylesheet_link_tag 'census' %>
+
+3. Add a link to the question admin page somewhere in your app:
 
      <%= link_to 'Set up questions', census_admin_path %>
 
-3. Include the partial that displays answers in your user show page:
+4. Include the partial that displays answers in your user show page:
 
      <%= render 'census/user_answers', :user => @user %>
 
-4. Include the partial that allows the user to enter answers in your user
+5. Include the partial that allows the user to enter answers in your user
    edit page:
 
      <%= render 'census/user_questions', :user => @user %>
 
-5. Migrate your database:
+6. Migrate your database:
 
      rake db:migrate
 

data/generators/census/templates/census.css

@@ -0,0 +1,71 @@
+.census_data_group_list {
+	font: 12pt sans-serif;
+	list-style: none;
+}
+
+.census_data_group_list li {
+	padding: 1px 0px;
+}
+
+.census_data_group_list a {
+	font-size: 0.9em;
+}
+
+.census_data_group_form {
+	font: 10pt sans-serif;
+}
+
+.census_data_group_form label {
+	display: inline-block;
+	margin-top: 5px;
+	margin-left: 10px;
+}
+
+.census_data_group_form label span {
+	margin-left: 20px;
+	font-size: 0.9em;
+	color: #777;
+}
+
+.census_data_group_form fieldset {
+	background: #fff;
+	border: none;
+	-moz-border-radius: 5px;
+	-webkit-border-radius: 5px;
+}
+
+.census_data_group_form fieldset legend {
+	padding: 30px 0px 5px;
+	margin: 0px;
+	font-size: 1.2em;
+}
+
+.census_data_group_form .census_question {
+	margin-top: 20px;
+	padding: 10px 8px;
+	background: #ddd;
+	-moz-border-radius: 10px;
+	-webkit-border-radius: 10px;
+}
+
+.census_data_group_form .census_question .choices {
+	font-size: 0.8em;
+	margin-top: 5px;
+	padding-top: 10px;
+}
+
+.census_data_group_form .census_choice {
+	padding: 5px;
+	margin-bottom: 5px;
+	background: #ccc;
+	-moz-border-radius: 5px;
+	-webkit-border-radius: 5px;
+}
+
+.census_data_group_form .census_question .choices label {
+	margin-left: 0px;
+}
+
+.census_data_group_form .census_question .choices a {
+	margin: 0px 20px 0px 2px;
+}

data/generators/census/templates/census.js

@@ -1,10 +1,47 @@
+jQuery.ajaxSetup({ 
+  'beforeSend': function(xhr) {xhr.setRequestHeader("Accept", "text/javascript")}
+})
+
 function remove_fields(link) {
   $(link).prev("input[type=hidden]").val("1");
   $(link).closest(".fields").hide();
+	update_positions();
 }
 
 function add_fields(link, association, content) {
   var new_id = new Date().getTime();
   var regexp = new RegExp("new_" + association, "g")
   $(link).parent().before(content.replace(regexp, new_id));
+	$('.census_question_list').sortable('refresh');
+	$('.census_choice_list').sortable('refresh');
+	
+	if (association == "questions") {
+		$('.census_choice_list').sortable({items:'.census_choice', containment:'parent', axis:'y', update: function() {
+			update_positions();
+		}});
+	}
+	
+	update_positions();
+}
+
+function update_positions() {
+	$('.census_question').each(function(index) {
+		$(this).find('.question_position').val(index + 1);
+	  $(this).find('.census_choice').each(function(index) {
+			$(this).find('.choice_position').val(index + 1);
+		});
+	});
 }
+
+$(function() {
+	$('.census_data_group_list').sortable({items:'.census_data_group', containment:'parent', axis:'y', update: function() {
+	  $.post('/census/data_groups/sort', '_method=put&'+$(this).sortable('serialize'));
+	}});	
+	$('.census_question_list').sortable({items:'.census_question', containment:'parent', axis:'y', update: function() {
+		update_positions();
+	}});	
+	$('.census_choice_list').sortable({items:'.census_choice', containment:'parent', axis:'y', update: function() {
+		update_positions();
+	}});
+	update_positions();
+})

data/generators/census/templates/census.rb

@@ -1,3 +1,22 @@
+Census.configure do |config|
+  # To restrict access to the census admin UI, specify a code snippet that
+  # evaluates to true for anyone who should have access. By default, everyone
+  # has access to the admin UI.
+  #
+  # config.admin_role = 'current_user.admin?'
+end
+
+#
+# Define data types. All data is stored in the database as strings, and you can
+# provide procs that will be used to convert from the stored strings to any data
+# type you need.
+#
+# :sql_transform - should return a SQL fragment that will be used for comparing
+#                  data when doing search queries
+# :format_data   - is used to convert data from its string representation
+# :validate_data - is used to validate form field submissions, and should return
+#                  nil if the data is valid and an error message if it is invalid
+#
 Census::DataType.define("String")
 
 Census::DataType.define(
@@ -6,9 +25,3 @@ Census::DataType.define(
   :format_data    => lambda {|data| data.to_i unless data.blank? },
   :validate_data  => lambda {|data| "must be a number" unless data =~ /^\d*$/}
 )
-
-Census::DataType.define(
-  "Yes/No",
-  :sql_transform  => lambda {|column_name| "CAST(#{column_name} AS CHAR)"},
-  :format_data    => lambda {|data| %w(1 T t Y y).include?(data) unless data.blank? }
-)

data/lib/census/configuration.rb

@@ -0,0 +1,25 @@
+module Census
+  class Configuration
+    attr_accessor :admin_role
+
+    def initialize
+      @admin_role = true
+    end
+  end
+
+  class << self
+    attr_accessor :configuration
+  end
+
+  # Configure Census someplace sensible,
+  # like config/initializers/census.rb
+  #
+  # @example
+  #   Census.configure do |config|
+  #     config.admin_role = 'current_user.admin?'
+  #   end
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration)
+  end
+end

data/lib/census.rb

@@ -1 +1,4 @@
+require 'census/configuration'
+require 'census/data_type'
 require 'census/user'
+require 'census/search'

data/test/controllers/data_groups_controller_test.rb

@@ -22,6 +22,9 @@ class DataGroupsControllerTest < ActionController::TestCase
   should_route :delete, '/census/data_groups/1',
     :controller => 'census/data_groups', :action  => 'destroy', :id => '1'
 
+  should_route :put, '/census/data_groups/sort',
+    :controller => 'census/data_groups', :action  => 'sort'
+
   context 'The Census::DataGroupsController' do
     
     context 'using GET to index' do
@@ -37,6 +40,25 @@ class DataGroupsControllerTest < ActionController::TestCase
       should_assign_to                  :data_groups
     
     end
+
+    context 'using GET to index with restricted access' do
+    
+      setup do
+        Census.configure do |config|
+          config.admin_role = false
+        end
+        get :index
+      end
+      
+      teardown do
+        Census.configure do |config|
+          config.admin_role = true
+        end
+      end        
+    
+      should_respond_with :unauthorized
+    
+    end
     
     context 'using GET to new' do
     
@@ -159,6 +181,26 @@ class DataGroupsControllerTest < ActionController::TestCase
       end
     
     end
+
+    context 'using PUT to sort' do
+    
+      setup do
+        @group_a = Factory(:data_group, :position => 1)
+        @group_b = Factory(:data_group, :position => 2)
+        @group_c = Factory(:data_group, :position => 3)
+        put :sort, :data_group => [@group_b.id.to_s, @group_a.id.to_s, @group_c.id.to_s]
+      end
+    
+      should_respond_with               :success
+      should_respond_with_content_type  :html
+    
+      should 'rearrange the data groups' do
+        assert_equal @group_b, DataGroup.all[0]
+        assert_equal @group_a, DataGroup.all[1]
+        assert_equal @group_c, DataGroup.all[2]
+      end
+    
+    end
     
   end
   

data/test/models/choice_test.rb

@@ -12,8 +12,6 @@ class ChoiceTest < ActiveSupport::TestCase
 
     should_belong_to                :question
     
-    should_act_as_list
-
     should_validate_presence_of     :value,
                                     :question
 

data/test/models/question_test.rb

@@ -14,8 +14,6 @@ class QuestionTest < ActiveSupport::TestCase
     should_have_many                :choices, :dependent => :destroy
     should_have_many                :answers, :dependent => :destroy
 
-    should_act_as_list
-
     should_validate_presence_of     :prompt,
                                     :data_group
     

data/test/rails_root/config/initializers/census.rb

@@ -1,3 +1,11 @@
+Census.configure do |config|
+  # To restrict access to the census admin UI, specify a code snippet that
+  # evaluates to true for anyone who should have access. By default, everyone
+  # has access to the admin UI.
+  #
+  # config.admin_role = 'current_user.admin?'
+end
+
 Census::DataType.define("String")
 
 Census::DataType.define(

data/test/rails_root/db/schema.rb

@@ -9,7 +9,7 @@
 #
 # It's strongly recommended to check this file into your version control system.
 
-ActiveRecord::Schema.define(:version => 20100408172932) do
+ActiveRecord::Schema.define(:version => 20100416173354) do
 
   create_table "answers", :force => true do |t|
     t.integer "question_id"

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 3
-  - 1
-  version: 0.3.1
+  - 4
+  - 0
+  version: 0.4.0
 platform: ruby
 authors: 
 - Mark Kendall
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-08 00:00:00 -04:00
+date: 2010-04-16 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -104,6 +104,7 @@ files:
 - generators/census/lib/insert_commands.rb
 - generators/census/lib/rake_commands.rb
 - generators/census/templates/README
+- generators/census/templates/census.css
 - generators/census/templates/census.js
 - generators/census/templates/census.rb
 - generators/census/templates/factories.rb
@@ -111,6 +112,7 @@ files:
 - generators/census/templates/migrations/without_users.rb
 - generators/census/templates/user.rb
 - lib/census.rb
+- lib/census/configuration.rb
 - lib/census/data_type.rb
 - lib/census/search.rb
 - lib/census/user.rb
@@ -169,7 +171,7 @@ test_files:
 - test/rails_root/config/initializers/new_rails_defaults.rb
 - test/rails_root/config/initializers/session_store.rb
 - test/rails_root/config/routes.rb
-- test/rails_root/db/migrate/20100408172932_create_census_tables.rb
+- test/rails_root/db/migrate/20100416173354_create_census_tables.rb
 - test/rails_root/db/schema.rb
 - test/rails_root/test/factories/census.rb
 - test/rails_root/test/performance/browsing_test.rb