zen 0.2.8 → 0.3b

data/lib/zen/package/categories/lib/categories/controller/category_groups.rb

@@ -1,157 +1,224 @@
-#:nodoc:
+##
+# Package for managing categories and category groups.
+#
+# ## Controllers
+#
+# * {Categories::Controller::CategoryGroups}
+# * {Categories::Controller::Categories}
+#
+# ## Helpers
+#
+# * {Ramaze::Helper::Category}
+# * {Ramaze::Helper::CategoryFrontend}
+#
+# ## Models
+#
+# * {Categories::Model::CategoryGroup}
+# * {Categories::Model::Category}
+#
+# @since  0.1
+#
 module Categories
   #:nodoc:
   module Controller
     ##
-    # Category groups can be used to group a number of categories into a single
-    # container. These groups are assigned to a section (rather than individual
-    # categories). It's important to remember that a section entry can't use a
-    # category group until it has been added to a section.
+    # Category groups are containers for individual categories. A category group
+    # can be assigned to multiple sections and it can have multiple categories.
+    #
+    # In order to manage a category group you must first go to the overview that
+    # shows all existing group (or a message telling you no groups have been
+    # added if this is the case). This can be done by clicking the "Categories"
+    # button in the top navigation menu or by manually pointing your browser to
+    # ``/admin/category-groups``. This overview looks like the image displayed
+    # below.
+    #
+    # ![Category Group Overview](../../_static/categories/category_groups.png)
+    #
+    # Editing an existing group can be done by clicking on the name of a group
+    # while managing the categories of a group is done by clicking the link
+    # "Manage Categories" (the text may differ depending on the language you're
+    # using). If you want to delete a number of groups all you'd have to do is
+    # clicking the checkboxes of each row you'd wish to delete followed by
+    # pressing the button "Delete selected groups". This will trigger an action
+    # that removes all category groups and the categories that belong to those
+    # groups.
+    #
+    # ## Adding/Editing Groups
+    #
+    # By clicking the name of a group or the "Add group" button you can edit an
+    # existing group or create a new one. The form used to manage such a group
+    # looks like the one in the image below.
+    #
+    # ![New Category Group](../../_static/categories/new_category_group.png)
+    #
+    # In this form you can set the following fields:
+    #
+    # * **Name**: the name of the category group. It can be any name in any
+    #   format as long as it's not longer than 255 characters.
+    # * **Description**: the description of the category group. While not
+    #   required it can be used to make it easier to remember that purpose a
+    #   category group has.
+    #
+    # ## Used Permissions
+    #
+    # * show_category_group
+    # * edit_category_group
+    # * new_category_group
+    # * delete_category_group
+    #
+    # ## Events
+    #
+    # All available events receive an instance of
+    # {Categories::Model::CategoyGroup}. However, the
+    # ``after_delete_category_group`` event will receive an instance that has
+    # already been removed from the database. This means that you can not make
+    # changes to the object and call ``#save()``.
+    #
+    # Example of logging when a new category group is created:
+    #
+    #     Zen::Event.listen(:after_new_category_group) do |group|
+    #       Ramaze::Log.info("New category: \"#{group.name}\"")
+    #     end
+    #
+    # Maybe you want to automatically add a category group to a section:
+    #
+    #     Zen::Event.listen(:after_new_category_group) do |group|
+    #       section = Sections::Model::Section[5]
+    #
+    #       begin
+    #         section.add_category_group(group)
+    #       rescue => e
+    #         Ramaze::Log.error(e.inspect)
+    #       end
+    #     end
     #
-    # @author Yorick Peterse
     # @since  0.1
+    # @map    /admin/category-groups
+    # @event  before_new_category_group
+    # @event  after_new_category_group
+    # @event  before_edit_category_group
+    # @event  after_edit_category_group
+    # @event  before_delete_category_group
+    # @event  after_delete_category_group
     #
     class CategoryGroups < Zen::Controller::AdminController
-      include ::Categories::Model
-
       helper :category
       map    '/admin/category-groups'
+      title  'category_groups.titles.%s'
 
-      before_all do
-        csrf_protection(:save, :delete) do
-          respond(lang('zen_general.errors.csrf'), 403)
-        end
-      end
-
-      ##
-      # The constructor is used to set various options such as the form URLs and
-      # load the language pack for the categories module.
-      #
-      # The following language files are loaded:
-      #
-      # * category_groups
-      #
-      # @author Yorick Peterse
-      # @since  0.1
-      #
-      def initialize
-        super
-
-        Zen::Language.load('category_groups')
-
-        # Set the page title
-        if !action.method.nil?
-          method      = action.method.to_s
-          @page_title = lang("category_groups.titles.#{method}") rescue nil
-        end
-      end
+      # Protects CategoryGroups#save() and CategoryGroups#delete() against CSRF
+      # attacks.
+      csrf_protection :save, :delete
 
       ##
       # Show an overview of all existing category groups and allow the user
       # to create new category groups or manage individual categories.
       #
-      # This method requires the following permissions:
-      #
-      # * read
-      #
-      # @author Yorick Peterse
-      # @since  0.1
+      # @since      0.1
+      # @permission show_category_group
       #
       def index
-        require_permissions(:read)
+        authorize_user!(:show_category_group)
 
         set_breadcrumbs(lang('category_groups.titles.index'))
 
-        @category_groups = paginate(CategoryGroup)
+        @category_groups = search do |query|
+          ::Categories::Model::CategoryGroup.search(query).order(:id.asc)
+        end
+
+        @category_groups ||= ::Categories::Model::CategoryGroup.order(:id.asc)
+        @category_groups   = paginate(@category_groups)
       end
 
       ##
-      # Edit an existing category group based on the ID specified in the URL.
-      # This method requires the following permissions:
+      # Allows a user to edit an existing category group.
       #
-      # * read
-      # * update
-      #
-      # @author Yorick Peterse
-      # @since  0.1
+      # @since      0.1
+      # @param      [Fixnum] id The ID of the category group to edit.
+      # @permission edit_category_group
       #
       def edit(id)
-        require_permissions(:read, :update)
+        authorize_user!(:edit_category_group)
 
         set_breadcrumbs(
           CategoryGroups.a(lang('category_groups.titles.index'), :index),
           lang('category_groups.titles.edit')
         )
 
-        if flash[:form_data]
-          @category_group = flash[:form_data]
-        else
-          @category_group = validate_category_group(id)
-        end
+        @category_group = flash[:form_data] || validate_category_group(id)
 
         render_view(:form)
       end
 
       ##
-      # Create a new category group. This method requires the following
-      # permissions:
+      # Allows the user to add a new category group.
       #
-      # * create
-      # * read
-      #
-      # @author Yorick Peterse
       # @since  0.1
+      # @permission new_category_group
       #
       def new
-        require_permissions(:create, :read)
+        authorize_user!(:new_category_group)
 
         set_breadcrumbs(
           CategoryGroups.a(lang('category_groups.titles.index'), :index),
           lang('category_groups.titles.new')
         )
 
-        @category_group = CategoryGroup.new
+        if flash[:form_data]
+          @category_group = flash[:form_data]
+        else
+          @category_group = ::Categories::Model::CategoryGroup.new
+        end
 
         render_view(:form)
       end
 
       ##
-      # Save or create a new category group based on the current POST data.
-      # This method requires the following permissions:
+      # Creates a new category or updates the data of an existing category. If a
+      # category ID is specified (in the POST key "id") that existing category
+      # will be updated, otherwise a new one will be created.
       #
-      # * create
-      # * update
-      #
-      # @author Yorick Peterse
-      # @since  0.1
+      # @since      0.1
+      # @permission edit_category_group (when editing a group)
+      # @permission new_category_group (when creating a group)
+      # @event      before_new_category_group
+      # @event      after_new_category_group
+      # @event      before_edit_category_group
+      # @event      after_edit_category_group
       #
       def save
         post = request.subset(:id, :name, :description)
 
+        # Get/create the group and set the event names.
         if post['id'] and !post['id'].empty?
-          require_permissions(:update)
+          authorize_user!(:edit_category_group)
 
           category_group = validate_category_group(post['id'])
           save_action    = :save
+          before_event   = :before_edit_category_group
+          after_event    = :after_edit_category_group
         else
-          require_permissions(:create)
+          authorize_user!(:new_category_group)
 
-          category_group = CategoryGroup.new
+          category_group = ::Categories::Model::CategoryGroup.new
           save_action    = :new
+          before_event   = :before_new_category_group
+          after_event    = :after_new_category_group
         end
 
-        # Set the messages
-        flash_success = lang("category_groups.success.#{save_action}")
-        flash_error   = lang("category_groups.errors.#{save_action}")
+        success = lang("category_groups.success.#{save_action}")
+        error   = lang("category_groups.errors.#{save_action}")
 
         post.delete('id')
 
-        # Try to run the query
+        # Set the values, call the events and try to save the category group.
         begin
-          category_group.update(post)
-          message(:success, flash_success)
+          post.each { |k, v| category_group.send("#{k}=", v) }
+          Zen::Event.call(before_event, category_group)
+
+          category_group.save
         rescue => e
-          message(:error, flash_error)
+          message(:error, error)
           Ramaze::Log.error(e.inspect)
 
           flash[:form_data]   = category_group
@@ -160,49 +227,52 @@ module Categories
           redirect_referrer
         end
 
-        if !category_group.nil? and category_group.id
-          redirect(CategoryGroups.r(:edit, category_group.id))
-        else
-          redirect(CategoryGroups.r(:new))
-        end
+        Zen::Event.call(after_event, category_group)
+
+        message(:success, success)
+        redirect(CategoryGroups.r(:edit, category_group.id))
       end
 
       ##
-      # Delete all specified category groups and their categories. In
-      # order to delete a number of groups an array of fields, named
-      # "category_group_ids" is required. This array will contain all the
-      # primary values of each group that has to be deleted.
+      # Deletes a number of category groups. The IDs of these groups should be
+      # specified in the POST array "category_group_ids".
       #
-      # This method requires the following permissions:
-      #
-      # * delete
-      #
-      # @author Yorick Peterse
-      # @since  0.1
+      # @since      0.1
+      # @permission delete_category_group
+      # @event      before_delete_category_group
+      # @event      after_delete_category_group
       #
       def delete
-        require_permissions(:delete)
+        authorize_user!(:delete_category_group)
 
         post = request.subset(:category_group_ids)
 
-        if !post['category_group_ids'] or post['category_group_ids'].empty?
+        if post['category_group_ids'].nil? or post['category_group_ids'].empty?
           message(:error, lang('category_groups.errors.no_delete'))
           redirect(CategoryGroups.r(:index))
         end
 
         post['category_group_ids'].each do |id|
+          group = ::Categories::Model::CategoryGroup[id]
+
+          next if group.nil?
+
+          Zen::Event.call(:before_delete_category_group, group)
+
           begin
-            CategoryGroup[id].destroy
-            message(:success, lang('category_groups.success.delete'))
+            group.destroy
           rescue => e
             Ramaze::Log.error(e.inspect)
             message(:error, lang('category_groups.errors.delete') % id)
 
             redirect_referrer
           end
+
+          Zen::Event.call(:after_delete_category_group, group)
         end
 
-        redirect(CategoryGroups.r(:index))
+        message(:success, lang('category_groups.success.delete'))
+        redirect_referrer
       end
     end # CategoryGroups
   end # Controller

data/lib/zen/package/categories/lib/categories/helper/category.rb

@@ -1,4 +1,3 @@
-#:nodoc:
 module Ramaze
   #:nodoc:
   module Helper
@@ -6,7 +5,6 @@ module Ramaze
     # Helper for the Categories package. Note that this helper requires the
     # helper Ramaze::Helper::Message to be loaded.
     #
-    # @author Yorick Peterse
     # @since   0.2.8
     #
     module Category
@@ -16,10 +14,9 @@ module Ramaze
       # returned, otherwise the user is redirected back to the overview of all
       # category groups and is informed about the group being invalid.
       #
-      # @author Yorick Peterse
       # @since  0.2.8
       # @param  [Fixnum] category_group_id The ID of the category group to
-      # validate.
+      #  validate.
       # @return [Categories::Model::CategoryGroup]
       #
       def validate_category_group(category_group_id)
@@ -39,11 +36,10 @@ module Ramaze
       # is displayed and the user is redirected back to the overview of
       # categories.
       #
-      # @author Yorick Peterse
       # @since  0.2.8
       # @param  [Fixnum] category_id The ID of the category.
       # @param  [Fixnum] category_group_id The ID of the category group, used
-      # when redirecting the user.
+      #  when redirecting the user.
       # @return [Categories::Model::Category]
       #
       def validate_category(category_id, category_group_id)
@@ -63,12 +59,11 @@ module Ramaze
       # Method that extracts all the possible parent categories for a given
       # category group ID.
       #
-      # @author Yorick Peterse
       # @since  0.2.8
       # @param  [Fixnum[ category_id The ID of the category, this one will be
-      # excluded from the hash.
+      #  excluded from the hash.
       # @param  [Fixnum] category_group_id The ID of a category group for which
-      # to retrieve all the possible parent items.
+      #  to retrieve all the possible parent items.
       # @return [Hash]
       #
       def parent_categories(category_id, category_group_id)

data/lib/zen/package/categories/lib/categories/helper/category_frontend.rb

@@ -0,0 +1,86 @@
+module Ramaze
+  module Helper
+    ##
+    # Helper that makes it easier to retrieve categories and category groups in
+    # your templates.
+    #
+    # @since  0.3
+    #
+    module CategoryFrontend
+      ##
+      # Gets a number of categories and optionally paginates them. Keep in mind
+      # that this method will either return a dataset or an instance of
+      # ``Ramaze::Helper::Paginate::Paginator``.
+      #
+      # When paginating the results and no custom ``:var`` or ``:limit`` options
+      # are given this method will use the ones defined in
+      # ``Zen::Controller::FrontendController.ancestral_trait[:paginate]``.
+      #
+      # @example Looping over a set of categories
+      #  get_categories('Test Group').each do |category|
+      #    puts category.name
+      #  end
+      #
+      # @example Paginating categories
+      #  categories = get_categories('Test Group', :paginate => true)
+      #
+      #  unless categories.empty?
+      #    categories.each do |category|
+      #      puts category.name
+      #    end
+      #  end
+      #
+      #  # Returns the navigation menu for the paginat5ed results.
+      #  categories.navigation
+      #
+      # @since  0.3
+      # @param  [String|Fixnum] group The ID or name of a category group for
+      #  which to retrieve all categories.
+      # @param  [Hash] options A hash containing various options to customize
+      #  the return value.
+      # @option options [TrueClass|FalseClass] :paginate When set to true the
+      #  results will be paginated. Keep in mind that this only works inside
+      #  an action/template.
+      # @option options [String] :var The name of the query string that contains
+      #  the current page.
+      # @option options [Fixnum] :limit The amount of rows to retrieve.
+      # @return [Mixed]
+      #
+      def get_categories(group, options = {})
+        trait   = Zen::Controller::FrontendController.ancestral_trait[:paginate]
+        options = {
+          :paginate => false,
+          :var      => trait[:var],
+          :limit    => trait[:limit]
+        }.merge(options)
+
+        query = Categories::Model::Category.select_all(:categories)
+        query = query.join(
+          :category_groups,
+          :categories__category_group_id => :category_groups__id
+        )
+
+        if group.is_a?(String)
+          query = query.filter(:category_groups__name => group)
+        else
+          query = query.filter(:category_groups__id => group)
+        end
+
+        # Paginate the results or return the dataset directly.
+        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 # CategoryFrontend
+  end # Helper
+end # Ramaze