acts_as_data_table 0.0.1

data/lib/acts_as_data_table/shared/session.rb

@@ -0,0 +1,312 @@
+module Acts
+  module DataTable
+    module Shared
+      class Session
+
+        def initialize(session, controller_path, action_name)
+          @session         = session
+          @controller_path = controller_path
+          @action_name     = action_name
+        end
+
+        def sf_session
+          @session[:scope_filters] ||= {}
+        end
+
+        def sc_session
+          @session[:sortable_columns] ||= {}
+        end
+
+        def model
+          Acts::DataTable::ScopeFilters::ActionController.get_request_model
+        end
+
+        def errors
+          @errors ||= {}
+        end
+
+        def errors_on(context)
+          errors[context.to_s] || []
+        end
+
+        #----------------------------------------------------------------
+        #                        Filter Management
+        #----------------------------------------------------------------
+
+        #
+        # @return [Hash] all active filters for the current controller action
+        #   by the group they are registered in.
+        #
+        def active_filters
+          sf_session[current_action_key] || {}
+        end
+
+        #
+        # Checks whether the given filter is currently active
+        # Note that it also checks if it is active with exactly the given arguments.
+        #
+        # @return [TrueClass, FalseClass] +true+ if the filter is active AND
+        #   the given +args+ match the ones used in the filter.
+        #
+        def active_filter?(group, scope, args)
+          args ||= {}
+          used_args = Acts::DataTable.lookup_nested_hash(active_filters, group.to_s, scope.to_s)
+          used_args && (args.stringify_keys.to_a - used_args.to_a).empty?
+        end
+        
+        #
+        # @return [String, NilClass] The name of the scope filter which is
+        #   currently active in the given group or +nil+ if no filter from this group is
+        #   currently active
+        #
+        def active_filter(group)
+          Acts::DataTable.lookup_nested_hash(active_filters, group.to_s).try(:keys).try(:first)
+        end
+
+        #
+        # Adds a new filter to the current controller action
+        # Before the filter is added, the following things are checked to ensure
+        # that no invalid filter is added (which could cause reoccurring errors in the application)
+        #
+        #   1. The given +scope+ has to be registered in the currently used model
+        #   2. The given arguments have to be sufficient for the given +scope+
+        #   3. The +scope+ has to pass the set up validation check
+        #
+        # @param [String] group
+        #   The group the given +scope+ is part of in the current #model
+        #
+        # @param [String] scope
+        #   The scope name within +group+ and #model
+        #
+        # @param [Hash] args
+        #   Arguments to be passed to the scope. They have to be in the format
+        #   {arg_name => arg_value} as set up in the model. This is necessary
+        #   to make validations as easy as possible.
+        #
+        def add_filter(group, scope, args)
+          reset_errors!
+
+          #Ensure that the argument hash is set properly. The following methods
+          #might fail for filters which do not require arguments otherwise.
+          args = {} unless args.is_a?(Hash)
+
+          #Check whether the given filter was registered properly in the model
+          unless Acts::DataTable::ScopeFilters::ActiveRecord.registered_filter?(model, group, scope)
+            add_error group, Acts::DataTable.t('scope_filters.add_filter.filter_not_registered', :model => model.name, :group => group, :scope_name => scope)
+            return false
+          end
+          
+          #Check whether the given arguments are sufficient for the given filter
+          unless Acts::DataTable::ScopeFilters::ActiveRecord.matching_arity?(model, group, scope, args.size)
+            add_error group, Acts::DataTable.t('scope_filters.add_filter.non_matching_arity', :model => model.name, :group => group, :scope_name => scope)
+            return false
+          end
+
+          #Run possible validation methods on the given filter and add generated error messages
+          if (errors = Acts::DataTable::ScopeFilters::Validator.new(model, group, scope, args).validate).any?
+            errors.each {|e| add_error(group, e)}
+            return false
+          end
+
+          #Add the new filter to the session
+          current_action_session[group.to_s] = {scope.to_s => args.stringify_keys}
+          true
+        end
+
+        #
+        # Removes the given filter group from the current controller action
+        # It is sufficient to only specify the group here as only one filter in a group
+        # may be active at a time.
+        #
+        def remove_filter!(group)
+          current_action_session.delete(group.to_s)
+        end
+
+        #
+        # Resets all filters for the current controller action
+        #
+        def remove_all_filters!
+          sf_session[current_action_key] = {}
+        end
+
+        #----------------------------------------------------------------
+        #                        Sortable Columns
+        #----------------------------------------------------------------
+
+        #
+        # @return [Array] The sorting columns for the current request
+        #   (controller + action) in the format [['col1', 'dir1'], ['col2', 'dir2'], ...]
+        #
+        #   If no columns are set, the given default ones are used.
+        #
+        def active_columns
+          current_action_session(sc_session, [])
+        end
+
+        #
+        # Adds or removes a column from the current sorting columns
+        # This happens whenever the user decides to sort a table by multiple columns
+        #
+        def toggle_column!(model_name, column_name)
+          if active_column?(model_name, column_name)
+            remove_column!(model_name, column_name)
+          else
+            add_column!(model_name, column_name)
+          end
+        end
+
+        #
+        # Changes the sorting direction for the given column
+        # If no direction is given, it will change it to the opposite of the current direction
+        #
+        def change_direction!(model_name, column_name, direction = nil)
+          if active_column?(model_name, column_name)
+            ca    = column_array(model_name, column_name)
+            ca[1] = (direction || opposite_direction(ca.last)).to_s.upcase
+          end
+        end
+
+        #
+        # Replaces all current sorting columns with the given one
+        #
+        def set_base_column!(model, column, direction = nil)
+          reset_columns!
+          add_column!(model, column, direction)
+        end
+
+        #
+        # Sets all sorting columns for the current controller action at once.
+        # This can be used when supplying the user with a form to choose
+        # the sorting in a separate area of the page instead of clicking
+        # on table column headers and adding one column after the other
+        #
+        # @param [Array<String>] columns
+        #   A 2D array of the form [['model_name', 'column_name', 'direction'], ...]
+        #
+        def set_columns!(columns)
+          reset_columns!
+          columns.each do |model, column, direction|
+            add_column!(model, column, direction)
+          end
+        end
+
+        #
+        # Retrieves the current sorting direction for a given column.
+        #
+        # @return [String, NilClass] 'ASC' or 'DESC' if the given column
+        #   is currently active, +nil+ otherwise
+        #
+        def sorting_direction(model_name, column_name)
+          column_array(model_name, column_name).try(:last)
+        end
+
+        #
+        # @return [TrueClass, FalseClass] +true+ if the given column is currently
+        #   used for sorting
+        #
+        def active_column?(model_name, column_name)
+          !!column_array(model_name, column_name)
+        end
+
+        private
+
+        #
+        # Removes all current sorting columns
+        #
+        def reset_columns!
+          sc_session[current_action_key] = []
+        end
+
+        #
+        # @return [String] the opposite direction to the given one
+        #
+        def opposite_direction(direction)
+          direction.downcase == 'asc' ? 'DESC' : 'ASC'
+        end
+
+        #
+        # Removes the given column from the current sorting
+        #
+        def remove_column!(model_name, column_name)
+          current_action_session(sc_session, []).delete(column_array(model_name, column_name))
+        end
+
+        #
+        # Adds the given column to the current sorting
+        #
+        def add_column!(model_name, column_name, direction = nil)
+          direction ||= 'ASC'
+          d           = column_data(model_name, column_name)
+          current_action_session(sc_session, []).push([d[:column], direction.to_s.upcase])
+        end
+
+        #
+        # Retrieves the array consisting of column name and direction from the session
+        #
+        # @return [Array, NilClass] Either an array of the form ['table.column', 'direction']
+        #   or +nil+ if the given column is not part of the current sorting
+        #
+        def column_array(model_name, column_name)
+          current_action_session(sc_session, []).assoc(column_data(model_name, column_name)[:column])
+        end
+
+        #
+        # @return [ActiveRecord::Base] The constantized model
+        #
+        def get_model(model_name)
+          model_name.to_s.camelize.constantize
+        end
+
+        #
+        # @return [Hash] The constantized model and column name with table prefix
+        #
+        def column_data(model_name, column_name)
+          m      = get_model(model_name)
+          column = "#{m.table_name}.#{column_name}"
+          {:model => m, :column => column}
+        end
+
+        def current_action_session(s = sf_session, default = {})
+          s[current_action_key] ||= default
+        end
+
+        #
+        # Clears old error messages. This is useful whenever only error messages from
+        # a current action should be retrieved.
+        #
+        def reset_errors!
+          @errors = {}
+        end
+
+        #
+        # Adds an error message to the errors array
+        #
+        # @param [String] context
+        #   Context the error occurred in, e.g. a scope filter group
+        #
+        # @param [String] message
+        #   The error message to be added.
+        #
+        def add_error(context, message)
+          errors[context.to_s] ||= []
+          errors[context.to_s] << message
+        end
+
+        #
+        # Generates a key from the given controller and action name
+        #
+        def action_key(controller, action)
+          [controller.gsub('/', '_'), action].join('_')
+        end
+
+        #
+        # @see #action_key, uses the current controller path and action name
+        #
+        def current_action_key
+          action_key(@controller_path, @action_name)
+        end
+
+      end
+    end
+  end
+end

data/lib/acts_as_data_table/sortable_columns/action_controller.rb

@@ -0,0 +1,111 @@
+module Acts
+  module DataTable
+    module SortableColumns
+      module ActionController
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        module ClassMethods
+
+          #
+          # Sets up automatic column sorting for this controller
+          #
+          # @param [Hash] options
+          #   Options to specify which controller actions should have column sorting
+          #   and to customize the filter's behaviour.
+          #   Options are everything that #around_filter would accept
+          #
+          # @option options [Hash] :default
+          #   Default sorting columns for different actions.
+          #   If none are specified for an action, the default order (usually 'id ASC') is used
+          #
+          # @example Set up automatic column sorting only for the index action
+          #          with the default ordering "deleted_at ASC, name ASC"
+          #
+          #     sortable_columns :only => [:index], :default => {:index => [['deleted_at', 'ASC'], ['name', 'ASC']]}
+          #
+          def sortable_columns(options = {})
+            #Include on-demand methods
+            include Acts::DataTable::Shared::ActionController::OnDemand
+
+            defaults = (options.delete(:default) || {}).stringify_keys
+
+            around_filter(options) do |controller, block|
+
+              af_params        = controller.request.params[:sortable_columns]
+              request_defaults = defaults[controller.action_name.to_s] || []
+
+              begin
+                #Ensure that the given action is valid
+                if af_params.present? && %w(toggle change_direction set_base set).include?(af_params[:action].to_s)
+                  case af_action = af_params[:action].to_s
+                    when 'toggle'
+                      controller.acts_as_data_table_session.toggle_column!(af_params[:model], af_params[:column])
+                    when 'change_direction'
+                      controller.acts_as_data_table_session.change_direction!(af_params[:model], af_params[:column])
+                    when 'set_base'
+                      controller.acts_as_data_table_session.set_base_column!(af_params[:model], af_params[:column])
+                    when 'set'
+                      controller.acts_as_data_table_session.set_columns!(af_params[:columns])
+                    else
+                      raise ArgumentError.new "Invalid scope filter action '#{af_action}' was given."
+                  end
+                end
+
+                #Set the defaults as sorting columns none were set by the user
+                if controller.acts_as_data_table_session.active_columns.empty?
+                  controller.acts_as_data_table_session.set_columns!(request_defaults)
+                end
+
+                #Set the updated filters
+                Acts::DataTable::SortableColumns::ActionController.set_request_sort_columns!(controller.acts_as_data_table_session.active_columns)
+                block.call
+              ensure
+                Acts::DataTable::SortableColumns::ActionController.clear_request_sort_columns!
+              end
+
+            end
+          end
+        end
+
+        #
+        # Returns the currently active sortable columns.
+        # This function should only be used when the automatic scope +with_sortable_columns+
+        # is not working due to a different execution time or thread, e.g. a background worker.
+        #
+        def current_sortable_columns
+          Acts::DataTable::SortableColumns::ActionController.get_request_sort_columns
+        end
+
+        #
+        # Retrieves the columns to order by for the current request from the thread space. This is used in the
+        # model's scope, so no string has to be supplied in the controller action manually.
+        #
+        # @return [Array<String>] the columns and their sorting directions in the format
+        #   [["col1", "dir1"], ["col2", "dir2"], ...]
+        #
+        def self.get_request_sort_columns
+          Thread.current[:sortable_columns] || []
+        end
+
+        #
+        # Sets the columns to order by for the current request
+        # in the thread space
+        #
+        # @param [Array<String>] columns
+        #
+        def self.set_request_sort_columns!(columns)
+          Thread.current[:sortable_columns] = columns
+        end
+
+        #
+        # Deletes the current sort columns from the thread space
+        #
+        def self.clear_request_sort_columns!
+          Thread.current[:sortable_columns] = nil
+        end
+      end
+    end
+  end
+end

data/lib/acts_as_data_table/sortable_columns/active_record.rb

@@ -0,0 +1,34 @@
+module Acts
+  module DataTable
+    module SortableColumns
+      module ActiveRecord
+        def self.included(base)
+
+          #
+          # Scope which applies the currently active sorting directions.
+          # The sorting columns are automatically fetched from the current thread space,
+          # however, it is also possible to pass these values in as first argument.
+          # This should only be done if absolutely necessary, e.g. if
+          # the calculation happens in a different time or thread as it would in a
+          # background calculation.
+          #
+          base.named_scope :with_sortable_columns, lambda {|*args|
+            sort_columns   = args.first
+            sort_columns ||= Acts::DataTable::SortableColumns::ActionController.get_request_sort_columns
+
+            if sort_columns.any?
+              sort_string = sort_columns.map {|col, dir| "#{col} #{dir}"}.join(', ')
+              {:order => sort_string}
+            else
+              {}
+            end
+          }
+
+        end
+
+
+
+      end
+    end
+  end
+end

data/lib/acts_as_data_table/sortable_columns/renderers/bootstrap2.rb

@@ -0,0 +1,17 @@
+module Acts
+  module DataTable
+    module SortableColumns
+      module Renderers
+        class Bootstrap2 < Default
+          def direction_indicator
+            if @sortable.direction == 'ASC'
+              @action_view.content_tag(:i, nil, :class => 'icon-sort-by-alphabet')
+            else
+              @action_view.content_tag(:i, nil, :class => 'icon-sort-by-alphabet-alt')
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/acts_as_data_table/sortable_columns/renderers/default.rb

@@ -0,0 +1,82 @@
+#
+# Default renderer for ActsAsDataTable sortable column links.
+# It uses the javascript library shipped with the gem and does not depend on
+# external sources like javascripts or additional stylesheets.
+#
+module Acts
+  module DataTable
+    module SortableColumns
+      module Renderers
+        def self.default_renderer
+          @@default_renderer ||= 'Acts::DataTable::SortableColumns::Renderers::Default'
+        end
+
+        def self.default_renderer=(renderer)
+          @@default_renderer = renderer.to_s
+        end
+
+        class Default
+          def initialize(sortable, action_view)
+            @action_view = action_view
+            @sortable    = sortable
+          end
+
+          #
+          # @return [String] an indicator about the sorting direction for the current column.
+          #   The direction is either 'ASC' or 'DESC'
+          #
+          def direction_indicator
+            @sortable.direction == 'ASC' ? 'Δ' : '∇'
+          end
+
+          #
+          # @return [String] The column header's caption
+          #
+          def caption
+            @sortable.caption
+          end
+
+          #
+          # @return [String] a link to change the sorting direction for an already active column
+          #
+          def direction_link
+            link_options                              = @sortable.html_options.clone
+            link_options['data-init']                 = 'sortable-column-direction'
+            link_options['data-remote']               = @sortable.remote
+            link_options['data-url-change-direction'] = @sortable.urls.change_direction
+            @action_view.link_to(direction_indicator, '#', link_options)
+          end
+
+          #
+          # @return [String] a link to toggle a column
+          #
+          def caption_link
+            link_options                              = @sortable.html_options.clone
+            link_options['data-init']                 = 'sortable-column'
+            link_options['data-remote']               = @sortable.remote
+            link_options['data-url-toggle']           = @sortable.urls.toggle
+            link_options['data-url-set-base']         = @sortable.urls.set_base
+            link_options['data-url-change-direction'] = @sortable.urls.change_direction
+            link_options['data-active']               = 'true' if @sortable.active
+
+            @action_view.link_to(@sortable.caption, '#', link_options)
+          end
+
+          #
+          # Generates the actual HTML (= caption and direction links)
+          # to be embedded into the view
+          #
+          # @return [String] the generated HTML code
+          #
+          def to_html
+            if @sortable.active
+              caption_link + ' ' + direction_link
+            else
+              caption_link
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/acts_as_data_table/version.rb

@@ -0,0 +1,3 @@
+module ActsAsDataTable
+  VERSION = '0.0.1'
+end

data/lib/acts_as_data_table.rb

@@ -0,0 +1,71 @@
+require 'acts_as_data_table/version'
+
+require 'acts_as_data_table/multi_column_scopes'
+
+require 'acts_as_data_table/shared/session'
+require 'acts_as_data_table/shared/action_controller'
+
+require 'acts_as_data_table/scope_filters/action_controller'
+require 'acts_as_data_table/scope_filters/active_record'
+require 'acts_as_data_table/scope_filters/validator'
+
+require 'acts_as_data_table/sortable_columns/action_controller'
+require 'acts_as_data_table/sortable_columns/active_record'
+require 'acts_as_data_table/scope_filters/form_helper'
+
+#Sortable Column Renderers
+require 'acts_as_data_table/sortable_columns/renderers/default'
+require 'acts_as_data_table/sortable_columns/renderers/bootstrap2'
+
+module ActsAsDataTable
+end
+
+module Acts
+  module DataTable
+    I18n_LOCALES = %w(en)
+
+    def self.log(level, message)
+      Rails.logger.send(level, "Acts::DataTable [#{level}] -- #{message}")
+    end
+
+    def self.ensure_nested_hash!(hash, *keys)
+      h = hash
+      keys.each do |key|
+        h[key] ||= {}
+        h = h[key]
+      end
+    end
+
+    def self.lookup_nested_hash(hash, *keys)
+      return nil if hash.nil?
+
+      h = hash
+      keys.each do |key|
+        return nil if h[key].nil?
+        h = h[key]
+      end
+      h
+    end
+
+    #
+    # Retrieves a value from the gem's locale namespace.
+    # If there are no translations for the application's locale, the
+    # english versions are used.
+    #
+    def self.t(key, options = {})
+      locale = I18n_LOCALES.include?(I18n.locale.to_s) ? I18n.locale : 'en'
+      I18n.t(key, options.merge({:scope => 'acts_as_data_table', :locale => locale}))
+    end
+  end
+end
+
+ActiveRecord::Base.class_eval do
+  include Acts::DataTable::MultiColumnScopes
+  include Acts::DataTable::ScopeFilters::ActiveRecord
+  include Acts::DataTable::SortableColumns::ActiveRecord
+end
+
+ActionController::Base.class_eval do
+  include Acts::DataTable::ScopeFilters::ActionController
+  include Acts::DataTable::SortableColumns::ActionController
+end