commontator 0.1.46 → 0.2.0

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright 2012 YOURNAME
+Copyright 2012 Rice University
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,25 +1,116 @@
 # Common Tator
 
 A Rails engine for comments
-This is not ready for use yet. We recommend you do not use this gem until it is done.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+There are 4 steps you must follow to install commontator:
 
-    gem 'commontator'
+1. Gem
 
-And then execute:
+  Add this line to your application's Gemfile:
 
-    $ bundle
+  ```ruby
+  gem 'commontator', '~> 0.2.0'
+  ```
 
-Or install it yourself as:
+  And then execute:
 
-    $ gem install commontator
+  ```sh
+  $ bundle
+  ```
+
+  Or install it yourself as:
+
+  ```sh
+  $ gem install commontator
+  ```
+
+2. Initializer and Migration
+
+  Run the following command to copy commontator's initializer and migration to your own app:
+
+  ```sh
+  $ rake commontator:install
+  ```
+
+  And then execute:
+
+  ```sh
+  $ rake db:migrate
+  ```
+
+  Or run each rake task manually:
+
+  ```sh
+  $ rake commontator:install:initializers
+
+  $ rake commontator:install:migrations
+
+  $ rake db:migrate
+  ```
+
+3. Configuration
+
+  Change commontator's configurations to suit your needs by editing config/intializers/commontator.rb.
+
+4. Routes
+
+  Add this line to your application's routes file:
+
+  ```ruby
+  mount Commontator::Engine => "/commontator"
+  ```
+
+  You can change the mount path if you would like a different one.
 
 ## Usage
 
-TODO: Write usage instructions here
+Follow the steps below to add commontator to your models and views:
+
+1. Models
+
+  Add this line to your user model(s) (or any models that should be able to make comments):
+
+  ```ruby
+  acts_as_commontator
+  ```
+    
+  Add this line to any models you want to be able to comment on:
+
+  ```ruby
+  acts_as_commontable
+  ```
+    
+2. Views
+
+  Add the following line to any view where you want to display comments:
+
+  ```erb
+  <%= commontator_thread_link(commontable) %>
+  ```
+    
+  Where commontable is an instance of some model that acts_as_commontable.
+
+That's it! Commontator is now ready for use.
+
+## Customization
+
+Copy commontator's files to your app using any of the following commands:
+
+```sh
+rake commontator:copy:images
+rake commontator:copy:stylesheets
+
+rake commontator:copy:views
+rake commontator:copy:mailers
+rake commontator:copy:helpers
+
+rake commontator:copy:controllers
+rake commontator:copy:models
+```
+
+You are now free to modify them and have any changes made manifest in your application.
 
 ## Contributing
 

data/app/mailers/commontator/subscriptions_mailer.rb

@@ -8,8 +8,7 @@ module Commontator
       setup_variables(comment)
 
       mail(:bcc => @bcc,
-           :subject => @subject,
-           :body => @body)
+           :subject => @subject)
     end
 
 protected
@@ -43,8 +42,6 @@ protected
       params[:commontable_id] = @commontable_id
       
       @subject = @config.subscription_email_subject_proc.call(params)
-      @body = @config.subscription_email_body_proc.blank? ? nil : \
-                @config.subscription_email_body_proc.call?(params)
     end
 
   end

data/app/mailers/commontator/subscriptions_mailer.rb~

@@ -42,9 +42,7 @@ protected
       params[:commontable_name] = @commontable_name
       params[:commontable_id] = @commontable_id
       
-      @subject = params[:config].subscription_email_subject_proc.call(params)
-      @body = params[:config].subscription_email_body_proc.blank? ? nil : \
-                params[:config].subscription_email_body_proc.call?(params)
+      @subject = @config.subscription_email_subject_proc.call(params)
     end
 
   end

data/app/models/commontator/comment.rb

@@ -1,6 +1,5 @@
 module Commontator
   class Comment < ActiveRecord::Base
-
     belongs_to :commontator, :polymorphic => true
     belongs_to :deleter, :polymorphic => true
     belongs_to :thread
@@ -79,6 +78,5 @@ module Commontator
       can_be_voted_on? && !thread.is_closed? &&\
         thread.can_be_read_by?(user) && user != commontator
     end
-    
   end
 end

data/app/models/commontator/comment.rb~

@@ -65,7 +65,7 @@ module Commontator
     end
 
     def can_be_deleted_by?(user)
-      !thread.is_closed? && !is_deleted? &&\
+      !thread.is_closed? &&\
         ((user == commontator && thread.config.can_delete_own_comments) &&\
         (thread.comments.last == self || thread.config.can_delete_old_comments)) ||\
         thread.can_be_edited_by?(user)

data/app/models/commontator/subscription.rb

@@ -1,6 +1,5 @@
 module Commontator
   class Subscription < ActiveRecord::Base
-
     belongs_to :subscriber, :polymorphic => true
     belongs_to :thread
 
@@ -16,6 +15,5 @@ module Commontator
     def mark_as_unread
       self.update_attribute(:is_unread, true)
     end
-
   end
 end

data/app/models/commontator/subscription.rb~

@@ -4,11 +4,11 @@ module Commontator
     belongs_to :subscriber, :polymorphic => true
     belongs_to :thread
 
-    attr_accessible :subscriber, :thread
-
     validates_presence_of :subscriber, :thread
     validates_uniqueness_of :thread_id, :scope => [:subscriber_id, :subscriber_type]
     
+    attr_accessible :subscriber, :thread
+    
     def mark_as_read
       self.update_attribute(:is_unread, false)
     end

data/app/models/commontator/thread.rb

@@ -1,16 +1,24 @@
 module Commontator
   class Thread < ActiveRecord::Base
-
     belongs_to :closer, :polymorphic => true
     belongs_to :commontable, :polymorphic => true
 
     has_many :comments, :dependent => :destroy
     has_many :subscriptions, :dependent => :destroy
 
-    validates_presence_of :commontable, :allow_nil => true
+    validates_presence_of :commontable, :on => :create
     
     attr_accessible :is_closed
     
+    def config
+      commontable.try(:commontable_config)
+    end
+    
+    def comments
+      (!commontable.blank? && config.comments_can_be_voted_on && config.comments_ordered_by_votes) ? \
+        super.order("cached_votes_down - cached_votes_up") : super
+    end
+    
     def subscribers
       subscriptions.collect{|s| s.subscriber}
     end
@@ -23,10 +31,6 @@ module Commontator
       !closed_at.blank?
     end
     
-    def config
-      commontable.commontable_config
-    end
-    
     def is_subscribed?(user)
       !subscription_for(subscriber).blank?
     end
@@ -69,7 +73,9 @@ module Commontator
     
     # Creates a new empty thread and assigns it to the commontable
     # The old thread is kept in the database for archival purposes
+    
     def clear(user = nil)
+      return if commontable.blank?
       new_thread = Thread.new
       new_thread.commontable = commontable
       self.with_lock do
@@ -91,27 +97,27 @@ module Commontator
     ####################
     
     def comment_created_callback(user, comment)
-      commontable.send(config.comment_created_callback, user, comment) unless config.comment_created_callback.blank?
+      commontable.send(config.comment_created_callback, user, comment) unless commontable.blank? || config.comment_created_callback.blank?
     end
     
     def comment_edited_callback(user, comment)
-      commontable.send(config.comment_edited_callback, user, comment) unless config.comment_edited_callback.blank?
+      commontable.send(config.comment_edited_callback, user, comment) unless commontable.blank? || config.comment_edited_callback.blank?
     end
     
     def comment_deleted_callback(user, comment)
-      commontable.send(config.comment_deleted_callback, user, comment) unless config.comment_deleted_callback.blank?
+      commontable.send(config.comment_deleted_callback, user, comment) unless commontable.blank? || config.comment_deleted_callback.blank?
     end
     
     def thread_closed_callback(user)
-      commontable.send(config.thread_closed_callback, user) unless config.thread_closed_callback.blank?
+      commontable.send(config.thread_closed_callback, user) unless commontable.blank? || config.thread_closed_callback.blank?
     end
     
     def subscribe_callback(user)
-      commontable.send(config.subscribe_callback, user) unless config.subscribe_callback.blank?
+      commontable.send(config.subscribe_callback, user) unless commontable.blank? || config.subscribe_callback.blank?
     end
           
     def unsubscribe_callback(user)
-      commontable.send(config.unsubscribe_callback, user) unless config.unsubscribe_callback.blank?
+      commontable.send(config.unsubscribe_callback, user) unless commontable.blank? || config.unsubscribe_callback.blank?
     end
 
     ##########################
@@ -119,20 +125,19 @@ module Commontator
     ##########################
 
     def can_be_read_by?(user) # Reader and poster capabilities
-      ((!is_closed? || config.closed_threads_are_readable) &&\
+      (!commontable.blank? && (!is_closed? || config.closed_threads_are_readable) &&\
         config.can_read_thread_method.blank? ? true : commontable.send(config.can_read_thread_method, user)) ||\
         can_be_edited_by?(user)
     end
 
     def can_be_edited_by?(user) # Thread admin capabilities
-      config.can_edit_thread_method.blank? ?
+      !commontable.blank? && (config.can_edit_thread_method.blank? ?
         (user.commontator_config.is_admin_method.blank? ? false : user.send(user.commontator_config.is_admin_method)) :
-        commontable.send(config.can_edit_thread_method, user)
+        commontable.send(config.can_edit_thread_method, user))
     end
 
     def can_subscribe?(user)
-      config.can_subscribe_to_thread && can_be_read_by?(user)
+      !commontable.blank? && config.can_subscribe_to_thread && can_be_read_by?(user)
     end
-
   end
 end

data/app/models/commontator/thread.rb~

@@ -1,16 +1,24 @@
 module Commontator
   class Thread < ActiveRecord::Base
-
     belongs_to :closer, :polymorphic => true
     belongs_to :commontable, :polymorphic => true
 
     has_many :comments, :dependent => :destroy
     has_many :subscriptions, :dependent => :destroy
 
-    validates_presence_of :commontable, :allow_nil => true
+    validates_presence_of :commontable, :on => :create
     
     attr_accessible :is_closed
     
+    def config
+      commontable.try(:commontable_config)
+    end
+    
+    def comments
+      (!commontable.blank? && config.comments_can_be_voted_on && config.comments_ordered_by_votes) ? \
+        super.order("cached_votes_down - cached_votes_up") : super
+    end
+    
     def subscribers
       subscriptions.collect{|s| s.subscriber}
     end
@@ -23,10 +31,6 @@ module Commontator
       !closed_at.blank?
     end
     
-    def config
-      commontable.commontable_config
-    end
-    
     def is_subscribed?(user)
       !subscription_for(subscriber).blank?
     end
@@ -69,7 +73,9 @@ module Commontator
     
     # Creates a new empty thread and assigns it to the commontable
     # The old thread is kept in the database for archival purposes
+    
     def clear(user = nil)
+      return if commontable.blank?
       new_thread = Thread.new
       new_thread.commontable = commontable
       self.with_lock do
@@ -91,30 +97,27 @@ module Commontator
     ####################
     
     def comment_created_callback(user, comment)
-      self.subscribe(user) if config.auto_subscribe_on_comment
-      self.mark_as_unread_except_for(user)
-      SubscriptionMailer.comment_created_email(comment)
-      commontable.send(config.comment_created_callback, user, comment) unless config.comment_created_callback.blank?
+      commontable.send(config.comment_created_callback, user, comment) unless commontable.blank? || config.comment_created_callback.blank?
     end
     
     def comment_edited_callback(user, comment)
-      commontable.send(config.comment_edited_callback, user, comment) unless config.comment_edited_callback.blank?
+      commontable.send(config.comment_edited_callback, user, comment) unless commontable.blank? || config.comment_edited_callback.blank?
     end
     
     def comment_deleted_callback(user, comment)
-      commontable.send(config.comment_deleted_callback, user, comment) unless config.comment_deleted_callback.blank?
+      commontable.send(config.comment_deleted_callback, user, comment) unless commontable.blank? || config.comment_deleted_callback.blank?
     end
     
     def thread_closed_callback(user)
-      commontable.send(config.thread_closed_callback, user) unless config.thread_closed_callback.blank?
+      commontable.send(config.thread_closed_callback, user) unless commontable.blank? || config.thread_closed_callback.blank?
     end
     
     def subscribe_callback(user)
-      commontable.send(config.subscribe_callback, user) unless config.subscribe_callback.blank?
+      commontable.send(config.subscribe_callback, user) unless commontable.blank? || config.subscribe_callback.blank?
     end
           
     def unsubscribe_callback(user)
-      commontable.send(config.unsubscribe_callback, user) unless config.unsubscribe_callback.blank?
+      commontable.send(config.unsubscribe_callback, user) unless commontable.blank? || config.unsubscribe_callback.blank?
     end
 
     ##########################
@@ -122,20 +125,19 @@ module Commontator
     ##########################
 
     def can_be_read_by?(user) # Reader and poster capabilities
-      ((!is_closed? || config.closed_threads_are_readable) &&\
+      (!commontable.blank? && (!is_closed? || config.closed_threads_are_readable) &&\
         config.can_read_thread_method.blank? ? true : commontable.send(config.can_read_thread_method, user)) ||\
         can_be_edited_by?(user)
     end
 
     def can_be_edited_by?(user) # Thread admin capabilities
-      config.can_edit_thread_method.blank? ?
+      !commontable.blank? && (config.can_edit_thread_method.blank? ?
         (user.commontator_config.is_admin_method.blank? ? false : user.send(user.commontator_config.is_admin_method)) :
-        commontable.send(config.can_edit_thread_method, user)
+        commontable.send(config.can_edit_thread_method, user))
     end
 
     def can_subscribe?(user)
-      config.can_subscribe_to_thread && can_be_read_by?(user)
+      !commontable.blank? && config.can_subscribe_to_thread && can_be_read_by?(user)
     end
-
   end
 end

data/config/initializers/commontator.rb

@@ -1,7 +1,164 @@
-# Example initializer
-
+# Change the settings below to suit your needs
+# All settings are initially set to their default values
 Commontator.configure do |config|
 
-  #config.current_user_method = :current_user
+  # Engine Configuration
+
+  # Method called on ApplicationController to return the current user
+  # Default: 'current_user'
+  config.current_user_method = 'current_user'
+
+  # Proc that is called when a view wants to set the page heading.
+  # Default: Proc.new {}
+  config.heading_proc = nil
+
+  # Proc that is called after any javascript runs (e.g. to clear flash notices)
+  # Default: Proc.new {}
+  config.javascript_proc = nil
+
+
+  # Commontator (User model) Configuration
+
+  # Whether the commontator's name is clickable in the comment view
+  # Default: false
+  config.commontator_name_clickable = false
+
+  # The method that return the commontator's email address
+  # Default: 'email'
+  config.commontator_email_method = 'email'
+
+  # The method that return the commontator's name
+  # Default: '' (Anonymous)
+  config.commontator_name_method = ''
+
+  # Method that returns true if the commontator is an admin for all threads
+  # Admins can always delete other users' comments and close threads
+  # Default: '' (no admins)
+  config.is_admin_method = ''
+
+
+  # Commontable (Commentable model) Configuration
+
+  # What a comment is called in your application
+  # Default: 'comment'
+  config.comment_name = 'comment'
+
+  # Verb used when creating comments (present)
+  # Default: 'post'
+  config.comment_create_verb_present = 'post'
+
+  # Verb used when creating comments (past)
+  # Default: 'posted'
+  config.comment_create_verb_past = 'posted'
+
+  # What a commontable is called in your application
+  # If you have multiple commontable models,
+  # you might want to pass this configuration value
+  # as an argument to acts_as_commontable in each one
+  # Default: 'commontable'
+  config.commontable_name = 'commontable'
+
+  # Proc that returns the subscription email subject
+  # Default: Proc.new {}
+  config.subscription_email_subject_proc = Proc.new {|params| \
+    "#{params[:commontator_name]} #{params[:config].comment_create_verb_past} a " + \
+    "#{params[:config].comment_name} on #{params[:commontable_name]} ##{params[:commontable_id]}"}
+
+  # The format of the timestamps used by Commontator
+  # Default: '%b %d %Y, %I:%M %p'
+  config.timestamp_format = '%b %d %Y, %I:%M %p'
+
+  # Whether admins can edit other users' comments
+  # Default: false
+  config.admin_can_edit_comments = false
+
+  # Whether users automatically subscribe to a thread when commenting
+  # Default: false
+  config.auto_subscribe_on_comment = false
+
+  # Whether users can edit their own comments
+  # Default: true
+  config.can_edit_own_comments = true
+
+  # Whether users can edit their own comments
+  # after someone posted a newer comment
+  # Default: false
+  config.can_edit_old_comments = false
+
+  # Whether users can delete their own comments
+  # Default: false
+  config.can_delete_own_comments = false
+
+  # Whether users can delete their own comments
+  # after someone posted a newer comment
+  # Default: false
+  config.can_delete_old_comments = false
+
+  # Whether users can manually subscribe or unsubscribe to threads
+  # Default: true
+  config.can_subscribe_to_thread = true
+
+  # Whether users can vote on other users' comments
+  # Note: requires acts_as_votable gem installed
+  # and configured for your application
+  # Default: false
+  config.comments_can_be_voted_on = false
+
+  # Whether comments should be ordered by vote score
+  # instead of by order posted
+  # Default: false
+  config.comments_ordered_by_votes = false
+
+  # Whether users can read threads closed by admins
+  # Default: true
+  config.closed_threads_are_readable = true
+
+  # Whether comments deleted by admins can be seen
+  # (the content will still be hidden)
+  # Default: true
+  config.deleted_comments_are_visible = true
+
+  # Method called on commontable to return its id
+  # Default: 'id'
+  config.commontable_id_method = 'id'
+
+  # Method called on commontable and passed user as argument
+  # If true, that user is an admin for that particular commontable's thread
+  # Default: '' (no thread-specific admins)
+  config.can_edit_thread_method = ''
+
+  # Method called on commontable and passed user as argument
+  # If true, that user is allowed to read that commontable's thread
+  # Default: '' (no read restrictions)
+  config.can_read_thread_method = ''
+
+  # Method called on commontable when a comment is created
+  # Passed user, comment as arguments
+  # Default: '' (no callback)
+  config.comment_created_callback = ''
+
+  # Method called on commontable when a comment is edited
+  # Passed user, comment as arguments
+  # Default: '' (no callback)
+  config.comment_edited_callback = ''
+
+  # Method called on commontable when a comment is deleted
+  # Passed user, comment as arguments
+  # Default: '' (no callback)
+  config.comment_deleted_callback = ''
+
+  # Method called on commontable when a thread is closed
+  # Passed user as argument
+  # Default: '' (no callback)
+  config.thread_closed_callback = ''
+
+  # Method called on commontable when a thread is subscribed to
+  # Passed user as argument
+  # Default: '' (no callback)
+  config.subscribe_callback = ''
 
+  # Method called on commontable when a thread is unsubscribed to
+  # Passed user as argument
+  # Default: '' (no callback)
+  config.unsubscribe_callback = ''
 end