search_autocomplete 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9c795f6eacd1ecd7cdba955188e9250b5e0a2b8e0d208742ffd41ea78cd7a380
+  data.tar.gz: e47d9e1270cea9d83343213f31f3ccf00040d761df2f2113630d24e2dd93acd1
+SHA512:
+  metadata.gz: d344fddbe8b93c3cbd31fbeb5c260a69a2b9a3c9fea650fc8f0717947d6c7b9ec1d86317860ab6eee70603d435cbaf032a897a703bad82a53f7d12058336b69f
+  data.tar.gz: ba277717530d72f6a7737c2d0fe816a20707687022a2cbc537aca8b7222b111dc260acf81f5f6f4716397d164348e7a38cca8f17ad3422a920a0cca2c2755b25

data/README.md

@@ -0,0 +1,132 @@
+# SearchAutocomplete
+This gem was created to add simple autocomplete and search/filter functionality to Ruby on Rails apps with minimal effort.
+
+Other alternatives available are outdated or aren't as simple, often requiring many external libraries such as jQuery.
+This gem only requires modules already shipped with Rails and the only external library required is available as a npm package you can add in your webpack files.
+
+## Installation
+
+### Ruby
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'search_autocomplete'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install search_autocomplete
+```
+
+### Webpack
+
+Add the compatible web component for npm:
+```bash
+yarn add @francisschiavo/search-autocomplete
+```
+
+and then require it anywhere in your scripts:
+
+```js
+require('@francisschiavo/search-autocomplete');
+```
+
+## Usage
+
+### Autocomplete
+
+After installing this gem you can configure its options with an initializer like this:
+
+**config/initializers/search_autocomplete.rb**
+```ruby
+SearchAutocomplete.configure do |options|
+  options.autocomplete_size = 5
+end
+```
+
+You must mount the autocomplete engine like this:
+
+**config/routes.rb**
+```ruby
+Rails.application.routes.draw do
+  mount SearchAutocomplete::Engine, at: '/autocomplete'
+end
+```
+
+To allow your model on the autocomplete search you must configure it like this:
+```ruby
+class Category < ApplicationRecord
+  belongs_to :category, optional: true
+
+  autocomplete :name
+end
+```
+The example above will allow searches on the `name` field for the `Category` model.
+
+To test this you can do a get request to: `{APP URL}/autocomplete/category?term=Cat 1`
+
+Note `/autocomplete` is the base uri you specify on the routes and `/category` is the lowercase name of the model.
+
+You can also search namespaced models by adding the lowercase name of every namespace as part of the URI:
+
+If your model is `Admin::User` the search would be: `{APP URL}/autocomplete/admin/user?term=Roger`
+
+### Search / Filter
+
+You can use the method `search` on your controllers as a way to filter data.
+
+This method takes 3 arguments:
+* The model class to perform the search
+* An array of fields to permit approximate matches (like)
+* An array of fields to permit exact matches (=)
+
+Here is a sample of the `index` action of a `category` controller:
+
+```ruby
+def index
+  @categories = search(Category, %i[name], []).all
+end
+```
+
+You can also use it with pagination gems like kaminari:
+
+```ruby
+def index
+  @categories = search(Category, %i[name], []).page(params[:page])
+end
+```
+
+### Postgres Jsonb support
+
+There is a limited support for `jsonb` fields, currently limited to one level deep fields.
+
+To query using a jsonb field you must pass an array as the name argument:
+
+```ruby
+class Category < ApplicationRecord
+  belongs_to :category, optional: true
+
+  autocomplete %i[name pt_BR]
+end
+```
+
+This will use `arel` infix operators to create the following query:
+
+```sql
+SELECT * FROM categories WHERE category.name->>'pt_BR' ILIKE "%term%";
+``` 
+
+## Known issues
+
+* Uses WebComponents requires modern browsers or polyfills
+* There is no automated tests at this moment.
+* There is no support for json fields other than `postgres`.
+* Json fields are supported but limited to one level deep fields. 
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'SearchAutocomplete'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path('test/dummy/Rakefile', __dir__)
+load 'rails/tasks/engine.rake'
+
+load 'rails/tasks/statistics.rake'
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/app/controllers/search_autocomplete/autocomplete_controller.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module SearchAutocomplete
+  # Autocomplete
+  class AutocompleteController < ActionController::Base
+    before_action :find_model, only: :autocomplete
+
+    ##
+    # Main autocomplete action
+    def autocomplete
+      data = autocomplete_search
+      render json: data.map { |item| { id: item.id, label: label(item), value: value(item) } }
+    end
+
+    private
+
+    def autocomplete_search
+      arel_table = @model.arel_table
+      node = Arel::Nodes::SqlLiteral.new "'%#{params[:term]}%'"
+
+      search_field = @model.autocomplete_options[:search_field]
+      # Assume postgres jsonb
+      if search_field.is_a? Array
+        op = Arel::Nodes::InfixOperation.new('->>', arel_table[search_field[0]], Arel::Nodes.build_quoted(search_field[1]))
+        query_builder = params[:term] ? @model.where(op.matches(node)) : @model
+      else
+        query_builder = params[:term] ? @model.where(arel_table[search_field].matches(node)) : @model
+      end
+
+      @model.autocomplete_options[:filters].each do |filter|
+        next unless params[filter.to_s].present?
+
+        query_builder = query_builder.where(arel_table[filter].eq(params[filter.to_s]))
+      end
+      query_builder.limit(SearchAutocomplete.autocomplete_size)
+    end
+
+    def label(item)
+      values = @model.autocomplete_options[:display_fields].map do |field|
+        if field.is_a? Array
+          item.instance_eval(field[0].to_s)[field[1].to_s]
+        else
+          item.instance_eval(field.to_s)
+        end
+      end
+      values.join ' - '
+    end
+
+    def value(item)
+      search_field = @model.autocomplete_options[:search_field]
+      if search_field.is_a? Array
+        item.instance_eval(search_field[0].to_s)[search_field[1].to_s]
+      else
+        item.instance_eval(search_field.to_s)
+      end
+    end
+
+    def find_model
+      model_name = params[:model_name].sub('/', '::').camelize
+      @model = model_name.constantize
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+SearchAutocomplete::Engine.routes.draw do
+  get '/*model_name', to: 'autocomplete#autocomplete', as: 'search'
+end

data/lib/search_autocomplete.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'search_autocomplete/engine'
+require 'search_autocomplete/options'
+
+# Provides an easy way to add autocomplete and filters to rails apps
+module SearchAutocomplete
+  extend SearchAutocomplete::Options
+end
+
+require 'search_autocomplete/autocompletable'
+require 'search_autocomplete/searchable'
+require 'search_autocomplete/form_builder_helper'
+
+::ActiveRecord::Base.include SearchAutocomplete::Autocompletable

data/lib/search_autocomplete/autocompletable.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SearchAutocomplete
+  # Autocompletable
+  module Autocompletable
+    extend ActiveSupport::Concern
+
+    included do
+      cattr_accessor :autocomplete_options
+      self.autocomplete_options = { configured: false }
+    end
+
+    # Autocompletable methods
+    module ClassMethods
+      ##
+      # Configures this model to respond to autocomplete searches
+      #
+      # @param search_field [String|Array] Name of the main field to perform the search. If an array is given it will search in a jsonb structure.
+      # @param display_fields [Array{Symbol}] Array of field names for concatenating as display result
+      # @param filters [Array{Symbol}] Array of additional fields to filter
+      #
+      def autocomplete(search_field, display_fields = [], filters = [])
+        self.autocomplete_options = {
+          configured: true,
+          search_field: search_field,
+          display_fields: display_fields.size.zero? ? [search_field] : display_fields,
+          filters: filters
+        }
+      end
+    end
+  end
+end

data/lib/search_autocomplete/engine.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SearchAutocomplete
+  # Autocomplete engine
+  class Engine < ::Rails::Engine
+    engine_name 'search_autocomplete'
+    isolate_namespace SearchAutocomplete
+  end
+end

data/lib/search_autocomplete/form_builder_helper.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Inherited from Rails
+module ActionView
+  # Inherited from Rails
+  module Helpers
+    # Helper method for form builder
+    class FormBuilder
+      ##
+      # Creates an autocomplete element from form builder
+      def autocomplete_field(method, display_value, autocomplete_path, options = {})
+        options.reverse_merge!(
+          'display-value': find_autocomplete_value(display_value),
+          value: @object.send(method),
+          url: autocomplete_path,
+          minlength: 2,
+          name: "#{@object_name}[#{method}]"
+        )
+
+        autocomplete_options[:autofocus] = options[:autofocus] if options.include? :autofocus
+        @template.content_tag(:'auto-complete', nil, options)
+      end
+
+      private
+
+      def find_autocomplete_value(display_expression)
+        @object.instance_eval(display_expression)
+      rescue StandardError
+        ''
+      end
+    end
+  end
+end

data/lib/search_autocomplete/options.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SearchAutocomplete
+  # Configuration module
+  module Options
+    mattr_accessor :autocomplete_size
+
+    def configure
+      yield self
+    end
+  end
+end

data/lib/search_autocomplete/searchable.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# Inherited from Rails
+module ActionController
+  # Searchable
+  class Base
+    ##
+    # Performs a search on the model based on permitted fields
+    #
+    # @param model [Class] Model to perform the search
+    # @param approximate_fields [Array{Symbol}] List of fields to allow as approximate filters
+    # @param exact_fields [Array{Symbol}] List of fields to allow as exact filters
+    # @param include_list [Array{Symbol}] List of related resources to include
+    def search(model, approximate_fields = [], exact_fields = [], include_list = nil)
+      arel_table = model.arel_table
+
+      search_conditions = prepare_search_fields arel_table, exact_fields
+      search_conditions += prepare_search_fields(arel_table, approximate_fields, false)
+
+      query = include_list.present? ? model.includes(include_list) : model
+      query = query.where(*search_conditions) if search_conditions.length.positive?
+      query
+    end
+
+    private
+
+    def prepare_search_fields(table, fields, exact = true)
+      search_conditions = []
+      fields.each do |field|
+        if field.is_a?(Array)
+          search_conditions.push prepare_jsonb_condition(table, field, exact)
+        else
+          search_conditions.push prepare_simple_condition(table, field, exact)
+        end
+      end
+      search_conditions
+    end
+
+    def prepare_simple_condition(table, field, exact)
+      return nil unless params.key? field
+
+      if exact
+        table[field].eq(params[field])
+      else
+        table[field].matches(Arel::Nodes::SqlLiteral.new("'%#{params[field]}%'"))
+      end
+    end
+
+    def prepare_jsonb_condition(table, field, exact)
+      field_name = field[0].to_s
+      return nil unless params.key? field_name
+
+      condition = Arel::Nodes::InfixOperation.new('->>', table[field_name], Arel::Nodes.build_quoted(field[1]))
+
+      if exact
+        condition.eq(params[field_name])
+      else
+        condition.matches(Arel::Nodes::SqlLiteral.new("'%#{params[field_name]}%'"))
+      end
+    end
+  end
+end

data/lib/search_autocomplete/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module SearchAutocomplete
+  # Gem version
+  VERSION = '0.1.0'
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: search_autocomplete
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Francis Schiavo
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-06-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0.0
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.2
+description: Search and autocomplete based on Arel and WebComponents.
+email:
+- francischiavo@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- app/controllers/search_autocomplete/autocomplete_controller.rb
+- config/routes.rb
+- lib/search_autocomplete.rb
+- lib/search_autocomplete/autocompletable.rb
+- lib/search_autocomplete/engine.rb
+- lib/search_autocomplete/form_builder_helper.rb
+- lib/search_autocomplete/options.rb
+- lib/search_autocomplete/searchable.rb
+- lib/search_autocomplete/version.rb
+homepage: https://github.com/francis-schiavo/search_autocomplete
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key: 
+specification_version: 4
+summary: This gem adds autocomplete and filter functionality to rails apps.
+test_files: []