آموزش کامل کار با Settings API در ووکامرس

اگر شما یک توسعه‌دهنده افزونه‌های جانبی برای ووکامرس هستید، احتمالاً می‌دانید که تجربه کاربری (UX) در پنل مدیریت چقدر اهمیت دارد. به جای ساخت صفحات تنظیمات پراکنده، بهترین روش استفاده از Settings API در ووکامرس است. این ابزار قدرتمند به شما اجازه می‌دهد تنظیمات افزونه خود را دقیقاً در قلب پیکربندی ووکامرس جای دهید. در این مقاله، گام‌به‌گام یاد می‌گیریم چگونه یک تب اختصاصی بسازیم و فیلدها را مدیریت کنیم. 🚀

چرا باید از Settings API ووکامرس استفاده کنیم؟

زمانی که برای وردپرس کدنویسی می‌کنیم، معمولاً از Settings API پیش‌فرض وردپرس استفاده می‌شود. اما وقتی هدف ما توسعه یک پلاگین مکمل برای ووکامرس است، ادغام تنظیمات در مسیر «ووکامرس > پیکربندی» حرفه‌ای‌تر به نظر می‌رسد.

مزایای استفاده از Settings API ووکامرس

✅ یکپارچگی بصری: تنظیمات شما دقیقاً مشابه استایل پیش‌فرض ووکامرس خواهد بود.

✅ امنیت بالا: مدیریت ذخیره‌سازی و اعتبارسنجی داده‌ها توسط هسته ووکامرس انجام می‌شود.

✅ تجربه کاربری بهتر: کاربر مجبور نیست برای تنظیم هر بخش به منوهای مختلف مراجعه کند.

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

گام اول: ساخت تب جدید در پیکربندی ووکامرس 🛠️

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

php

function rngwc_add_settings_tab($setting_tabs) {
    // شناسه تب و عنوان آن را تعریف می‌کنیم
    $setting_tabs['aqua_config'] = __("تنظیمات آکوا", "text-domain");
    return $setting_tabs;
}
add_action("woocommerce_settings_tabs_array", "rngwc_add_settings_tab", 100);

نکته حرفه‌ای: عدد ۱۰۰ در اولویت (Priority)، باعث می‌شود تب شما در آخرین جایگاه قرار بگیرد.

گام دوم: تعریف فیلدهای تنظیمات (ساختار آرایه) 📝

پیش از نمایش فیلدها، باید آن‌ها را در یک تابع مجزا تعریف کنیم. این کار باعث می‌شود در مراحل نمایش و ذخیره‌سازی، از تکرار کد جلوگیری شود.

کاربردهای انواع فیلدها

در Settings API ووکامرس، فیلدها انواع مختلفی دارند که مهم‌ترین آن‌ها عبارتند از:

🔹 title: برای ایجاد یک عنوان بخش جدید.
🔹 text: فیلد متنی ساده برای دریافت رشته یا عدد.
🔹 select: منوی کشویی برای انتخاب گزینه‌ها.
🔹 single_select_page: انتخابی خاص برای لیست کردن برگه های وردپرس.
🔹 sectionend: برای بستن یک بخش تنظیمات (الزامی).

php

function rngwc_aqua_config_settings() {
    $options = array(
        'section_title' => array(
            'name' => __("تنظیمات عمومی افزونه", "text-domain"),
            'type' => "title",
            'id'   => 'aqua_config_title'
        ),
        'payments_guid_page' => array(
            'name'     =>  __("برگه راهنمای پرداخت", "text-domain"),
            'type'     => 'single_select_page',
            'id'       => 'rngwc_payment_guid_page',
            'class'    => 'wc-enhanced-select-nostd',
            'args'     => array('show_option_none' => 'انتخاب برگه')
        ),
        'section_end' => array('type' => 'sectionend', 'id' => 'aqua_config_end')
    );
    return apply_filters('wc_aqua_config_settings', $options);
}

گام سوم: نمایش فیلدها و ذخیره‌سازی داده‌ها 💾

حالا که تب و فیلدها را تعریف کردیم، باید آن‌ها را به ووکامرس متصل کنیم تا در خروجی نمایش داده شوند و هنگام زدن دکمه ذخیره، مقادیر در دیتابیس ثبت شوند.

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

از اکشن woocommerce_settings_tabs_{tab_id} استفاده می‌کنیم:

php

function rngwc_populate_aqua_config() {
    woocommerce_admin_fields(rngwc_aqua_config_settings());
}
add_action("woocommerce_settings_tabs_aqua_config", "rngwc_populate_aqua_config");

۲. ذخیره‌سازی مقادیر

برای ذخیره خودکار، از اکشن woocommerce_update_options_{tab_id} استفاده می‌کنیم:

php

function rngwc_update_aqua_config() {
    woocommerce_update_options(rngwc_aqua_config_settings());
}
add_action("woocommerce_update_options_aqua_config", "rngwc_update_aqua_config");

نحوه استفاده از مقادیر ذخیره شده 🔍

پس از اینکه کاربر تنظیمات را ذخیره کرد، شما می‌توانید در هر کجای قالب یا افزونه خود با استفاده از تابع استاندارد وردپرس یعنی get_option به این داده‌ها دسترسی داشته باشید:

php

$page_id = get_option('rngwc_payment_guid_page');
echo "آیدی برگه انتخاب شده: " . $page_id;

ثبت‌نام در پنل توسعه‌دهندگان 💡

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

مراحل ثبت‌نام:

🔗 به وب‌سایت p.api.ir مراجعه کنید.
👤 اطلاعات هویتی خود را وارد نمایید.
✅ حساب خود را تایید کرده و از امکانات API بهره‌مند شوید.

استفاده از Settings API در ووکامرس نه تنها کدنویسی شما را استاندارد می‌کند، بلکه باعث می‌شود کاربران افزونه شما حس راحتی بیشتری داشته باشند. در این مقاله آموختیم که چگونه با ۴ مرحله ساده (ساخت تب، تعریف فیلد، نمایش و ذخیره) یک پنل حرفه‌ای بسازیم. 👨‍💻

شما از چه روشی برای ساخت تنظیمات افزونه استفاده می‌کنید؟ نظرات و سوالات خود را در بخش دیدگاه‌ها با ما در میان بگذارید تا در سریع‌ترین زمان پاسخگوی شما باشیم. 👇