SearchObject

Objet de recherche

DSL pour créer des objets de recherche.

Les objets de recherche commencent par une collection initiale (portée) et permettent de la filtrer en fonction de diverses options.

Utilisations :

• formulaires de recherche compliqués (exemple)
• Points de terminaison d'API avec plusieurs conditions de filtrage
• Résolveurs GraphQL (exemple)
• ... rechercher des objets ?

Installation

Ajoutez cette ligne au Gemfile de votre application :

 gem 'search_object'

Et puis exécutez :

 $ bundle

Ou installez-le vous-même en tant que :

 $ gem install search_object

Journal des modifications

Les modifications sont disponibles dans CHANGELOG.md

Usage

Incluez simplement le SearchObject.module et définissez vos options de recherche :

 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

Ensuite, vous pouvez simplement rechercher la portée donnée :

 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

Exemple

Vous pouvez trouver des exemples des fonctionnalités et plugins les plus importants - ici.

Plugins

Les plugins de support SearchObject , qui sont transmis à la méthode SearchObject.module .

Les plugins sont simplement de simples modules Ruby, inclus avec SearchObject.module . Ils se trouvent sous le module SearchObject::Plugin .

Plugin de pagination

Plugin de pagination très simple, qui utilise les méthodes simples .limit et .offset .

 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

Bien sûr, si vous souhaitez des plugins de pagination plus sophistiqués vous pouvez utiliser :

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

Plugin d'énumération

Vous donne un filtre avec des options prédéfinies.

 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

Plugin de modèle

Étend votre objet de recherche avec ActiveModel , afin que vous puissiez l'utiliser dans les formulaires 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 %> 

Plugin GraphQL

Installé en tant que gem distincte, il est conçu pour fonctionner avec 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

Plugin de tri

Correction de la difficulté liée à la gestion des attributs et des directions de tri.

 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' ) 

Trucs et astuces

Raccourci des résultats

Très souvent, vous aurez simplement besoin des résultats de recherche :

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

Passer la portée comme argument

 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

Gestion des options nulles

 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

Bloc d'options par défaut

 class ProductSearch
  include SearchObject . module

  scope { Product . all }

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

Utilisation de la méthode d'instance dans les blocs d'options

 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

Utilisation de la méthode d'instance pour une répartition directe

 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

L'enregistrement actif n'est pas requis

 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éthodes d'écrasement

Vous pouvez avoir une portée plus fine en écrasant la méthode 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 vous pouvez ajouter une pagination simple en écrasant initialize et fetch_results (utilisés pour récupérer les résultats) :

 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

Extraction du module de base

Vous pouvez extraire une classe de recherche de base pour votre application.

 class BaseSearch
  include SearchObject . module

  # ... options and configuration
end

Ensuite, utilisez-le comme :

 class ProductSearch < BaseSearch
 scope { Product }
end 

Contribuer

1. Fourchette-le
2. Créez votre branche de fonctionnalités ( git checkout -b my-new-feature )
3. Validez vos modifications ( git commit -am 'Add some feature' )
4. Pousser vers la branche ( git push origin my-new-feature )
5. Exécuter les tests ( rake )
6. Créer une nouvelle demande de tirage

Auteurs

• Radoslav Stankov - créateur - RStankov

Voir aussi la liste des contributeurs ayant participé à ce projet.

Licence

Licence MIT