zen 0.4.2 → 0.4.3

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

@@ -0,0 +1,124 @@
+module Ramaze
+  module Helper
+    ##
+    # Helper for the controller {Sections::Controller::Revisions}.
+    #
+    # @since 2012-04-30
+    #
+    module Revision
+      ##
+      # Validates a revision ID. If the ID is invalid the user will be
+      # redirected back to the previous page and a message will be displayed.
+      #
+      # If the revision ID resulted in a valid Revision object then that object
+      # is returned.
+      #
+      # @since  2012-05-05
+      # @param  [Fixnum|String] revision_id The ID of the revision.
+      # @return [Sections::Model::Revision]
+      #
+      def validate_revision(revision_id)
+        unless revision_id =~ /\d+/
+          message(:error, lang('revisions.errors.invalid'))
+          redirect_referer
+        end
+
+        revision = Sections::Model::Revision[revision_id]
+
+        if revision
+          return revision
+        else
+          message(:error, lang('revisions.errors.invalid'))
+          redirect_referer
+        end
+      end
+
+      ##
+      # Returns a hash containing the difference between the values of two
+      # section entries.
+      #
+      # @since 2012-04-30
+      # @param  [Sections::Model::SectionEntry] entry The entry for which to
+      #  generate the diff.
+      # @param  [Fixnum|String] old_revision The old revision ID.
+      # @param  [Fixnum|String] new_revision The new revision ID.
+      # @return [Hash]
+      #
+      def revision_diff(entry, old_revision, new_revision)
+        validate_revision(old_revision)
+        validate_revision(new_revision)
+
+        old_values = entry.custom_fields_and_values(old_revision)
+        new_values = entry.custom_fields_and_values(new_revision)
+        diff       = {}
+
+        old_values.each do |field_id, hash|
+          new_hash = new_values[field_id]
+
+          if hash[:value] != new_hash[:value]
+            diff[hash[:name]] = Zen::HTMLDiff.diff(
+              hash[:value],
+              new_hash[:value]
+            )
+          end
+        end
+
+        return diff
+      end
+
+      ##
+      # Generates a radio button for an old revision ID.
+      #
+      # @since  2012-05-01
+      # @param  [Fixnum|String] rev_id The revision ID.
+      # @param  [Fixnum|String] current_rev_id The currently active old revision
+      #  ID.
+      # @return [String]
+      #
+      def old_revision_radio(rev_id, current_rev_id)
+        g     = Ramaze::Gestalt.new
+        attrs = {
+          :name  => 'old_revision_id',
+          :id    => "old_revision_id_#{rev_id}",
+          :type  => 'radio',
+          :value => rev_id
+        }
+
+        if rev_id.to_i == current_rev_id.to_i
+          attrs[:checked] = 'checked'
+        end
+
+        g.input(attrs)
+
+        return g.to_s
+      end
+
+      ##
+      # Generates a radio button for a new revision ID.
+      #
+      # @since  2012-05-01
+      # @param  [Fixnum|String] rev_id The revision ID.
+      # @param  [Fixnum|String] current_rev_id The currently active new revision
+      #  ID.
+      # @return [String]
+      #
+      def new_revision_radio(rev_id, current_rev_id)
+        g     = Ramaze::Gestalt.new
+        attrs = {
+          :name  => 'new_revision_id',
+          :id    => "new_revision_id_#{rev_id}",
+          :type  => 'radio',
+          :value => rev_id
+        }
+
+        if rev_id.to_i == current_rev_id.to_i
+          attrs[:checked] = 'checked'
+        end
+
+        g.input(attrs)
+
+        return g.to_s
+      end
+    end # Revision
+  end # Helper
+end # Ramaze

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

@@ -52,7 +52,7 @@ module Ramaze
       ##
       # Creates or updates a set of custom fields for a given section entry.
       #
-      # @since 17-02-2012
+      # @since 2012-02-17
       # @param [Sections::Model::SectionEntry] entry The entry for which to
       #  create or update the fields.
       # @return [Hash] Hash containing any errors for the custom fields.
@@ -62,10 +62,9 @@ module Ramaze
 
         field_values = {}
         field_errors = {}
-
-        entry.custom_field_values.each do |value|
-          field_values[value.custom_field_id] = value
-        end
+        revision     = entry.add_revision(
+          :user_id => (user.id rescue entry.user_id)
+        )
 
         entry.custom_fields.each do |field|
           key = "custom_field_value_#{field.id}"
@@ -80,14 +79,17 @@ module Ramaze
 
           next unless request.POST.key?(key)
 
-          if field_values.key?(field.id)
-            field_values[field.id].update(:value => request.POST[key])
-          else
-            entry.add_custom_field_value(
-              :custom_field_id => field.id,
-              :value           => request.POST[key]
-            )
-          end
+          entry.add_custom_field_value(
+            :custom_field_id => field.id,
+            :value           => request.POST[key],
+            :revision_id     => revision.id
+          )
+        end
+
+        if field_errors.empty?
+          entry.update(:revision_id => revision.id)
+        else
+          revision.destroy
         end
 
         return field_errors
@@ -97,7 +99,7 @@ module Ramaze
       # Redirects the user to the sections overview and shows a message
       # informing the user that the section he/she tried to access is invalid.
       #
-      # @since 09-04-2012
+      # @since 2012-04-09
       #
       def redirect_invalid_section
         message(:error, lang('sections.errors.invalid_section'))
@@ -109,7 +111,7 @@ module Ramaze
       # section and shows a message informing the user that the section entry
       # he/she tried to access is invalid.
       #
-      # @since 09-04-2012
+      # @since 2012-04-09
       # @param [Fixnum] section_id The ID of the section.
       #
       def redirect_invalid_section_entry(section_id)

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

@@ -1,13 +1,101 @@
 module Ramaze
   module Helper
     ##
-    # Helper for retrieving section entries in your templates.
+    # Helper for retrieving section entries in your templates. See
+    # {Ramaze::Helper::SectionFrontend#get\_entries} and
+    # {Ramaze::Helper::SectionFrontend#get\_entry}.
     #
     # @since  0.3
     #
     module SectionFrontend
       ##
       # Retrieves a number of entries for a given section ID or section slug.
+      # The return value is a Sequel dataset or an empty array in case no rows
+      # were found.
+      #
+      # Each row returned by this method is an instance of
+      # {Sections::Model::SectionEntry}. The custom fields and their values of
+      # each row are stored as a hash (the keys are symbols) in the "fields"
+      # attribute. For example, if you want to access the value of the "body"
+      # custom field you can do so as following:
+      #
+      #     get_entries('pages').each do |page|
+      #       puts page.fields[:body]
+      #     end
+      #
+      # Because the returned value is a Sequel dataset paginating content is
+      # very easy. This can be done by setting the option `:paginate` to true
+      # and calling `#navigation()` on the result set to generate a list of
+      # pagination links:
+      #
+      #     pages = get_entries('pages', :paginate => true)
+      #
+      #     pages.each do |page|
+      #       # ...
+      #     end
+      #
+      #     pages.navigation
+      #
+      # ## Lazy Loading
+      #
+      # To increase performance this method does not automatically retrieve
+      # related data such as comments and categories until they are used.
+      # However, if you plan on using this data for each returned row it is
+      # recommended to eager load this data as you'll otherwise have to execute
+      # a number of extra queries for each row.
+      #
+      # For example, this code block would generate a query for every row in
+      # order to retrieve user data:
+      #
+      #     get_entries('pages').each do |page|
+      #       page.user.email
+      #     end
+      #
+      # To work around this problem you can set the option `:user` (or another
+      # option depending on the related data you plan on using) to `true`. Doing
+      # so will make it possible to retrieve all related rows in a single query:
+      #
+      #     get_entries('pages', :user => true).each do |page|
+      #       page.user.email
+      #     end
+      #
+      # The following options can be set to `true` to enable eager loading
+      # (these are set to `false` by default):
+      #
+      # * comments
+      # * categories
+      # * user
+      #
+      # ## Disabling Markup
+      #
+      # By default each row's markup will be converted to HTML. If you don't
+      # need the markup you can disable this to speed things up a bit. This can
+      # be done by setting `:markup` to `false`:
+      #
+      #     get_entries('pages', :markup => false).each do |page|
+      #       page.title
+      #     end
+      #
+      # ## Etanni Example
+      #
+      # Below is an example on how to use this method inside an Etanni template.
+      #
+      #     <?r entries = get_entries('blog', :user => true) ?>
+      #
+      #     <?r entries.each do |entry| ?>
+      #     <article>
+      #         <header>
+      #             <h1>#{entry.title}</h1>
+      #             <p>Written by #{entry.user.name}</p>
+      #         </header>
+      #
+      #         <div class="body">
+      #             #{entry.fields[:body]}
+      #         </div>
+      #     </article>
+      #     <?r end ?>
+      #
+      #     #{entries.navigation}
       #
       # @example Retrieving all entries by a section's ID
       #  get_entries(2)
@@ -45,15 +133,15 @@ module Ramaze
       #  results should be paginated.
       # @option options [String] :var The name of the query string item that
       #  contains the current page number.
-      # @option options [TrueClass|FalseClass] :field_values Whether or not
-      #  custom fields and their values should be eager loaded. When set to
+      # @option options [TrueClass|FalseClass] :custom_field_values Whether or
+      #  not custom fields and their values should be eager loaded. When set to
       #  false the hash ``fields`` on each entry will **not** be filled.
       # @option options [TrueClass|FalseClass] :user Whether or not the user
       #  objects should be eager loaded for all entries. Set to ``false`` by
       #  default.
       # @option options [TrueClass|FalseClass] :markup When set to true
       #  (default) the values of custom fields are processed using
-      #  {Zen::Markup}}.
+      #  {Zen::Markup}.
       # @return [Mixed]
       #
       def get_entries(section, options = {})
@@ -127,12 +215,22 @@ module Ramaze
       end
 
       ##
-      # Retrieves the details of a single section entry.
+      # Retrieves the details of a single section entry. Due to the nature of
+      # this method all related data such as user details and categories are
+      # lazy loaded.
       #
-      # @example Get a single entry
+      # @example Get a single entry by the entry slug.
       #  entry = get_entry('home')
       #
+      #  puts entry.title
+      #
+      # @example Get an entry by its ID.
+      #  entry = get_entry(10)
+      #
+      #  puts entry.title
+      #
       # @since  0.3
+      # @see    Ramaze::Helper::SectionFrontend#get_entries()
       # @param  [String|Fixnum] entry The ID or slug of an entry to retrieve.
       # @param  [Hash] options A hash containing various options to customize
       #  the return value.

data/lib/zen/package/sections/lib/sections/language/en/revisions.rb

@@ -0,0 +1,34 @@
+Zen::Language::Translation.add do |trans|
+  trans.language = 'en'
+  trans.name     = 'revisions'
+
+  trans.translate do |t|
+    t['titles.index']         = 'Revisions'
+    t['titles.differences']   = 'Differences'
+    t['titles.revisions_for'] = 'Revisions for %s'
+
+    t['labels.old']        = 'Old'
+    t['labels.new']        = 'New'
+    t['labels.id']         = '#'
+    t['labels.user']       = 'User'
+    t['labels.created_at'] = 'Created at'
+    t['labels.restore']    = 'Restore'
+    t['labels.maximum']    = 'Revision amount'
+
+    t['descriptions.maximum'] = 'The maximum amount of revisions to keep.'
+
+    t['buttons.compare'] = 'Compare'
+
+    t['messages.no_differences'] = 'There are no differences between the ' \
+      'two specified revisions.'
+
+    t['messages.no_revisions'] = 'There are no revisions for this entry.'
+
+    t['success.restore'] = 'The revision has been restored'
+    t['errors.restore']  = 'The revision could not be restored'
+    t['errors.invalid']  = 'The specified revision is invalid'
+
+    t['permissions.show']    = 'Show revision'
+    t['permissions.restore'] = 'Restore revision'
+  end
+end

data/lib/zen/package/sections/lib/sections/language/en/sections.rb

@@ -27,6 +27,7 @@ Zen::Language::Translation.add do |trans|
     t['tabs.general']           = 'General'
     t['tabs.comment_settings']  = 'Comment Settings'
     t['tabs.group_assignments'] = 'Group Assignments'
+    t['tabs.content']           = 'Content'
 
     t['messages.no_sections'] = 'No sections have been created yet.'
 

data/lib/zen/package/sections/lib/sections/language/nl/revisions.rb

@@ -0,0 +1,35 @@
+Zen::Language::Translation.add do |trans|
+  trans.language = 'nl'
+  trans.name     = 'revisions'
+
+  trans.translate do |t|
+    t['titles.index']         = 'Revisies'
+    t['titles.differences']   = 'Verschillen'
+    t['titles.revisions_for'] = 'Revisies voor %s'
+
+    t['labels.old']        = 'Oud'
+    t['labels.new']        = 'Nieuw'
+    t['labels.id']         = '#'
+    t['labels.user']       = 'Gebruiker'
+    t['labels.created_at'] = 'Aangemaak datum'
+    t['labels.restore']    = 'Herstel'
+    t['labels.maximum']    = 'Aantal revisies'
+
+    t['descriptions.maximum'] = 'Het maximale aantal revisies dat behouden ' \
+      'moet blijven.'
+
+    t['buttons.compare'] = 'Vergelijk'
+
+    t['messages.no_differences'] = 'Er zijn geen verschillen tussen de twee ' \
+      'geselecteerde revisies.'
+
+    t['messages.no_revisions'] = 'Er zijn geen revisies voor dit item.'
+
+    t['success.restore'] = 'De revisie is hersteld'
+    t['errors.restore']  = 'De revisie kon niet worden hersteld'
+    t['errors.invalid']  = 'De opgegeven revisie is ongeldig'
+
+    t['permissions.show']    = 'Revisie weergeven'
+    t['permissions.restore'] = 'Revisie herstellen'
+  end
+end

data/lib/zen/package/sections/lib/sections/language/nl/sections.rb

@@ -27,6 +27,7 @@ Zen::Language::Translation.add do |trans|
     t['tabs.general']           = 'Algemeen'
     t['tabs.comment_settings']  = 'Reactie instellingen'
     t['tabs.group_assignments'] = 'Groepen'
+    t['tabs.content']           = 'Inhoud'
 
     t['messages.no_sections'] = 'Er konden geen secties worden gevonden.'
 

data/lib/zen/package/sections/lib/sections/model/revision.rb

@@ -0,0 +1,76 @@
+module Sections
+  module Model
+    ##
+    # Model for storing section entry revisions and linking these to custom
+    # field values.
+    #
+    # @since 2012-04-29
+    #
+    class Revision < Sequel::Model
+      many_to_one :section_entry,
+        :class => 'Sections::Model::SectionEntry'
+
+      many_to_one :user,
+        :class => 'Users::Model::User'
+
+      one_to_many :custom_field_values,
+        :class => 'CustomFields::Model::CustomFieldValue'
+
+      plugin :timestamps, :create => :created_at
+
+      plugin :association_dependencies,
+        :custom_field_values => :delete
+
+      ##
+      # Hook executed before inserting a new row. This hook is used to purge
+      # for a section entry if the amount of revisions for such an entry exceeds
+      # the maximum amount.
+      #
+      # @since 2012-05-01
+      #
+      def before_create
+        amount = Revision.filter(:section_entry_id => section_entry_id).count
+        max    = get_setting(:maximum_revisions).value.to_i
+
+        if amount >= max
+          Revision.filter(:section_entry_id => section_entry_id) \
+            .order(:id.asc) \
+            .first \
+            .delete
+        end
+
+        super
+      end
+
+      ##
+      # Hook that is executed before deleting the revision. This hook is used to
+      # prevent the last revision of an entry from being deleted.
+      #
+      # @since 2012-04-29
+      #
+      def before_destroy
+        entry = section_entry
+        _id   = id
+
+        # Set the revision ID of the entry to the previous revision.
+        if entry.revision_id == _id
+          prev_revision = Revision \
+            .filter(:section_entry_id => entry.id) { id < _id } \
+            .limit(1) \
+            .first
+
+          if prev_revision
+            entry.update(:revision_id => prev_revision.id)
+          else
+            raise(
+              Sequel::Error::InvalidOperation,
+              'You can not delete the last revision'
+            )
+          end
+        end
+
+        super
+      end
+    end # Revision
+  end # Model
+end # Sections