آموزش تابع get_theme_mod() در وردپرس و کاربرد آن

تابع get_theme_mod() یکی از ابزارهای پایه‌ای در توسعه قالب وردپرس است که برای خواندن مقادیر تنظیمات ذخیره‌شده در Customizer (سفارشی‌ساز) یا تنظیمات تم استفاده می‌شود. این تابع راهی ساده و استاندارد برای واکشی «theme modification»ها فراهم می‌کند. در ادامه به ساختار، نمونه‌های عملی، نکات امنیتی و بهترین روش‌ها می‌پردازیم.

ساختار و پارامترها

امکان بازیابی همه تنظیمات با get_theme_mods() نیز وجود دارد که آرایه‌ای از تمامی theme_modها را برمی‌گرداند.

مثال ساده: خواندن یک مقدار سفارشی برای نمایش لوگو

// در فایل header.php یا هر فایل تم
$logo_url = get_theme_mod( 'mytheme_logo', '' );

if ( $logo_url ) {
    echo '';
} else {
    // نمایش نام سایت یا لوگوی پیش‌فرض
    echo '<h1>' . esc_html( get_bloginfo( 'name' ) ) . '</h1>';
}

در این کد، ابتدا مقدار ذخیره‌شده برای کلید ‘mytheme_logo’ دریافت شده و اگر موجود بود با esc_url خروجی داده می‌شود. esc_attr و esc_html برای جلوگیری از XSS کاربرد دارند.

ثبت تنظیم در Customizer و استفادهٔ get_theme_mod

add_action( 'customize_register', 'mytheme_customize_register' );

function mytheme_customize_register( $wp_customize ) {
    $wp_customize->add_setting( 'mytheme_logo', array(
        'default'           => '',
        'sanitize_callback' => 'esc_url_raw',
        'transport'         => 'refresh',
    ) );

    $wp_customize->add_control( new WP_Customize_Image_Control( $wp_customize, 'mytheme_logo_control', array(
        'label'    => __( 'Logo', 'mytheme' ),
        'section'  => 'title_tagline', // یا بخش دلخواه
        'settings' => 'mytheme_logo',
    ) ) );
}

در این مثال یک setting و یک کنترل تصویری ساخته شده است. مقدار توسط esc_url_raw هنگام ذخیره پاک‌سازی می‌شود. سپس در قالب با get_theme_mod آن مقدار را می‌توان خواند.

استفاده در تولید CSS دینامیک

// چاپ استایل در head یا فایل css پیوست‌شده
$accent = get_theme_mod( 'mytheme_accent_color', '#0073aa' );
echo '<style>:root { --accent-color: ' . esc_attr( $accent ) . '; }</style>';

مثال نشان می‌دهد چگونه می‌توان رنگ‌های تنظیم‌شده را در CSS با متغیرهای CSS قرار داد. به جای چاپ مستقیم می‌توانید از wp_add_inline_style استفاده کنید تا بهتر مدیریت شود.

تفاوت get_theme_mod و get_option

• get_theme_mod برای مقادیری است که به صورت «theme modification» ذخیره می‌شوند و معمولاً توسط Customizer کنترل می‌شوند.
• get_option برای گزینه‌های عمومی دیتابیس وردپرس (در جدول wp_options) است و محدود به تم نیست.
• اگر می‌خواهید تنظیمی را بین تم‌ها مشترک نگه دارید، از گزینه‌ها (option) استفاده کنید؛ برای تنظیمات وابسته به تم از theme_modها بهره ببرید.

نکات امنیتی و بهترین شیوه‌ها

• همیشه هنگام ذخیره در Customizer از sanitize_callback مناسب استفاده کنید (مثلاً esc_url_raw، sanitize_text_field، absint و غیره).
• قبل از خروجی در قالب از توابع escaping مثل esc_url، esc_attr، esc_html و wp_kses_post استفاده کنید.
• به هنگام کار با داده‌های پیچیده (آرایه‌ها یا JSON) از json_encode/json_decode همراه با sanitize و validate استفاده کنید.
• برای مقادیر بولی یا عددی مقدار پیش‌فرض منطقی قرار دهید تا قالب در صورت نبود تنظیم، رفتار قابل پیش‌بینی داشته باشد.

ذخیره و حذف برنامه‌ای (set_theme_mod و remove_theme_mod)

// تنظیم برنامه‌ای یک theme_mod
set_theme_mod( 'mytheme_footer_text', 'تمام حقوق برای سایت محفوظ است.' );

// حذف یک theme_mod
remove_theme_mod( 'mytheme_footer_text' );

set_theme_mod به‌صورت برنامه‌ای مقدار را ذخیره می‌کند و remove_theme_mod آن را پاک می‌کند. این توابع برای اسکریپت‌های فعال‌سازی، ایمپورت یا تنظیمات پیش‌فرض کارآمد هستند.

کاربردهای پیشرفته و نکات حرفه‌ای

• Selective Refresh: هنگام ساخت Customizer، با قرار دادن transport => ‘postMessage’ و نوشتن JS لازم می‌توانید پیش‌نمایش بی‌درنگ تغییرات (بدون رفرش کامل) فراهم کنید. get_theme_mod همچنان منبع دادهٔ نمایش اصلی است.
• تنظیمات پیچیده: برای ذخیره آرایه‌ها از set_theme_mod/get_theme_mod استفاده می‌شود، اما توجه کنید sanitize_callback باید دادهٔ آرایه را هم پاک‌سازی کند.
• واحد تست: هنگام نوشتن تست‌های واحد (unit tests) می‌توانید با set_theme_mod مقدار را ست کنید و سپس get_theme_mod را تست کنید تا از سازگاری اطمینان حاصل شود.
• سازگاری با child theme: theme_modها به تم فعال مرتبط هستند؛ اگر تم رو تغییر دهید ممکن است theme_modهای دیگری در دسترس نباشند. برای مقادیر مشترک بین parent/child نیاز به هماهنگی دارید.

نمونهٔ پیشرفته: تنظیمات آرایه‌ای و sanitize

function mytheme_sanitize_social_links( $input ) {
    $output = array();
    if ( ! is_array( $input ) ) {
        return $output;
    }
    foreach ( $input as $network => $url ) {
        $network = sanitize_key( $network );
        $output[ $network ] = esc_url_raw( $url );
    }
    return $output;
}

$wp_customize->add_setting( 'mytheme_social', array(
    'default'           => array(),
    'sanitize_callback' => 'mytheme_sanitize_social_links',
) );

در این قطعه، یک آرایه از لینک‌های شبکه‌های اجتماعی از Customizer ذخیره می‌شود و هنگام ذخیره با تابعی اختصاصی پاک‌سازی می‌گردد تا از ورود URL نامعتبر جلوگیری شود. سپس get_theme_mod(‘mytheme_social’) آرایهٔ پاک‌شده را بازخواهد گرداند.

جمع‌بندی و توصیه‌های عملی

• get_theme_mod تابع اصلی برای خواندن تنظیمات مرتبط با تم است و با Customizer یکپارچه می‌شود.
• همیشه sanitize در ذخیره و escape در خروجی را رعایت کنید تا امنیت و سازگاری حفظ شود.
• برای مقادیر پیچیده از sanitize_callback مناسب استفاده و برای نمایش CSS از روش‌های استاندارد مانند wp_add_inline_style بهره ببرید.
• تست و مستندسازی تنظیمات (نام‌های کلید، نوع داده و پیش‌فرض) به نگهداری طولانی‌مدت پروژه کمک زیادی می‌کند.

با آشنایی کامل با get_theme_mod، می‌توانید یک تجربه سفارشی‌سازی قابل‌اطمینان، امن و قابل توسعه برای کاربران قالب خود فراهم کنید.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال