پرش به محتویات

مرتب‌سازی، فیلتر و جستجوی زنده (Query Sort, Filter & Live Search)

این مجموعه قابلیت جدید، معرفی‌شده در Bricks 1.9.6، تعامل محتوا را از طریق المان‌های فیلتر مبتنی بر AJAX مانند search، checkbox، select، radio button، range slider و date selector بهبود می‌دهد.

امکان مرتب‌سازی، فیلتر و جستجوی پیشرفته real-time بدون refresh صفحه را می‌دهد و تجربه کاربری پویاتر و تعاملی‌تر ایجاد می‌کند.

YouTube
YouTube ↗

نحوه فعال‌سازی Query Filters

Query Filters را از داشبورد وردپرس در Bricks > Settings > Query filters فعال کنید.

پس از فعال‌سازی، گروه المان جدید «Filter» با همه المان‌های فیلتر در پنل المان‌های سازنده در دسترس می‌شود.

المان‌های Filter در Bricks 1.9.6

نکات مهم

  • هشدار سازگاری: Query Filters ممکن است با افزونه‌هایی که فیلتر bricks/query/force_run را override می‌کنند تداخل داشته باشد. بهتر است از ترکیب Bricks query filters با افزونه‌های فیلتر دیگر پرهیز کنید.
  • محدودیت scope: مرتب‌سازی و فیلتر کوئری فقط لایه بیرونی را هدف می‌گیرد (در سناریوهای query تودرتو). انواع کوئری پشتیبانی‌شده: «Post»، «Term» و «User» (@since 1.12)
  • پشتیبانی custom field: به‌طور پیش‌فرض Bricks Query Filters فقط با مقادیر custom field ساده plain-text کار می‌کند. فیلدهایی که داده را در فرمت serialized ذخیره می‌کنند پشتیبانی نمی‌شوند. (اگر از ACF یا Metabox.io استفاده می‌کنید Custom Fields Integration را بخوانید — در 1.11.1 بهبود یافت)
  • محدودیت Component: المان‌های Filter نباید داخل Bricks component استفاده شوند. همچنین target query loop نباید حلقه‌ای باشد که داخل component قرار دارد مگر root component خود query loop باشد. بیشتر بخوانید

محدودیت scope — Posts query

نحوه راه‌اندازی فیلتر

هنگام افزودن المان فیلتر به صفحه، همیشه باید «Target Query» به آن اختصاص دهید. این لازم است تا Bricks بداند هر فیلتر کدام کوئری را تحت تأثیر قرار دهد.

تنظیم Target Query فیلتر

این انعطاف در تنظیم Target Query روی خود المان فیلتر به شما اجازه می‌دهد فیلترها را هرجای صفحه قرار دهید. لازم نیست همه فیلترها را داخل یک block بچینید.

مثلاً می‌توانید المان مرتب‌سازی را جای دیگری روی صفحه قرار دهید — در مثال زیر همه فیلترها در ستون چپ هستند و المان مرتب‌سازی در ستون راست، بالای query loop.

فیلتر و مرتب‌سازی محصولات WooCommerce

اعمال فیلتر روی «Input» یا «Submit»

به‌طور پیش‌فرض هر تغییری در فیلتر — مانند انتخاب گزینه radio یا مقدار checkbox — target query را به‌روز می‌کند. می‌توانید با تنظیم کنترل «Apply to» روی «Submit» این رفتار را تغییر دهید. این‌طور کوئری فقط با کلیک روی المان «Filter - Submit» متصل به همان Target Query به‌روز می‌شود.

اعمال فیلتر روی Submit

المان‌های فیلتر

1. Filter - Active Filters

  • Function: فیلترهای فعال یا انتخاب‌شده فعلی را نمایش می‌دهد و کاربر می‌تواند با یک کلیک فیلتر را حذف کند. (@since 1.11)
  • Exclude filter IDs: اگر می‌خواهید فیلترهای خاص در فهرست فیلترهای فعال ظاهر نشوند، Bricks element ID آن‌ها را اینجا (با کاما جدا) وارد کنید.

به‌طور پیش‌فرض Bricks مقدار فیلتر فعال را به‌عنوان برچسب نمایش می‌دهد. می‌توانید با تنظیم Prefix، Suffix و Title (attribute) روی المان‌های فیلتر جداگانه برچسب را سفارشی کنید. (تب «Active Filter» روی هر المان فیلتر را ببینید.)

Prefix برای Active Filters

2. Filter - Search

  • Function: جستجوی AJAX زنده. (عبارت جستجو را به پارامتر «s» برای Post queries یا «search» برای User و Term queries پاس می‌دهد.)
  • URL parameter: برای populate کردن پارامتر URL فیلتر در frontend استفاده می‌شود. (@since 1.11)
  • Debounce (ms): تأخیر قبل از trigger جستجو پس از توقف تایپ. با کاهش کوئری‌های غیرضروری عملکرد بهبود می‌یابد.
  • Min. characters: حداقل کاراکتر برای trigger جستجو. با کاراکتر کمتر جستجو شروع نمی‌شود. پیش‌فرض 3 کاراکتر.
  • Icon (Clear): آیکون تنظیم کنید تا با کلیک مقدار جستجو پاک شود. (@since 1.11)

آیکون Clear در Filter Search

نکته

نکته: برای سازگاری با تابع جستجوی وردپرس هنگام استفاده از Filter - Search در قالب Search، URL parameter را روی «s» بگذارید. فیلتر با جستجوی native وردپرس یکپارچه کار می‌کند.

3. Filter - Checkbox

  • Filter options: Taxonomy، Post Fields، Post Meta Fields.
  • Hierarchy display: پشتیبانی می‌شود.
  • Indent: Prefix/Gap: prefix یا gap برای نمایش سلسله‌مراتبی تعریف کنید.
  • URL parameter: برای populate پارامتر URL فیلتر در frontend. (@since 1.11)
  • Terms Order by & Order: پارامتر order کوئری taxonomy را مشخص کنید. (@since 1.11)
  • Terms (Include/Exclude): اصطلاحات taxonomy خاص را شامل یا مستثنی کنید. (@since 1.11)
  • Top Level Terms Only: فقط اصطلاحات سطح بالا (parent = 0) وقتی منبع taxonomy است. (@since 1.11)
  • Hide Count Bracket: پرانتز دور مقدار count را حذف کنید. count را با .brx-option-count استایل دهید. (@since 1.11)
  • Auto Toggle Child Terms: اگر گزینه hierarchical فعال باشد، با کلیک parent مقدار child terms را خودکار toggle می‌کند. (@since 1.11)
  • Mode: «Button» یا «Checkbox» سنتی برای نمایش فیلتر. (@since 1.11)

Filter Checkbox 1.11

4. Filter - Datepicker

  • Filter options: Taxonomy، Post Fields، Post Meta Fields.
  • Enable time: انتخاب زمان به فیلتر تاریخ اضافه می‌شود.
  • Date range: انتخاب بازه تاریخ فعال می‌شود.
  • Min/max date: استفاده از حداقل/حداکثر تاریخ از index table.
  • URL parameter: برای populate پارامتر URL فیلتر در frontend. (@since 1.11)

5. Filter - Radio

  • Filter options: Taxonomy، Post Fields، Post Meta Fields.
  • Hierarchy display: پشتیبانی می‌شود.
  • Indent: Prefix/Gap: prefix یا gap برای نمایش سلسله‌مراتبی.
  • Action: انتخاب بین اعمال فیلتر یا مرتب‌سازی.
  • Mode: «Button» یا «Radio» سنتی.
  • URL parameter: برای populate پارامتر URL فیلتر در frontend. (@since 1.11)
  • Terms Order by & Order: پارامتر order کوئری taxonomy. (@since 1.11)
  • Terms (Include/Exclude): شامل/مستثنی اصطلاحات. (@since 1.11)
  • Top Level Terms Only: فقط اصطلاحات سطح بالا وقتی منبع taxonomy است. (@since 1.11)
  • Hide Count Bracket: پرانتز count را حذف کنید. با .brx-option-count استایل دهید. (@since 1.11)

استایل .brx-option-count

6. Filter - Range

  • Source: فعلاً محدود به «Custom Field» برای meta key (مثلاً _regular_price — قیمت استاندارد محصول در WooCommerce).
  • Automatic min/max: حداقل/حداکثر را بر اساس نتایج query loop تنظیم می‌کند.
  • Mode: «Slider» یا «Input» برای انتخاب بازه.
  • URL parameter: برای populate پارامتر URL فیلتر در frontend. (@since 1.11)
  • بخش Slider: کنترل‌های بیشتر برای استایل حالت «Slider». (@since 1.11)

بخش کنترل Range Slider

7. Filter - Select

  • Filter options: Taxonomy، Post Fields، Post Meta Fields.
  • Hierarchy display: پشتیبانی می‌شود.
  • Indent: Prefix: prefix برای نمایش سلسله‌مراتبی.
  • Action: فیلتر یا مرتب‌سازی.
  • URL parameter: برای populate پارامتر URL فیلتر در frontend. (@since 1.11)
  • Terms Order by & Order: پارامتر order کوئری taxonomy. (@since 1.11)
  • Terms (Include/Exclude): شامل/مستثنی اصطلاحات. (@since 1.11)
  • Top Level Terms Only: فقط اصطلاحات سطح بالا وقتی منبع taxonomy است. (@since 1.11)

8. Filter - Submit / Reset

  • Functionality: دکمه‌های reset یا submit (اعمال) همه فیلترهای target query.
  • Action: دکمه به‌عنوان «Submit» یا «Reset» عمل می‌کند.
  • Hide if No Active Filter: وقتی فیلتر فعالی روی target query نیست دکمه مخفی شود. Bricks کلاس .brx-no-active-filter به دکمه اضافه می‌کند. (فقط Reset action). (@since 1.11)
  • Redirect to: URL که Bricks کاربر را به آن redirect کند و همه مقادیر فیلتر فعلی حفظ شوند. برای Live Search در homepage و redirect به صفحه Search مفید است. (فقط Submit action). (@since 1.11)

کنترل‌های Filter Submit 1.11

9. المان Pagination

گزینه «Enable AJAX» را روی المان Pagination فعال کنید تا با سایر المان‌های فیلتر سازگار باشد.

فعال‌سازی AJAX در Pagination

تگ‌های داده پویا

Query Sort / Filter با دو تگ داده پویای جدید (search_term_filter، query_results_count_filter) همراه است که مقدارشان با تغییر نتایج کوئری به‌طور خودکار به‌روز می‌شود.

{search_term_filter:quer34} - نتیجه عبارت جستجو را در span data-brx-ls-term="quer34">> می‌پیچد. با AJAX وقتی Query ID هدف quer34 (Query ID المان شما) refresh شود به‌روز می‌شود.

{query_results_count_filter:quer34} - تعداد نتایج کوئری را در span data-brx-qr-count="quer34">> قرار می‌دهد. با تغییرات AJAX در Query ID quer34 به‌روز می‌شود.

search_term

تگ داده پویای جدید search_term مقدار عبارت جستجو را رندر می‌کند.

{search_term} - مقدار $_GET['s'] یا get_query_var('s') — برای نمایش عبارت جستجوی فعلی روی صفحه.

{search_term:quer34} - متغیر query search را از Query ID quer34 می‌گیرد. برای یافتن Query ID، element ID المان query را کپی کنید و شش کاراکتر آخر را بدون پیشوند «#brxe-» استفاده کنید.

برای صفحه نتایج جستجوی static است. برای نمایش مقدار Filter - Search از search_term_filter استفاده کنید.

active_filters_count

از نسخه 2.0، Bricks تگ {active_filters_count} را برای نمایش پویا تعداد فیلترهای فعال target query معرفی کرد. یک span> تولید می‌کند که با تغییر فیلترها به‌روز می‌شود.

{active_filters_count:ehljca} - تعداد فیلتر فعال برای کوئری با ID ehljca.

{active_filters_count:ehljca @exclude:'desplk,mn3p9,88510'} - element IDهای فیلتر مشخص‌شده از شمارش مستثنی می‌شوند.

می‌توانید span را استایل دهید:

span[data-brx-af-count] {
  /* Your styles here */
}

مثال active_filters_count

برای یکپارچه‌سازی آسان در دکمه‌ها، badgeها یا UI دیگر وقتی فیلترها داخل Offcanvas هستند.

«Filter - Search» متصل به Target Query نتایج را فوراً به‌روز می‌کند، اما برای کوئری‌هایی است که در بارگذاری اولیه صفحه رندر می‌شوند — مانند صفحه فروشگاه WooCommerce یا صفحه اصلی وبلاگ.

می‌توانید Live Search واقعی بسازید که نتایج فقط پس از جستجو با «Filter - Search» ظاهر شوند.

کافی است «Is live search» را در المان target query loop فعال کنید:

Is live search در Query Control

پس از فعال‌سازی، این کوئری فقط هنگام live search اجرا می‌شود.

برای مخفی کردن کوئری در ابتدا (بارگذاری صفحه)، المانی که نتایج live search را نگه می‌دارد ویرایش کنید — معمولاً parent المان query loop یا المان بیرونی دیگر.

سپس element ID آن را کپی کنید (مثلاً #brxe-dx44gp)، به تنظیمات query برگردید و element ID را در فیلد Live search results paste کنید.

دموی Live search: https://youtu.be/5oDHG-bTAfQ?si=ZR61wiAVxFFbjP-c&t=461

به‌روزرسانی Filter Index

برای checkbox، datepicker، radio، range و select داخل سازنده. همچنین از داشبورد وردپرس در Bricks > Settings > Query filters.

Regenerate و Continue index job

یادداشت

اگر indexing jobها pending بمانند و پیشرفت نکنند، این راه‌حل را ببینید.

Regenerate filter index:

  • Purpose: اطمینان از به‌روز بودن همه گزینه‌های فیلتر.
  • Function: job indexing را برای همه المان‌های فیلتر دوباره تولید می‌کند، رکوردهای index را می‌سازد و در جدول سفارشی ذخیره می‌کند.

Continue index job: (@since 1.10)

  • Purpose: اجرای فوری jobهای index باقی‌مانده/صف‌شده به‌جای انتظار برای WP cronjob بعدی.
  • Function: jobهای indexing را trigger می‌کند و پیشرفت را در صفحه تنظیمات به‌روز می‌کند.

اگر سایت با HTTP Authentication محافظت شده، فرآیند indexing ممکن است گیر کند. snippet زیر را به child theme اضافه کنید.

add_filter( 'bricks/remote_post', function( $args, $url ) {
  if ( strpos( $url, 'action=bricks_background_index_job' ) === false && strpos( $url, 'action=bricks_system_info_wp_remote_post_test' === false ) ) {
    return $args;
  }

  // Add Basic Auth to the request
  $username = 'XXXX'; // Replace XXXX to your HTTP Auth username
  $password = 'XXXX'; // Replace XXXX to your HTTP Auth password

  $args['headers']['Authorization'] = 'Basic ' . base64_encode( $username . ':' . $password );

  return $args;
}, 10, 2 );

برچسب‌های سفارشی گزینه

برای checkbox، radio و select.

  • Use Case: «Source» روی «Custom field» یا «WordPress field» است.
  • Example: نگاشت _stock_status به برچسب کاربرپسند.

نگاشت برچسب سفارشی

فیلتر بر اساس URL Parameter

از نسخه 1.11، Bricks Query Filters فیلتر بر اساس URL parameter را پشتیبانی می‌کنند.

کنترل جدید «URL Parameter» برای Filter types: Search، Checkbox، Radio، Range، Datepicker و Select اضافه شده. اگر parameter سفارشی تعریف نکنید، Bricks به‌طور خودکار brx_{BRICKS_ID} را استفاده می‌کند. مثلاً فیلتر با ID qwe123 از brx_qwe123 استفاده می‌کند.

می‌توانید parameter یکتا به هر فیلتر با فیلد «URL Parameter» اختصاص دهید. برای parameterهای سفارشی prefix یکتا توصیه می‌شود تا با افزونه‌ها یا parameterهای رزرو وردپرس تداخل نداشته باشد.

چه انتظاری داشته باشید

  • گزینه‌های فیلتر از قبل انتخاب/فعال می‌شوند اگر URL parameter مربوط را داشته باشد، مانند: /my-page/?filter-a=230&filter-b[]=3&filter-b[]=5
  • در بارگذاری صفحه، کوئری نتایج فیلترشده بر اساس URL parameterها نمایش می‌دهد.
  • با تعامل کاربر پس از بارگذاری، URL parameterها به‌صورت پویا به‌روز می‌شوند.
  • برای Live Search Queries، URL parameter populate نمی‌شود. می‌توانید Filter-Submit و URL تعریف کنید تا مقادیر فیلتر فعلی به صفحه یا URL هدف منتقل شوند.

Browser History

از نسخه 1.11، هر action فیلتر با رویداد popstate در history مرورگر ثبت می‌شود. کاربر می‌تواند با دکمه‌های forward/backward مرورگر در history فیلتر پیمایش کند و نتایج فیلترشده نمایش داده می‌شود.

تجربه مرور روان‌تر — کاربر به‌راحتی به state فیلتر قبلی برمی‌گردد. هنگام پیمایش history، کوئری خودکار به فیلترهای فعال در آن مرحله به‌روز می‌شود.

تعاملات (Interactions)

در نسخه 1.11، دو trigger جدید — Filter: Empty و Filter: Not Empty — معرفی شد. المان‌ها را بر اساس اینکه گزینه‌ها یا مقادیر فیلتر شرایط خاص را برآورده می‌کنند یا نه، show/hide کنید.

برای UX بهتر با visibility پویا المان‌ها بر اساس state فیلتر — بدون JavaScript سفارشی.

مثال: یک block شامل:

  • heading: متن «Active Filters»
  • Active Filters element که فیلترهای اعمال‌شده را فهرست می‌کند

می‌خواهید وقتی فیلتری اعمال نشده کل block مخفی شود. روی block interaction بگذارید:

  • Filter: Empty > Hide element
  • Filter: Not Empty > Show element

یادداشت

در این setup، triggerها بر اساس خود Active Filters element ارزیابی می‌شوند، نه مستقیم کوئری: - Filter: Empty وقتی Active Filters element آیتمی‌برای نمایش ندارد (یعنی فیلتر فعالی برای target query نیست). - Filter: Not Empty وقتی Active Filters element یک یا چند آیتم دارد (یعنی حداقل یک فیلتر فعال است).

Trigger Filter Empty با Active Filters

نتیجه مورد انتظار:

  • Filter: Empty – block وقتی Active Filters element آیتمی‌ندارد مخفی می‌شود. UI غیرضروری نمایش داده نمی‌شود.
  • Filter: Not Empty – block وقتی حداقل یک آیتم دارد نمایش داده می‌شود. heading و فهرست فیلتر برای کاربر قابل تعامل می‌ماند.

یادداشت

برای جزئیات بیشتر triggerها، مستندات Interactions را ببینید.

یکپارچه‌سازی Custom Fields

از نسخه 1.11.1، Bricks Custom Fields Integrations را معرفی کرد — در Bricks > Settings > Query Filters فعال کنید. Bricks تنظیمات را از providerهای پشتیبانی‌شده می‌گیرد، مقادیر فیلد را index می‌کند و query parameter برای فیلتر تولید می‌کند — حتی برای فیلدهای serialized که قبلاً ممکن نبود.

Custom Fields Integration در Query Filters

در سازنده، وقتی منبع فیلتر «Custom Field» است، dropdown Provider ظاهر می‌شود. provider مناسب را انتخاب کنید و Dynamic Tag picker در فیلد «Meta Key» ظاهر می‌شود. custom field را انتخاب کنید. از این نقطه Bricks تنظیمات فیلد را خودکار می‌گیرد.

یادداشت

تگ داده پویا برای parse مستقیم داده پویا نیست؛ فقط به Bricks دسترسی به تنظیمات فیلد می‌دهد. تگ نامربوط استفاده نکنید.

Provider در سازنده — Custom Fields Integration

با این قابلیت Bricks می‌تواند:

  • choices تعریف‌شده در ACF یا Meta Box را خودکار بگیرد و در Filter - Checkbox، Radio و Select نمایش دهد.
  • Filter - Datepicker: فرمت تاریخ/زمان ACF و Meta Box بدون پیکربندی دستی.
  • ACF Compatibility: Relationship، فیلدهای چندمقداری و Post Object.
  • Meta Box Compatibility: multiple choices و فیلدهای Post، Taxonomy و User. Custom Table fields پشتیبانی نمی‌شود.

فعلاً یکپارچه‌سازی برای Advanced Custom Fields (ACF) و Meta Box موجود است.

اکشن جدید: «Results Per Page» برای Select و Radio

از نسخه 1.12.2، اکشن «Results Per Page» برای Filter - Select و Filter - Radio در دسترس است. کاربر می‌تواند تعداد نتایج در هر صفحه target query را پویا تنظیم کند. انواع کوئری: «Post»، «Term» و «User»

اکشن Results Per Page

گزینه‌های پیش‌فرض 10، 20، 50 و 100. با کنترل «Options: Results Per Page» سفارشی کنید. URL parameter هم مانند سایر المان‌های فیلتر تولید و پشتیبانی می‌شود.

مثال:

مثال Results Per Page

یادداشت

این اکشن تنظیم اصلی query per page را تغییر نمی‌دهد. وقتی فعال باشد در Active Filters element (در صورت وجود) نمایش داده می‌شود. برای مخفی کردن، element ID را در تنظیمات Active Filters element در Exclude وارد کنید.

این انعطاف بیشتری می‌دهد تا کاربر تعداد نتایج در هر صفحه را انتخاب کند.

پشتیبانی فیلتر WooCommerce (Source)

از نسخه 2.0، اگر WooCommerce نصب باشد می‌توانید WooCommerce را به‌عنوان Filter Source انتخاب کنید.

پس از انتخاب، هر المان فیلتر گزینه‌های WooCommerce-specific بسته به المان و action mode نمایش می‌دهد.

منبع فیلتر WooCommerce

منبع مرتب‌سازی WooCommerce

Filter - Radio, Filter - Select Filter - Checkbox Filter - Range
On Sale ✔️ ✔️
In Stock ✔️ ✔️
Featured Products ✔️ ✔️
Product Type ✔️ ✔️
Rating ✔️
Price ✔️
(Sort) Price ✔️
(Sort) Rating ✔️

مثال frontend فیلترهای WooCommerce

این فیلترها تجربه فیلتر محصول intuitive برای فروشگاه WooCommerce بدون کد سفارشی می‌سازند. مشتریان با وضعیت موجودی، قیمت، rating و بیشتر لیست محصولات را محدود می‌کنند — یکپارچه با Bricks Query Filters. (توجه: Filter by Rating در Radio یا Select فقط text-based است.)