acts_as_data_table 0.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+
+.idea/
+.ruby-gemset
+.ruby-version

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in acts_as_data_table.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Stefan Exner
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,55 @@
+# ActsAsDataTable
+
+This gem adds automatic filtering and sorting to models and controllers in Rails applications.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'acts_as_data_table'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install acts_as_data_table
+    
+The `sortable_columns` helper will also need a javascript file if you'd like to
+use the `CTRL + Click` way of adding new sorting columns. 
+You can easily generated it by using
+
+    $ ruby script/generate acts_as_data_table js
+    
+Please note that this javascript addon requires jQuery.
+
+## Usage
+
+The gem consists of 3 parts:
+
+1. Multi Column Queries, e.g. a full text search over several table columns
+2. Automatic filtering based on (named) scopes defined in the model
+3. Automatic sorting (`ORDER BY`) by multiple columns
+
+### Multi Column Queries
+
+TODO
+
+### Scope Filters
+
+TODO
+
+### Sortable Columns
+
+TODO
+
+## Contributing
+
+1. Fork it ( https://github.com/stex/acts_as_data_table/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+
+desc "Compiles the plugin's coffeescript to a js file"
+task :make do |t|
+  input_files      = Dir['./app/coffeescripts/**/*.coffee']
+  output_directory = './generators/acts_as_data_table/templates/assets/js'
+
+  input_files.each do |file|
+    `coffee -c --no-header -b  -o #{output_directory} #{file}`
+  end
+end

data/acts_as_data_table.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'acts_as_data_table/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "acts_as_data_table"
+  spec.version       = ActsAsDataTable::VERSION
+  spec.authors       = ["Stefan Exner"]
+  spec.email         = ["stex@sterex.de"]
+  spec.summary       = %q{Adds automatic scope based filtering and column sorting to controllers and models.}
+  spec.description   = %q{Adds methods to models and controllers to perform automatic filtering, sorting and multi-column-queries without having to worry about the implementation.}
+  spec.homepage      = 'https://www.github.com/stex/acts_as_data_table'
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+
+  spec.add_dependency 'rails', '~> 2.3'
+end

data/app/coffeescripts/acts_as_data_table.coffee

@@ -0,0 +1,47 @@
+#
+# Handles clicks on table column headers and adds the functionality
+# for CTRL+Click. The different actions are triggered as follows:
+#
+# Normal click: The column will be the only sorting column
+# CTRL + click on inactive column: Column will be added to sorting list
+# CTRL + click on active column: Column will be removed from sorting list
+#
+jQuery(document).ready () ->
+  jQuery(document).on "click", '[data-init=sortable-column]', (e) ->
+    #Keep the browser from jumping to the top due to the href='#'
+    e.preventDefault()
+
+    urlToggle          = jQuery(@).data('urlToggle')
+    urlSetBase         = jQuery(@).data('urlSetBase')
+
+    remote             = jQuery(@).data('remote')
+    active             = jQuery(@).data('active')
+
+    url = urlSetBase
+
+    if e.ctrlKey || e.metaKey
+      url = urlToggle
+
+    if remote
+      jQuery.ajax
+        'url': url,
+        dataType: 'script'
+    else
+      window.location.href = url
+
+    return false
+
+  jQuery(document).on "click", "[data-init=sortable-column-direction]", (e) ->
+    e.preventDefault()
+
+    url    = jQuery(@).data('urlChangeDirection')
+    remote = jQuery(@).data('remote')
+
+    if remote
+      jQuery.ajax
+        'url': url,
+        dataType: 'script'
+    else
+      window.location.href = url
+
+                                                   

data/app/helpers/acts_as_data_table_helper.rb

@@ -0,0 +1,170 @@
+module ActsAsDataTableHelper
+  require 'ostruct'
+
+  #
+  # Generates a link to add/remove a certain scope filter
+  #
+  # @param [Hash] options
+  #   Options to customize the generated link
+  #
+  # @option options [String, Symbol] :scope
+  #   The scope within the given +group+ to be added/removed
+  #
+  # @option options [TrueClass, FalseClass] :toggle (false)
+  #   If set to +true+, the link will automatically remove the filter
+  #   if it's currently active without having to explicitly set +:remove+
+  #
+  # @option options [TrueClass, FalseClass] :remove (false)
+  #   If set to +true+, the link will always attempt to remove
+  #   the given +:scope+ within the given +group+ and cannot be used
+  #   to add it.
+  #
+  def scope_filter_link(group, scope, options = {})
+    caption         = options.delete(:caption) || scope_filter_caption(group, scope, options[:args])
+    surrounding_tag = options.delete(:surrounding)
+    remote          = options.delete(:remote)
+    args            = options[:args]
+    url             = scope_filter_link_url(group, scope, options)
+
+    classes = options[:class].try(:split, ' ') || []
+    classes << 'active' if scope && acts_as_data_table_session.active_filter?(group, scope, args)
+
+    options[:class] = classes.join(' ')
+
+    if remote
+      link = link_to_remote caption, :url => url, :method => :get, :html => options
+    else
+      link = link_to caption, url, options
+    end
+
+    surrounding_tag ? content_tag(surrounding_tag, link, :class => options[:class]) : link
+  end
+
+  #
+  # Generates a URL to add/remove/toggle a given scope filter
+  #
+  # @see #scope_filter_link for arguments
+  #
+  # @return [String] The generated URL
+  #
+  def scope_filter_link_url(group, scope, options)
+    args            = options.delete(:args)
+    toggle          = options.delete(:toggle)
+    auto_remove     = scope && toggle && acts_as_data_table_session.active_filter?(group, scope, args)
+    remove          = options.delete(:remove) || auto_remove
+
+    if remove
+      url_for({:scope_filters => {:action => 'remove', :group => group}})
+    else
+      url_for({:scope_filters => {:action => 'add', :group => group, :scope => scope, :args => args}})
+    end
+  end
+
+  #
+  # Generates a URL to be used as form action for filters which require
+  # dynamic arguments
+  #
+  # @return [String] the generated URL
+  #
+  # @example Using the rails form helper with a scope filter url
+  #
+  #     - form_tag(scope_filter_form_url) do
+  #       ...
+  #
+  def scope_filter_form_url(group, scope)
+    url_for({:scope_filters => {:action => 'add', :group => group, :scope => scope}})
+  end
+
+
+  def scope_filter_form(group, scope, options = {}, &proc)
+    content = capture(Acts::DataTable::ScopeFilters::FormHelper.new(self, group, scope), &proc)
+    method  = options[:method] || :get
+    if options.delete(:remote)
+      options.delete(:method)
+      form_remote_tag :url => scope_filter_form_url(group, scope), :method => method, :html => options do
+        concat(content)
+      end
+    else
+      form_tag scope_filter_form_url(group, scope), options do
+        concat(content)
+      end
+    end
+  end
+
+  #
+  # @return [String] URL to remove all active scope filters for the current action
+  #
+  def scope_filter_reset_url
+    url_for({:scope_filters => {:action => :reset}})
+  end
+
+  #
+  # Looks up a set argument for a given filter, e.g. to highlight it
+  # in the search results
+  #
+  # @return [Object, NilClass] the argument used for the given scope
+  #   or +nil+ if the filter is currently not active
+  #
+  def scope_filter_arg(group, scope, name)
+    Acts::DataTable.lookup_nested_hash(acts_as_data_table_session.active_filters, group.to_s, scope.to_s, name.to_s)
+  end
+
+  #
+  # @return [Hash] Arguments used for the given filter
+  #
+  def scope_filter_args(group, scope)
+    Acts::DataTable.lookup_nested_hash(acts_as_data_table_session.active_filters, group.to_s, scope.to_s) || {}
+  end
+
+  #
+  # Generates a scope filter caption
+  #
+  def scope_filter_caption(group, scope, args = {})
+    model = Acts::DataTable::ScopeFilters::ActionController.get_request_model
+    Acts::DataTable::ScopeFilters::ActiveRecord.scope_filter_caption(model, group, scope, args)
+  end
+
+  def active_scope_filter(group)
+    acts_as_data_table_session.active_filter(group)
+  end
+
+  #----------------------------------------------------------------
+  #                       Sortable Columns
+  #----------------------------------------------------------------
+
+  def sortable_column(model, column, caption, options = {}, &proc)
+    renderer_class = options.delete(:renderer) || Acts::DataTable::SortableColumns::Renderers.default_renderer
+
+    sortable                 = sortable_column_data(model, column)
+    sortable[:html_options]  = options
+    sortable[:caption]       = caption
+    sortable[:remote]        = options.delete(:remote)
+    sortable[:remote]        = true if sortable[:remote].blank?
+    sortable                 = OpenStruct.new(sortable)
+
+    #If a block is given, we let the user handle the content of the table
+    #header himself. Otherwise, we'll generate the default links.
+    if block_given?
+      yield sortable
+    else
+      renderer = renderer_class.constantize.new(sortable, self)
+      renderer.to_html
+    end
+  end
+
+  def sortable_column_data(model, column)
+    sortable                = {}
+
+    sortable[:direction]    = acts_as_data_table_session.sorting_direction(model, column)
+    sortable[:active]       = acts_as_data_table_session.active_column?(model, column)
+
+    urls                    = {}
+    urls[:toggle]           = url_for({:sortable_columns => {:action => :toggle, :model => model, :column => column}})
+    urls[:change_direction] = url_for({:sortable_columns => {:action => :change_direction, :model => model, :column => column}})
+    urls[:set_base]         = url_for({:sortable_columns => {:action => :set_base, :model => model, :column => column}})
+    sortable[:urls]         = OpenStruct.new(urls)
+
+    sortable
+  end
+
+end

data/config/locales/acts_as_data_table.en.yml

@@ -0,0 +1,11 @@
+en:
+  acts_as_data_table:
+    scope_filters:
+      add_filter:
+        filter_not_registered: "The filter '%{scope_name}' in group '%{group}' was not properly registered in model '%{model}'"
+        non_matching_arity: "The filter '%{scope_name}' in group '%{group}' registered in model '%{model}' did not get the required amount of arguments"
+
+      validations:
+        general_error:  "The scope filter could not be applied successfully"
+        invalid_date:   "%{arg_name} ('%{arg_value}') is not a valid date"
+        invalid_record: "The filter argument '%{arg_name}' did not match any valid record in the system."

data/generators/acts_as_data_table/acts_as_data_table_generator.rb

@@ -0,0 +1,13 @@
+class ActsAsDataTableGenerator < Rails::Generator::NamedBase
+  def manifest
+    record do |m|
+      m.file File.join('assets', 'js', 'acts_as_data_table.js'), File.join('public', 'javascripts', 'acts_as_data_table.js')
+    end
+  end
+
+  protected
+
+  def banner
+    "Usage: #{$0} acts_as_data_table js"
+  end
+end

data/generators/acts_as_data_table/templates/assets/js/acts_as_data_table.js

@@ -0,0 +1,37 @@
+jQuery(document).ready(function() {
+  jQuery(document).on("click", '[data-init=sortable-column]', function(e) {
+    var active, remote, url, urlSetBase, urlToggle;
+    e.preventDefault();
+    urlToggle = jQuery(this).data('urlToggle');
+    urlSetBase = jQuery(this).data('urlSetBase');
+    remote = jQuery(this).data('remote');
+    active = jQuery(this).data('active');
+    url = urlSetBase;
+    if (e.ctrlKey || e.metaKey) {
+      url = urlToggle;
+    }
+    if (remote) {
+      jQuery.ajax({
+        'url': url,
+        dataType: 'script'
+      });
+    } else {
+      window.location.href = url;
+    }
+    return false;
+  });
+  return jQuery(document).on("click", "[data-init=sortable-column-direction]", function(e) {
+    var remote, url;
+    e.preventDefault();
+    url = jQuery(this).data('urlChangeDirection');
+    remote = jQuery(this).data('remote');
+    if (remote) {
+      return jQuery.ajax({
+        'url': url,
+        dataType: 'script'
+      });
+    } else {
+      return window.location.href = url;
+    }
+  });
+});

data/init.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__) + '/rails/init'

data/lib/acts_as_data_table/multi_column_scopes.rb

@@ -0,0 +1,116 @@
+module Acts
+  module DataTable
+    module MultiColumnScopes
+      def self.included(base)
+        base.send :extend, ClassMethods
+      end
+
+      module ClassMethods
+        #
+        # Generates a scope to search for a given string in multiple
+        # columns at once. Columns may either be in the own table
+        # or in associated tables.
+        # It also automatically generates concat queries to enable
+        # full name searches, e.g. for a users table with
+        # separate columns for first and last name (see examples below)
+        #
+        # The result can be used further to chain the query like
+        # every other scope
+        #
+        # @param [String, Symbol] scope_name
+        #   The newly generated scope's name, e.g. :full_text
+        #
+        # If the last argument is a Hash, it will be used as options.
+        #
+        # @option options [Boolean] :downcase (true)
+        #   If set to +true+, the both searched query and
+        #   database values will be converted to lowercase to support
+        #   case insensitivity
+        #
+        # @example Basic usage, searching in two columns
+        #   has_multi_column_scope :email_or_name, :email, :name
+        #
+        # @example Searching for a full name by concatenating two columns
+        #   has_multi_column_scope :email_or_name, :email, [:first_name, :last_name]
+        #
+        # @example Including an association named :title (belongs_to :title)
+        #   has_multi_column_scope :name_or_title, [:first_name, :last_name], {:title => :name}, {}
+        #   #The empty has at the end is necessary as otherwise the title-hash would
+        #   #be taken as options.
+        #
+        # The method does currently not support chained includes, this
+        # will be added in the future (e.g. :user_rooms => {:room => :number})
+        #
+        def has_multi_column_scope(scope_name, *args)
+          options = {:downcase => true}
+          options.merge!(args.pop) if args.size > 1 && args.last.is_a?(Hash)
+
+          include_chain = []
+
+          fields        = args.map {|arg| Acts::DataTable::MultiColumnScopes.process_column_arg(arg, include_chain, self)}
+          fields        = fields.flatten.map {|f| Acts::DataTable::MultiColumnScopes.database_cast(f)}
+          fields        = fields.map {|f| "LOWER(#{f})"} if options[:downcase]
+
+          conditions    = fields.map {|f| "#{f} LIKE ?"}.join(' OR ')
+          include_chain = include_chain.uniq.compact
+
+          named_scope scope_name, lambda {|search|
+            if search.present?
+              s = "%#{search}%"
+              s = s.downcase if options[:downcase]
+              { :include => include_chain, :conditions => [conditions] + Array.new(fields.size, s) }
+            else
+              {}
+            end
+          }
+        end
+      end
+
+      #
+      # Processes a single argument for has_multi_column_scope.
+      # Handles
+      #   - simple values (e.g. :first_name),
+      #   - arrays which will be concatenated with a space character (e.g. [:first_name, :last_name])
+      #   - hashes which represent associations on the main model (e.g. :student => [:mat_num])
+      #
+      def self.process_column_arg(arg, includes, model = self)
+        if arg.is_a?(Hash)
+          res = []
+          arg.each do |association, columns|
+            includes << association
+            Array(columns).each do |column|
+              res << process_column_arg(column, includes, association.to_s.singularize.classify.constantize)
+            end
+          end
+          res
+        elsif arg.is_a?(Array)
+          columns = arg.map {|a| process_column_arg(a, includes, model)}
+          columns = columns.map {|c| "TRIM(#{c})"}
+          "CONCAT(#{columns.join(", ' ', ")})"
+        else
+          if model.column_names.include?(arg.to_s)
+            [model.table_name, arg.to_s].join('.')
+          else
+            raise ArgumentError.new "The table '#{model.table_name}' does not have a column named '#{arg}'"
+          end
+        end
+      end
+
+      #
+      # Performs a cast to text-like for various database types
+      #
+      def self.database_cast(content)
+        case ActiveRecord::Base.connection.adapter_name
+          when 'MySQL'
+            "CAST(#{content} AS CHAR(10000) CHARACTER SET utf8)"
+          else
+            "CAST(#{content} AS TEXT)"
+        end
+      end
+
+      def self.build_scope_name(*args)
+        args.join('_').to_sym
+      end
+    end
+  end
+end

data/lib/acts_as_data_table/scope_filters/action_controller.rb

@@ -0,0 +1,139 @@
+module Acts
+  module DataTable
+    module ScopeFilters
+      module ActionController
+
+        def self.included(base)
+          base.send :extend, ClassMethods
+        end
+
+        module ClassMethods
+          #
+          # Adds scope filter support to this controller (or parts of it)
+          #
+          # @param [Hash] options
+          #   Options to customize the behaviour
+          #
+          # @option options [Array<Symbol>] :only
+          #   If given, filters are only applied to actions which are in the given array
+          #
+          # @option options [Array<Symbol>] :except
+          #   If given, filters are only applied to actions which _not_ in the given array
+          #
+          # @option options [String, Symbol] :model
+          #   The model name which will be used as filter base.
+          #   If not given, the name is inferred from the controller name
+          #
+          def scope_filters(options = {})
+            #Include on-demand methods
+            include Acts::DataTable::Shared::ActionController::OnDemand
+
+            #Add helper methods to this controller's views
+            helper :acts_as_data_table
+
+            model_name = (options.delete(:model) || self.name.underscore.split('/').last.sub('_controller', '')).to_s.camelize.singularize
+
+            #Create a custom before filter
+            around_filter(options) do |controller, block|
+
+              sf_params = controller.request.params[:scope_filters]
+
+              begin
+
+                #Set current filters before adding/removing based on the current request
+                #This is needed for certain actions within the session
+                Acts::DataTable::ScopeFilters::ActionController.set_request_filters!(model_name, controller.acts_as_data_table_session.active_filters)
+
+                #Ensure that any scope filter related params are given and
+                #that the given action is valid (add a filter, remove a filter, remove all filters)
+                if sf_params.present? && %w(add remove reset).include?(sf_params[:action])
+                  case sf_action = sf_params[:action].to_s
+                  when 'add'
+                    #Ensure that a group and a scope name are given
+                    if [:group, :scope].all? { |p| sf_params[p].present? }
+                      unless controller.acts_as_data_table_session.add_filter(sf_params[:group], sf_params[:scope], sf_params[:args])
+                        #TODO: add error message if the validation failed or the filter was not available
+                      end
+                    end
+                  when 'remove'
+                    #Ensure that a group and a filter name are given
+                    if sf_params[:group].present?
+                      controller.acts_as_data_table_session.remove_filter!(sf_params[:group])
+                    end
+                  when 'reset'
+                    controller.acts_as_data_table_session.remove_all_filters!
+                  else
+                    raise ArgumentError.new "Invalid scope filter action '#{sf_action}' was given."
+                  end
+                end
+
+                #Set the updated filters
+                Acts::DataTable::ScopeFilters::ActionController.set_request_filters!(model_name, controller.acts_as_data_table_session.active_filters)
+                block.call
+              ensure
+                Acts::DataTable::ScopeFilters::ActionController.clear_request_filters!
+              end
+            end
+          end
+        end
+
+        #
+        # Returns the currently active scope filters
+        #
+        # This function should only be used when the automatic scope +with_scope_filters+
+        # is not working due to a different execution time or thread, e.g. a background worker.
+        #
+        def current_scope_filters
+          Acts::DataTable::ScopeFilters::ActionController.get_request_filters
+        end
+
+        #----------------------------------------------------------------
+        #                        Module Methods
+        #----------------------------------------------------------------
+
+        #
+        # Saves the current request's active filters to the thread space
+        #
+        def self.set_request_filters!(model, filters)
+          Acts::DataTable.ensure_nested_hash!(Thread.current, :scope_filters)
+
+          current_scopes = filters.inject({}) do |h, (group, scope)|
+            h[group] = [scope.keys.first, scope[scope.keys.first]]
+            h
+          end
+
+          Thread.current[:scope_filters] = {:model => model.to_s, :filters => current_scopes}
+        end
+
+        #
+        # Fetches the current request's filter data from the thread space
+        #
+        def self.get_request_data
+          Acts::DataTable.lookup_nested_hash(Thread.current, :scope_filters)
+        end
+
+        #
+        # Fetches the current request's active filters from the thread space
+        #
+        def self.get_request_filters
+          self.get_request_data[:filters]
+        end
+
+        #
+        # @return [ActiveRecord::Base] the model used for filtering in the current request
+        #
+        def self.get_request_model
+          model = self.get_request_data[:model]
+          model.camelize.constantize
+        end
+
+        #
+        # Clears all active filters from the thread space.
+        #
+        def self.clear_request_filters!
+          Thread.current[:scope_filters] = nil
+        end
+      end
+    end
+  end
+end