zen 0.2.8 → 0.3b

data/lib/zen/package/all.rb

@@ -1,10 +1,11 @@
-# Loads all core packages that ship with Zen. Note that it's important to load 
-# these packages in the correct order as otherwise migrations that create 
+# Loads all core packages that ship with Zen. Note that it's important to load
+# these packages in the correct order as otherwise migrations that create
 # foreign keys might not work.
-require __DIR__('users/lib/users')
 require __DIR__('settings/lib/settings')
+require __DIR__('users/lib/users')
 require __DIR__('sections/lib/sections')
 require __DIR__('comments/lib/comments')
 require __DIR__('categories/lib/categories')
 require __DIR__('custom_fields/lib/custom_fields')
 require __DIR__('menus/lib/menus')
+require __DIR__('extensions/lib/extensions')

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

@@ -1,47 +1,35 @@
-# Update the helper path before loading the controllers
-Ramaze::HelpersHelper.options.paths.push(__DIR__('categories'))
+Zen::Package.add do |p|
+  p.name       = :categories
+  p.title      = 'categories.titles.index'
+  p.author     = 'Yorick Peterse'
+  p.url        = 'http://zen-cms.com/'
+  p.about      = 'category_groups.description'
+  p.root       = __DIR__('categories')
+  p.migrations = __DIR__('../migrations')
 
-require __DIR__('categories/model/category_group')
-require __DIR__('categories/model/category')
-require __DIR__('categories/controller/category_groups')
-require __DIR__('categories/controller/categories')
-require __DIR__('categories/plugin/categories')
+  p.menu(
+    'categories.titles.index',
+    '/admin/category-groups',
+    :permission => :show_category_group
+  )
 
-# Load the language pack manually so it can be used in the block below
-Zen::Language.options.paths.push(__DIR__('categories'))
-Zen::Language.load('categories')
-Zen::Language.load('category_groups')
+  p.permission :show_category_group  , 'category_groups.permissions.show'
+  p.permission :edit_category_group  , 'category_groups.permissions.edit'
+  p.permission :new_category_group   , 'category_groups.permissions.new'
+  p.permission :delete_category_group, 'category_groups.permissions.delete'
 
-# Describe what this package is all about
-Zen::Package.add do |p|
-  p.name          = 'categories'
-  p.author        = 'Yorick Peterse'
-  p.url           = 'http://yorickpeterse.com/'
-  p.about         = "Module for managing categories. Categories can be used to 
-organize section entries."
+  p.permission :show_category  , 'categories.permissions.show'
+  p.permission :edit_category  , 'categories.permissions.edit'
+  p.permission :new_category   , 'categories.permissions.new'
+  p.permission :delete_category, 'categories.permissions.delete'
+end
 
-  p.directory     = __DIR__('categories')
-  p.migration_dir = __DIR__('../migrations')
-  
-  p.menu = [{
-    :title => lang('categories.titles.index'),
-    :url   => "admin/category-groups"
-  }]
+Zen::Language.load('categories')
+Zen::Language.load('category_groups')
 
-  # Register all controllers
-  p.controllers = {
-    lang('categories.titles.index')      => Categories::Controller::Categories,
-    lang('category_groups.titles.index') => Categories::Controller::CategoryGroups
-  }
-end
+require __DIR__('categories/model/category_group')
+require __DIR__('categories/model/category')
+require __DIR__('categories/controller/category_groups')
+require __DIR__('categories/controller/categories')
 
-# Register our plugins
-Zen::Plugin.add do |p|
-  p.name   = 'categories'
-  p.author = 'Yorick Peterse'
-  p.url    = 'http://yorickpeterse.com/'
-  p.about  = 'Plugin that makes it easier to retrieve categories and category 
-groups.'
-  
-  p.plugin = Categories::Plugin::Categories
-end
+Zen::Controller::FrontendController.helper(:category_frontend)

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

@@ -1,68 +1,107 @@
-#:nodoc:
 module Categories
   #:nodoc:
   module Controller
     ##
-    # Categories can be seen as "tags" for your section entries. They describe
-    # the type of entry just like tags except that categories generally cover
-    # larger elements. When adding a new entry categories aren't required so
-    # you're free to ignore them if you don't need them.
+    # Categories are data containers that work similar to tags. Categories can
+    # be used to group section entries that share similar topics together. A
+    # category is always related to a category group and thus you must first
+    # create such a group before you can add individual categories. Read the
+    # chapter about {Categories::Controller::CategoryGroups Category groups} for
+    # more information.
+    #
+    # In order to manage categories you must first navigate to the category
+    # groups overview. In this overview you can click the link "Manage
+    # categories" of a certain group to add, edit or remove categories. Once
+    # you've reached the categories overview you'll be presented with an
+    # overview that looks like the following image:
+    #
+    # ![Categories Overview](../../_static/categories/categories.png)
+    #
+    # ## Adding/Editing Categories
+    #
+    # Editing a category can be done by clicking on the name of that category.
+    # If you want to create a new category instead you should click the button
+    # "Add category". In both cases you'll end up with the following form:
+    #
+    # ![New Category](../../_static/categories/new_category.png)
+    #
+    # In this form you can specify the following fields:
+    #
+    # * **Name** (required): the name of the category. This name can be anything
+    #   and there's no restriction to it's format. An example of such a name
+    #   would be "Code" or "Products".
+    # * **Slug**: a URL friendly version of a category name. If no slug is
+    #   specified one will be generated based on the category name.
+    # * **Parent**: the name of the parent category.
+    # * **Description**: a description of the category. While not required it
+    #   can help you remember what the category is meant for in case the name
+    #   doesn't already make this clear enough.
+    #
+    # Note that both the name of a category and it's slug can not be longer than
+    # 255 characters.
+    #
+    # ## Used Permissions
+    #
+    # This controller uses the following permissions:
+    #
+    # * show_category
+    # * edit_category
+    # * new_category
+    # * delete_category
+    #
+    # ## Events
+    #
+    # All available events will receive an instance of
+    # {Categories::Model::Category}. Do note that the event
+    # ``after_delete_category`` will receive an instance of this model *after*
+    # ``#destroy()`` has been invoked on the instance. This means that you can
+    # not save any changes made to the object as the database no longer
+    # exists.
+    #
+    # Say you want to notify a user whenever a category is removed you could do
+    # the following:
+    #
+    #     # "mail" can be installed by running gem install mail.
+    #     require 'mail'
+    #
+    #     Zen::Event.listen(:delete_category) do |category|
+    #       user = Users::Model::User[:name => 'admin']
+    #       Mail.deliver do
+    #         from    'example@domain.com'
+    #         to      user.email
+    #         subject "Category \"#{category.name}\" has been removed"
+    #           "has been removed from the database."
+    #       end
+    #     end
     #
-    # @author Yorick Peterse
     # @since  0.1
+    # @map    /admin/categories
+    # @event  before_new_category
+    # @event  after_new_category
+    # @event  before_edit_category
+    # @event  after_edit_category
+    # @event  before_delete_category
+    # @event  after_delete_category
     #
     class Categories < Zen::Controller::AdminController
-      include ::Categories::Model
-
-      map '/admin/categories'
+      map    '/admin/categories'
       helper :category
+      title  'categories.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:
-      #
-      # * categories
-      # * category_groups
-      #
-      # @author Yorick Peterse
-      # @since  0.1
-      #
-      def initialize
-        super
-
-        Zen::Language.load('categories')
-        Zen::Language.load('category_groups')
-
-        # Set the page title
-        if !action.method.nil?
-          method      = action.method.to_s
-          @page_title = lang("categories.titles.#{method}") rescue nil
-        end
-      end
+      # Protect Categories#save() and Categories#delete() against CSRF attacks.
+      csrf_protection :save, :delete
 
       ##
       # Show an overview of all existing categories and allow the user
-      # to create and manage these categories.
-      #
-      # This method requires the following permissions:
-      #
-      # * read
+      # manage these categories.
       #
-      # @author Yorick Peterse
-      # @param  [Fixnum] category_group_id The ID of the category group that's
-      # currently being managed by the user.
-      # @since  0.1
+      # @param  [Fixnum] category_group_id The ID of the category group for
+      #  which to retrieve all categories.
+      # @since      0.1
+      # @permission show_category
       #
       def index(category_group_id)
-        require_permissions(:read)
+        authorize_user!(:show_category)
 
         set_breadcrumbs(
           CategoryGroups.a(lang('category_groups.titles.index'), :index),
@@ -72,37 +111,42 @@ module Categories
         # Validate the category group
         category_group     = validate_category_group(category_group_id)
         @category_group_id = category_group_id
-        @categories        = Category.filter(
-          :category_group_id => category_group_id
-        )
+
+        @categories = search do |query|
+          ::Categories::Model::Category \
+            .search(query) \
+            .filter(:category_group_id => category_group_id) \
+            .order(:id.asc)
+        end
+
+        @categories ||= ::Categories::Model::Category \
+          .filter(:category_group_id => category_group_id) \
+          .order(:id.asc)
 
         @categories = paginate(@categories)
       end
 
       ##
-      # Edit an existing category based on the ID specified in the URL.
-      #
-      # This method requires the following permissions:
-      #
-      # * read
-      # * update
+      # Allows the user to create a new category.
       #
-      # @author Yorick Peterse
-      # @param  [Integer] category_group_id The category group ID.
-      # @param  [Integer] id The ID of the category to edit.
-      # @since  0.1
+      # @param      [Fixnum] category_group_id The ID of the category group.
+      # @since      0.1
+      # @permission new_category
       #
-      def edit(category_group_id, id)
-        require_permissions(:read, :update)
+      def new(category_group_id)
+        authorize_user!(:new_category)
 
         set_breadcrumbs(
           CategoryGroups.a(
-            lang('category_groups.titles.index'), :index
+            lang('category_groups.titles.index'),
+            :index
           ),
           Categories.a(
-            lang('categories.titles.index'), :index, category_group_id
+            lang('categories.titles.index'),
+            :index,
+            category_group_id
           ),
-          lang('categories.titles.edit')
+          lang('categories.titles.new')
         )
 
         validate_category_group(category_group_id)
@@ -112,41 +156,45 @@ module Categories
         if flash[:form_data]
           @category = flash[:form_data]
         else
-          @category = validate_category(id, category_group_id)
+          @category = ::Categories::Model::Category.new
         end
 
         render_view(:form)
       end
 
       ##
-      # Create a new category.
-      #
-      # This method requires the following permissions:
-      #
-      # * read
-      # * create
+      # Edit an existing category based on the ID specified in the URL.
       #
-      # @author Yorick Peterse
-      # @param  [Integer] category_group_id The ID of the category group.
-      # @since  0.1
+      # @param      [Fixnum] category_group_id The category group ID.
+      # @param      [Fixnum] id The ID of the category to edit.
+      # @since      0.1
+      # @permission edit_category
       #
-      def new(category_group_id)
-        require_permissions(:read, :create)
+      def edit(category_group_id, id)
+        authorize_user!(:edit_category)
 
         set_breadcrumbs(
           CategoryGroups.a(
-            lang('category_groups.titles.index'), :index
+            lang('category_groups.titles.index'),
+            :index
           ),
           Categories.a(
-            lang('categories.titles.index'), :index, category_group_id
+            lang('categories.titles.index'),
+            :index,
+            category_group_id
           ),
-          lang('categories.titles.new')
+          lang('categories.titles.edit')
         )
 
         validate_category_group(category_group_id)
 
         @category_group_id = category_group_id
-        @category          = Category.new
+
+        if flash[:form_data]
+          @category = flash[:form_data]
+        else
+          @category = validate_category(id, category_group_id)
+        end
 
         render_view(:form)
       end
@@ -155,16 +203,15 @@ module Categories
       # Save the changes made to an existing category or create a new one based
       # on the current POST data.
       #
-      # This method requires the following permissions:
-      #
-      # * create
-      # * update
-      #
-      # @author Yorick Peterse
-      # @since  0.1
+      # @since      0.1
+      # @permission edit_category (when editing a category)
+      # @permission new_category (when creating a category)
+      # @event      before_edit_category
+      # @event      after_edit_category
+      # @event      before_new_category
+      # @event      after_new_category
       #
       def save
-        # Fetch all the required fields
         post = request.subset(
           :id,
           :parent_id,
@@ -174,36 +221,40 @@ module Categories
           :category_group_id
         )
 
-        # Validate the category group
         validate_category_group(post['category_group_id'])
 
         # Retrieve the category and set the notifications based on if the ID has
         # been specified or not.
         if post['id'] and !post['id'].empty?
-          require_permissions(:update)
+          authorize_user!(:edit_category)
 
-          category    = validate_category(post['id'], post['category_group_id'])
-          save_action = :save
+          category     = validate_category(post['id'], post['category_group_id'])
+          save_action  = :save
+          before_event = :before_edit_category
+          after_event  = :after_edit_category
         else
-          require_permissions(:create)
+          authorize_user!(:new_category)
 
-          category    = Category.new
-          save_action = :new
+          category     = ::Categories::Model::Category.new
+          save_action  = :new
+          before_event = :before_new_category
+          after_event  = :after_new_category
         end
 
-        post.delete('slug') if post['slug'].empty?
         post.delete('id')
 
-        # Set the messages to display
-        flash_success = lang("categories.success.#{save_action}")
-        flash_error   = lang("categories.errors.#{save_action}")
+        success = lang("categories.success.#{save_action}")
+        error   = lang("categories.errors.#{save_action}")
 
         # Try to update the category
         begin
-          category.update(post)
-          message(:success, flash_success)
-        rescue
-          message(:error, flash_error)
+          post.each { |k, v| category.send("#{k}=", v) }
+          Zen::Event.call(before_event, category)
+
+          category.save
+        rescue => e
+          Ramaze::Log.error(e.inspect)
+          message(:error, error)
 
           flash[:form_errors] = category.errors
           flash[:form_data]   = category
@@ -211,52 +262,56 @@ module Categories
           redirect_referrer
         end
 
-        if category.id
-          redirect(Categories.r(:edit, post['category_group_id'], category.id))
-        else
-          redirect(Categories.r(:new, post['category_group_id']))
-        end
+        Zen::Event.call(after_event, category)
+
+        message(:success, success)
+        redirect(Categories.r(:edit, category.category_group_id, category.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.
-      #
-      # This method requires the following permissions:
+      # 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.
       #
-      # * delete
-      #
-      # @author Yorick Peterse
-      # @since  0.1
+      # @since      0.1
+      # @permission delete_category
+      # @event      before_delete_category
+      # @event      after_delete_category
       #
       def delete
-        require_permissions(:delete)
+        authorize_user!(:delete_category)
 
-        post = request.subset(:category_ids, :category_group_id)
+        post = request.subset(:category_ids)
 
         # Obviously we'll require some IDs
-        if !request.params['category_ids'] \
-        or request.params['category_ids'].empty?
+        if post['category_ids'].nil? or post['category_ids'].empty?
           message(:error, lang('categories.errors.no_delete'))
-          redirect(Categories.r(:index, post['category_group_id']))
+          redirect_referrer
         end
 
-        # Delete each section
+        # Remove each category and call the event.
         request.params['category_ids'].each do |id|
+          category = ::Categories::Model::Category[id]
+
+          next if category.nil?
+
+          Zen::Event.call(:before_delete_category, category)
+
           begin
-            Category[id].destroy
-            message(:success, lang('categories.success.delete'))
+            category.destroy
           rescue => e
             Ramaze::Log.error(e.inspect)
             message(:error, lang('categories.errors.delete') % id)
 
             redirect_referrer
           end
+
+          Zen::Event.call(:after_delete_category, category)
         end
 
-        redirect(Categories.r(:index, post['category_group_id']))
+        message(:success, lang('categories.success.delete'))
+        redirect_referrer
       end
     end # Categories
   end # Controller