راهنمای جامع افزودن فیلد سفارشی با ACF در وردپرس (از ساخت تا نمایش در پوسته)

فیلدهای پیش‌فرض وردپرس مانند عنوان، متن‌اصلی و تصویر شاخص، جوابگوی ساخت وب‌سایت‌های مدرن مانند املاکی، فروشگاهی، یا معرفی کتاب نیستند. افزونه Advanced Custom Fields (ACF) دقیقاً برای حل این محدودیت طراحی شده است تا بتوانید اطلاعات ساختاریافته را به فرم ساخت نوشته اضافه کنید و مدیریت اطلاعات سایت را کاملاً استاندارد و منظم پیش ببرید.

فیلد سفارشی چیست و چرا افزونه ACF بهترین انتخاب است؟

پاسخ کوتاه: فیلد سفارشی (Custom Field) داده‌ای اضافه است که به پست‌ها، برگاه‌ها یا پست‌تایپ‌های وردپرس متصل می‌شود و ACF ابزاری گرافیکی برای مدیریت بی‌دردسر این داده‌ها در پایگاه‌داده بدون نیاز به کدنویسی پیچیده فراهم می‌کند.

وردپرس به‌طور نیتیو سیستم متادیتا (Post Meta) دارد، اما رابط کاربری آن بسیار ساده و ابتدایی است. افزونه ACF رابط کاربری بسیار پیشرفته‌ای ارائه می‌دهد که بیش از ۳۰ نوع فیلد مختلف (مانند متنی، آپلود فایل، نقشه گوگل، انتخاب‌گر رنگ، و ارتباط بین نوشته‌ها) را به پیشخوان وردپرس می‌افزاید.

آموزش گام‌به‌گام ساخت اولین فیلد سفارشی در ACF

برای قرار دادن فیلد جدید در پیشخوان نوشته‌ها، روند ساخت گروه فیلد را طبق مراحل زیر دنبال کنید:

1. نصب افزونه: از بخش افزونه‌ها > افزودن، عبارت Advanced Custom Fields را جستجو و فعال کنید.
2. ایجاد گروه فیلد جدید: به منوی «ACF» یا «فیلدهای سفارشی» رفته و روی گزینه «افزودن جدید» (Add New) کلیک کنید.
3. تنظیم عنوان گروه: یک عنوان مشخص (مثلاً «اطلاعات محصول») برای این دسته از فیلدها انتخاب کنید.
4. افزودن فیلد: روی دکمه «افزودن فیلد» کلیک کنید. در این بخش سه مقدار مهم را باید تنظیم کنید:
   • برچسب فیلد (Field Label): نامی که کاربر در پیشخوان می‌بیند (مثلاً: قیمت محصول).
   • نام فیلد (Field Name): شناسه یکتای لاتین برای استفاده در کدهای قالب (مثلاً: product_price).
   • نوع فیلد (Field Type): انتخاب فرمت داده (متن، عدد، تصویر، ایمیل و…).
5. تعیین قوانین مکان (Location Rules): مشخص کنید این فیلد در چه بخش‌هایی ظاهر شود (مثلاً: اگر نوع نوشته برابر با «محصول» بود).
6. انتشار: تغییرات را ذخیره کنید. حالا فیلد در صفحه ویرایش نوشته مربوطه نمایش داده می‌شود.

نحوه فراخوانی و نمایش فیلدها در کدهای قالب وردپرس

پاسخ کوتاه: برای نمایش مقدار فیلد سفارشی در فایل‌های قالب، ساده‌ترین روش استفاده از تابع the_field('field_name'); برای چاپ مستقیم و get_field('field_name'); برای دریافت مقدار در متغیر است.

اگر قصد دارید اطلاعات ذخیره‌شده را در پوسته وب‌سایت خود نمایش دهید، باید فایل مربوطه در پوسته (مانند single.php یا page.php) را ویرایش کنید. در ادامه نمونه‌های پرکاربرد کدنویسی با ACF آورده شده است. اگر تمایل دارید دسترسی سریع به کدهای آماده داشته باشید، بررسی بخش تکه‌کدهای وردپرس نیز به شما کمک خواهد کرد.

۱. نمایش فیلد متنی ساده

<?php 
$price = get_field('product_price');
if ( $price ) : ?>
    <div class="product-price">
        <span>قیمت: </span><?php echo esc_html($price); ?> تومان
    </div>
<?php endif; ?>

۲. نمایش فیلد تصویر (Return Value روی Array)

وقتی تنظمات بازگشتی فیلد تصویر را روی “Image Array” قرار می‌دهید، ساختار تصویر با ویژگی‌های استاندارد بارگذاری می‌شود:

<?php 
$image = get_field('custom_image');
if ( !empty( $image ) ) : ?>
    <img src="<?php echo esc_url($image['url']); ?>" alt="<?php echo esc_attr($image['alt']); ?>" />
<?php endif; ?>

جدول مقایسه پرکاربردترین انواع فیلدهای ACF

برای اینکه بدانید کدام نوع فیلد برای سناریوی کاری شما مناسب‌تر است، به جدول زیر توجه کنید:

۳ نکته تخصصی برای بهینه‌سازی سرعت و امنیت ACF

بسیاری از توسعه‌دهندگان پس از نصب ACF با مشکل کندی وب‌سایت یا بروز چالش‌های امنیتی مواجه می‌شوند. رعایت این سه نکته طلایی، کیفیت پروژه شما را در سطح حرفه‌ای تضمین می‌کند:

• ۱. فعال‌سازی ویژگی Local JSON:
  به طور پیش‌فرض تنظیمات ACF در دیتابیس ذخیره می‌شود. با ایجاد یک پوشه به نام acf-json در پوشه پوسته فعال خود، افزونه تمامی گروه‌های فیلد را در قالب فایل‌های JSON ذخیره می‌کند. این کار علاوه بر انتقال آسان تنظیمات بین محیط لوکال‌هاست و سرور اصلی، تعداد کوئری‌های دیتابیس (Database Queries) را در هر بارگذاری به شدت کاهش می‌دهد.
• ۲. پاک‌سازی و ایمن‌سازی خروجی‌ها (Output Escaping):
  هرگز مقدار خروجی تابع را مستقیم بدون پاک‌سازی چاپ نکنید. همواره از توابع ایمن‌سازی وردپرس استفاده کنید. برای داده‌های متنی ساده از esc_html()، برای آدرس‌ها از esc_url() و برای متون حاوی HTML از wp_kses_post() استفاده کنید. برای مطالعه کدهای استاندارد بدین منظور، می‌توانید از بخش مجموعه کدهای HTML استفاده کنید.
• ۳. تفاوت کلیدی get_field و get_post_meta:
  تابع get_field() داده‌ها را پردازش کرده و متناسب با نوع فیلد، آرایه یا شیء می‌سازد. اگر در یک حلقه (Loop) با تعداد بالا فقط به متن ساده نیاز دارید، استفاده از تابع نیتیو وردپرس یعنی get_post_meta($post_id, 'field_name', true) سریع‌تر عمل کرده و حافظه RAM کمتری روی سرور مصرف می‌کند.

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

راهنمای عیب‌یابی سریع مشکلات ACF