zen 0.2.8 → 0.3b

data/lib/zen/package/comments/lib/comments/controller/comments_form.rb

@@ -1,38 +1,101 @@
-#:nodoc:
 module Comments
   #:nodoc:
   module Controller
     ##
-    # Frontend controller for the comments system used for saving user-submitted
-    # comments. When the anti-spam system is enabled Zen will use Defensio to
-    # check if the comment is spam or ham.
+    # Controller that makes it possible for users to submit comments to section
+    # entries. Zen does not provide any way of generating a comment form for
+    # you and thus you'll have to do this yourself. When creating such a form
+    # you must add the following fields to it:
+    #
+    # * **section_entry** (required): an ID of a section entry where the
+    #   comments belong to.
+    # * **user_id**: the ID of the currently logged in user (if any). If this ID
+    #   isn't specified the "name" and "Email" fields are required.
+    # * **comment**: the text of the comment.
+    # * **name**: the name of the author, required when the "user_id" field is
+    #   empty.
+    # * **website**: the website of the user, if any.
+    # * **email**: the Email address of the user, required if the "user_id"
+    #   field is empty.
+    #
+    # An example of such a form looks like the code below. Note that this block
+    # of code should be wrapped in a ``#{}`` tag.
+    #
+    #     form_for(
+    #       flash[:form_data],
+    #       :method => :post,
+    #       :action => Comments::Controller::CommentsForm.r(:save)
+    #     ) do |f|
+    #       if logged_in?
+    #         f.input_hidden(:user_id, user.id)
+    #       end
+    #
+    #       f.input_hidden(:section_entry, 10)
+    #
+    #       # No need to show these, they'll be filled in based on the user ID.
+    #       unless logged_in?
+    #         f.input_text('Name', :name)
+    #         f.input_text('Email', :email)
+    #         f.input_text('Website', :website)
+    #       end
+    #
+    #       f.textarea('Comment', :comment)
+    #
+    #       f.input_submit('Submit')
+    #     end
+    #
+    # In the above example ``flash[:form_data]`` is used. This controller sets
+    # two objects in the flash just like the backend controllers. These are the
+    # following two items:
+    #
+    # * **form_data**: an instance of {Comments::Model::Comment}
+    # * **form_errros**: a hash containing all errors, automatically used by
+    # ``Ramaze::Helper::BlueForm`` if the form was created using the
+    # ``form_for()`` method.
+    #
+    # Note that both these objects are only set if the comment contained invalid
+    # data or the user wasn't allowed to submit the comment.
+    #
+    # In the above example the BlueForm helper was used but you're free to use
+    # plain old HTML or another helper if you like. If you want to use a helper
+    # you'll have to load it into {Zen::Controller::MainController}. This can
+    # be done as following:
+    #
+    #     Zen::Controller::MainController.helper(:some_helper_name)
+    #
+    # ## Events
+    #
+    # Just like {Comments::Controller::Comments} newly created comments are
+    # passed to an event called "new_comment".
+    #
+    # @example Logging whenever a new comment is created
+    #  Zen::Event.call(:new_comment) do |comment|
+    #    Ramaze::Log.info(
+    #      "A new comment has been created with ID ##{comment.id}"
+    #    )
+    #  end
     #
-    # @author Yorick Peterse
     # @since  0.1
+    # @map    /comments-form
+    # @event  before_new_comment
+    # @event  after_new_comment
     #
     class CommentsForm < Zen::Controller::FrontendController
-      include ::Comments::Model
-
-      map '/comments-form'
+      map    '/comments-form'
       helper :message
 
-      before_all do
-        csrf_protection(:save) do
-          respond(lang('zen_general.errors.not_authorized'), 403)
-        end
-      end
+      csrf_protection :save
 
       ##
       # Creates a new comment for the section entry. Once the comment has been
       # saved the user will be redirected back to the previous page.
       #
-      # @author Yorick Peterse
       # @since  0.1
+      # @event  before_new_comment
+      # @event  after_new_comment
       #
       def save
-        Zen::Language.load('comments')
-
-        comment = Comment.new
+        comment = ::Comments::Model::Comment.new
         post    = request.subset(
           :section_entry,
           :user_id,
@@ -44,7 +107,7 @@ module Comments
 
         # Get all the comment statuses.
         comment_statuses = {}
-        draft_status     = Sections::Model::SectionEntryStatus[
+        draft_status     = ::Sections::Model::SectionEntryStatus[
           :name => 'draft'
         ].id
 
@@ -71,7 +134,7 @@ module Comments
         end
 
         # Validate the section entry
-        if entry.nil? or entry.section_entry_status_id === draft_status
+        if entry.nil? or entry.section_entry_status_id == draft_status
           message(:error, lang('comments.errors.invalid_entry'))
           redirect_referrer
         end
@@ -86,29 +149,47 @@ module Comments
         end
 
         # Comments allowed?
-        if section.comment_allow === false
+        if section.comment_allow == false
           message(:error, lang('comments.errors.comments_not_allowed'))
           redirect_referrer
         end
 
         # Comments require an account?
-        if section.comment_require_account === true and session[:user].nil?
+        if section.comment_require_account == true and !logged_in?
           message(:error, lang('comments.errors.comments_require_account'))
           redirect_referrer
         end
 
         # Require moderation?
-        if section.comment_moderate === true
+        if section.comment_moderate == true
           comment.comment_status_id = comment_statuses['closed']
         end
 
-        # Require anti-spam validation?
-        if plugin(:settings, :get, :enable_antispam).value === '1'
-          engine = plugin(:settings, :get, :anti_spam_system).value.to_sym
-          spam   = plugin(:anti_spam, engine, nil, nil, nil, post['comment'])
+        # Get the details for the anti spam plugin
+        if !post['user_id'].nil? and !post['user_id'].empty?
+          user  = ::Users::Model::User[post['user_id']]
+          name  = user.name
+          email = user.email
+          url   = user.website
+        else
+          name  = post['name']
+          email = post['email']
+          url   = post['website']
+        end
 
-          # Time to validate the Defensio response
-          if spam === false
+        # Require anti-spam validation?
+        if get_setting(:enable_antispam).true?
+          engine = get_setting(:anti_spam_system).value
+          spam   = ::Comments::AntiSpam.validate(
+            engine,
+            name,
+            email,
+            url,
+            post['comment']
+          )
+
+          # Is it spam?
+          if spam == false
             if section.comment_moderate == true
               comment.comment_status_id = comment_statuses['closed']
             else
@@ -121,18 +202,25 @@ module Comments
 
         # Save the comment
         begin
+          Zen::Event.call(:before_new_comment, comment)
           comment.save
-
-          if section.comment_moderate == true
-            message(:success, lang('comments.success.moderate'))
-          else
-            message(:success, lang('comments.success.new'))
-          end
         rescue => e
           Ramaze::Log.error(e.inspect)
           message(:error, lang('comments.errors.new'))
+
+          flash[:form_data]   = comment
+          flash[:form_errors] = comment.errors
+
+          redirect_referrer
+        end
+
+        if section.comment_moderate == true
+          message(:success, lang('comments.success.moderate'))
+        else
+          message(:success, lang('comments.success.new'))
         end
 
+        Zen::Event.call(:after_new_comment, comment)
         redirect_referrer
       end
     end # CommentsForm

data/lib/zen/package/comments/lib/comments/helper/comment.rb

@@ -1,11 +1,9 @@
-#:nodoc:
 module Ramaze
   #:nodoc:
   module Helper
     ##
     # Helper used by the comments package.
     #
-    # @author Yorick Peterse
     # @since  0.2.8
     #
     module Comment
@@ -15,7 +13,6 @@ module Ramaze
       # returned, otherwise the user is redirected back to the comment overview
       # and is shown a message.
       #
-      # @author Yorick Peterse
       # @since  0.2.8
       # @param  [Fixnum] comment_id The ID of the comment to validate.
       # @return [Comments::Model::Comment]

data/lib/zen/package/comments/lib/comments/helper/comment_frontend.rb

@@ -0,0 +1,90 @@
+module Ramaze
+  module Helper
+    ##
+    # Helper that provides the means to retrieve comments in your templates.
+    #
+    # @since  0.3
+    #
+    module CommentFrontend
+      ##
+      # Retrieves a list of comments by a section entry's ID or slug and
+      # optionally paginates these comments.
+      #
+      # When paginating the results the default values for the ``:var`` and
+      # ``:limit`` options are taken from
+      # ``Zen::Controller::FrontendController.ancestral_trait[:paginate]``.
+      #
+      # @example Looping over a set of comments
+      #  get_comments(5).each do |comment|
+      #    puts comment.html
+      #  end
+      #
+      # @example Paginating the comments
+      #  comments = get_comments(5, :paginate => true)
+      #
+      #  comments.each do |comment|
+      #    puts comment.user_name
+      #  end
+      #
+      #  comments.navigation
+      #
+      # @since  0.3
+      # @param  [String|Fixnum] entry Either the slug of an entry or the ID of an
+      #  entry for which to retrieve all comments.
+      # @param  [Hash] options A hash containing various options to customize
+      #  the return value.
+      # @option options [TrueClass|FalseClass] :paginate Whether or not the
+      #  results should be paginated. This only works inside an action.
+      # @option options [Fixnum] :limit The amount of comments to retrieve.
+      # @option options [String] :var The name of the query string that contains
+      #  the current page.
+      # @return [Mixed]
+      #
+      def get_comments(entry, options = {})
+        trait   = Zen::Controller::FrontendController.ancestral_trait[:paginate]
+        options = {
+          :paginate => false,
+          :limit    => trait[:limit],
+          :var      => trait[:var]
+        }.merge(options)
+
+        query = Comments::Model::Comment.select_all(:comments)
+        query = query.join(
+          :comment_statuses,
+          :comments__comment_status_id => :comment_statuses__id
+        )
+
+        # Add the section entry to the comment so that the comments can be
+        # filtered by the IDs/slugs without having to use a separate query.
+        query = query.join(
+          :section_entries,
+          :comments__section_entry_id => :section_entries__id
+        )
+
+        if entry.is_a?(String)
+          query = query.filter(:section_entries__slug => entry)
+        else
+          query = query.filter(:section_entries__id => entry)
+        end
+
+        # Only show comments with a status of "Open"
+        query = query.filter(:comment_statuses__name => 'open')
+        query = query.eager(:user, :section_entry)
+
+        if options[:paginate] == true and respond_to?(:paginate)
+          return paginate(
+            query,
+            :var   => options[:var],
+            :limit => options[:limit]
+          )
+        else
+          if options[:limit]
+            query = query.limit(options[:limit])
+          end
+
+          return query
+        end
+      end
+    end # CommentFrontend
+  end # Helper
+end # Ramaze

data/lib/zen/package/comments/lib/comments/language/en/comments.rb

@@ -0,0 +1,57 @@
+Zen::Language::Translation.add do |trans|
+  trans.language = 'en'
+  trans.name     = 'comments'
+
+  trans.translate do |t|
+    t['titles.index'] = 'Comments'
+    t['titles.edit']  = 'Edit Comment'
+
+    t['labels.id']               = '#'
+    t['labels.website']          = 'Website'
+    t['labels.entry']            = 'Section Entry'
+    t['labels.email']            = 'Email'
+    t['labels.status']           = 'Status'
+    t['labels.comment']          = 'Comment'
+    t['labels.name']             = 'Name'
+    t['labels.created_at']       = 'Created'
+    t['labels.updated_at']       = 'Updated'
+    t['labels.defensio']         = 'Defensio'
+    t['labels.anti_spam_system'] = 'Anti-spam System'
+    t['labels.open']             = 'Open'
+    t['labels.closed']           = 'Closed'
+    t['labels.spam']             = 'Spam'
+    t['labels.defensio_key']     = 'Defensio Key'
+
+    t['messages.no_comments'] = 'No comments were found.'
+
+    t['descriptions.anti_spam_system'] = 'The anti-spam system to use for ' \
+      'validating comments.'
+    t['description.defensio_key'] = 'The API key for the Defensio anti-spam ' \
+      'system.'
+
+    t['success.new']      = 'The comment has been created.'
+    t['success.save']     = 'The comment has been modified.'
+    t['success.delete']   = 'The selected comments have been deleted.'
+    t['success.moderate'] = 'The comment has been posted but must be approved ' \
+      'by a moderator before it will be displayed.'
+
+    t['errors.new']                  = 'Failed to create the new comment.'
+    t['errors.save']                 = 'Failed to modify the comment.'
+    t['errors.delete']               = 'Failed to delete the comment with ID #%s.'
+    t['errors.no_delete']            = 'You need to specify a comment to delete.'
+    t['errors.invalid_entry']        = 'The specified section entry is invalid.'
+    t['errors.comments_not_allowed'] = 'Comments are not allowed for this section.'
+    t['errors.comments_require_account'] = 'You have to be logged in in order ' \
+      'to post a comment.'
+    t['errors.invalid_comment'] = 'The specified comment is invalid.'
+
+    t['buttons.delete'] = 'Delete selected comments'
+    t['buttons.save']   = 'Save comment'
+
+    t['permissions.show']   = 'Show comment'
+    t['permissions.edit']   = 'Edit comment'
+    t['permissions.delete'] = 'Delete comment'
+
+    t['description'] = 'Manage comments'
+  end
+end

data/lib/zen/package/comments/lib/comments/language/nl/comments.rb

@@ -0,0 +1,61 @@
+# encoding: utf-8
+
+Zen::Language::Translation.add do |trans|
+  trans.language = 'nl'
+  trans.name     = 'comments'
+
+  trans.translate do |t|
+    t['titles.index'] = 'Reacties'
+    t['titles.edit']  = 'Reactie aanpassen'
+
+    t['labels.id']               = '#'
+    t['labels.website']          = 'Website'
+    t['labels.entry']            = 'Sectie artikel'
+    t['labels.email']            = 'Email'
+    t['labels.stats']            = 'Status'
+    t['labels.comment']          = 'Reactie'
+    t['labels.name']             = 'Naam'
+    t['labels.created_at']       = 'Aangemaakt'
+    t['labels.updated_at']       = 'Aangepast'
+    t['labels.defensio']         = 'Defensio'
+    t['labels.anti_spam_system'] = 'Anti-spam systeem'
+    t['labels.open']             = 'Open'
+    t['labels.closed']           = 'Gesloten'
+    t['labels.spam']             = 'Spam'
+    t['labels.defensio_key']     = 'Defensio sleutel'
+
+    t['messages.no_comments'] = 'Er konden geen reacties worden gevonden.'
+
+    t['descriptions.anti_spam_system'] = 'Het anti-spam systeem dat gebruikt ' \
+      'moet worden voor het verifiëren van reacties.'
+    t['descriptions.defensio_key'] = 'De API sleutel voor het Defensio ' \
+      'anti-spam systeem.'
+
+    t['success.new']      = 'De reactie is aangemaakt.'
+    t['success.save']     = 'De reactie is aangepast.'
+    t['success.delete']   = 'De geselecteerde reacties zijn verwijderd.'
+    t['success.moderate'] = 'De reactie is aangemaakt en zal worden ' \
+      'weergegeven zodra deze is goedgekeurd.'
+
+    t['errors.new']           = 'De reactie kon niet worden aangemaakt.'
+    t['errors.save']          = 'De reactie kon niet worden aangepast.'
+    t['errors.delete']        = 'De reactie met ID #%s kon niet worden verwijderd.'
+    t['errors.no_delete']     = 'U moet een reactie opgeven om te verwijderen.'
+    t['errors.invalid_entry'] = 'Het opgegeven artikel is ongeldig.'
+
+    t['errors.comments_not_allowed'] = 'Reacties zijn niet toegestaan voor ' \
+      'deze sectie.'
+    t['errors.comments_require_account'] = 'U moet ingelogd zijn om een ' \
+      'reactie te kunnen plaatsen.'
+    t['errors.invalid_comment'] = 'De opgegeven reactie is ongeldig.'
+
+    t['buttons.delete'] = 'Reacties verwijderen'
+    t['buttons.save']   = 'Reactie opslaan'
+
+    t['permissions.show']   = 'Reactie weergeven'
+    t['permissions.edit']   = 'Reactie aanpassen'
+    t['permissions.delete'] = 'Reactie verwijderen'
+
+    t['description'] = 'Reacties beheren'
+  end
+end