auto_select2 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a68cb3144bf87121bda7928fbd8a21924253eafb
-  data.tar.gz: ed7470fa356f8003f5bd3f259ee4bb73da03f908
+  metadata.gz: 1959785b4c590ab8a899b2ae4d04ae92877bff2d
+  data.tar.gz: ec11ae6b9ab6bea151a90327d444e9a1188283ea
 SHA512:
-  metadata.gz: ea72345387f6253f7ab2fe1c3b25d30ef0a0587d2358cf292747b5f71a64e188a6e5c12bb3cccce15f887efb7085d28d79fc106cd106c6a3faccb18db012ca73
-  data.tar.gz: 427c82d917c6accd35c66fa5fc908eb66060870ecabfd8d87f405be0eaa697095bb8e8ecc340437b88155a3b58c5c8fbafb2c3ce67f8f809895df0d5831c82f5
+  metadata.gz: c51d13d9a225ccbff420e2aefacbafeb2ed86db076af426a701f75f5d4bd309c2744d556f356e38ceae2c3c1eda1f03f57a7180daa7cdee349dcdabfa3fa22c2
+  data.tar.gz: a9de852f51f7573b7ae71d7c20ec17a7007cd49f0820659153cb674b3c1b2a8aefe6299a8f37829fe216da68d1d5e6d295d80ddbe2c481e7d9fcf46c9c64046a

data/README.md

@@ -1,9 +1,23 @@
 # AutoSelect2
 
-TODO: Write a gem description
+Gem provide API (scripts, helpers, controller and base class for ajax-search)
+for initialize different select2 elements: static, ajax and multi-ajax.
+
+The `AutoSelect2` based on [select2-rails](https://github.com/argerim/select2-rails) gem.
+
+[![Gem Version](https://badge.fury.io/rb/auto_select2.png)](http://badge.fury.io/rb/auto_select2)
 
 ## Installation
 
+### First
+
+Install [select2-rails](https://github.com/argerim/select2-rails#install-select2-rails-gem)
+and include javascript and stylesheet assets as
+[described](https://github.com/argerim/select2-rails#include-select2-rails-javascript-assets)
+on `select2-rails` page.
+
+### Second
+
 Add this line to your application's Gemfile:
 
     gem 'auto-select2'
@@ -12,13 +26,224 @@ And then execute:
 
     $ bundle
 
-Or install it yourself as:
+### Third
+
+Select one of ways to include js in pipeline. Ways described below in section `Javascript include variants`
+
+### Fourth
+
+Check controller and route collation. Gem contain controller `Select2AutocompletesController` and
+route
+
+    get 'select2_autocompletes/:class_name'
+
+### Fifth
+
+Prepare folder `app/select2_search_adapter` if you want to use `ajax-select2`. This folder needed
+for storage custom `SearchAdapter`.
+
+## Compatibility
+
+Gem tested and works in Rails 3.2 and Rails 4.0. You can test compatibility with other versions by yourself.
+
+## Easiest way to use
+
+Use [AutoSelect2Tag](https://github.com/Loriowar/auto_select2_tag). It provide helpers:
+
+* select2_tag
+* select2_ajax_tag
+
+and you can define select2 element like any other view elements in rails.
+
+## Example
 
-    $ gem install auto-select2
+You can find example project [here](https://github.com/Loriowar/auto-select2_tag_example).
 
 ## Usage
 
-TODO: Write usage instructions here
+### Element types
+
+Gem provides 3 types of select2 elements:
+
+* static
+* ajax
+* multi-ajax
+
+For each of it exist javascript initializer. This is:
+
+* static_select2.js
+* ajax_select2.js
+* multi_ajax_select2_value_parser.js
+
+**Note:** `multi_ajax_select2_value_parser.js` work only together with `ajax_select2.js`
+
+### Javascript include variants
+
+You have two ways to include javascript files. First: in gem presents helper methods
+
+* static_select2_init_header_tags
+* ajax_select2_init_header_tags
+* ajax_multi_select2_init_header_tags
+
+This helpers call `javascript_include_tag` and it is useful for initialize select2
+scripts on a single page. Example of usage in a view:
+
+    - static_select2_init_header_tags
+    
+    %div
+      = select_tag :my_select, my_options_for_select, class: 'small'
+
+Second variant: include files in javascript asset. For this add the
+following to your `app/assets/javascripts/application.js`:
+
+    //= require auto_select2/static_select2
+    //= require auto_select2/ajax_select2
+    //= require auto_select2/multi_ajax_select2_value_parser
+
+### Select2 options
+
+If you want to specify any parameters for [select2 constructor](http://ivaynberg.github.io/select2/)
+you can pass it as hash into data-attribute `s2options`. This parameter handle most options
+but you can't pass through js-functions.
+
+### Static select2 usage
+
+For initialize static select2 you must set `auto-static-select2` css-class for select element:
+
+    = select_tag :my_select, my_options_for_select, class: 'my-class auto-static-select2'
+
+### Ajax select2 usage
+
+For initialize ajax select 2 you must set `auto-ajax-select2` css-class for hidden-input element.
+Then you have two ways. Easy way for simple selection: specify `default_class_name`, `default_text_column` and
+`default_id_column` as params for `:href` within data-attribute `s2options` (look at the end of this section).
+Other way for custom selection: create `SearchAdapter`. This adapter has following requirements:
+
+* class must be inherited from `AutoSelect2::Select2SearchAdapter::Base`
+* file must be put in folder `app/select2_search_adapter`
+* name of a adapter class must end with `SearchAdapter`
+* must has function `search_default(term, page, options)`
+  (description of the function and return value goes below)
+
+Returned value of `search_default` function must be follow:
+
+* if options contain `:init` key function must return hash
+  `{text: 'displayed text', id: 'id_of_initial_element'}`
+* otherwise function must return the follow hash:
+
+
+    { items:
+      [
+        { text: 'first element', id: 'first_id' },
+        { text: 'second element', id: 'second_id' }
+      ],
+      total: count
+    }
+
+Here in total must be specified amount of all select variants. For example you have select
+element with 42 variants. Function `search_default` return part of it in `items` and in
+`total` each time you must set 42.
+
+**TIP:** in `search_default` you can use functions from `Select2SearchAdapter::Base`:
+
+* `default_finder(searched_class, term, options)`
+* `default_count(searched_class, term, options = {})`
+* `get_init_values(searched_class, ids, title_method=nil)`
+
+More about this function you can find in [example project](https://github.com/Loriowar/auto-select2_tag_example),
+in example below and in source code.
+
+Finally hidden-input must has `:href` parameter in data-attribute `s2options`. This
+parameter specify url for ajax load select options. You can use helper
+
+    select2_autocompletes_path(class_name: :my_class_name)
+or
+
+    select2_autocompletes_path(default_class_name: my_class,
+                               default_text_column: :name,
+                               default_id_column: :id)
+
+### Example of minimalistic SearchAdapter
+    class SystemRoleSearchAdapter < AutoSelect2::Select2SearchAdapter::Base
+      class << self
+        def search_default(term, page, options)
+          if options[:init].nil?
+            roles = default_finder(SystemRole, term, page: page)
+            count = default_count(SystemRole, term)
+            {
+              items: roles.map do |role|
+                { text: role.name, id: role.id.to_s } # here is optional parameter 'class_name'
+              end,
+              total: count
+            }
+          else
+            get_init_values(SystemRole, options[:item_ids])
+          end
+        end
+      end
+    end
+
+### More about SearchAdapter
+
+`SearchAdapter` has some additional functions. First, you can define multiple search
+functions in one adapter. For example in adapter for User you want to find among all
+users, find users only in one department and so on. For this purpose define methods like
+
+    def search_unusual_case(term, page, options)
+      # must has same behavior as search_default
+    end
+
+near the `search_default` in `SearchAdapter`. Requirement for non-default search methods:
+
+* it must has same behavior as search_default
+* name of methods must start with `search_`
+
+For use custom searcher specify it into `:href` within data-attribute `s2options`:
+
+    select2_autocompletes_path(class_name: MyClassName, search_method: :unusual_case)
+
+Second, you may want to pass additional parameters in `SearchAdapter`. For example
+select options depend from another field on page. For this purpose you can specify
+
+    additional_ajax_data: {selector: 'input.css-class'}
+
+inside data-attribute `s2options`. In this case in options of `SearchAdapter` appear
+additional values. It construct from name and value of html-elements. Example:
+
+    = hidden_field_tag 'token', 'VUBJKB23UIVI1UU1VOBVI@', class: 'add-to-select2'
+    = hidden_field_tag 'select2element', '',
+                        class: 'auto-ajax-select2',
+                        data: {s2options: { href: select2_autocompletes_path(class_name: :adapter_name,
+                                                                             search_method: :unusual_case),
+                                            additional_ajax_data: {selector: '.add-to-select2'}}}
+
+Here we initialize ajax select2 and during load select variants in `SearchAdapter` options hash
+appear key :token with value 'VUBJKB23UIVI1UU1VOBVI@'.
+
+Third, in hash with items from search method exist additional optional parameter `class_name`.
+This parameter specify css-class for result element in select2. It useful for show different
+icons for different select variants.
+
+### Multi ajax select2 usage
+
+This feature require absolutely same things as ajax select2. Additionally you must
+add `multiple` css-class for input element, doesn't forget about
+`multi_ajax_select2_value_parser.js` script and pass `multiple: true` into
+data-attribute `s2options`.
+
+### Different multi ajax select2
+
+Honestly speaking you can just pass `multiple: true` into data-attribute `s2options` and
+ajax-select2 become multiple. But in this case selected options from select2 become as
+comma separated string. As opposed to it `multi_ajax_select2_value_parser.js` make array
+of multiple ids. This is more comfortable for use in controller.
+
+### Initializing
+
+Scripts automatically initialize on `$(document).ready()` and after `ajaxSuccess`. Moreover
+script handle [cocoon](https://github.com/nathanvda/cocoon) events and run on
+`cocoon:after-insert`. If you for any reasons want to manually initializing select2,
+you can call `initAutoAjaxSelect2()` and/or `initAutoStaticSelect2()`.
 
 ## Contributing
 

data/app/controllers/select2_autocompletes_controller.rb

@@ -1,7 +1,17 @@
 class Select2AutocompletesController < ApplicationController
   def search
     begin
-      adapter = "::Select2SearchAdapter::#{params[:class_name].camelize}SearchAdapter".constantize
+      if params[:class_name].present?
+        adapter = "::#{params[:class_name].camelize}SearchAdapter".constantize
+      elsif params[:default_class_name].present? &&
+          params[:default_text_column].present? &&
+          params[:default_id_column].present?
+        adapter = ::AutoSelect2::Select2SearchAdapter::Default
+      else
+        render json: {error: "not enough search parameters'"}.to_json,
+               status: 500
+        return
+      end
     rescue NameError
       render json: {error: "not found search adapter for '#{params[:class_name]}'"}.to_json,
              status: 500

data/config/routes.rb

@@ -1,4 +1,4 @@
 Rails.application.routes.draw do
-  get 'select2_autocompletes/:class_name', to: 'select2_autocompletes#search',
-                                           as: 'select2_autocompletes'
+  get 'select2_autocompletes/(:class_name)', to: 'select2_autocompletes#search',
+                                             as: 'select2_autocompletes'
 end

data/lib/auto_select2.rb

@@ -1,16 +1,9 @@
 require 'auto_select2/version'
 require 'auto_select2/helpers'
-require 'select2_search_adapter/base'
+require 'auto_select2/engine'
 
 module AutoSelect2
-  class Engine < ::Rails::Engine
-    # Get rails to add app, lib, vendor to load path
+  extend ActiveSupport::Autoload
 
-    initializer :javascripts do |app|
-      app.config.assets.precompile +=
-          %w(auto_select2/ajax_select2.js
-             auto_select2/multi_ajax_select2_value_parser.js
-             auto_select2/static_select2.js)
-    end
-  end
+  autoload :Select2SearchAdapter
 end

data/lib/auto_select2/engine.rb

@@ -0,0 +1,12 @@
+module AutoSelect2
+  class Engine < ::Rails::Engine
+    # Get rails to add app, lib, vendor to load path
+
+    initializer :javascripts do |app|
+      app.config.assets.precompile +=
+          %w(auto_select2/ajax_select2.js
+             auto_select2/multi_ajax_select2_value_parser.js
+             auto_select2/static_select2.js)
+    end
+  end
+end

data/lib/auto_select2/select2_search_adapter.rb

@@ -0,0 +1,8 @@
+module AutoSelect2
+  module Select2SearchAdapter
+    extend ActiveSupport::Autoload
+
+    autoload :Base
+    autoload :Default
+  end
+end

data/lib/auto_select2/select2_search_adapter/base.rb

@@ -0,0 +1,97 @@
+module AutoSelect2
+  module Select2SearchAdapter
+    class Base
+      class << self
+        # Amount rows per ajax-request
+        def limit
+          25 # TODO: move to settings/config
+        end
+
+        def search_from_autocomplete(term, page, search_method, options)
+          if search_method.nil?
+            search_default(term, page, options)
+          else
+            self.public_send("search_#{search_method}", term, page, options)
+          end
+        end
+
+      private
+
+        def default_finder(searched_class, term, options)
+          column = options[:column].present? ? options[:column] : 'name'
+          conditions = default_search_conditions(term, options[:basic_conditions], column)
+          if term.nil?
+            [ searched_class.where(options[:basic_conditions]) ]
+          else
+            skip_count = 0
+            unless options.nil? || options[:page].nil?
+              page = options[:page].to_i > 0 ? options[:page].to_i : 1
+              skip_count = limit * ( page - 1 )
+            end
+            query = searched_class.where( conditions ).limit( limit ).offset(skip_count).order(column)
+            query = query.select(options[:select]) if options[:select].present?
+            options[:uniq] ? query.uniq : query
+          end
+        end
+
+        def default_count(searched_class, term, options = {})
+          conditions = default_search_conditions(term, options[:basic_conditions], options[:column] || 'name')
+          query = searched_class.where(conditions)
+          query = query.select(options[:select]) if options[:select].present?
+          query = options[:uniq] ? query.uniq : query
+          query.count
+        end
+
+        def default_search_conditions(term, basic_conditions, columns)
+          term_filter = ''
+          conditions = []
+          columns = [columns] unless columns.is_a?(Array)
+          unless term.nil?
+            words = term.split(' ')
+            words.each_with_index do |word, index|
+              term_filter += ' AND ' if index > 0
+              columns.each_with_index do |column, idx|
+                term_filter += ' OR ' if idx > 0
+                term_filter +=  "#{column} LIKE ?"
+                conditions << "%#{word}%"
+              end
+            end
+            term_filter = term_filter.empty? ? nil : "(#{term_filter})"
+            basic_conditions_part = basic_conditions.present? ? "(#{basic_conditions }) " : nil
+            conditions.unshift([term_filter, basic_conditions_part].compact.join(' AND '))
+          end
+        end
+
+        def get_init_values(searched_class, ids, options = {})
+          title_method = options[:title_method]
+          id_column = options[:id_column] || searched_class.primary_key
+          ids = ids.split(',')
+          if ids.size > 1
+            result = []
+            ids.each do |id|
+              item = searched_class.where(id_column => id).first
+              if item.present?
+                result << get_select2_hash(item, title_method, id)
+              end
+            end
+            result
+          elsif ids.size == 1
+            item = searched_class.where(id_column => ids[0]).first
+            get_select2_hash(item, title_method, ids[0]) if item.present?
+          else
+            nil
+          end
+        end
+
+        def get_select2_hash(item, title_method, id)
+          if item.respond_to?(:to_select2) && title_method.blank?
+            item.to_select2
+          else
+            title_method ||= :name
+            { text: item.public_send(title_method), id: id }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/auto_select2/select2_search_adapter/default.rb

@@ -0,0 +1,31 @@
+module AutoSelect2
+  module Select2SearchAdapter
+    class Default < Base
+      class << self
+        def search_default(term, page, options)
+          begin
+            default_arel = options[:default_class_name].camelize.constantize
+          rescue NameError
+            return {error: "not found class '#{options[:default_class_name]}'"}.to_json
+          end
+
+          if options[:init].nil?
+            default_values = default_finder(default_arel, term, page: page,
+                                                                column: options[:default_text_column])
+            default_count = default_count(default_arel, term, column: options[:default_text_column])
+            {
+                items: default_values.map do |default_value|
+                  { text: default_value.public_send(options[:default_text_column]),
+                    id: default_value.public_send(options[:default_id_column]) }
+                end,
+                total: default_count
+            }
+          else
+            get_init_values(default_arel, options[:item_ids], id_column: options[:default_id_column])
+          end
+        end
+      end
+    end
+  end
+end
+

data/lib/auto_select2/version.rb

@@ -1,3 +1,3 @@
 module AutoSelect2
-  VERSION = '0.1.2'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: auto_select2
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Dmitriy Lisichkin
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-11-24 00:00:00.000000000 Z
+date: 2014-12-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -116,10 +116,13 @@ files:
 - auto_select2.gemspec
 - config/routes.rb
 - lib/auto_select2.rb
+- lib/auto_select2/engine.rb
 - lib/auto_select2/helpers.rb
 - lib/auto_select2/helpers/select2_helpers.rb
+- lib/auto_select2/select2_search_adapter.rb
+- lib/auto_select2/select2_search_adapter/base.rb
+- lib/auto_select2/select2_search_adapter/default.rb
 - lib/auto_select2/version.rb
-- lib/select2_search_adapter/base.rb
 - vendor/assets/javascripts/auto_select2/ajax_select2.js.coffee
 - vendor/assets/javascripts/auto_select2/multi_ajax_select2_value_parser.js.coffee
 - vendor/assets/javascripts/auto_select2/static_select2.js.coffee

data/lib/select2_search_adapter/base.rb

@@ -1,97 +0,0 @@
-module Select2SearchAdapter
-  class Base
-    class << self
-      # Amount rows per ajax-request
-      def limit
-        25 # TODO: move to settings/config
-      end
-
-      def search_from_autocomplete(term, page, search_method, options)
-        if search_method.nil?
-          search_default(term, page, options)
-        else
-          self.send("search_#{search_method}", term, page, options)
-        end
-      end
-
-    private
-
-      def default_finder(searched_class, term, options)
-        column = options[:column].present? ? options[:column] : 'name'
-        conditions = default_search_conditions(term, options[:basic_conditions], column)
-        if term.nil?
-          [ searched_class.where(options[:basic_conditions]) ]
-        else
-          skip_count = 0
-          unless options.nil? || options[:page].nil?
-            page = options[:page].to_i > 0 ? options[:page].to_i : 1
-            skip_count = limit * ( page - 1 )
-          end
-          query = searched_class.where( conditions ).limit( limit ).offset(skip_count).order(column)
-          query = query.select(options[:select]) if options[:select].present?
-          options[:uniq] ? query.uniq : query
-        end
-      end
-
-      def default_count(searched_class, term, options = {})
-        conditions = default_search_conditions(term, options[:basic_conditions], options[:column] || 'name')
-        query = searched_class.where(conditions)
-        query = query.select(options[:select]) if options[:select].present?
-        query = options[:uniq] ? query.uniq : query
-        query.count
-      end
-
-      def default_search_conditions(term, basic_conditions, columns)
-        term_filter = ''
-        conditions = []
-        columns = [columns] unless columns.is_a?(Array)
-        unless term.nil?
-          words = term.split(' ')
-          words.each_with_index do |word, index|
-            term_filter += ' AND ' if index > 0
-            columns.each_with_index do |column, idx|
-              term_filter += ' OR ' if idx > 0
-              term_filter +=  "#{column} LIKE ?"
-              conditions << "%#{word}%"
-            end
-          end
-          term_filter = term_filter.empty? ? nil : "(#{term_filter})"
-          basic_conditions_part = basic_conditions.present? ? "(#{basic_conditions }) " : nil
-          conditions.unshift([term_filter, basic_conditions_part].compact.join(' AND '))
-        end
-      end
-
-      def get_init_values(searched_class, ids, title_method=nil)
-        ids = ids.split(',')
-        if ids.size > 1
-          result = []
-          ids.each do |id|
-            item = searched_class.find_by_id(id)
-            if item.present?
-              result << get_select2_hash(item, title_method, id)
-            end
-          end
-          result
-        elsif ids.size == 1
-          item = searched_class.find_by_id(ids[0])
-          if item.present?
-            get_select2_hash(item, title_method, ids[0])
-          else
-            nil
-          end
-        else
-          nil
-        end
-      end
-
-      def get_select2_hash(item, title_method, id)
-        if item.respond_to?(:to_select2) && title_method.nil?
-          item.to_select2
-        else
-          title_method ||= :name
-          { text: item.send(title_method), id: id }
-        end
-      end
-    end
-  end
-end