zen 0.2.8 → 0.3b

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

@@ -1,80 +1,92 @@
-#:nodoc:
 module Sections
   #:nodoc:
   module Controller
     ##
-    # Section entries can be seen as blog entries, products, all sorts of things.
-    # Each section belongs to a section and can't be created without one.
+    # Section entries are collections of custom field values as well as some
+    # meta data related to a section. In a typical application a blog can be
+    # seen as a section and blog articles would be section entries.
+    #
+    # Section entries can be managed by going to a section and clicking the link
+    # "Manage entries". This will bring you to an overview of all existing
+    # entries that looks like the one in the image below.
+    #
+    # ![Section Entries](../../_static/sections/entries.png)
+    #
+    # Editing an entry can be done by clicking on it's name, creating a new one
+    # can be done by clicking on the "Add section entry" button. In both cases
+    # you'll see a form that looks similar to the one displayed in the images
+    # below.
+    #
+    # ![Edit Entry](../../_static/sections/edit_entry.png)
+    # ![Categories](../../_static/sections/edit_entry_categories.png)
+    # ![General](../../_static/sections/edit_entry_general.png)
+    # ![Meta](../../_static/sections/edit_entry_meta.png)
+    #
+    # In the images above there are four tabs displayed. "Basic", "Categories",
+    # "General" and "Meta". The first two are always available, the last two
+    # tabs are tabs specific to the custom field groups assigned to a section
+    # the entry belongs to. This means that you might have other tabs depending
+    # on the names of your field groups.
+    #
+    # Regardless of what field groups and categories you have assigned you can
+    # always specify the following fields:
+    #
+    # * **Title** (required): the title of your entry.
+    # * **Slug**: a URL friendly version of the title. If no slug is specified
+    #   one will be generated manually.
+    # * **Created at**: The date on which the entry was created. This field is
+    #   filled in automatically when an entry is created.
+    # * **Author** (required): the name of the person who wrote the entry.
+    # * **Status** (required): the status of an entry. If an entry has a status
+    #   other than "Published" it will not be displayed when using the
+    #   sectio_entries plugin.
+    #
+    # Depending on whether or not you have category and field groups assigned
+    # you can also use these fields. In the images above there's a "Body" field
+    # which is required and converts the text to HTML using Markdown.
+    #
+    # ## Permissions
+    #
+    # This controller uses the following permissions:
+    #
+    # * show_section_entry
+    # * new_section_entry
+    # * edit_section_entry
+    # * delete_section_entry
+    #
+    # ## Events
+    #
+    # All events in this controller receive an instance of
+    # {Sections::Model::SectionEntry}. The event ``after_delete_section_entry``
+    # receives an instance of this model that has already been destroyed using
+    # ``#destroy()``.
     #
-    # @author Yorick Peterse
     # @since  0.1
+    # @map    /admin/section-entries
+    # @event  before_new_section_entry
+    # @event  after_new_section_entry
+    # @event  before_edit_section_entry
+    # @event  after_edit_section_entry
+    # @event  before_delete_section_entry
+    # @event  after_delete_section_entry
     #
     class SectionEntries < Zen::Controller::AdminController
-      include ::Sections::Model
-
-      map '/admin/section-entries'
+      map    '/admin/section-entries'
       helper :section
+      title  'section_entries.titles.%s'
 
-      # Load all required Javascript files
-      javascript(
-        [
-          'zen/lib/tabs',
-          'zen/lib/editor',
-          'zen/lib/editor/markdown',
-          'zen/lib/editor/textile',
-          'vendor/datepicker'
-        ],
-        :method => [:edit, :new]
-      )
-
-      # Load all required CSS files
-      stylesheet(['zen/datepicker'], :method => [:edit, :new])
-
-      before_all do
-        csrf_protection(:save, :delete) do
-          respond(lang('zen_general.errors.csrf'), 403)
-        end
-      end
+      load_asset_group [:tabs, :editor, :datepicker], [:edit, :new]
+      csrf_protection  :save, :delete
 
       ##
-      # 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
-      # * section_entries
-      # * zen_models
-      #
-      # @author Yorick Peterse
-      # @since  0.1
-      #
-      def initialize
-        super
-
-        Zen::Language.load('section_entries')
-        Zen::Language.load('sections')
-
-        # Set the page title
-        if !action.method.nil?
-          method      = action.method.to_sym
-          @page_title = lang("section_entries.titles.#{method}") rescue nil
-        end
-      end
-
-      ##]
       # Show an overview of all entries for the current section.
       #
-      # This method requires the following permissions:
-      #
-      # * read
-      #
-      # @author Yorick Peterse
-      # @param  [Fixnum] section_id The ID of the current section.
-      # @since  0.1
+      # @param      [Fixnum] section_id The ID of the current section.
+      # @since      0.1
+      # @permission show_section_entry
       #
       def index(section_id)
-        require_permissions(:read)
+        authorize_user!(:show_section_entry)
 
         set_breadcrumbs(
           Sections.a(lang('sections.titles.index'), :index),
@@ -83,25 +95,28 @@ module Sections
 
         section     = validate_section(section_id)
         @section_id = section_id
-        @entries    = SectionEntry.filter(:section_id => section_id)
-        @entries    = paginate(@entries)
+        @entries    = search do |query|
+          ::Sections::Model::SectionEntry.search(query) \
+            .filter(:section_id => section_id) \
+            .order(:id.asc)
+        end
+
+        @entries  ||= ::Sections::Model::SectionEntry \
+          .filter(:section_id => section_id) \
+          .order(:id.asc)
+
+        @entries = paginate(@entries)
       end
 
       ##
-      # Show a form that lets the user edit an existing section entry.
-      #
-      # This method requires the following permissions:
-      #
-      # * read
-      # * update
+      # Show a form that lets the user create a new section entry.
       #
-      # @author Yorick Peterse
-      # @param  [Fixnum] section_id The ID of the current section.
-      # @param  [Fixnum] entry_id The ID of the current section entry.
-      # @since  0.1
+      # @param      [Fixnum] section_id The ID of the current section.
+      # @since      0.1
+      # @permission new_section_entry
       #
-      def edit(section_id, entry_id)
-        require_permissions(:read, :update)
+      def new(section_id)
+        authorize_user!(:new_section_entry)
 
         set_breadcrumbs(
           Sections.a(
@@ -110,18 +125,21 @@ module Sections
           SectionEntries.a(
             lang('section_entries.titles.index'), :index, section_id
           ),
-          lang('section_entries.titles.edit')
+          lang('section_entries.titles.new')
         )
 
         validate_section(section_id)
 
+        @section_id  = section_id
+
         if flash[:form_data]
           @entry = flash[:form_data]
         else
-          @entry = validate_section_entry(entry_id, section_id)
+          @entry = ::Sections::Model::SectionEntry.new(
+            :section_id => section_id
+          )
         end
 
-        @section_id          = section_id
         @possible_categories = @entry.possible_categories
         @custom_fields_hash  = @entry.custom_fields_hash
 
@@ -129,19 +147,15 @@ module Sections
       end
 
       ##
-      # Show a form that lets the user create a new section entry.
-      #
-      # This method requires the following permissions:
-      #
-      # * read
-      # * create
+      # Show a form that lets the user edit an existing section entry.
       #
-      # @author Yorick Peterse
-      # @param  [Fixnum] section_id The ID of the current section.
-      # @since  0.1
+      # @param      [Fixnum] section_id The ID of the current section.
+      # @param      [Fixnum] entry_id The ID of the current section entry.
+      # @since      0.1
+      # @permission edit_section_entry
       #
-      def new(section_id)
-        require_permissions(:read, :create)
+      def edit(section_id, entry_id)
+        authorize_user!(:edit_section_entry)
 
         set_breadcrumbs(
           Sections.a(
@@ -150,13 +164,18 @@ module Sections
           SectionEntries.a(
             lang('section_entries.titles.index'), :index, section_id
           ),
-          lang('section_entries.titles.new')
+          lang('section_entries.titles.edit')
         )
 
         validate_section(section_id)
 
+        if flash[:form_data]
+          @entry = flash[:form_data]
+        else
+          @entry = validate_section_entry(entry_id, section_id)
+        end
+
         @section_id          = section_id
-        @entry               = SectionEntry.new(:section_id => section_id)
         @possible_categories = @entry.possible_categories
         @custom_fields_hash  = @entry.custom_fields_hash
 
@@ -164,21 +183,16 @@ module Sections
       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 entry and all the field values or
+      # creates a new entry.
       #
-      # * create
-      # * save
-      #
-      # @author Yorick Peterse
-      # @since  0.1
-      # @todo The way this method handles the creation of field values might
-      # require some patches as it executes quite a few queries. I'll keep it
-      # as it is for now.
+      # @since      0.1
+      # @event      before_new_section_entry
+      # @event      after_new_section_entry
+      # @event      before_edit_section_entry
+      # @event      after_edit_section_entry
+      # @permission edit_section_entry (when editing an entry)
+      # @permission new_section_entry (when creating a new entry)
       #
       def save
         section_id = request.params['section_id']
@@ -186,48 +200,70 @@ module Sections
         validate_section(section_id)
 
         if request.params['id'] and !request.params['id'].empty?
-          require_permissions(:update)
+          authorize_user!(:edit_section_entry)
 
-          @entry      = SectionEntry[request.params['id']]
-          save_action = :save
+          entry        = ::Sections::Model::SectionEntry[request.params['id']]
+          save_action  = :save
+          before_event = :before_edit_section_entry
+          after_event  = :after_edit_section_entry
 
           # Section entries aren't considered to be updated whenever a custom
           # field value is modified, this solves that problem
           request.params['updated_at'] = Time.new
         else
-          require_permissions(:create)
+          authorize_user!(:new_section_entry)
 
-          @entry      = SectionEntry.new(:section_id => section_id)
-          save_action = :new
+          entry = ::Sections::Model::SectionEntry.new(:section_id => section_id)
+          before_event = :before_new_section_entry
+          after_event  = :after_new_section_entry
+          save_action  = :new
         end
 
-        request.params.delete('slug') if request.params['slug'].empty?
         request.params.delete('id')
 
-        flash_success = lang("section_entries.success.#{save_action}")
-        flash_error   = lang("section_entries.errors.#{save_action}")
-        custom_fields = @entry.custom_fields
+        success       = lang("section_entries.success.#{save_action}")
+        error         = lang("section_entries.errors.#{save_action}")
+        custom_fields = entry.custom_fields
         field_errors  = {}
         field_values  = {}
 
-        @entry.custom_field_values.each do |value|
+        entry.custom_field_values.each do |value|
           field_values[value.custom_field_id] = value
         end
 
         begin
           Zen.database.transaction do
             # Update the entry itself
-            @entry.update(request.subset(
+            post_data = request.subset(
               :title,
               :created_at,
               :updated_at,
               :section_id,
               :user_id,
               :slug,
-              :section_entry_status_id
-            ))
+              :section_entry_status_id,
+              :category_pks
+            )
+
+            # Transform the dates properly
+            if post_data[:created_at]
+              post_data[:created_at] = Time.strptime(
+                post_data[:created_at],
+                date_format
+              )
+            end
 
-            message(:success, flash_success)
+            if post_data[:updated_at]
+              post_data[:updated_at] = Time.strptime(
+                post_data[:updated_at],
+                date_format
+              )
+            end
+
+            post_data.each { |k, v| entry.send("#{k}=", v) }
+            Zen::Event.call(before_event, entry)
+
+            entry.save
 
             # Update/add all the custom field values
             custom_fields.each do |field|
@@ -249,7 +285,7 @@ module Sections
                   field_values[field.id].update(:value => request.params[key])
                 # Add it
                 else
-                  @entry.add_custom_field_value(
+                  entry.add_custom_field_value(
                     :custom_field_id => field.id,
                     :value           => request.params[key]
                   )
@@ -264,34 +300,31 @@ module Sections
         # 3. Something else went wrong, god knows what.
         rescue => e
           Ramaze::Log.error(e.inspect)
-          message(:error, flash_error)
+          message(:error, error)
 
-          flash[:form_errors] = @entry.errors.merge(field_errors)
-          flash[:form_data]   = @entry
+          flash[:form_errors] = entry.errors.merge(field_errors)
+          flash[:form_data]   = entry
 
           redirect_referrer
         end
 
-        if @entry.id
-          redirect(SectionEntries.r(:edit, section_id, @entry.id))
-        else
-          redirect_referrer
-        end
+        Zen::Event.call(after_event, entry)
+
+        message(:success, success)
+        redirect(SectionEntries.r(:edit, section_id, entry.id))
       end
 
       ##
       # Delete a set of section entries based on the supplied POST
       # field "section_entry_ids".
       #
-      # This method requires the following permissions:
-      #
-      # * delete
-      #
-      # @author Yorick Peterse
-      # @since  0.1
+      # @since      0.1
+      # @permission delete_section_entry
+      # @event      before_delete_section_entry
+      # @event      after_delete_section_entry
       #
       def delete
-        require_permissions(:delete)
+        authorize_user!(:delete_section_entry)
 
         if !request.params['section_entry_ids'] \
         or request.params['section_entry_ids'].empty?
@@ -300,17 +333,24 @@ module Sections
         end
 
         request.params['section_entry_ids'].each do |id|
+          entry = ::Sections::Model::SectionEntry[id]
+
+          next if entry.nil?
+          Zen::Event.call(:before_delete_section_entry, entry)
+
           begin
-            SectionEntry[id].destroy
-            message(:success, lang('section_entries.success.delete'))
+            entry.destroy
           rescue => e
             Ramaze::Log.error(e.inspect)
             message(:error,lang('section_entries.errors.delete') % id)
 
             redirect_referrer
           end
+
+          Zen::Event.call(:after_delete_section_entry, entry)
         end
 
+        message(:success, lang('section_entries.success.delete'))
         redirect_referrer
       end
     end  # SectionEntries