zen 0.2.8 → 0.3b

data/lib/zen/package/categories/lib/categories/view/admin/category-groups/form.xhtml

@@ -1,38 +1,36 @@
-<article>
+<section>
     <header>
         <h1>#{get_breadcrumbs}</h1>
     </header>
-    
-    #{
-    form_for(
-      @category_group, 
-      :method => :post, 
-      :action => Categories::Controller::CategoryGroups.r(:save), 
+
+    #{form_for(
+      @category_group,
+      :method => :post,
+      :action => Categories::Controller::CategoryGroups.r(:save),
       :id     => :category_group_form
     ) do |f|
       f.input_hidden(:id        , @category_group.id)
       f.input_hidden(:csrf_token, get_csrf_token)
-      
+
       f.input_text(
-        lang('category_groups.labels.name'), 
-        :name, 
-        :placeholder => lang('category_groups.placeholders.name'), 
-        :required    => :required,
-        :maxlength   => 255
+        lang('category_groups.labels.name'),
+        :name,
+        :title     => lang('category_groups.descriptions.name'),
+        :required  => :required,
+        :maxlength => 255
       )
 
       f.textarea(
-        lang('category_groups.labels.description'), 
-        :description, 
+        lang('category_groups.labels.description'),
+        :description,
         :rows => 8
       )
-      
+
       f.g.div(:class => 'button') do
         f.g.input(
-          :type  => 'submit', 
+          :type  => 'submit',
           :value => lang('category_groups.buttons.save')
         )
       end
-    end
-    }
-</article>
+    end}
+</section>

data/lib/zen/package/categories/lib/categories/view/admin/category-groups/index.xhtml

@@ -1,4 +1,6 @@
-<article>
+<section>
+    #{render_search_form(::Categories::Controller::CategoryGroups.r(:index))}
+
     <header>
         <h1>#{get_breadcrumbs}</h1>
     </header>
@@ -8,10 +10,11 @@
         <input type="hidden" name="csrf_token" value="#{get_csrf_token}" />
 
         <?r if !@category_groups.empty? ?>
+
         <table>
             <thead>
                 <tr>
-                    <?r if user_authorized?([:delete]) ?>
+                    <?r if user_authorized?(:delete_category_group) ?>
                     <th class="no_sort">
                         <input type="checkbox" />
                     </th>
@@ -20,9 +23,7 @@
                     <th>#{lang('category_groups.labels.id')}</th>
                     <th>#{lang('category_groups.labels.name')}</th>
 
-                    <?r if user_authorized?(
-                      [:read], true, 'Categories::Controller::Categories'
-                    ) ?>
+                    <?r if user_authorized?(:show_category) ?>
                     <th></th>
                     <?r end ?>
                 </tr>
@@ -30,7 +31,7 @@
             <tbody>
                 <?r @category_groups.each do |group| ?>
                 <tr>
-                    <?r if user_authorized?([:delete]) ?>
+                    <?r if user_authorized?(:delete_category_group) ?>
                     <td>
                         <input type="checkbox" name="category_group_ids[]"
                         value="#{group.id}" />
@@ -39,19 +40,21 @@
 
                     <td>#{group.id}</td>
 
-                    <?r if user_authorized?([:update]) ?>
+                    <?r if user_authorized?(:edit_category_group) ?>
+
                     <td>
                         #{Categories::Controller::CategoryGroups.a(
                           group.name, :edit, group.id
                         )}
                     </td>
+
                     <?r else ?>
+
                     <td>#{group.name}</td>
+
                     <?r end ?>
 
-                    <?r if user_authorized?(
-                      [:read], true, 'Categories::Controller::Categories'
-                    ) ?>
+                    <?r if user_authorized?(:show_category) ?>
                     <td>
                         #{Categories::Controller::Categories.a(
                           lang('category_groups.labels.manage'),
@@ -60,24 +63,23 @@
                         )}
                     </td>
                     <?r end ?>
-
                 </tr>
                 <?r end ?>
             </tbody>
         </table>
 
-        #{
-        if @category_groups.respond_to?(:navigation) \
+        #{if @category_groups.respond_to?(:navigation) \
         and @category_groups.page_count > 1
           @category_groups.navigation
-        end
-        }
+        end}
 
         <?r else ?>
+
         <p>#{lang('category_groups.messages.no_groups')}</p>
+
         <?r end ?>
 
-        <?r if user_authorized?([:create]) ?>
+        <?r if user_authorized?(:new_category_group) ?>
         <div class="button">
             #{Categories::Controller::CategoryGroups.a(
               lang('category_groups.buttons.new'), :new
@@ -85,11 +87,12 @@
         </div>
         <?r end ?>
 
-        <?r if user_authorized?([:delete]) and !@category_groups.empty? ?>
+        <?r if user_authorized?(:delete_category_group) \
+        and !@category_groups.empty? ?>
         <div class="button">
             <input type="submit"
             value="#{lang('category_groups.buttons.delete')}" />
         </div>
         <?r end ?>
     </form>
-</article>
+</section>

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

@@ -1,66 +1,46 @@
-Ramaze::HelpersHelper.options.paths.push(__DIR__('comments'))
+Zen::Package.add do |p|
+  p.name       = :comments
+  p.title      = 'comments.titles.index'
+  p.author     = 'Yorick Peterse'
+  p.url        = 'http://zen-cms.com/'
+  p.about      = 'comments.description'
+  p.root       = __DIR__('comments')
+  p.migrations = __DIR__('../migrations')
+
+  p.menu(
+    'comments.titles.index',
+    '/admin/comments',
+    :permission => :show_comment
+  )
+
+  p.permission :show_comment  , 'comments.permissions.show'
+  p.permission :edit_comment  , 'comments.permissions.edit'
+  p.permission :delete_comment, 'comments.permissions.delete'
+end
+
+Zen::Language.load('comments')
 
 require __DIR__('comments/model/comment_status')
 require __DIR__('comments/model/comment')
 require __DIR__('comments/controller/comments')
 require __DIR__('comments/controller/comments_form')
-require __DIR__('comments/plugin/comments')
-require __DIR__('comments/plugin/anti_spam')
-
-Zen::Language.options.paths.push(__DIR__('comments'))
-Zen::Language.load('comments')
-
-Zen::Package.add do |p|
-  p.name          = 'comments'
-  p.author        = 'Yorick Peterse'
-  p.url           = 'http://yorickpeterse.com/'
-  p.about         = "Allow users to post comments on any given section entry (as long as
-the section allows it)."
+require __DIR__('comments/anti_spam')
 
-  p.directory     = __DIR__('comments')
-  p.migration_dir = __DIR__('../migrations')
-
-  p.menu = [{
-    :title => lang('comments.titles.index'),
-    :url   => "admin/comments"
-  }]
-
-  p.controllers = {
-    lang('comments.titles.index') => Comments::Controller::Comments
-  }
-end
-
-Zen::Plugin.add do |p|
-  p.name    = 'comments'
-  p.author  = 'Yorick Peterse'
-  p.url     = 'http://yorickpeterse.com/'
-  p.about   = 'Plugin that can be used to retrieve comments.'
-  p.plugin  = Comments::Plugin::Comments
-end
-
-Zen::Plugin.add do |p|
-  p.name    = 'anti_spam'
-  p.author  = 'Yorick Peterse'
-  p.url     = 'http://yorickpeterse.com/'
-  p.about   = 'Plugin used for checking if a comment is spam or ham.'
-  p.plugin  = Comments::Plugin::AntiSpam
-end
+Zen::Controller::FrontendController.helper(:comment_frontend)
 
-plugin(:settings, :register) do |setting|
-  setting.title       = lang('comments.labels.anti_spam_system')
-  setting.description = lang('comments.placeholders.anti_spam_system')
+Settings::Setting.add do |setting|
+  setting.title       = 'comments.labels.anti_spam_system'
+  setting.description = 'comments.descriptions.anti_spam_system'
   setting.name        = 'anti_spam_system'
   setting.group       = 'security'
   setting.type        = 'select'
   setting.default     = 'defensio'
-  setting.values      = {
-    'defensio' => lang('comments.labels.defensio')
-  }
+  setting.values      = lambda { Comments::AntiSpam::REGISTERED }
 end
 
-plugin(:settings, :register) do |setting|
-  setting.title       = lang('comments.labels.defensio_key')
-  setting.description = lang('comments.placeholders.defensio_key')
+Settings::Setting.add do |setting|
+  setting.title       = 'comments.labels.defensio_key'
+  setting.description = 'comments.descriptions.defensio_key'
   setting.name        = 'defensio_key'
   setting.group       = 'security'
   setting.type        = 'textbox'

data/lib/zen/package/comments/lib/comments/anti_spam.rb

@@ -0,0 +1,138 @@
+module Comments
+  ##
+  # {Comments::AntiSpam} is a module that can be used to verify if a comment is
+  # spam or ham. In order to validate a comment you'll have to call
+  # {Comments::AntiSpam.validate} and pass a set of parameters to it (see the
+  # documentation of {Comments::AntiSpam.validate} for more information). An
+  # example of validating a comment using Defensio looks like the following:
+  #
+  #     spam = Comments::AntiSpam.validate(
+  #       :defensio,
+  #       nil,
+  #       nil,
+  #       nil,
+  #       'This is a comment that has to be validated'
+  #     )
+  #
+  # ## Supported Systems
+  #
+  # By default only Defensio is supported.
+  #
+  # ## Adding Systems
+  #
+  # Adding a new anti spam system is done in two steps. First you must add the
+  # name of the method to {Comments::AntiSpam::REGISTERED} (the method should be
+  # a symbol). This constant is a hash of which the keys are the method names of
+  # the engines to invoke and the values the labels to display in the admin
+  # panel. Without this the {Comments::AntiSpam.validate} method will raise an
+  # error. This check is put in place to ensure that the user can't potentially
+  # exploit the system.
+  #
+  # Once the method has been added to the list you must actually implement it as
+  # a class method. The syntax of such a method looks like the following:
+  #
+  #     def self.method_name(author, email, url, comment)
+  #
+  #     end
+  #
+  # The return value should be a boolean that indicates whether or not the
+  # comment is spam. A return value of ``true`` indicates that the comment is
+  # spam, anything that evaluates to ``false`` indicates that the comment is
+  # valid.
+  #
+  # In order to add your method you simply add it like you normally would with
+  # any other class:
+  #
+  #     module Comments
+  #       module AntiSpam
+  #         private
+  #
+  #         def self.custom_method(author, email, url, comment)
+  #
+  #         end
+  #       end
+  #     end
+  #
+  #
+  # @since  0.3
+  #
+  module AntiSpam
+    # Array containing the method names of the various supported engines and
+    # their labels to display in the admin interface.
+    REGISTERED = {
+      :defensio => lang('comments.labels.defensio')
+    }
+
+    class << self
+      ##
+      # Validates a comment to see if it's spam or ham using a given engine.
+      # Defensio only validates the comment itself.
+      #
+      # @example
+      #  Comments::AntiSpam.validate(
+      #    :defensio,
+      #    'Chuch Norris',
+      #    'chuck@chucknorris.com',
+      #    'http://chucknorris.com/',
+      #    '.....'
+      #  )
+      #
+      # @since  0.3
+      # @param  [#to_sym] engine The name of the anti spam engine to use.
+      # @param  [String] author The name of the author of the comment.
+      # @param  [String] email The Email address of the author.
+      # @param  [String] url The URL that points to the user's website
+      #  (optional).
+      # @param  [String] comment The comment to validate.
+      # @return [TrueClass|FalseClass]
+      #
+      def validate(engine, author, email, url, comment)
+        engine = engine.to_sym
+
+        unless REGISTERED.key?(engine)
+          raise(ArgumentError, "The engine \"#{engine}\" is invalid")
+        end
+
+        return send(engine, author, email, url, comment)
+      end
+
+      ##
+      # Validates a comment using Defensio.
+      #
+      # @since  0.3
+      # @see    Comments::AntiSpam.validate
+      #
+      def defensio(author, email, url, comment)
+        if !Kernel.const_defined?(:Defensio)
+          Ramaze.setup(:verbose => false) do
+            gem 'defensio'
+          end
+        end
+
+        spam    = true
+        api_key = get_setting(:defensio_key).value
+
+        if api_key.nil? or api_key.empty?
+          raise('You need to specify an API key for the defensio system')
+        end
+
+        client           = Defensio.new(api_key)
+        status, response = client.post_document(
+          :content  => comment,
+          :platform => 'zen',
+          :type     => 'comment'
+        )
+
+        return spam if status != 200
+
+        if response['allow'] == true and response['spaminess'] <= 0.85
+          spam = false
+        else
+          spam = true
+        end
+
+        return spam
+      end
+    end # class << self
+  end # AntiSpam
+end # Comments

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

@@ -1,114 +1,176 @@
-#:nodoc:
+##
+# Package that allows users to manage and submit comments.
+#
+# ## Controllers
+#
+# * {Comments::Controller::Comments}
+# * {Comments::Controller::CommentsForm}
+#
+# ## Helpers
+#
+# * {Ramaze::Helper::Comment}
+# * {Ramaze::Helper::CommentFrontend}
+#
+# ## Models
+#
+# * {Comments::Model::Comment}
+# * {Comments::Model::CommentStatus}
+#
+# ## Generic Modules & Classes
+#
+# * {Comments::AntiSpam}
+#
+# @since  0.1
+#
 module Comments
   #:nodoc:
   module Controller
     ##
-    # Controller used for managing comments. Administrations can't actually
-    # add new comments using the backend controller but can edit or delete them.
-    # Comments can be submitted to any section entry as long as the section
-    # allows it. When submitting a comment the user data such as the name and
-    # email will be retrieved from either the users table (if the user is logged
-    # in) or from the form that was submitted.
+    # Controller for managing existing comments. When logged in a user can not
+    # add a comment, for that they'd have to use the frontend.
     #
-    # @author  Yorick Peterse
-    # @since   0.1
+    # Depending on the settings of a section the comments belong to (via a
+    # section entry) users may have to meet certain requirements in order to be
+    # able to post a comment. For example, a section might require users to be
+    # logged in in order to post comments. If this is the case and the user
+    # tries to submit a comment a message will be displayed and the HTTP status
+    # code is changed to 403. See {Comments::Controller::CommentsForm} for more
+    # information.
+    #
+    # In order to manage existing comments you'll have to navigate to
+    # ``/admin/comments``. This page will show an overview of all existing
+    # comments (or a message if no comments were found).
+    #
+    # ![Comments](../../_static/comments/comments.png)
+    #
+    # Comments can be edited by clicking on their name. Deleting comments can be
+    # done by checking the checkboxes in each row followed by clicking the
+    # "Delete selected comments" button.
+    #
+    # ## Editing Comments
+    #
+    # ![Edit Comment](../../_static/comments/edit_comment.png)
+    #
+    # When editing a comment you can specify/update the following fields:
+    #
+    # * **Name**: the name of the author. This field can only be changed if the
+    #   comment was posted by somebody that wasn't logged in.
+    # * **Website**: the website of the author that posted the comment.
+    # * **Email**: the Email address of the author. If the comment was posted by
+    #   a user that wasn't logged in then this field is required.
+    # * **Status**: the status of a comment, can be "Open", "Closed" or "Spam".
+    #   If the status is something other than "Open" it will be hidden when the
+    #   comments plugin is used.
+    # * **Comment** (required): the actual comment. Based on a section's
+    #   settings these are formatted using Markdown, Textile or any of the other
+    #   available markup processors.
+    #
+    # Note that if a comment was posted by a user that was logged in you won't
+    # be able to change the name of the author.
+    #
+    # ## Used Permissions
+    #
+    # This controller uses the following permissions:
+    #
+    # * show_comment
+    # * edit_comment
+    # * new_comment
+    # * delete_comment
+    #
+    # ## Events
+    #
+    # All events called in this controller receive an instance of
+    # {Comments::Model::Comment}. However, just like all other controllers the
+    # ``delete_comment`` receives an instance of this model that has already
+    # been destroyed.
+    #
+    # An example of using one of these events is to notify a user when his
+    # comment has been marked as spam:
+    #
+    #     require 'mail'
+    #
+    #     Zen::Event.call(:after_edit_comment) do |comment|
+    #       email = comment.user.email
+    #       spam  = Comments::Model::CommentStatus[:name => 'spam']
+    #
+    #       if comment.comment_status_id == spam.id
+    #         Mail.deliver do
+    #           from    'example@domain.tld'
+    #           to      email
+    #           subject 'Your comment has been marked as spam'
+    #           body    "Dear #{comment.user.name}, your comment has been " \
+    #             "marked as spam"
+    #        end
+    #      end
+    #    end
+    #
+    # @since  0.1
+    # @map    /admin/comments
+    # @event  before_edit_comment
+    # @event  after_edit_comment
+    # @event  beore_delete_comment
+    # @event  after_delete_comment
     #
     class Comments < Zen::Controller::AdminController
-      include ::Comments::Model
-
-      map '/admin/comments'
+      map    '/admin/comments'
       helper :comment
+      title  'comments.titles.%s'
 
-      before_all do
-        csrf_protection(:save, :delete) do
-          respond(lang('zen_general.errors.csrf'), 403)
-        end
-      end
+      csrf_protection :save, :delete
 
       ##
-      # Constructor method that pre-loads several variables and language files.
-      # The following language files are loaded:
+      # Shows an overview of all existing comments and allows the user to edit
+      # or remove these comments.
       #
-      # * comments
+      # @since      0.1
+      # @permission show_comment
       #
-      # @author Yorick Peterse
-      # @since  0.1
-      #
-      def initialize
-        super
+      def index
+        authorize_user!(:show_comment)
 
-        Zen::Language.load('comments')
+        set_breadcrumbs(lang('comments.titles.index'))
 
-        # Set the page title
-        if !action.method.nil?
-          method      = action.method.to_s
-          @page_title = lang("comments.titles.#{method}") rescue nil
+        @comments = search do |query|
+          ::Comments::Model::Comment.search(query).order(:comments__id.asc)
         end
-      end
-
-      ##
-      # Shows an overview of all posted comments along with their status,
-      # author and so on.
-      #
-      # This method requires the following permissions:
-      #
-      # * read
-      #
-      # @author Yorick Peterse
-      # @since  0.1
-      #
-      def index
-        require_permissions(:read)
 
-        set_breadcrumbs(lang('comments.titles.index'))
+        @comments ||= ::Comments::Model::Comment \
+          .eager(:comment_status, :user) \
+          .order(:id.asc)
 
-        @comments = paginate(Comment.eager(:comment_status))
+        @comments = paginate(@comments)
       end
 
       ##
-      # Edits an existing comment based on the ID.
+      # Allows a user to edit an existing comment.
       #
-      # This method requires the following permissions:
-      #
-      # * read
-      # * update
-      #
-      # @author Yorick Peterse
-      # @param  [Integer] id The ID of the comment to retrieve so that we can
-      # edit it.
-      # @since  0.1
+      # @param      [Fixnum] id The ID of the comment to edit.
+      # @since      0.1
+      # @permission edit_comment
       #
       def edit(id)
-        require_permissions(:read, :update)
+        authorize_user!(:edit_comment)
 
         set_breadcrumbs(
           Comments.a(lang('comments.titles.index'), :index),
           @page_title
         )
 
-        if flash[:form_data]
-          @comment = flash[:form_data]
-        else
-          @comment = validate_comment(id)
-        end
+        @comment = flash[:form_data] || validate_comment(id)
 
         render_view(:form)
       end
 
       ##
-      # Saves a comment based on the current POST data. Note that this
-      # method won't create a new comment as this can't be done using the
-      # backend.
+      # Saves the changes made to an existing comment.
       #
-      # This method requires the following permissions:
-      #
-      # * update
-      #
-      # @author Yorick Peterse
-      # @since  0.1
+      # @since      0.1
+      # @permission edit_comment
+      # @event      before_edit_comment
+      # @event      after_edit_comment
       #
       def save
-        require_permissions(:update)
+        authorize_user!(:edit_comment)
 
         # Copy the POST data so we can work with it without messing things up
         post = request.subset(
@@ -127,8 +189,10 @@ module Comments
         post.delete('id')
 
         begin
-          comment.update(post)
-          message(:success, lang('comments.success.save'))
+          post.each { |k, v| comment.send("#{k}=", v) }
+          Zen::Event.call(:before_edit_comment, comment)
+
+          comment.save
         rescue => e
           Ramaze::Log.error(e.inspect)
           message(:error, lang('comments.errors.save'))
@@ -139,27 +203,23 @@ module Comments
           redirect_referrer
         end
 
-        # Redirect the user to the proper page.
-        if comment.id
-          redirect(Comments.r(:edit, comment.id))
-        else
-          redirect_referrer
-        end
+        Zen::Event.call(:after_edit_comment, comment)
+
+        message(:success, lang('comments.success.save'))
+        redirect(Comments.r(:edit, comment.id))
       end
 
       ##
-      # Deletes a number of comments based on the comment IDs specified
-      # in the POST array "comment_ids".
+      # Deletes a number of comments. The IDs of these comments should be
+      # specified in the POSt array "comment_ids".
       #
-      # This method requires the following permissions:
-      #
-      # * delete
-      #
-      # @author Yorick Peterse
-      # @since  0.1
+      # @since      0.1
+      # @permission delete_comment
+      # @event      before_delete_comment
+      # @event      after_delete_comment
       #
       def delete
-        require_permissions(:delete)
+        authorize_user!(:delete_comment)
 
         # Obviously we'll require some IDs
         if !request.params['comment_ids'] \
@@ -170,17 +230,24 @@ module Comments
 
         # Delete each section
         request.params['comment_ids'].each do |id|
+          comment = ::Comments::Model::Comment[id]
+
+          next if comment.nil?
+          Zen::Event.call(:before_delete_comment, comment)
+
           begin
-            Comment[id].destroy
-            message(:success, lang('comments.success.delete'))
+            comment.destroy
           rescue => e
             Ramaze::Log.error(e.inspect)
             message(:error, lang('comments.errors.delete') % id)
 
             redirect_referrer
           end
+
+          Zen::Event.call(:after_delete_comment, comment)
         end
 
+        message(:success, lang('comments.success.delete'))
         redirect_referrer
       end
     end # Comments