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

حلقه پرس‌وجو (Query Loop)

YouTube
YouTube ↗

Query Loop builder برای همه المان‌های layout، Accordion و Slider در دسترس است.

همچنین برای Accordion (Nestable)، Tabs (Nestable) و Slider (Nestable) قابل فعال‌سازی است.

پایگاه داده را (طبق پارامترهای کوئری) query می‌کند و نتایجی را که داخل حلقه می‌خواهید نمایش دهید رندر می‌کند (داده پویا).

می‌توانید post typeها، taxonomy termها و userها را query کنید. موارد استفاده معمول:

  • Posts: آخرین پست‌ها، پست‌های مرتبط (برای هر post type ثبت‌شده و public)
  • Terms: دسته‌بندی‌ها و تگ‌های پست، دسته‌بندی محصولات و غیره
  • Users: فهرست نویسندگان وبلاگ، اعضای community و اعضای تیم

مهم

Bricks Query Loop به‌طور خودکار commentهای HTML !--brx-loop-xxxxx--> را در frontend تولید می‌کند. این commentها برای AJAX Pagination، Query Filters، Load More و Infinite Scroll ضروری هستند.

یادداشت

این commentها را حذف نکنید — در غیر این صورت این قابلیت‌ها ممکن است از کار بیفتند.

برخی افزونه‌های بهینه‌سازی عملکرد به‌طور پیش‌فرض همه commentهای HTML را حذف می‌کنند. اگر چنین افزونه‌ای دارید، commentهای تولیدشده Bricks را حفظ کنید.

نحوه ساخت query loop

یک المان «Container» به canvas اضافه کنید. تنظیم Use Query Loop را فعال کنید تا container به آیتم حلقه (repeater) تبدیل شود.

کنترل Query Loop در Container

المان Container: کنترل query loop جدید

پس از فعال‌سازی Use Query Loop، کنترل Query (آیکون loop/infinity) را می‌بینید.

کنترل query را باز کنید و پارامترهای کوئری برای دریافت محتوا از پایگاه داده را تنظیم کنید.

این container اکنون repeater item شماست. همه المان‌های داخل آن به‌اندازه تعداد نتایج کوئری تکرار می‌شوند.

کنترل Query

کنترل Query سه object type پشتیبانی می‌کند: posts، terms و users.

نوع object در Query Control

  • Posts کوئری از نوع WP_Query فعال می‌کند. پیش‌فرض است — برای حلقه posts، pages، media یا custom post type.
  • Terms WP_Term_Query را فعال می‌کند — برای حلقه‌زدن اصطلاحات taxonomy. مفید برای فهرست دسته‌بندی محصولاتی که محصول دارند.
  • Users WP_User_Query را فعال می‌کند — برای حلقه userهای سایت. مفید برای نویسندگان وبلاگ یا اعضای تیم (اگر به‌عنوان user سایت ثبت شده باشند).

کنترل‌های query بر اساس نوع انتخاب‌شده تطبیق می‌یابند.

Query editor (PHP)

Bricks 1.9.1 کنترل Query editor را معرفی کرد که کوئری PHP سفارشی برای انعطاف و قابلیت query بیشتر.

Query editor پس از فعال‌سازی «Query editor (PHP)» ظاهر می‌شود.

یادداشت

باید code execution را در تنظیمات Bricks فعال کنید تا به این قابلیت دسترسی داشته باشید.

Query editor PHP در Bricks 1.9.1

کوئری سفارشی با داده پویا (ACF) برای post type، برگرداندن همه پست‌های سپتامبر 2023.

باید آرایه PHP حاوی WordPress query arguments برگردانید.

طبق screenshot، query editor از داده پویا پشتیبانی می‌کند.

کوئری Posts

تنظیمات Post query

Post type: یک یا چند post type (پیش‌فرض: posts)

Order by: مرتب‌سازی بر اساس post ID، author، title، published یا modified date، comment count، relevance، menu order یا random (پیش‌فرض: published date). (چند مقدار @since 1.11.1)

Order: صعودی یا نزولی (پیش‌فرض). (چند مقدار @since 1.11.1)

Posts Per Page: تعداد پست در هر صفحه (پیش‌فرض: وردپرس > تنظیمات > Reading > Blog pages show at most)

Offset: تعداد پست‌های ردشده.

Ignore Sticky Posts: اگر نمی‌خواهید sticky posts به ابتدای مجموعه منتقل شوند فعال کنید.

Disable Query Merge: اگر نمی‌خواهید کوئری در archive، search و غیره auto-merge شود فعال کنید. معمولاً برای Query loop در footer، header یا non-main query. GUI برای فیلتر bricks/posts/merge_query است.

Child Of: parent ID برای برگرداندن فقط فرزندان. (post_parent در WP_Query)

Include/Exclude: شامل یا مستثنی کردن یک یا چند پست. می‌توانید dynamic tag روی این کنترل هم استفاده کنید (@since 1.12)

Exclude Current Post: پست فعلی از حلقه مستثنی می‌شود (مفید برای «related posts»)

Terms Include/Exclude: شامل یا مستثنی پست‌هایی با یک یا چند term.

Taxonomy Query: یک یا چند taxonomy query برای فیلتر پست‌ها.

Tax Query Relation: taxonomy queryها inclusive (OR) یا exclusive (AND).

Meta Query: یک یا چند meta query بر اساس custom field.

Relation: meta queryها inclusive (OR) یا exclusive (AND).

Random seed TTL: مدت (دقیقه) که random seed وجود دارد. برای جلوگیری از duplicate در order random. «0» برای خاموش کردن.

اگر TTL را 10 دقیقه بگذارید، نتیجه کوئری 10 دقیقه یکسان می‌ماند — duplicate در صفحات مختلف یا infinite scroll جلوگیری می‌شود. (@since 1.7.1)

Is main query (Archive, Search): در قالب archive یا search، یکی از حلقه‌ها را main query انتخاب کنید. 404 هنگام پیمایش صفحات جلوگیری می‌شود. Pagination element را هم درست تنظیم کنید.

این گزینه را برای چند کوئری روی یک صفحه فعال نکنید — فقط اولی main query archive می‌شود. (@since 1.8)

گزینه‌های مرتب‌سازی پیشرفته

از نسخه 1.11.1، Order By و Order در Bricks Query Loop چند معیار مرتب‌سازی را پشتیبانی می‌کنند. قوانین پیچیده مستقیماً در Bricks — بدون PHP filter سفارشی.

مثال Order By پیشرفته 1

مثلاً مرتب‌سازی بر اساس name نزولی و سپس ID نزولی. Bricks معیارها را به‌ترتیب اعمال می‌کند.

سناریوهای مثال:

  • Multi-Criteria Ordering: فهرست directory — ابتدا popularity (custom field) نزولی، سپس date added صعودی.
  • Custom Order Clauses with Meta Queries: مرتب‌سازی بر اساس performance date و time در meta query. مثال کد در این مقاله.

مثال Order By پیشرفته 2

بهترین روش برای Pagination و Order By

با چند معیار مرتب‌سازی، ID را به‌عنوان معیار دوم بگنجانید تا duplicate در صفحات paginate نشود. مثلاً 5 پست در صفحه و 15 پست با price یکسان — فقط order by price ممکن است پست را در چند صفحه نشان دهد. order by price سپس ID نتیجه یکنواخت می‌دهد.

مثال 1: آخرین پست‌ها

در این مثال چهار آخرین پست (تصویر شاخص، عنوان، excerpt) با Query Loop Builder.

Query Loop — آخرین پست‌ها

نمایش آخرین پست‌ها با query loop سفارشی

Container به canvas اضافه کنید — blueprint هر آیتم کوئری.

Use Query Loop را فعال کنید.

Image داخل container — «Featured Image» از Dynamic Data.

Container دیگر با Heading و Text. Heading: {post_title}. Text: {post_excerpt}.

می‌توانید Post Title element یا Post Excerpt element هم استفاده کنید.

Posts Per Page را روی 4 بگذارید.

کوئری Media

Bricks 1.5 امکان query فایل‌های media (attachment post type). Media (attachment) در Posts query type.

پس از انتخاب Media، کنترل mime type. پیش‌فرض images؛ mime type دیگر با کاما (مثلاً image/jpeg,image/png,image/gif).

برای تصاویر attach شده به پست، Child of با post ID. پویا: {post_id}.

تنظیمات Media query loop

مثال 2: گالری media

Container، Block داخل آن، Image داخل Block.

Container: flex-wrap wrap، direction افقی (row). Block: Query Loop، Media post type، posts per page. Block layout: width و height (مثلاً 300px).

Image: {post_id} — attachment posts برمی‌گردد، image ID همان post ID. object-fit cover، height 300px.

نتیجه گالری media با Query Loop

نتیجه نهایی گالری media با Query Loop builder

کوئری محصولات WooCommerce

از 1.10، تنظیمات جدید برای WooCommerce products query. با انتخاب Products post type بخش WooCommerce. (فقط اگر WooCommerce فعال باشد)

10 محصول featured آخر در homepage:

تنظیمات Featured products

4 محصول related در قالب single product:

تنظیمات Related products

مثال 3: محصولات Upsells WooCommerce

3 upsell در قالب single product:

تنظیمات Upsell products

کوئری Terms

کنترل Terms query

Taxonomies: یک یا چند taxonomy (پیش‌فرض: none).

Order by: term ID، name، parent، count یا include list.

Order: صعودی (پیش‌فرض) یا نزولی.

Number: تعداد term در هر صفحه. وردپرس پیش‌فرض all؛ Bricks پیش‌فرض Reading settings. 0 برای همه.

Offset: تعداد term ردشده.

Parent: parent term ID برای direct-child. 0 برای termهایی که فرزند دارند. مثلاً 55 فقط T-shirts.

Child of: term ID برای child terms. مثلاً 55 → T-shirts و Tees (ساختار).

Childless: (bool) فقط term بدون فرزند. روی non-hierarchical بی‌اثر. پیش‌فرض false.

Disable Query Merge: auto-merge خاموش. (@since 1.7.1)

Terms Include/Exclude: شامل/مستثنی term

Show empty: term بدون post assign.

Meta Query: فیلتر بر اساس custom field.

Relation: OR یا AND.

No Results: متن وقتی نتیجه‌ای نیست.

Current post term: termهای assign شده به پست فعلی. (@since 1.8.4) فقط single post. فقط اگر «Type» = «Term». همان منطق bricks/terms/query_vars

Current post term در Terms query

مثال 3: دسته‌بندی محصولات

فهرست پویا دسته‌بندی محصول (تصویر + لینک archive).

WooCommerce و sample products. Container loop. Basic Text با {term_name}.

Query Loop terms — دسته‌بندی محصول

نمایش دسته‌بندی محصول با لینک

Query: «terms»، Taxonomy «Product Categories». در canvas به‌اندازه دسته‌ها container. dynamic data: term ID، name، archive URL، description، term meta.

Background image container: Product Category Image:

Background image دسته‌بندی

تنظیم background image container

Container به archive لینک — Term Archive URL. HTML tag «a (link)»، link type Dynamic Data:

لینک archive term

کوئری Users

کنترل Users query

Roles: یک یا چند role (پیش‌فرض: any)

Order by: user ID، name، username، nicename، login، email، registered date، post count یا include list.

Order: صعودی (پیش‌فرض) یا نزولی.

Number: تعداد user در صفحه. وردپرس all؛ Bricks Reading settings. -1 برای همه.

Offset: user ردشده.

Current post author: نویسنده پست فعلی (@since 1.9.1)

Disable Query Merge: (@since 1.7.1)

Meta Query: فیلتر custom field.

Relation: OR یا AND.

No Results: متن بدون نتیجه.

مثال 4: نویسندگان وبلاگ

بخش فهرست نویسندگان — role «Author».

Container با query user type. Image (ACF profile) و Basic Text {wp_user_display_name}.

Query Loop users — نویسندگان وبلاگ

نمایش نویسندگان وبلاگ

المان Pagination

همراه query loop builder. Pagination در گروه WordPress پنل المان‌ها.

المان Pagination

Pagination جدا layout انعطاف‌پذیر می‌دهد.

Pagination را به canvas اضافه کنید و در Related Query المان query را انتخاب کنید:

Related Query در Pagination

نکته: نام توصیفی به containerهای query-enabled بدهید.

Load more (دکمه)

علاوه بر infinite scroll، هر المان (معمولاً Button) با interaction «Load more» interaction:

دکمه Load more Query Loop

Query loop در Accordion و Slider

Accordion و Slider هم Query Loop برای تغذیه پویا بخش‌ها.

Query Loop control در Accordion — به‌اندازه نتایج accordion item.

title، subtitle و content «master» accordion item به‌عنوان template:

Query loop در Accordion

Query loop در المان accordion

همان در Slider — Query control و slide item به‌عنوان template:

Query loop در Slider

Query loop در المان slider.

Include/Exclude: پشتیبانی dynamic data tag

از 1.12، dynamic data tag در «Include» و «Exclude».

include/exclude پویا از ACF یا Meta Box relationship:

  • Include: ID به post__in.
  • Exclude: ID به post__not_in.

Include با dynamic values

داده پویا برای post ID از custom field — همراه meta query یا taxonomy query.

انواع فیلد پشتیبانی‌شده

  • ACF: Relationship، Post Object، Gallery
  • Meta Box: Relationship، Post، Image Advanced، Image، Image Upload، Single Image
  • JetEngine: Relationship، Post، Gallery، Media (@since 2.2)

مهم

با dynamic data در Include، Post Type با مقادیر فیلد همخوان باشد. Gallery field → Post Type Media.

مثال 1: ACF Relationship با Post Type و Order

ACF Relationship به چند post type — فقط «Book» به ترتیب relationship field:

مثال Include dynamic values 1

مثال 2: Meta Box Image Advanced برای Nestable Slider

قبلاً PHP filter برای post__in. اکنون مستقیم در UI.

dynamic field، Post Type = Media، Mime Type در صورت نیاز.

یادداشت

داخل حلقه {post_id} و {post_title} — نه {featured_image}.

مثال Meta Box Image Advanced

Post Type Media، Mime Type در صورت نیاز، Random (rand).

یادداشت

{post_id} و {post_title} — نه {featured_image}.

مثال ACF Gallery random 1

نتیجه ACF Gallery random

Query Type: Array

Array query loop — حلقه‌زدن هر آرایه PHP یا JSON. (@since 2.2)

مفید برای:

  • آرایه‌های پاسخ API. (API query)
  • ترکیب منابع (posts + آرایه سفارشی).
  • خروجی functionهای سفارشی.

کنترل Array query

مانند هر query Bricks: استایل، dynamic tag، pagination.

پشتیبانی: AJAX/non-AJAX pagination، Load More، Infinite Scroll

Use Case 1: آرایه‌های تودرتو از API

cars: ['BMW', 'Mazda'] — nested array loop و path در Array Editor:

Nested array loop با dynamic tag

Use Case 2: آرایه PHP سفارشی

Function با dynamic tag {echo:my_custom_array()}:

// Ensure that my_custom_array is whitelisted via the bricks/code/echo_function_names hook
function my_custom_array() {
  return [
    ['name' => 'John', 'age' => 30],
    ['name' => 'Jane', 'age' => 25],
  ];
}

Dynamic Data Tag: {query_array:raw}

{query_array:raw} - مقدار آرایه فعلی (لیست ساده رشته).

{query_array:raw @key:'age'} - کلید خاص از آیتم آرایه.

مثال 1: لیست ساده

[
  'Apple',
  'Banana',
  'Cherry',
  'Donut'
]

{query_array:raw} داخل حلقه.

مثال 2: آرایه Associative

[
  ['name' => 'John', 'age' => 30],
  ['name' => 'Alan', 'age' => 25],
  ['name' => 'Pony', 'age' => 66]
]

{query_array:raw @key:'name'} و {query_array:raw @key:'age'}

مثال 3: آرایه‌های تودرتو

[
  {
    "name": "John",
    "age": 30,
    "cars": ["Ford", "BMW", "Fiat"]
  },
  {
    "name": "Elbert",
    "age": 66,
    "cars": ["Mazda", "Benz"]
  }
]

حلقه‌زدن هر cars:

  1. Array Loop تودرتو داخل parent.
  2. Array Editor: {query_array:raw @key:'cars'}
  3. {query_array:raw} در nested loop.

Results Filter

Results Filter — فیلتر نتایج پس از fetch و قبل از render (مانند bricks/query/result PHP filter). (@since 2.2)

Loop Types: Array، ACF Repeater

  • حذف نتایج غیرضروری
  • جلوگیری از render حلقه ناخواسته

کنترل Results Filter

مثال: فیلتر بر اساس Age

[
  ['name' => 'John', 'age' => 30],
  ['name' => 'Alan', 'age' => 25],
  ['name' => 'Pony', 'age' => 66]
]

فقط age کمتر از 50:

Field Operator Value
{query_array:raw @key:'age'} < 50

Pony (66) حذف — فقط John و Alan.

یادداشت

چند rule با منطق AND. فیلتر پیچیده‌تر: hook bricks/query/result.

هوک‌های query loop