SearchObject

كائن البحث

DSL لبناء كائنات البحث.

تبدأ كائنات البحث بمجموعة (نطاق) أولية وتسمح بتصفيتها بناءً على خيارات متنوعة.

الاستخدامات:

• نماذج بحث معقدة (مثال)
• نقاط نهاية API مع شروط تصفية متعددة
• محللات GraphQL (مثال)
• ... كائنات البحث؟

تثبيت

أضف هذا السطر إلى ملف Gemfile الخاص بالتطبيق الخاص بك:

 gem 'search_object'

ومن ثم تنفيذ:

 $ bundle

أو قم بتثبيته بنفسك على النحو التالي:

 $ gem install search_object

سجل التغيير

التغييرات متاحة في CHANGELOG.md

الاستخدام

ما عليك سوى تضمين SearchObject.module وتحديد خيارات البحث الخاصة بك:

 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

ثم يمكنك فقط البحث في النطاق المحدد:

 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

مثال

يمكنك العثور على أمثلة لأهم الميزات والمكونات الإضافية - هنا.

الإضافات

يدعم SearchObject المكونات الإضافية، التي يتم تمريرها إلى طريقة SearchObject.module .

الإضافات هي مجرد وحدات روبي بسيطة، والتي تم تضمينها مع SearchObject.module . وهي موجودة ضمن وحدة SearchObject::Plugin .

البرنامج المساعد لصفحات

مكون إضافي بسيط جدًا للصفحات، والذي يستخدم أساليب .limit و .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

بالطبع، إذا كنت تريد مكونات إضافية أكثر تعقيدًا لترقيم الصفحات، يمكنك استخدام:

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

التعداد البرنامج المساعد

يمنحك التصفية بخيارات محددة مسبقًا.

 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

البرنامج المساعد النموذجي

يوسع كائن البحث الخاص بك باستخدام ActiveModel ، حتى تتمكن من استخدامه في نماذج 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 %> 

البرنامج المساعد GraphQL

تم تثبيته كجوهرة منفصلة، ​​وهو مصمم للعمل مع 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

فرز البرنامج المساعد

إصلاح ألم التعامل مع فرز السمات والاتجاهات.

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

نصائح وحيل

اختصار النتائج

في كثير من الأحيان ستحتاج فقط إلى نتائج البحث:

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

تمرير النطاق كوسيطة

 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

التعامل مع خيارات الصفر

 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

كتلة الخيار الافتراضي

 class ProductSearch
  include SearchObject . module

  scope { Product . all }

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

استخدام أسلوب المثيل في كتل الخيار

 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

استخدام أسلوب المثيل للإرسال المباشر

 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

السجل النشط غير مطلوب

 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

طرق الكتابة الفوقية

يمكن أن يكون لديك نطاق دقيق، عن طريق الكتابة فوق طريقة 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

أو يمكنك إضافة ترقيم صفحات بسيط عن طريق الكتابة فوق كل من initialize و fetch_results (المستخدمين لجلب النتائج):

 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

استخراج الوحدة الأساسية

يمكنك استخراج فئة بحث أساسية لتطبيقك.

 class BaseSearch
  include SearchObject . module

  # ... options and configuration
end

ثم استخدمه مثل:

 class ProductSearch < BaseSearch
 scope { Product }
end 

المساهمة

1. شوكة ذلك
2. قم بإنشاء فرع الميزات الخاص بك ( git checkout -b my-new-feature )
3. تنفيذ تغييراتك ( git commit -am 'Add some feature' )
4. ادفع إلى الفرع ( git push origin my-new-feature )
5. إجراء الاختبارات ( rake )
6. إنشاء طلب سحب جديد

المؤلفون

• رادوسلاف ستانكوف - المبدع - رستانكوف

انظر أيضًا قائمة المساهمين الذين شاركوا في هذا المشروع.

رخصة

رخصة معهد ماساتشوستس للتكنولوجيا