zen 0.2.8 → 0.3b

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

@@ -1,121 +1,162 @@
-#:nodoc:
+##
+# Package for managing sections and section entries.
+#
+# ## Controllers
+#
+# * {Sections::Controller::Sections}
+# * {Sections::Controller::SectionEntries}
+#
+# ## Helpers
+#
+# * {Ramaze::Helper::Section}
+# * {Ramaze::Helper::SectionFrontend}
+#
+# ## Models
+#
+# * {Sections::Model::Section}
+# * {Sections::Model::SectionEntry}
+# * {Sections::Model::SectionEntryStatus}
+#
 module Sections
   #:nodoc:
   module Controller
     ##
-    # Sections can be seen as mini applications inside your website.  Examples
-    # of sections can be a blog, pages, a products listing, etc.  Before being
-    # able to properly add section entries you need to assign the following data
-    # to a section:
+    # Sections are data containers with a specific purpose. For example, you
+    # might have a "Blog" or "Pages" section each with it's own entries,
+    # categories, custom fields and so on. A section and it's entries glue all
+    # the other data types (such as those mentioned earlier) together to form
+    # the content displayed on your website.
     #
-    # * a category group
-    # * a custom field group
+    # Sections can be managed by going to ``/admin``. This page will show an
+    # overview of all existing sections as well as a few buttons and links that
+    # allow you to edit, create or delete sections as well as managing the
+    # entries for each existing section.
     #
-    # @author  Yorick Peterse
-    # @since   0.1
+    # ![Sections](../../_static/sections/sections.png)
+    #
+    # ## Creating/Editing Sections
+    #
+    # Creating a new section can be done by clicking the button "Add section"
+    # while editing a section can be done by clicking the name of a section. In
+    # both cases you'll end up with a form that looks like the one in the images
+    # below.
+    #
+    # ![General](../../_static/sections/edit_section_general.png)
+    # ![Comments](../../_static/sections/edit_section_comments.png)
+    # ![Groups](../../_static/sections/edit_section_groups.png)
+    #
+    # In this form you can specify the following fields:
+    #
+    # * **Name** (required): the name of the section.
+    # * **Slug**: a URL friendly version of the section name. If no slug is
+    #   specified one will be generated automatically.
+    # * **Description**: a description of the section to help clarify it's
+    #   purpose.
+    # * **Allow comments** (required): whether or not users can submit comments
+    #   for entries assigned to the section.
+    # * **Comments require an account** (required): when set to "Yes" a user has
+    #   to be logged in in order to post a comment.
+    # * **Moderate comments** (required): when enabled a comment first has to be
+    #   approved before it's displayed. This option is disabled by default.
+    # * **Comment format** (required): the format comments are posted in such as
+    #   Markdown or plain text.
+    # * **Custom field groups**: all the custom field groups to assign to the
+    #   section. These groups can then be used by all the entries in the
+    #   section.
+    # * **Category groups**: all the category groups that should be available to
+    #   the section entries of this section.
+    #
+    # Note that the name and the slug of a section can not be longer than 255
+    # characters.
+    #
+    # ## Used Permissions
+    #
+    # * show_section
+    # * new_section
+    # * edit_section
+    # * delete_section
+    #
+    # ## Events
+    #
+    # All events in this controller receive an instance of
+    # {Sections::Model::Section}. The event ``after_delete_section`` receives an
+    # instance that has already been removed, thus you can't make any changes to
+    # it and save those in the database.
+    #
+    # Example of creating a dummy section entry:
+    #
+    #     Zen::Event.listen(:new_section) do |section|
+    #       section.add_section_entry(:title   => 'My Entry', :user_id => user.id)
+    #     end
+    #
+    # @since  0.1
+    # @map    /admin
+    # @event  before_new_section
+    # @event  after_new_section
+    # @event  before_edit_section
+    # @event  after_edit_section
+    # @event  before_delete_section
+    # @event  after_delete_section
     #
     class Sections < Zen::Controller::AdminController
-      include ::Sections::Model
-
       map    '/admin'
       helper :section
+      title  'sections.titles.%s'
 
-      # Load all required Javascript files
-      javascript(['zen/lib/tabs'], :method => [:edit, :new])
-
-      before_all do
-        csrf_protection(:save, :delete) do
-          respond(lang('zen_general.errors.csrf'), 403)
-        end
-      end
-
-      ##
-      # Constructor method, called upon initialization. It's used to set the URL
-      # to which forms send their data and load the language pack.
-      #
-      # This method loads the following language files:
-      #
-      # * sections
-      #
-      # @author Yorick Peterse
-      # @since  0.1
-      #
-      def initialize
-        super
-
-        Zen::Language.load('sections')
-
-        # Set the page title
-        if !action.method.nil?
-          method      = action.method.to_sym
-          @page_title = lang("sections.titles.#{method}") rescue nil
-        end
+      csrf_protection  :save, :delete
+      load_asset_group :tabs, [:edit, :new]
 
+      # Hook that is executed before Sections#index(), Sections#new() and
+      # Sections#edit().
+      before(:index, :new, :edit) do
         @boolean_hash = {
           true  => lang('zen_general.special.boolean_hash.true'),
           false => lang('zen_general.special.boolean_hash.false')
         }
+
+        @custom_field_group_pk_hash = ::CustomFields::Model::CustomFieldGroup \
+          .pk_hash(:name).invert
+
+        @category_group_pk_hash = ::Categories::Model::CategoryGroup \
+          .pk_hash(:name).invert
       end
 
       ##
       # Show an overview of all existing sections. Using this overview a user
       # can manage an existing section, delete it or create a new one.
       #
-      # This method requires the following permissions:
-      #
-      # * read
-      #
-      # @author Yorick Peterse
-      # @since  0.1
+      # @since      0.1
+      # @permission show_section
       #
       def index
-        require_permissions(:read)
+        authorize_user!(:show_section)
 
         set_breadcrumbs(lang('sections.titles.index'))
 
-        @sections = paginate(Section)
-      end
-
-      ##
-      # Hook that is executed before the edit() and new() methods.
-      #
-      # @author Yorick Peterse
-      # @since  0.2.8
-      #
-      before(:edit, :new) do
-        @custom_field_group_pk_hash = CustomFields::Model::CustomFieldGroup \
-          .pk_hash(:name)
+        @sections = search do |query|
+          ::Sections::Model::Section.search(query).order(:id.asc)
+        end
 
-        @category_group_pk_hash = Categories::Model::CategoryGroup \
-          .pk_hash(:name)
+        @sections ||= ::Sections::Model::Section.order(:id.asc)
+        @sections   = paginate(@sections)
       end
 
       ##
       # Show a form that lets the user edit an existing section.
       #
-      # This method requires the following permissions:
-      #
-      # * read
-      # * update
-      #
-      # @author Yorick Peterse
-      # @param  [Integer] id The ID of the section to retrieve so that we can
-      # edit it.
-      # @since  0.1
+      # @param      [Fixnum] id The ID of the section to edit.
+      # @since      0.1
+      # @permission edit_section
       #
       def edit(id)
-        require_permissions(:read, :update)
+        authorize_user!(:edit_section)
 
         set_breadcrumbs(
           Sections.a(lang('sections.titles.index'), :index),
           @page_title
         )
 
-        if flash[:form_data]
-          @section = flash[:form_data]
-        else
-          @section = validate_section(id)
-        end
+        @section = flash[:form_data] || validate_section(id)
 
         render_view(:form)
       end
@@ -123,40 +164,32 @@ module Sections
       ##
       # Show a form that lets the user create a new section.
       #
-      # This method requires the following permissions:
-      #
-      # * create
-      # * read
-      #
-      # @author Yorick Peterse
-      # @since  0.1
+      # @since      0.1
+      # @permission new_section
       #
       def new
-        require_permissions(:create, :read)
+        authorize_user!(:new_section)
 
         set_breadcrumbs(
           Sections.a(lang('sections.titles.index'), :index),
           @page_title
         )
 
-        @section = Section.new
+        @section = flash[:form_data] || ::Sections::Model::Section.new
 
         render_view(:form)
       end
 
       ##
-      # Method used for processing the form data and redirecting the user back
-      # to the proper URL. Based on the value of a hidden field named "id" we'll
-      # determine if the data will be used to create a new section or to update
-      # an existing one.
-      #
-      # This method requires the following permissions:
+      # Saves any changes made to an existing section or creates a new one.
       #
-      # * create
-      # * update
-      #
-      # @author Yorick Peterse
-      # @since  0.1
+      # @since      0.1
+      # @event      before_new_section
+      # @event      after_new_section
+      # @event      before_edit_section
+      # @event      ater_edit_section
+      # @permission new_section (when creating a section)
+      # @permission edit_section (when editing a section)
       #
       def save
         post = request.subset(
@@ -173,92 +206,92 @@ module Sections
         )
 
         if post['id'] and !post['id'].empty?
-          require_permissions(:update)
+          authorize_user!(:edit_section)
 
-          @section      = validate_section(post['id'])
-          save_action   = :save
+          section      = validate_section(post['id'])
+          save_action  = :save
+          before_event = :before_edit_section
+          after_event  = :after_edit_section
         else
-          require_permissions(:create)
+          authorize_user!(:new_section)
 
-          @section      = Section.new
-          save_action   = :new
+          section      = ::Sections::Model::Section.new
+          save_action  = :new
+          before_event = :before_new_section
+          after_event  = :after_new_section
         end
 
-        flash_success = lang("sections.success.#{save_action}")
-        flash_error   = lang("sections.errors.#{save_action}")
+        success = lang("sections.success.#{save_action}")
+        error   = lang("sections.errors.#{save_action}")
 
         post['custom_field_group_pks'] ||= []
         post['category_group_pks']     ||= []
 
-        # The primary keys have to be integers otherwise Sequel will soil it's
-        # pants
-        ['custom_field_group_pks', 'category_group_pks'].each do |k|
-          post[k].map! { |value| value.to_i }
-        end
-
-        # Auto generate the slug if it's empty
-        post.delete('slug') if post['slug'].empty?
         post.delete('id')
 
         begin
-          @section.update(post)
+          post.each { |k, v| section.send("#{k}=", v) }
+          Zen::Event.call(before_event, section)
+
+          section.save
 
           if save_action == :new
-            @section.custom_field_group_pks = post['custom_field_group_pks']
-            @section.category_group_pks     = post['category_group_pks']
+            section.custom_field_group_pks = post['custom_field_group_pks']
+            section.category_group_pks     = post['category_group_pks']
           end
-
-          message(:success, flash_success)
         rescue => e
           Ramaze::Log.error(e.inspect)
-          message(:error, flash_error)
+          message(:error, error)
 
-          flash[:form_data]   = @section
-          flash[:form_errors] = @section.errors
+          flash[:form_data]   = section
+          flash[:form_errors] = section.errors
 
           redirect_referrer
         end
 
-        if @section.id
-          redirect(Sections.r(:edit, @section.id))
-        else
-          redirect_referrer
-        end
+        Zen::Event.call(after_event, section)
+
+        message(:success, success)
+        redirect(Sections.r(:edit, section.id))
       end
 
       ##
-      # Delete an existing section. Poor section, what did he do wrong? In order
-      # to delete a section you'll need to send a POST request that contains a
-      # field named "section_ids[]". This field should contain the primary
-      # values of each section that has to be deleted.
-      #
-      # This method requires the following permissions:
-      #
-      # * delete
+      # Deletes a number of sections and all the related data. These sections
+      # should be specified in the POST array "section_ids[]".
       #
-      # @author Yorick Peterse
-      # @since  0.1
+      # @since      0.1
+      # @event      before_delete_section
+      # @event      after_delete_section
+      # @permission delete_section
       #
       def delete
-        require_permissions(:delete)
+        authorize_user!(:delete_section)
 
-        if !request.params['section_ids'] or request.params['section_ids'].empty?
+        if !request.params['section_ids'] \
+        or request.params['section_ids'].empty?
           message(:error, lang('sections.errors.no_delete'))
           redirect_referrer
         end
 
         request.params['section_ids'].each do |id|
+          section = ::Sections::Model::Section[id]
+
+          next if section.nil?
+          Zen::Event.call(:before_delete_section, section)
+
           begin
-            Section[id.to_i].destroy
-            message(:success, lang('sections.success.delete'))
+            section.destroy
           rescue => e
             Ramaze::Log.error(e.inspect)
             message(:error, lang('sections.errors.delete') % id)
 
             redirect_referrer
           end
+
+          Zen::Event.call(:after_delete_section, section)
         end
 
+        message(:success, lang('sections.success.delete'))
         redirect_referrer
       end
     end # Sections

data/lib/zen/package/sections/lib/sections/helper/section.rb

@@ -3,14 +3,12 @@ module Ramaze
     ##
     # Helper for the sections package.
     #
-    # @author Yorick Peterse
     # @since  0.2.8
     #
     module Section
       ##
       # Validates the section ID and returns the section if it's valid.
       #
-      # @author Yorick Peterse
       # @since  0.2.8
       # @param  [Fixnum] section_id The ID of the section to validate.
       # @return [Sections::Model::Section]
@@ -29,13 +27,12 @@ module Ramaze
       ##
       # Validates a section entry and returns it if it's valid.
       #
-      # 
-      # @author Yorick Peterse
+      #
       # @since  0.2.8
       # @param  [Fixnum] section_entry_id The ID of the section entry to
-      # validate.
+      #  validate.
       # @param  [Fixnum] section_id The ID of the section to use when
-      # redirecting the user to the overview of all entries.
+      #  redirecting the user to the overview of all entries.
       # @return [Sections::Model::SectionEntry]
       #
       def validate_section_entry(section_entry_id, section_id)