zen 0.2.8 → 0.3b

data/lib/zen/package/custom_fields/lib/custom_fields/controller/custom_field_types.rb

@@ -1,43 +1,88 @@
-#:nodoc:
 module CustomFields
   #:nodoc:
   module Controller
     ##
-    # Controller that can be used to manage individual custom field types.
+    # Custom field types allow you to create your own types of fields. Being
+    # able to create your own field types without having to write any code can
+    # be very useful. For example, say you want to be able to create a textarea
+    # with a special class (maybe you can to use CKEditor), all you'd have to do
+    # is create a new field type, add the class and you're good to go.
+    #
+    # In order to manage field types you'll have to navigate to
+    # ``/admin/custom-field-types``. This can be done by either manually
+    # entering the URL into your browser's URL bar or by hovering over the
+    # "Custom fields" menu item, this will cause the menu to expand and show a
+    # URL called "Custom field types". Clicking this URL will take you to an
+    # overview of all existing field types.
+    #
+    # ![Types](../../_static/custom_fields/custom_field_types.png)
+    #
+    # ## Adding/Editing Field Types
+    #
+    # Editing a field type can be done by clicking on the name of the field
+    # type, creating a new one can be done by clicking the "Add field type"
+    # button. In both cases you'll end up at a form that looks like the image
+    # below.
+    #
+    # ![Edit Type](../../_static/custom_fields/edit_custom_field_type.png)
+    #
+    # In this form you can specify the following fields:
+    #
+    # * **Name** (required): the name of the custom field type. This name can be
+    #   anything you like.
+    # * **Language string** (required): a valid language string that will result
+    #   in a language specific block of text. This text will be used for the
+    #   label.
+    # * **HTML Class**: a space separated list of HTML classes to apply to the
+    #   field type. The format of this value has to match the regular expression
+    #   ``/^[a-zA-Z\-_0-9\s]*$/``.
+    # * **Serialize**: whether or not the value of a field using this type
+    #   should be serialized. Set this to "Yes" if a field takes multiple values
+    #   such as a checkbox or a select element with the attribute
+    #   ``multiple="multiple"``.
+    # * **Allow markup**: whether or not users can use markup, such as Markdown
+    #   in a field using this type.
+    # * **Custom field method** (required): the name of a method in
+    #   {CustomFields::BlueFormParameters}. This method will be used to generate
+    #   all the parameters for the BlueForm helper.
+    #
+    # Note that the name, language string and HTML class can not be longer than
+    # 255 characters.
+    #
+    # ## Used Permissions
+    #
+    # * show_custom_field_type
+    # * edit_custom_field_type
+    # * new_custom_field_type
+    # * delete_custom_field_type
+    #
+    # ## Events
+    #
+    # All events in this controller will receive an instance of
+    # {CustomFields::Model::CustomFieldType}. Just like other packages the event
+    # ``after_delete_custom_field_type`` receives an instance that has already
+    # been destroyed. This means that this event can not be used to make changes
+    # to the object and save them.
     #
-    # @author Yorick Peterse
     # @since  0.2.8
+    # @map    /admin/custom-field-types
+    # @event  before_new_custom_field_type
+    # @event  after_new_custom_field_type
+    # @event  before_edit_custom_field_type
+    # @event  after_edit_custom_field_type
+    # @event  before_delete_custom_field_type
+    # @event  after_delete_custom_field_type
     #
     class CustomFieldTypes < Zen::Controller::AdminController
-      include ::CustomFields::Model
-
       map    '/admin/custom-field-types'
       helper :custom_field
+      title  'custom_field_types.titles.%s'
 
-      before_all do
-        csrf_protection(:save, :delete) do
-          respond(lang('zen_general.errors.csrf'), 403)
-        end
-      end
-
-      ##
-      # Creates a new instance of the controller, loads all the required
-      # language files and sets the page title.
-      #
-      # @author Yorick Peterse
-      # @since  0.2.8
-      #
-      def initialize
-        super
-
-        Zen::Language.load('custom_field_types')
-
-        if !action.method.nil?
-          @page_title = lang(
-            "custom_field_types.titles.#{action.method}"
-          ) rescue nil
-        end
+      csrf_protection :save, :delete
 
+      # Blck that's executed before CustomFieldTypes#edit() and
+      # CustomFieldTypes#new().
+      before(:index, :edit, :new) do
         @boolean_hash = {
           true  => lang('zen_general.special.boolean_hash.true'),
           false => lang('zen_general.special.boolean_hash.false')
@@ -49,86 +94,86 @@ module CustomFields
       # user to create new ones, edit existing ones or delete a group of field
       # types.
       #
-      # This method requires read permissions for a user to be able to view all
-      # the field types.
-      #
-      # @author Yorick Peterse
-      # @since  0.2.8
+      # @since      0.2.8
+      # @permission show_custom_field_type
       #
       def index
-        require_permissions(:read)
+        authorize_user!(:show_custom_field_type)
 
         set_breadcrumbs(lang('custom_field_types.titles.index'))
 
-        @field_types = paginate(CustomFieldType.eager(:custom_field_method))
+        @field_types = search do |query|
+          ::CustomFields::Model::CustomFieldType.search(query).order(:id.asc)
+        end
+
+        @field_types ||= ::CustomFields::Model::CustomFieldType \
+          .eager(:custom_field_method) \
+          .order(:id.asc)
+
+        @field_types = paginate(@field_types)
       end
 
       ##
       # Allows a user to edit an existing custom field type.
       #
-      # This method requires the following permissions:
-      #
-      # * read
-      # * update
-      #
-      # @author Yorick Peterse
-      # @since  0.2.8
-      # @param  [Fixnum] custom_field_type_id The ID of the custom field type to
-      # edit.
+      # @since      0.2.8
+      # @param      [Fixnum] id The ID of the custom field type to edit.
+      # @permission edit_custom_field_type
       #
-      def edit(custom_field_type_id)
-        require_permissions(:read, :update)
+      def edit(id)
+        authorize_user!(:edit_custom_field_type)
 
         set_breadcrumbs(
           CustomFieldTypes.a(lang('custom_field_types.titles.index'), :index),
           lang('custom_field_types.titles.edit')
         )
 
-        if flash[:form_data]
-          @custom_field_type = flash[:form_data]
-        else
-          @custom_field_type = validate_custom_field_type(custom_field_type_id)
-        end
-
-        @custom_field_methods = CustomFieldMethod.pk_hash(:name)
+        @custom_field_type = flash[:form_data] || validate_custom_field_type(id)
+        @custom_field_methods = ::CustomFields::Model::CustomFieldMethod \
+          .pk_hash(:name)
 
-        render_view :form
+        render_view(:form)
       end
 
       ##
       # Allows a user to add a new custom field type.
       #
-      # This method requires the following permissions:
-      #
-      # * read
-      # * create
-      #
-      # @author Yorick Peterse
-      # @since  0.2.8
+      # @since      0.2.8
+      # @permission new_custom_field_type
       #
       def new
-        require_permissions(:read, :create)
+        authorize_user!(:new_custom_field_type)
 
         set_breadcrumbs(
           CustomFieldTypes.a(lang('custom_field_types.titles.index'), :index),
           lang('custom_field_types.titles.new')
         )
 
-        @custom_field_methods = CustomFieldMethod.pk_hash(:name)
-        @custom_field_type    = CustomFieldType.new
+        @custom_field_methods = ::CustomFields::Model::CustomFieldMethod \
+          .pk_hash(:name)
+
+        if flash[:form_data]
+          @custom_field_type = flash[:form_data]
+        else
+          @custom_field_type = ::CustomFields::Model::CustomFieldType.new
+        end
 
-        render_view :form
+        render_view(:form)
       end
 
       ##
-      # Saves the data submitted by CustomFieldTypes#edit() and
-      # CustomFieldTypes#add().
+      # Creates a new custom field type or edits an existing one.
       #
       # This method requires either create or update permissions based on the
       # supplied data.
       #
-      # @author Yorick Peterse
-      # @since  0.2.8
+      # @since      0.2.8
+      # @event      before_edit_custom_field_type
+      # @event      after_edit_custom_field_type
+      # @event      before_new_custom_field_type
+      # @event      after_new_custom_field_type
+      # @permission edit_custom_field_type (when editing a field type)
+      # @permission new_custom_field_type (when creating a field type)
       #
       def save
         post = request.subset(
@@ -142,15 +187,19 @@ module CustomFields
         )
 
         if post['id'] and !post['id'].empty?
-          require_permissions(:update)
+          authorize_user!(:edit_custom_field_type)
 
-          field_type  = validate_custom_field_type(post['id'])
-          save_action = :save
+          field_type   = validate_custom_field_type(post['id'])
+          save_action  = :save
+          before_event = :before_edit_custom_field_type
+          after_event  = :after_edit_custom_field_type
         else
-          require_permissions(:create)
+          authorize_user!(:new_custom_field_type)
 
-          field_type  = CustomFieldType.new
-          save_action = :new
+          field_type   = ::CustomFields::Model::CustomFieldType.new
+          save_action  = :new
+          before_event = :before_new_custom_field_type
+          after_event  = :after_new_custom_field_type
         end
 
         post.delete('id')
@@ -159,8 +208,10 @@ module CustomFields
         error   = lang("custom_field_types.errors.#{save_action}")
 
         begin
-          field_type.update(post)
-          message(:success, success)
+          post.each { |k, v| field_type.send("#{k}=", v) }
+          Zen::Event.call(before_event, field_type)
+
+          field_type.save
         rescue => e
           Ramaze::Log.error(e.inspect)
           message(:error, error)
@@ -171,24 +222,23 @@ module CustomFields
           redirect_referrer
         end
 
-        if field_type.id
-          redirect(CustomFieldTypes.r(:edit, field_type.id))
-        else
-          redirect_referrer
-        end
+        Zen::Event.call(after_event, field_type)
+
+        message(:success, success)
+        redirect(CustomFieldTypes.r(:edit, field_type.id))
       end
 
       ##
-      # Deletes a number of custom field types.
-      #
-      # This method requires delete permissions for a user to be able to remove
-      # a number of database records.
+      # Deletes a number of custom field types. These types should be specified
+      # in the POST array "custom_field_type_ids".
       #
-      # @author Yorick Peterse
-      # @since  0.2.8
+      # @since      0.2.8
+      # @event      before_delete_custom_field_type
+      # @event      after_delete_custom_field_type
+      # @permission delete_custom_field_type
       #
       def delete
-        require_permissions(:delete)
+        authorize_user!(:delete_custom_field_type)
 
         if !request.params['custom_field_type_ids'] \
         or request.params['custom_field_type_ids'].empty?
@@ -197,14 +247,21 @@ module CustomFields
         end
 
         request.params['custom_field_type_ids'].each do |id|
+          type = ::CustomFields::Model::CustomFieldType[id]
+
+          next if type.nil?
+          Zen::Event.call(:before_delete_custom_field_type, type)
+
           begin
-            CustomFieldType[id].destroy
+            type.destroy
           rescue => e
             Ramaze::Log.error(e.inspect)
             message(:error, lang('custom_field_types.errors.delete') % id)
 
             redirect_referrer
           end
+
+          Zen::Event.call(:after_delete_custom_field_type, type)
         end
 
         message(:success, lang('custom_field_types.success.delete'))

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

@@ -1,67 +1,91 @@
-#:nodoc:
 module CustomFields
   #:nodoc:
   module Controller
     ##
-    # Controller for managing custom fields. Custom fields are one of
-    # the most important elements in Zen. Custom fields can be used to
-    # create radio buttons, textareas, the whole shebang. Before
-    # being able to use a custom field you'll need to add it to a group
-    # and bind that group to a section.
+    # Custom fields allow you to create fields for your entries in their own
+    # format and with their own types. This means you're not restricted to the
+    # typical "Title" and "Body" fields you'd get when using other systems.
+    #
+    # Custom fields can be managed to by going to a custom field group and
+    # clicking the link "Manage custom fields" (see
+    # {CustomFields::Controller::CustomFieldGroups} for more information). Once
+    # you've reached this page you'll see an overview of all your custom fields
+    # or a message saying no fields were found (if this is the case).
+    #
+    # ![Custom Fields](../../_static/custom_fields/custom_fields.png)
+    #
+    # Editing a custom field can be done by clicking on the name of the field,
+    # creating a new one can be done by clicking on the button "Add custom
+    # field". In both cases you'll be shown a form that looks like the one in
+    # the image below.
+    #
+    # ![General](../../_static/custom_fields/edit_custom_field_general.png)
+    # ![Settings](../../_static/custom_fields/edit_custom_field_settings.png)
+    #
+    # In this form you can specify the following fields:
+    #
+    # * **Name** (required): the name of the custom field, can be anything you
+    #   like. Examples are "Body" and "Date picker".
+    # * **Slug**: a URL friendly version of the name. If none is specified one
+    #   will be generated automatically.
+    # * **Field type** (required): the type of custom field.
+    # * **Format** (required): the markup engine to use for the custom field. If
+    #   a custom field type doesn't allow the use of markup this setting will
+    #   be ignored.
+    # * **Description**: a description of the custom field.
+    # * **Possible values**: in case a custom field type allows you to specify
+    #   multiple values (such as a checkbox) you can specify a value on each
+    #   line. These values can be specified as following:
+    #
+    #       key|value
+    #
+    #   Example:
+    #
+    #       Yes!|yes
+    #
+    # * **Requires a value**: whether or not this field requires a value.
+    # * **Enable a text editor**: when set to "Yes" the user can use the markup
+    #   editor when adding/editing a value of a field.
+    # * **Textarea rows**: the amount of rows when the field type is a textarea.
+    # * **Character limit**: the maximum amount of characters a user can enter
+    #   in the field.
+    # * **Sort order**: a number that indicates the sort order of the field.
+    #
+    # ## Used Permissions
+    #
+    # * show_custom_field
+    # * new_custom_field
+    # * edit_custom_field
+    # * delete_custom_field
+    #
+    # ## Events
+    #
+    # All events in this controller receive an instance of
+    # {CustomFields::Model::CustomField}. Just like other packages the event
+    # ``after_delete_custom_field`` receives an instance that has already been
+    # destroyed, thus you won't be able to make any changes to the object and
+    # save them in the database.
     #
-    # @author Yorick Peterse
     # @since  0.1
+    # @map    /admin/custom-fields
+    # @event  before_new_custom_field
+    # @event  after_new_custom_field
+    # @event  before_edit_custom_field
+    # @event  after_edit_custom_field
+    # @event  before_delete_custom_field
+    # @event  after_delete_custom_field
     #
     class CustomFields < Zen::Controller::AdminController
-      include ::CustomFields::Model
-
       helper :custom_field
       map    '/admin/custom-fields'
+      title  'custom_fields.titles.%s'
 
-      # Load all required Javascript files
-      javascript ['zen/lib/tabs']
-
-      before_all do
-        csrf_protection(:save, :delete) do
-          respond(lang('zen_general.errors.csrf'), 403)
-        end
-      end
+      csrf_protection  :save; :delete
+      load_asset_group :tabs, [:edit, :new]
 
-      ##
-      # Hook that is executed before the index(), edit() and new() methods.
-      #
-      # @author Yorick Peterse
-      # @since  0.2.8
-      #
       before(:index, :edit, :new) do
-        @custom_field_types = CustomFieldType.type_hash
-      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:
-      #
-      # * custom_fields
-      # * custom_field_groups
-      #
-      # @author Yorick Peterse
-      # @since  0.1
-      #
-      def initialize
-        super
-
-        Zen::Language.load('custom_fields')
-        Zen::Language.load('custom_field_groups')
-
-        # Set the page title
-        if !action.method.nil?
-          method      = action.method.to_sym
-          @page_title = lang("custom_fields.titles.#{method}") rescue nil
-        end
-
-        @boolean_hash = {
+        @custom_field_types = ::CustomFields::Model::CustomFieldType.type_hash
+        @boolean_hash       = {
           true  => lang('zen_general.special.boolean_hash.true'),
           false => lang('zen_general.special.boolean_hash.false')
         }
@@ -71,29 +95,31 @@ module CustomFields
       # Show an overview of all existing custom fields. Using this overview a
       # user can manage an existing field, delete it or create a new one.
       #
-      # This method requires the following permissions:
-      #
-      # * read
-      #
-      # @author Yorick Peterse
       # @param  [Fixnum] custom_field_group_id The ID of the custom field group
-      # to which all fields belong.
-      # @since  0.1
+      #  to which all fields belong.
+      # @since      0.1
+      # @permission show_custom_field
       #
       def index(custom_field_group_id)
-        require_permissions(:read)
-
-        field_group = validate_custom_field_group(custom_field_group_id)
+        authorize_user!(:show_custom_field)
 
         set_breadcrumbs(
           CustomFieldGroups.a(lang('custom_field_groups.titles.index'), :index),
           lang('custom_fields.titles.index')
         )
 
+        field_group = validate_custom_field_group(custom_field_group_id)
         @custom_field_group_id = custom_field_group_id
-        @custom_fields         = CustomField.filter(
-          :custom_field_group_id => custom_field_group_id
-        )
+        @custom_fields         = search do |query|
+          ::CustomFields::Model::CustomField \
+            .search(query) \
+            .filter(:custom_field_group_id => custom_field_group_id) \
+            .order(:id.asc)
+        end
+
+        @custom_fields ||= ::CustomFields::Model::CustomField \
+          .filter(:custom_field_group_id => custom_field_group_id) \
+          .order(:id.asc)
 
         @custom_fields = paginate(@custom_fields)
       end
@@ -101,29 +127,27 @@ module CustomFields
       ##
       # Show a form that lets the user edit an existing custom field group.
       #
-      # This method requires the following permissions:
-      #
-      # * read
-      # * update
-      #
-      # @author Yorick Peterse
-      # @param  [Fixnum] custom_field_group_id The ID of the custom field
-      # group to which all fields belong.
+      # @param  [Fixnum] id The ID of the custom field
+      #  group to which all fields belong.
       # @param  [Fixnum] id The ID of the custom field to retrieve so that we
-      # can edit it.
-      # @since  0.1
+      #  can edit it.
+      # @since      0.1
+      # @permission edit_custom_field
       #
       def edit(custom_field_group_id, id)
-        require_permissions(:read, :update)
+        authorize_user!(:edit_custom_field)
 
         validate_custom_field_group(custom_field_group_id)
 
         set_breadcrumbs(
           CustomFieldGroups.a(
-            lang('custom_field_groups.titles.index'), :index
+            lang('custom_field_groups.titles.index'),
+            :index
           ),
           CustomFields.a(
-            lang('custom_fields.titles.index'), :index, custom_field_group_id
+            lang('custom_fields.titles.index'),
+            :index,
+            custom_field_group_id
           ),
           lang('custom_fields.titles.edit')
         )
@@ -142,50 +166,50 @@ module CustomFields
       ##
       # Show a form that lets the user create a new custom field group.
       #
-      # This method requires the following permissions:
-      #
-      # * create
-      # * read
-      #
-      # @author Yorick Peterse
       # @param  [Fixnum] custom_field_group_id The ID of the custom field group
-      # to which all fields belong.
-      # @since  0.1
+      #  to which all fields belong.
+      # @since      0.1
+      # @permission new_custom_field
       #
       def new(custom_field_group_id)
-        require_permissions(:read, :create)
+        authorize_user!(:new_custom_field)
 
         validate_custom_field_group(custom_field_group_id)
 
         set_breadcrumbs(
           CustomFieldGroups.a(
-            lang('custom_field_groups.titles.index'), :index
+            lang('custom_field_groups.titles.index'),
+            :index
           ),
           CustomFields.a(
-            lang('custom_fields.titles.index'), :index, custom_field_group_id
+            lang('custom_fields.titles.index'),
+            :index,
+            custom_field_group_id
           ),
           lang('custom_fields.titles.new')
         )
 
         @custom_field_group_id = custom_field_group_id
-        @custom_field          = CustomField.new
+
+        if flash[:form_data]
+          @custom_field = flash[:form_data]
+        else
+          @custom_field = ::CustomFields::Model::CustomField.new
+        end
 
         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 custom field or to
-      # update an existing one.
-      #
-      # This method requires the following permissions:
+      # Saves the changes made by {#edit} and {#new}.
       #
-      # * create
-      # * update
-      #
-      # @author Yorick Peterse
-      # @since  0.1
+      # @since      0.1
+      # @event      before_new_custom_field
+      # @event      after_new_custom_field
+      # @event      before_edit_custom_field
+      # @event      after_edit_custom_field
+      # @permission edit_custom_field (when editing a field)
+      # @permission new_custom_field (when creating a new field)
       #
       def save
         post = request.subset(
@@ -209,32 +233,37 @@ module CustomFields
         # Get or create a custom field group based on the ID from the hidden
         # field.
         if post['id'] and !post['id'].empty?
-          require_permissions(:update)
+          authorize_user!(:edit_custom_field)
 
           custom_field = validate_custom_field(
             post['id'], post['custom_field_group_id']
           )
 
           save_action  = :save
+          before_event = :before_edit_custom_field
+          after_event  = :after_edit_custom_field
         else
-          require_permissions(:create)
+          authorize_user!(:new_custom_field)
 
-          custom_field = CustomField.new
+          custom_field = ::CustomFields::Model::CustomField.new
           save_action  = :new
+          before_event = :before_new_custom_field
+          after_event  = :after_new_custom_field
         end
 
-        post.delete('slug') if post['slug'].empty?
         post.delete('id')
 
-        flash_success = lang("custom_fields.success.#{save_action}")
-        flash_error   = lang("custom_fields.errors.#{save_action}")
+        success = lang("custom_fields.success.#{save_action}")
+        error   = lang("custom_fields.errors.#{save_action}")
 
         begin
-          custom_field.update(post)
-          message(:success, flash_success)
+          post.each { |k, v| custom_field.send("#{k}=", v) }
+          Zen::Event.call(before_event, custom_field)
+
+          custom_field.save
         rescue => e
           Ramaze::Log.error(e.inspect)
-          message(:error, flash_error)
+          message(:error, error)
 
           flash[:form_data]   = custom_field
           flash[:form_errors] = custom_field.errors
@@ -242,15 +271,12 @@ module CustomFields
           redirect_referrer
         end
 
-        if custom_field.id
-          redirect(
-            CustomFields.r(
-              :edit, post['custom_field_group_id'], custom_field.id
-            )
-          )
-        else
-          redirect_referrer
-        end
+        Zen::Event.call(after_event, custom_field)
+
+        message(:success, success)
+        redirect(
+          CustomFields.r(:edit, post['custom_field_group_id'], custom_field.id)
+        )
       end
 
       ##
@@ -260,36 +286,40 @@ module CustomFields
       # request that contains a field named 'custom_field_ids[]'. This field
       # should contain the primary values of each field that has to be deleted.
       #
-      # This method requires the following permissions:
-      #
-      # * delete
-      #
-      # @author Yorick Peterse
-      # @since  0.1
+      # @since      0.1
+      # @event      before_delete_custom_field
+      # @event      after_delete_custom_field
+      # @permission delete_custom_field
       #
       def delete
-        require_permissions(:delete)
+        authorize_user!(:delete_custom_field)
 
-        post = request.subset(:custom_field_ids, :custom_field_group_id)
+        post = request.subset(:custom_field_ids)
 
-        if !request.params['custom_field_ids'] \
-        or request.params['custom_field_ids'].empty?
+        if post['custom_field_ids'].nil? or post['custom_field_ids'].empty?
           message(:error, lang('custom_fields.errors.no_delete'))
-          redirect(CustomFields.r(:index, post['custom_field_group_id']))
+          redirect_referrer
         end
 
         request.params['custom_field_ids'].each do |id|
+          custom_field = ::CustomFields::Model::CustomField[id]
+
+          next if custom_field.nil?
+          Zen::Event.call(:before_delete_custom_field, custom_field)
+
           begin
-            CustomField[id].destroy
-            message(:success, lang('custom_fields.success.delete'))
+            custom_field.destroy
           rescue => e
             Ramaze::Log.error(e.inspect)
             message(:error, lang('custom_fields.errors.delete') % id)
 
             redirect_referrer
           end
+
+          Zen::Event.call(:after_delete_custom_field, custom_field)
         end
 
+        message(:success, lang('custom_fields.success.delete'))
         redirect_referrer
       end
     end # CustomFields