SearchObject

Objeto de pesquisa

DSL para construção de objetos de pesquisa.

Os objetos de pesquisa começam com uma coleção inicial (escopo) e permitem que ela seja filtrada com base em diversas opções.

Usos:

• formulários de pesquisa complicados (exemplo)
• Endpoints de API com diversas condições de filtro
• Resolvedores GraphQL (exemplo)
• ... objetos de pesquisa?

Instalação

Adicione esta linha ao Gemfile da sua aplicação:

 gem 'search_object'

E então execute:

 $ bundle

Ou instale você mesmo como:

 $ gem install search_object

Registro de alterações

As alterações estão disponíveis em CHANGELOG.md

Uso

Basta incluir SearchObject.module e definir suas opções de pesquisa:

 class PostSearch
  include SearchObject . module

  scope { Post . all }

  option ( :name )             { | scope , value | scope . where name : value }
  option ( :created_at )       { | scope , dates | scope . created_after dates }
  option ( :published , false ) { | scope , value | value ? scope . unopened : scope . opened }
end

Então você pode simplesmente pesquisar o escopo fornecido:

 search = PostSearch . new ( filters : params [ :filters ] )

# accessing search options
search . name                        # => name option
search . created_at                  # => created at option

# accessing results
search . count                       # => number of found results
search . results?                    # => is there any results found
search . results                     # => found results

# params for url generations
search . params                      # => option values
search . params opened : false        # => overwrites the 'opened' option

Exemplo

Você pode encontrar exemplos dos recursos e plug-ins mais importantes - aqui.

Plug-ins

Plug-ins de suporte SearchObject , que são passados ​​​​para o método SearchObject.module .

Plugins são simplesmente módulos Ruby, incluídos em SearchObject.module . Eles estão localizados no módulo SearchObject::Plugin .

Plug-in Paginar

Plugin de paginação realmente simples, que usa os métodos .limit e .offset simples.

 class ProductSearch
  include SearchObject . module ( :paging )

  scope { Product . all }

  option :name
  option :category_name

  # per page defaults to 10
  per_page 10

  # range of values is also possible
  min_per_page 5
  max_per_page 100
end

search = ProductSearch . new ( filters : params [ :filters ] , page : params [ :page ] , per_page : params [ :per_page ] )

search . page                                                 # => page number
search . per_page                                             # => per page (10)
search . results                                              # => paginated page results

Claro que se você quiser plugins de paginação mais sofisticados você pode usar:

 include SearchObject . module ( :will_paginate )
include SearchObject . module ( :kaminari )

Plug-in Enum

Oferece filtro com opções predefinidas.

 class ProductSearch
  include SearchObject . module ( :enum )

  scope { Product . all }

  option :order , enum : %w( popular date )

  private

  # Gets called when order with 'popular' is given
  def apply_order_with_popular ( scope )
    scope . by_popularity
  end

  # Gets called when order with 'date' is given
  def apply_order_with_date ( scope )
    scope . by_date
  end

  # (optional) Gets called when invalid enum is given
  def handle_invalid_order ( scope , invalid_value )
    scope
  end
end

Plug-in de modelo

Estende seu objeto de pesquisa com ActiveModel , para que você possa usá-lo em formulários Rails.

 class ProductSearch
  include SearchObject . module ( :model )

  scope { Product . all }

  option :name
  option :category_name
end 

 <%# in some view: %>

<%= form_for ProductSearch.new do |form| %>
  <% form.label :name %>
  <% form.text_field :name %>
  <% form.label :category_name %>
  <% form.text_field :category_name %>
<% end %> 

Plug-in GraphQL

Instalado como gem separado, ele foi projetado para funcionar com GraphQL:

 gem 'search_object_graphql'

 class PostResolver
  include SearchObject . module ( :graphql )

  type PostType

  scope { Post . all }

  option ( :name , type : types . String )       { | scope , value | scope . where name : value }
  option ( :published , type : types . Boolean ) { | scope , value | value ? scope . published : scope . unpublished }
end

Plug-in de classificação

Resolvendo a dor de lidar com a classificação de atributos e direções.

 class ProductSearch
  include SearchObject . module ( :sorting )

  scope { Product . all }

  sort_by :name , :price
end

search = ProductSearch . new ( filters : { sort : 'price desc' } )

search . results                                # => Product sorted my price DESC
search . sort_attribute                         # => 'price'
search . sort_direction                         # => 'desc'

# Smart sort checking
search . sort? ( 'price' )                         # => true
search . sort? ( 'price desc' )                    # => true
search . sort? ( 'price asc' )                     # => false

# Helpers for dealing with reversing sort direction
search . reverted_sort_direction                # => 'asc'
search . sort_direction_for ( 'price' )            # => 'asc'
search . sort_direction_for ( 'name' )             # => 'desc'

# Params for sorting links
search . sort_params_for ( 'name' ) 

Dicas e truques

Atalho de resultados

Muitas vezes você só precisará dos resultados da pesquisa:

 ProductSearch . new ( params ) . results == ProductSearch . results ( params )

Passando escopo como argumento

 class ProductSearch
  include SearchObject . module
end

# first arguments is treated as scope (if no scope option is provided)
search = ProductSearch . new ( scope : Product . visible , filters : params [ :f ] )
search . results # => includes only visible products

Lidando com opções nulas

 class ProductSearch
  include SearchObject . module

  scope { Product . all }

  # nil values returned from option blocks are ignored
  option ( :sold ) { | scope , value | scope . sold if value }
end

Bloco de opções padrão

 class ProductSearch
  include SearchObject . module

  scope { Product . all }

  option :name # automaticly applies => { |scope, value| scope.where name: value unless value.blank? }
end

Usando o método de instância em blocos de opções

 class ProductSearch
  include SearchObject . module

  scope { Product . all }

  option ( :date ) { | scope , value | scope . by_date parse_dates ( value ) }

  private

  def parse_dates ( date_string )
    # some "magic" method to parse dates
  end
end

Usando o método de instância para envio direto

 class ProductSearch
  include SearchObject . module

  scope { Product . all }

  option :date , with : :parse_dates

  private

  def parse_dates ( scope , value )
    # some "magic" method to parse dates
  end
end

O registro ativo não é necessário

 class ProductSearch
  include SearchObject . module

  scope { RemoteEndpoint . fetch_product_as_hashes }

  option ( :name )     { | scope , value | scope . select { | product | product [ :name ] == value } }
  option ( :category ) { | scope , value | scope . select { | product | product [ :category ] == value } }
end

Métodos de substituição

Você pode ter um escopo refinado, substituindo o método initialize :

 class ProductSearch
  include SearchObject . module

  option :name
  option :category_name

  def initialize ( user , options = { } )
    super options . merge ( scope : Product . visible_to ( user ) )
  end
end

Ou você pode adicionar paginação simples substituindo initialize e fetch_results (usado para buscar resultados):

 class ProductSearch
  include SearchObject . module

  scope { Product . all }

  option :name
  option :category_name

  attr_reader :page

  def initialize ( filters = { } , page = 0 )
    super filters
    @page = page . to_i . abs
  end

  def fetch_results
    super . paginate page : @page
  end
end

Extraindo Módulo Básico

Você pode extrair uma classe de pesquisa básica para seu aplicativo.

 class BaseSearch
  include SearchObject . module

  # ... options and configuration
end

Então use como:

 class ProductSearch < BaseSearch
 scope { Product }
end 

Contribuindo

1. Garfo
2. Crie sua ramificação de recursos ( git checkout -b my-new-feature )
3. Confirme suas alterações ( git commit -am 'Add some feature' )
4. Empurre para o branch ( git push origin my-new-feature )
5. Execute os testes ( rake )
6. Criar nova solicitação pull

Autores

• Radoslav Stankov - criador - RStankov

Veja também a lista de colaboradores que participaram deste projeto.

Licença

Licença MIT