داده پویا (Dynamic Data)

از داده پویا برای نمایش انواع اطلاعات از پایگاه داده وردپرس در Bricks استفاده کنید.

برای مثال: تصویر شاخص، عنوان پست، تاریخ پست، نام نویسنده، دسته‌بندی‌ها، تگ‌ها، عنوان سایت، فیلدهای دلخواه و غیره.

بیشترین کاربرد داده پویا هنگام ساخت قالب‌ها در Bricks است؛ مانند قالب پست وبلاگ و قالب‌های نوع پست سفارشی (مثلاً صفحه ملک تکی).

نحوه درج داده پویا

انتخابگر داده پویا برای متن، هنگامی‌که { را روی بوم تایپ کنید ظاهر می‌شود. همچنین می‌توانید روی آیکون «صاعقه» در پنل تنظیمات کلیک کنید تا آن را باز کنید:

YouTube ↗

داده پویا برای تنظیمات غیرمتنی مانند تصاویر، ویدیوها و غیره از منوی کشویی «انتخاب داده پویا» در تنظیمات پنل در دسترس است.

در زیر یک گالری Advanced Custom Fields (با نام «Gallery») را می‌بینید که درون المان گالری تصاویر Bricks رندر شده:

تمام تگ‌های داده پویا در همه المان‌هایی که داده پویا را پشتیبانی می‌کنند در دسترس هستند. این یعنی می‌توانید یک فیلد گالری (مثلاً نوع فیلد گالری ACF) را درون یک المان متنی قرار دهید و به‌صورت مجموعه‌ای از تگ‌های img رندر می‌شود (با استفاده از فیلتر :image):

یکپارچه‌سازی با فیلدهای سفارشی

می‌توانید بسیار بیشتر از داده‌های استاندارد وردپرس را رندر کنید. Bricks از محبوب‌ترین افزونه‌های فیلد سفارشی پشتیبانی می‌کند:

• Advanced Custom Fields
• Meta Box
• Crocoblock (JetEngine) (از WooCommerce Product Data / Variation Meta Box پشتیبانی نمی‌کند)
• Pods
• CMB2
• Toolset

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

Advanced Custom Fields

Bricks با تمام فیلدهای ACF و ACF Pro از جمله Flexible Content و Nested Groups یکپارچه می‌شود.

فیلدها در منوی کشویی داده پویا درون سازنده Bricks فهرست می‌شوند تا بتوانید هنگام ساخت صفحات و قالب‌ها از آن‌ها استفاده کنید.

نوع فیلدهای Relationship (شامل پیاده‌سازی دوطرفه) و Repeater نیز درون سازنده Query Loop در دسترس هستند، بنابراین می‌توانید خروجی این فیلدها را حلقه بزنید و زیرفیلدها را به‌عنوان داده پویا رندر کنید.

نوع فیلد ACF «True / False» برای بررسی شرطی در شرایط المان عالی است. به‌طور پیش‌فرض برچسب محلی‌سازی‌شده «True / False» بازگردانده می‌شود. هنگام استفاده در شرایط المان، مطمئن شوید فیلتر :value را اعمال می‌کنید. برای بررسی false می‌توانید با == 0 مقایسه کنید، یا برای true از == 1 استفاده کنید.

داده پویای زیر می‌تواند با شرایط المان به‌طور مؤثر استفاده شود:

{acf_get_row_layout:raw} - نام لایوت Flexible در ACF را برمی‌گرداند

Meta Box

Bricks با Post Types، Taxonomies، Custom Fields و Relationships در Meta Box سازگار است. درمورد Custom Fields، Bricks فیلدها را در سازنده در منوی کشویی داده پویا فهرست می‌کند. بر اساس محتوای فیلد، این تگ‌ها در فرانت‌اند به‌درستی رندر می‌شوند.

فیلد Group (وقتی cloneable است) و Relationships نیز درون سازنده Query Loop در دسترس خواهند بود. می‌توانید از طریق این مقادیر حلقه بزنید و زیرفیلدها را به‌عنوان داده پویا رندر کنید.

همچنین می‌توان فیلدهای Group تودرتوی غیر-cloneable را در Bricks Query Loop ساخت.

Crocoblock JetEngine

Bricks با Post Types، Meta Boxes (فیلدهای سفارشی)، Taxonomies، Relations و صفحات Options در Crocoblock JetEngine سازگار است.

Custom Content Types (CCT) از آوریل ۲۰۲۴ توسط افزونه JetEngine پشتیبانی می‌شود، نه خود Bricks. برای هرگونه سؤال درباره CCT، مستقیماً با پشتیبانی JetEngine تماس بگیرید.

یکپارچه‌سازی Bricks با JetEngine فیلدهای سفارشی را به‌عنوان داده پویا درون سازنده در دسترس قرار می‌دهد.

Bricks همچنین با Relations و Repeater های JetEngine برای تغذیه Query Loop سازنده یکپارچه می‌شود.

داده‌های استاندارد وردپرس

به‌طور پیش‌فرض می‌توانید از تگ‌های داده پویای زیر استفاده کنید.

فیلدهای پست

فیلدهای زیر به پست‌ها یا انواع پست سفارشی مرتبط هستند:

{post_title} - عنوان پست را برمی‌گرداند

{post_id} - شناسه پست را برمی‌گرداند

{post_url} - لینک پست را برمی‌گرداند

{post_slug} - اسلاگ پست را برمی‌گرداند

{post_type} - نوع پست را برمی‌گرداند (از نسخه ۱.۱۲)

{post_date} - تاریخ انتشار پست را برمی‌گرداند

{post_modified} - تاریخ آخرین ویرایش پست را برمی‌گرداند

{post_time} - زمان انتشار پست را برمی‌گرداند

{post_comments_count} - تعداد نظرات را برمی‌گرداند

{post_content} - محتوای پست (ویرایشگر Gutenberg) را برمی‌گرداند

{post_excerpt} - خلاصه پست را برمی‌گرداند

{read_more} - یک تگ لینک به پست با برچسب «Read more» رندر می‌کند

{featured_image} - یک تگ تصویر با تصویر شاخص رندر می‌کند

این فیلدها از فیلترهای داده پویا زیر پشتیبانی می‌کنند:

{post_title:link} - عنوان پست را به‌صورت لینک به پست رندر می‌کند

{post_title:link:3} - مانند قبلی اما عنوان به ۳ کلمه محدود می‌شود

{post_title:link:newTab} - عنوان پست را در تب جدید باز می‌کند

{post_date:human_time_diff} - اختلاف زمانی را به‌صورت قابل‌خواندن نمایش می‌دهد مانند «۱ ساعت»، «۵ دقیقه»، «۲ روز»

{post_excerpt:55} - خلاصه پست را به ۵۵ کلمه محدود می‌کند

{post_excerpt:format:10} - فرمت HTML را حفظ کرده و خلاصه پست را به ۱۰ کلمه محدود می‌کند

{featured_image:medium_large} - تگ تصویر شاخص با اندازه medium_large رندر می‌کند (پیش‌فرض thumbnail)

{featured_image:large:link} - تگ تصویر شاخص اندازه large که درون تگ لینک به پست پیچیده شده

رده‌بندی‌ها

تگ‌های داده پویای زیر فهرستی از اصطلاح‌های رده‌بندی تخصیص‌یافته به پست را رندر می‌کنند. هر اصطلاح با لینک به آرشیو آن پوشیده می‌شود:

{post_terms_category} - دسته‌بندی‌ها

{post_terms_post_tag} - تگ‌ها

{post_terms_my_taxonomy_slug} - «my_taxonomy_slug» را با اسلاگ واقعی رده‌بندی موردنظر جایگزین کنید

{post_terms_category:plain} - لینک‌ها را با فیلتر :plain حذف می‌کند

اصطلاح‌های رده‌بندی

تگ‌های داده پویای زیر اطلاعات مرتبط با اصطلاح‌های رده‌بندی را رندر می‌کنند:

{term_id} - شناسه اصطلاح

{term_name} - نام اصطلاح

{term_slug} - اسلاگ اصطلاح

{term_count} - تعداد پست‌های اصطلاح

{term_taxonomy_slug} - اسلاگ رده‌بندی اصطلاح (از نسخه ۱.۱۱)

{term_url} - لینک آرشیو اصطلاح

{term_description} - توضیحات اصطلاح

{term_meta:my_term_meta_key} - مقدار متا «my_term_meta_key» را رندر می‌کند

فیلدهای نویسنده

{author_id} - شناسه نویسنده پست

{author_name} - نام نویسنده پست

{author_bio} - بیوگرافی نویسنده پست

{author_email} - ایمیل نویسنده پست

{author_website} - وب‌سایت نویسنده پست

{author_archive_url} - آدرس آرشیو نویسنده

{author_avatar} - آواتار نویسنده به‌صورت تگ تصویر (متن) یا آدرس تصویر (لینک)

{author_meta:meta_key} - مقدار متای مشخص‌شده نویسنده. برای مثال author_meta:first_name نام کوچک نویسنده را برمی‌گرداند.

این فیلدها از فیلترهای داده پویا زیر پشتیبانی می‌کنند:

{author_bio:20} - بیوگرافی نویسنده محدود به ۲۰ کلمه

{author_name:link} - نام نویسنده به‌صورت لینک به صفحه پروفایل

{author_email:link} - ایمیل نویسنده به‌صورت لینک

{author_website:link} - وب‌سایت نویسنده به‌صورت لینک

{author_avatar:200} - آواتار نویسنده محدود به عرض/ارتفاع ۲۰۰ پیکسل

فیلدهای Query

{query_loop_index:raw} - ایندکس آیتم فعلی حلقه را از ۰ برمی‌گرداند. از آرگومان @start-at برای شروع از عدد دیگر استفاده کنید. مثال: {query_loop_index:raw @start-at:1} ایندکس را از ۱ شروع می‌کند. آرگومان @pad padding با صفر را تعریف می‌کند.

{query_results_count:raw} – تعداد نتایج کوئری را درون یا بیرون حلقه برمی‌گرداند. برای استفاده خارج از حلقه باید شناسه Query Loop را به‌صورت فیلتر پاس دهید: {query_results_count:quer34:raw}

فیلدهای سایت و آرشیو

{site_title} - عنوان سایت از وردپرس > تنظیمات > عمومی

{site_tagline} - توضیح سایت از وردپرس > تنظیمات > عمومی

{site_url} - آدرس سایت از وردپرس > تنظیمات > عمومی

{site_login} - آدرس ورود سایت. با تعیین شناسه پست به‌عنوان فیلتر می‌توانید آدرس ریدایرکت بعد از ورود را تنظیم کنید: {site_login:3}

{site_logout} - آدرس خروج سایت. با تعیین شناسه پست به‌عنوان فیلتر می‌توانید آدرس ریدایرکت بعد از خروج را تنظیم کنید: {site_logout:3}

{archive_title} - عنوان آرشیو

{archive_title:context} - عنوان آرشیو با زمینه

{archive_description} - توضیحات آرشیو (نویسنده، نوع پست یا اصطلاح)

می‌توانید داده پویا را از پارامترهای URL دریافت کنید:

{url_parameter:my_key} - مقدار پارامتر my_key در URL را برمی‌گرداند (https://mydomain.pt/?my_key=value)

فیلدهای پروفایل کاربر

{wp_user_id} - شناسه کاربر فعلی

{wp_user_login} - نام کاربری کاربر فعلی

{wp_user_email} - ایمیل کاربر فعلی

{wp_user_url} - وب‌سایت کاربر فعلی

{wp_user_author_url} - آدرس نویسنده کاربر فعلی

{wp_user_role} - نقش اصلی کاربر فعلی. از :value برای اسلاگ نقش استفاده کنید. (از نسخه ۱.۱۲)

{wp_user_registered_date} - تاریخ ثبت‌نام کاربر فعلی (از نسخه ۱.۱۲)

{wp_user_nicename} - نام مستعار کاربر فعلی

{wp_user_description} - بیوگرافی کاربر فعلی

{wp_user_first_name} - نام کاربر فعلی

{wp_user_last_name} - نام‌خانوادگی کاربر فعلی

{wp_user_display_name} - نام نمایشی کاربر فعلی

{wp_user_picture} - آواتار کاربر فعلی به‌صورت تگ تصویر یا آدرس

{wp_user_meta:my_user_meta_key} - مقدار متا «my_user_meta_key» کاربر فعلی

فیلدهای سفارشی بومی‌وردپرس

برای رندر فیلدهای سفارشی، باید پیشوند cf_ اضافه کنید.

اگر نام فیلد سفارشی شما phone_number است، از {cf_phone_number} برای نمایش آن در فرانت‌اند استفاده کنید.

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

فیلدهای تاریخ جاری

{current_date} - تاریخ جاری (UTC) با فرمت تعریف‌شده در وردپرس > تنظیمات > عمومی > فرمت تاریخ

{current_wp_date} - تاریخ جاری (منطقه زمانی وردپرس) با فرمت تعریف‌شده

می‌توانید فرمت تاریخ متفاوتی با فرمت تاریخ PHP تعیین کنید:

{current_date:Y} ، {current_date:Y-m-d} ، {current_date:g:i A} ، {current_date:timestamp}

تبدیل فرمت تاریخ

Bricks 2.2 یک تگ داده پویای جدید {format_date:raw} معرفی کرد که به شما امکان می‌دهد بدون نوشتن PHP یک رشته تاریخ را از یک فرمت به فرمت دیگر تبدیل کنید:

{format_date:raw @date:'your-date-value' @from:'input-format' @to:'output-format'}

پارامترها: - @date: رشته تاریخ اصلی برای تبدیل - @from: فرمت ورودی (مثلاً Y-m-d) - @to: فرمت خروجی مطلوب (مثلاً d M Y)

مثال ۱: {format_date:raw @date:'2025-01-10' @from:'Y-m-d' @to:'d M Y'} → خروجی: 10 Jan 2025

مثال ۲: تبدیل پاسخ API: {format_date:raw @date:'{query_api:raw @key:'registered'}' @from:'Y-m-d\TH:i:s.v\Z' @to:'Y m d (l)'}

مثال ۳: تبدیل به timestamp برای مقایسه تاریخ‌ها: {format_date:raw @date:'{cf_my_date:raw}' @from:'Y/m/d' @to:'timestamp'}

پیشرفته: echo

نکته مهم

از نسخه Bricks 1.9.7، باید هر نام تابعی که می‌خواهید از طریق تگ echo فراخوانی شود را با فیلتر bricks/code/echo_function_names صریحاً مجاز کنید.

Bricks 1.4 تگ echo را برای رندر خروجی هر تابع PHP معرفی کرد:

{echo:my_custom_function} - خروجی تابع PHP my_custom_function() را نمایش می‌دهد

می‌توانید آرگومان‌ها را با یا بدون تک‌نقل‌قول پاس دهید:

{echo:get_the_date('Y-m-d', '55')} - تاریخ پست شماره ۵۵ با فرمت Y-m-d

قانون فرمت‌بندی آرگومان: همه آرگومان‌ها باید در تک‌نقل‌قول باشند (از نسخه ۱.۹.۳):

{echo:my_function('static value')} ، {echo:my_function('{post_title}')}

نکته

تگ echo از دوتایی‌قول‌قول پشتیبانی نمی‌کند و تابع PHP سفارشی باید مقدار را return کند نه echo.

پیشرفته: do_action

تگ do_action به توسعه‌دهندگان و سایر افزونه‌ها اجازه می‌دهد با طراحی قالب‌های شما یکپارچه شوند. می‌توانید action hook هایی مانند {do_action:my_custom_hook} را در هرجایی قرار دهید.

مثلاً می‌توانید {do_action:woocommerce_after_single_product} را در قالب محصول تکی WooCommerce خود درج کنید تا افزونه‌های دیگر بتوانند به آن hook بزنند.

نکته

تگ do_action از پاس کردن آرگومان به action پشتیبانی نمی‌کند. do_action فقط در فرانت‌اند سایت اجرا می‌شود، نه درون سازنده.

WooCommerce

وقتی افزونه WooCommerce نصب و فعال باشد، به مجموعه‌ای از تگ‌های داده پویا مرتبط با محصولات و سفارشات دسترسی خواهید داشت. برای جزئیات به مقاله WooCommerce builder مراجعه کنید.

فیلترها

می‌توانید خروجی تگ‌های داده پویا را با فیلترهای زیر تغییر دهید:

• :*عدد* - محتوا را به تعداد کلمه مشخص محدود می‌کند (مثلاً {post_excerpt:10})
• :context یا :prefix - زمینه به عنوان آرشیو اضافه می‌کند
• :image - فیلد را به‌صورت تگ تصویر خروجی می‌دهد
• :link - فیلد را به‌صورت تگ لینک خروجی می‌دهد
• :newTab - لینک را در تب جدید باز می‌کند
• :tel - آدرس لینک را به‌صورت شماره تلفن فرمت می‌کند
• :value - مقدار را به‌جای برچسب خروجی می‌دهد (مفید برای فیلدهای choice در ACF/MetaBox)
• :raw - پردازش تگ داده پویا را رد می‌کند
• :url - آدرس URL از شناسه پست برمی‌گرداند
• :format - فرمت HTML را حفظ می‌کند
• :plain - تگ‌های HTML را با wp_strip_all_tags حذف می‌کند
• :array_value|{KEY} - مقدار یک کلید آرایه خاص را در نتیجه تگ داده پویا برمی‌گرداند
• :timestamp - داده تاریخ/زمان را به مقدار timestamp تبدیل می‌کند
• :slug و :term_id - برای خروجی اسلاگ یا شناسه اصطلاح به‌جای نام اصطلاح (از نسخه ۲.۰)

مثال‌های فیلتر :array_value:

{acf_place_map:array_value|lat} - مقدار lat از فیلد google map در ACF

{acf_ext_link:array_value|title} - مقدار title از فیلد link در ACF

{echo:custom_function:array_value|hello} - مقدار hello از تابع PHP custom_function()

آرگومان‌های key-value

این قابلیت انعطاف بیشتری در نمایش محتوای پویا می‌دهد. سینتکس کلی:

{dynamic_data_tag @key:value}

آرگومان‌های موجود:

@fallback – متن جایگزین اگر تگ داده پویا داده‌ای برنگرداند (از نسخه ۱.۱۰):

• مثال: {acf_text_field @fallback:'این متن جایگزین است!'} - اگر acf_text_field خالی باشد، این متن نمایش داده می‌شود.

@fallback-image – برای تگ‌های داده پویای تصویر. یک شناسه attachment یا آدرس URL می‌پذیرد:

• مثال: {acf_image @fallback-image:554} یا {acf_image @fallback-image:'https://example.com/placeholder.png'}

@sanitize - کنترل روش sanitize اعمال‌شده روی تمام تگ‌های داده پویا در زمینه «متن» (از نسخه ۱.۱۱.۱):

• {acf_my_wysiwyg @sanitize:false} – sanitize را غیرفعال می‌کند (با احتیاط استفاده کنید)
• {acf_my_wysiwyg @sanitize:sanitize_email} – sanitize_email را اعمال می‌کند

هوک‌های مرتبط با داده پویا

bricks/dynamic_data/exclude_tags - فهرستی از تگ‌ها را از منطق داده پویا Bricks مستثنی می‌کند

bricks/dynamic_data/replace_nonexistent_tags - رفتار پیش‌فرض Bricks در جایگزینی تگ‌های غیرموجود با رشته خالی را غیرفعال می‌کند