config/initializers/commontator.rb in commontator-4.5.4 vs config/initializers/commontator.rb in commontator-4.6.0

@@ -1,125 +1,177 @@
 # Change the settings below to suit your needs
 # All settings are initially set to their default values
 
-# Note: Do not "return" from procs
-#       Use "next" instead
+# Note: Do not "return" from a Proc, use "next" instead if necessary
+#       "return" in a lambda is OK
 Commontator.configure do |config|
   # Engine Configuration
 
-  # Proc that is passed the current controller as argument
-  # Returns the current user
+  # current_user_proc
+  # Type: Proc
+  # Arguments: the current controller (ActionController::Base)
+  # Returns: the current user (acts_as_commontator)
+  # The default works for Devise and similar authentication plugins
   # Default: lambda { |controller| controller.current_user }
   config.current_user_proc = lambda { |controller| controller.current_user }
 
-  # Proc called with the current view_context as argument
-  # Returns a string to be appended to all JavaScript responses from Commontator
+  # javascript_proc
+  # Type: Proc
+  # Arguments: a view (ActionView::Base)
+  # Returns: a String that is appended to Commontator JS views
   # Can be used, for example, to display/clear Rails error messages
-  # Objects visible in view templates can be accessed through
-  # the view_context object (for example, view_context.flash)
-  # However, the view_context does not include the main application's helpers
-  # Default: lambda { |view_context| '$("#error_explanation").remove();' }
-  config.javascript_proc = lambda { |view_context|
+  # Objects visible in view templates can be accessed
+  # through the view object (for example, view.flash)
+  # However, the view does not include the main application's helpers
+  # Default: lambda { |view| '$("#error_explanation").remove();' }
+  config.javascript_proc = lambda { |view|
                                     '$("#error_explanation").remove();' }
 
 
 
   # User (acts_as_commontator) Configuration
 
-  # Proc called with a user as argument
-  # Returns the user's display name
-  # Important: change this to return actual names or usernames
-  # Default: lambda { |user| t('commontator.anonymous') } (all users are Anonymous)
+  # user_name_proc
+  # Type: Proc
+  # Arguments: a user (acts_as_commontator)
+  # Returns: the user's name (String)
+  # Default: lambda { |user| I18n.t('commontator.anonymous') } (all users are anonymous)
   config.user_name_proc = lambda { |user| I18n.t('commontator.anonymous') }
 
-  # Proc called with a user and the current view_context as arguments
-  # Returns an HTML image tag containing the user's avatar image
+  # user_link_proc
+  # Type: Proc
+  # Arguments: a user (acts_as_commontator),
+  #            the app_routes (ActionDispatch::Routing::RoutesProxy)
+  # Returns: a path to the user's `show` page (String)
+  # If anything non-blank is returned, the user's name in comments
+  # comments will become a hyperlink pointing to this path
+  # The main application's routes can be accessed through the app_routes object
+  # Default: lambda { |user, app_routes| '' } (no link)
+  config.user_link_proc = lambda { |user, app_routes| '' }
+
+  # user_avatar_proc
+  # Type: Proc
+  # Arguments: a user (acts_as_commontator), a view (ActionView::Base)
+  # Returns: a String containing a HTML <img> tag pointing to the user's avatar image
   # The commontator_gravatar_image_tag helper takes a user object,
-  # a border size, and an options hash for gravatar
+  # a border size and an options hash for Gravatar, and produces a Gravatar image tag
   # See available options at http://en.gravatar.com/site/implement/images/)
-  # Default: lambda { |user, view_context|
-  #            view_context.commontator_gravatar_image_tag(
+  # Note: Gravatar has several security implications for your users
+  #       It makes your users trackable across different sites and
+  #       allows de-anonymization attacks against their email addresses
+  #       If you absolutely want to keep users' email addresses or identities secret,
+  #       do not use Gravatar or similar services
+  # Default: lambda { |user, view|
+  #            view.commontator_gravatar_image_tag(
   #              user, 1, :s => 60, :d => 'mm') }
-  config.user_avatar_proc = lambda { |user, view_context|
-                                     view_context.commontator_gravatar_image_tag(
+  config.user_avatar_proc = lambda { |user, view|
+                                     view.commontator_gravatar_image_tag(
                                        user, 1, :s => 60, :d => 'mm') }
 
-  # Proc called with a user and a mailer object as arguments
-  # If the mailer argument is nil, the email is for internal use only and
-  # this method should always return the user's email, no matter what
-  # If the mailer argument is not nil, then an actual email will be sent to the
-  # address returned; you can prevent it from being sent by checking the
-  # arguments and returning a blank string, if appropriate
-  # Default: lambda { |user, mailer| user.email }
-  config.user_email_proc = lambda { |user, mailer| user.email }
+  # user_email_proc
+  # Type: Proc
+  # Arguments: a user (acts_as_commontator), a mailer (ActionMailer::Base)
+  # Returns: the user's email address (String)
+  # The default works for Devise's defaults
+  # If the mailer argument is nil, Commontator intends to hash the email and send the hash
+  # to Gravatar, so you should always return the user's email address (if using Gravatar)
+  # If the mailer argument is not nil, then Commontator intends to send an email to
+  # the address returned; you can prevent it from being sent by returning a blank String
+  # Default: lambda { |user, mailer| user.try(:email) || '' }
+  config.user_email_proc = lambda { |user, mailer| user.try(:email) || '' }
 
-  # Proc called with a user and the current view_context as arguments
-  # Returns a link to the user's page
-  # If anything non-blank is returned, the user's name in comments
-  # will become a hyperlink pointing to this
-  # The main application's routes can be accessed through the main_app object
-  # Default: lambda { |user, main_app| '' } (no link)
-  config.user_link_proc = lambda { |user, main_app| '' }
 
 
-
   # Thread/Commontable (acts_as_commontable) Configuration
 
-  # Proc called with a mailer object as argument
-  # Returns the address emails are sent "from"
-  # Important: Change this to at least match your domain name
-  # Default: lambda { |mailer| '[e-mail]' }
-  config.email_from_proc = lambda { |mailer| '[e-mail]' }
+  # comment_filter
+  # Type: Arel node (Arel::Nodes::Node) or nil
+  # Arel that filters visible comments
+  # If specified, visible comments will be filtered according to this Arel node
+  # A value of nil will cause no filtering to be done
+  # Moderators can manually override this filter for themselves
+  # Example: Commontator::Comment.arel_table[:deleted_at].eq(nil) (hides deleted comments)
+  #          This is not recommended, as it can cause confusion over deleted comments
+  #          If using pagination, it can also cause comments to change pages
+  # Default: nil (no filtering - all comments are visible)
+  config.comment_filter = nil
 
-  # Proc called with a thread and a user as arguments
-  # Returns true iif the user should be allowed to read that thread
-  # Note: can be called with a user object that is false or nil if not logged in
+  # thread_read_proc
+  # Type: Proc
+  # Arguments: a thread (Commontator::Thread), a user (acts_as_commontator)
+  # Returns: a Boolean, true iif the user should be allowed to read that thread
+  # Note: can be called with a user object that is nil (if they are not logged in)
   # Default: lambda { |thread, user| true } (anyone can read any thread)
   config.thread_read_proc = lambda { |thread, user| true }
 
-  # Proc called with a thread and a user as arguments
-  # Returns true iif the user is a moderator for that thread
-  # Moderators can delete other users' comments and close threads
-  # If you want global moderators, make this proc true for them
-  # Note: moderators must "acts_as_commontator" too (like other users)
+  # thread_moderator_proc
+  # Type: Proc
+  # Arguments: a thread (Commontator::Thread), a user (acts_as_commontator)
+  # Returns: a Boolean, true iif the user is a moderator for that thread
+  # If you want global moderators, make this proc true for them regardless of thread
   # Default: lambda { |thread, user| false } (no moderators)
   config.thread_moderator_proc = lambda { |thread, user| false }
 
-  # Whether users can subscribe to threads to receive activity email notifications
+  # comment_editing
+  # Type: Symbol
+  # Whether users can edit their own comments
   # Valid options:
-  #   :n (no subscriptions)
-  #   :a (automatically subscribe when you comment; cannot do it manually)
-  #   :m (manual subscriptions only)
-  #   :b (both automatic, when commenting, and manual)
-  # Default: :m
-  config.thread_subscription = :m
+  #   :a (always)
+  #   :l (only if it's the latest comment)
+  #   :n (never)
+  # Default: :l
+  config.comment_editing = :l
 
+  # comment_deletion
+  # Type: Symbol
+  # Whether users can delete their own comments
+  # Valid options:
+  #   :a (always)
+  #   :l (only if it's the latest comment)
+  #   :n (never)
+  # Note: For moderators, see the next option
+  # Default: :l
+  config.comment_deletion = :l
+
+  # moderator_permissions
+  # Type: Symbol
+  # What permissions moderators have
+  # Valid options:
+  #   :e (delete and edit comments and close threads)
+  #   :d (delete comments and close threads)
+  #   :c (close threads only)
+  # Default: :d
+  config.moderator_permissions = :d
+
+  # comment_voting
+  # Type: Symbol
   # Whether users can vote on other users' comments
   # Valid options:
-  #   :n (no voting)
-  #   :l (likes - requires acts_as_votable gem)
+  #   :n  (no voting)
+  #   :l  (likes - requires acts_as_votable gem)
   #   :ld (likes/dislikes - requires acts_as_votable gem)
   # Not yet implemented:
-  #   :s (star ratings)
-  #   :r (reputation system)
-  # Note: you can format how the votes are displayed by modifying the locale file
+  #   :s  (star ratings)
+  #   :r  (reputation system)
   # Default: :n
   config.comment_voting = :n
 
-  # This proc is called with the value of config.comment_voting as an argument,
-  # as well as pos and neg
-  # pos is the number of likes or the rating or the reputation
+  # vote_count_proc
+  # Type: Proc
+  # Arguments: a thread (Commontator::Thread), pos (Fixnum), neg (Fixnum)
+  # Returns: vote count to be displayed (String)
+  # pos is the number of likes, or the rating, or the reputation
   # neg is the number of dislikes, if applicable, or 0 otherwise
-  # Returns the text to be displayed in between the voting buttons
-  # Default: lambda { |comment_voting, pos, neg| "%+d" % (pos - neg) }
-  config.voting_text_proc = lambda { |comment_voting, pos, neg|
-                                     "%+d" % (pos - neg) }
+  # Default: lambda { |thread, pos, neg| "%+d" % (pos - neg) }
+  config.vote_count_proc = lambda { |thread, pos, neg| "%+d" % (pos - neg) }
 
+  # comment_order
+  # Type: Symbol
   # What order to use for comments
   # Valid options:
-  #   :e (earliest comment first)
-  #   :l (latest comment first)
+  #   :e  (earliest comment first)
+  #   :l  (latest comment first)
   #   :ve (highest voted first; earliest first if tied)
   #   :vl (highest voted first; latest first if tied)
   # Notes:
   #   :e is usually used in forums (discussions)
   #   :l is usually used in blogs (opinions)
@@ -128,74 +180,59 @@
   # If :l is selected, the "reply to thread" form will appear before the comments
   # Otherwise, it will appear after the comments
   # Default: :e
   config.comment_order = :e
 
+  # comments_per_page
+  # Type: Fixnum or nil
   # Number of comments to display in each page
   # Set to nil to disable pagination
   # Any other value requires the will_paginate gem
   # Default: nil (no pagination)
   config.comments_per_page = nil
 
-  # Proc called with a thread as argument
-  # Returns a LinkRenderer to be used with will_paginate for that thread,
-  # assuming pagination is enabled
-  # Commontator supplies its own RemoteLinkRenderer,
-  # which is exactly like will_paginate's default, except it returns remote links
-  # For more information, see:
-  # https://github.com/mislav/will_paginate/wiki/Link-renderer
-  # Default: lambda { |thread| Commontator::RemoteLinkRenderer }
-  config.wp_link_renderer_proc = lambda { |thread|
-                                          Commontator::RemoteLinkRenderer }
-
-  # Whether users can edit their own comments
+  # thread_subscription
+  # Type: Symbol
+  # Whether users can subscribe to threads to receive activity email notifications
   # Valid options:
-  #   :a (always)
-  #   :l (only if it's the latest comment)
-  #   :n (never)
-  # Default: :l
-  config.comment_editing = :l
+  #   :n (no subscriptions)
+  #   :a (automatically subscribe when you comment; cannot do it manually)
+  #   :m (manual subscriptions only)
+  #   :b (both automatic, when commenting, and manual)
+  # Default: :n
+  config.thread_subscription = :n
 
-  # Whether users can delete their own comments
-  # Valid options:
-  #   :a (always)
-  #   :l (only if it's the latest comment)
-  #   :n (never)
-  # Note: moderators can always delete any comment
-  # Default: :l
-  config.comment_deletion = :l
+  # email_from_proc
+  # Type: Proc
+  # Arguments: a thread (Commontator::Thread)
+  # Returns: the address emails are sent "from" (String)
+  # Important: If using subscriptions, change this to at least match your domain name
+  # Default: lambda { |thread|
+  #                   "no-reply@#{Rails.application.class.parent.to_s.downcase}.com" }
+  config.email_from_proc = lambda { |thread|
+    "no-reply@#{Rails.application.class.parent.to_s.downcase}.com" }
 
-  # Whether moderators can edit other users' comments
-  # Default: false
-  config.moderators_can_edit_comments = false
+  # commontable_name_proc
+  # Type: Proc
+  # Arguments: a thread (Commontator::Thread)
+  # Returns: a name that refers to the commontable object (String)
+  # If you have multiple commontable models, you can also pass this
+  # configuration value as an argument to acts_as_commontable for each one
+  # Default: lambda { |thread|
+  #                   "#{thread.commontable.class.name} ##{thread.commontable.id}" }
+  config.commontable_name_proc = lambda { |thread|
+    "#{thread.commontable.class.name} ##{thread.commontable.id}" }
 
-  # Whether to hide deleted comments completely or show a placeholder message
-  # that indicates when a comment was deleted in a thread
-  # (moderators will always see the placeholder;
-  # the content of the comment will be hidden from all users with either option)
-  # Default: false (show placeholder message)
-  config.hide_deleted_comments = false
-
-  # If set to true, threads closed by moderators will be invisible to normal users
-  # (moderators can still see them)
-  # Default: false (normal users can still read closed threads)
-  config.hide_closed_threads = false
-
-  # Proc called with the commontable object as argument
-  # Returns the name by which the commontable object will be called in email messages
-  # If you have multiple commontable models, you may want to pass this
-  # configuration value as an argument to acts_as_commontable in each one
-  # Default: lambda { |commontable|
-  #            "#{commontable.class.name} ##{commontable.id}" }
-  config.commontable_name_proc = lambda { |commontable|
-    "#{commontable.class.name} ##{commontable.id}" }
-
-  # Proc called with main_app and a commontable object as arguments
-  # Return the url that contains the commontable's thread
+  # commontable_url_proc
+  # Type: Proc
+  # Arguments: a thread (Commontator::Thread),
+  #            the app_routes (ActionDispatch::Routing::RoutesProxy)
+  # Returns: a String containing the url of the view that displays the given thread
   # This usually is the commontable's "show" page
-  # The main application's routes can be accessed through the main_app object
-  # Default: lambda { |commontable, main_app|
-  #            main_app.polymorphic_url(commontable) }
+  # The main application's routes can be accessed through the app_routes object
+  # Default: lambda { |commontable, app_routes|
+  #            app_routes.polymorphic_url(commontable) }
   # (defaults to the commontable's show url)
-  config.commontable_url_proc = lambda { |commontable, main_app|
-    main_app.polymorphic_url(commontable) }
+  config.commontable_url_proc = lambda { |thread, app_routes|
+    app_routes.polymorphic_url(thread.commontable) }
 end
+