چند سال پیش، یک قالب اختصاصی برای یک شرکت ساختمانی تحویل دادم. سه ماه بعد، مشتری زنگ زد که «رنگ دکمه‌ها را می‌خواهیم عوض کنیم، نمی‌توانیم». رفتم سراغ کد و دیدم رنگ دکمه‌ها به‌صورت هاردکد در فایل style.css نوشته شده. هر بار مشتری می‌خواست تغییری بدهد، باید من فایل را ویرایش می‌کردم و آپلود می‌کردم. آن روز تصمیم گرفتم که در هیچ پروژه‌ای رنگ، فونت، لوگو و تنظیمات ظاهری را هاردکد نکنم. از آن پروژه به بعد، هر قالب اختصاصی که می‌سازم، با یک لایه تنظیمات مبتنی بر توابع استاندارد وردپرس همراه است — تا مشتری بتواند بدون دست‌زدن به کد، ظاهر سایت را مدیریت کند. این مقاله، همان نقشه‌ای است که در پروژه‌های واقعی برای تنظیمات قالب به کار می‌برم.

اگر با مفاهیم پایه آشنا نیستید، وردپرس چیست و چگونه شروع کنیم، نحوه استفاده از توابع وردپرس در پروژه‌ها و قالب وردپرس چیست پیش‌نیاز این مقاله هستند. مکمل این مقاله Customizer وردپرس، کار با Options API و توابع گزینه‌های سایت است.

چرا تنظیمات قالب اهمیت دارد؟

قالب حرفه‌ای، سه لایه تنظیمات دارد که در سطوح مختلف انعطاف‌پذیری را فراهم می‌کنند:

  • تنظیمات سراسری سایت: رنگ‌بندی، فونت، لوگو، چیدمان هدر و فوتر — که با Customizer مدیریت می‌شوند.
  • پشتیبانی از قابلیت‌ها: فعال/غیرفعال کردن قابلیت‌های قالب مثل تصویر شاخص، اندازه‌های تصویر، فرمت‌های نوشته — که با add_theme_support اعلام می‌شوند.
  • تنظیمات ساختاری: پالت رنگ، تایپوگرافی، و تنظیمات ویرایشگر بلوک — که با theme.json تعریف می‌شوند.

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

قالبی که تنظیماتش در دسترس مشتری باشد، عمرش دو برابر قالبی است که همه‌چیزش هاردکد است — چون هر تغییر کوچک، یک پروژه ویرایش کد نیست.

get_theme_mod و set_theme_mod: هسته تنظیمات قالب

پایه‌ای‌ترین توابع تنظیمات قالب، get_theme_mod و set_theme_mod هستند. این توابع، مقادیر تنظیمات را در جدول wp_options با کلیدهای پیشوندی theme_mods_{themename} ذخیره می‌کنند:

// خواندن یک تنظیم
$primary_color = get_theme_mod( "primary_color", "#0b8a5c" );

// ذخیره یک تنظیم (معمولاً از طریق Customizer انجام می‌شود)
set_theme_mod( "primary_color", "#ff5722" );

// حذف یک تنظیم
remove_theme_mod( "primary_color" );

نکته حیاتی: پارامتر دوم get_theme_mod، مقدار پیش‌فرض است. اگر آن را ندهید و تنظیم وجود نداشته باشد، false برمی‌گردد و در نمایش، مشکل ایجاد می‌کند. یک قاعده در پروژه‌های خودم: همیشه مقدار پیش‌فرض را در یک ثابت مرکزی نگه می‌دارم:

class My_Theme_Defaults {
    const PRIMARY_COLOR = "#0b8a5c";
    const TEXT_COLOR    = "#222222";
    const FONT_FAMILY   = "Vazirmatn, sans-serif";
}

$color = get_theme_mod( "primary_color", My_Theme_Defaults::PRIMARY_COLOR );

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

تفاوت get_theme_mod و get_option

گاهی این سؤال پیش می‌آید که چرا از get_theme_mod استفاده کنیم و نه get_option. تفاوت در سه چیز است:

ویژگیget_theme_modget_option
پیشوند خودکاربله (theme_mods_*)خیر
اتصال به Customizerکاملدستی
پیش‌نمایش زندهخودکارنیاز به کد اضافه
ذخیره خودکاربله (از طریق Customizer)بله (از طریق Settings API)
حذف با تغییر قالبخیر (کلید قالب‌محور)خیر (عمومی)

نکته مهم: get_theme_mod فقط برای تنظیمات ظاهری قالب است. برای تنظیمات منطقی مثل کلید API یا سطح فعال‌سازی افزونه، از get_option استفاده کنید. راهنمای کامل در کار با Options API و توابع گزینه‌های سایت.

add_theme_support و get_theme_support

توابع add_theme_support برای اعلام قابلیت‌های قالب به وردپرس استفاده می‌شوند. این توابع، در هوک after_setup_theme فراخوانی می‌شوند:

add_action( "after_setup_theme", function() {
    // تصویر شاخص
    add_theme_support( "post-thumbnails" );
    
    // فرمت‌های نوشته
    add_theme_support( "post-formats", array( "gallery", "video", "quote" ) );
    
    // عرض‌های بلوک گوتنبرگ
    add_theme_support( "align-wide" );
    
    // استایل‌های ویرایشگر
    add_theme_support( "editor-styles" );
    
    // لوگوی سفارشی
    add_theme_support( "custom-logo", array(
        "height"      => 100,
        "width"       => 400,
        "flex-height" => true,
        "flex-width"  => true,
    ) );
    
    // عنوان سایت
    add_theme_support( "title-tag" );
    
    // HTML5
    add_theme_support( "html5", array( "search-form", "comment-form", "comment-list" ) );
} );

برای بررسی اینکه آیا قابلیتی فعال است، از current_theme_supports یا get_theme_support استفاده کنید:

if ( current_theme_supports( "post-thumbnails" ) ) {
    the_post_thumbnail( "medium" );
}

$formats = get_theme_support( "post-formats" );

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

پشتیبانی از لوگوی سفارشی

یکی از پرکاربردترین قابلیت‌ها، لوگوی سفارشی است. بعد از فعال‌سازی با add_theme_support، نمایش در قالب با the_custom_logo انجام می‌شود:

<?php if ( has_custom_logo() ) : ?>
    <div class="site-logo">
        <?php the_custom_logo(); ?>
    </div>
<?php else : ?>
    <a href="<?php echo esc_url( home_url( "/" ) ); ?>" class="site-title">
        <?php bloginfo( "name" ); ?>
    </a>
<?php endif; ?>

الگو با شرط has_custom_logo، تجربه کاربری حرفه‌ای می‌سازد: اگر لوگو تنظیم شده، نمایش داده می‌شود؛ در غیر این صورت، نام سایت نمایش داده می‌شود. راهنمای کامل در توابع تنظیمات قالب و ساختار فایل‌های قالب.

Customizer API: رابط تنظیمات قالب

Customizer وردپرس، رابط استاندارد برای تنظیمات ظاهری است. اسکلت پایه ثبت تنظیمات:

add_action( "customize_register", function( $wp_customize ) {
    // افزودن بخش
    $wp_customize->add_section( "my_theme_colors", array(
        "title"    => "رنگ‌های قالب",
        "priority" => 30,
    ) );
    
    // افزودن تنظیم
    $wp_customize->add_setting( "primary_color", array(
        "default"           => "#0b8a5c",
        "sanitize_callback" => "sanitize_hex_color",
        "transport"         => "postMessage",
    ) );
    
    // افزودن کنترل
    $wp_customize->add_control( new WP_Customize_Color_Control(
        $wp_customize,
        "primary_color",
        array(
            "label"    => "رنگ اصلی",
            "section"  => "my_theme_colors",
            "settings" => "primary_color",
        )
    ) );
} );

سه نکته در Customizer: یک — sanitize_callback الزامی است. بدون آن، خطر XSS. دو — transport: اگر postMessage باشد، پیش‌نمایش زنده نیاز به کد JavaScript دارد؛ اگر refresh باشد، صفحه کامل رفرش می‌شود. سه — priority: ترتیب نمایش بخش‌ها. راهنمای کامل در Customizer وردپرس، ساخت صفحه تنظیمات اختصاصی و پاک‌سازی داده‌ها.

استفاده از تنظیمات در قالب

پس از ثبت تنظیمات، در فایل‌های قالب:

<?php
$primary_color = get_theme_mod( "primary_color", "#0b8a5c" );
$text_color    = get_theme_mod( "text_color", "#222222" );
?>

<style>
    :root {
        --primary-color: <?php echo esc_attr( $primary_color ); ?>;
        --text-color: <?php echo esc_attr( $text_color ); ?>;
    }
</style>

نکته مهم: استفاده از CSS Variables به‌جای تولید CSS جداگانه برای هر رنگ. این الگو، سبک‌تر و قابل نگهداری‌تر است. برای تولید فایل CSS داینامیک، از wp_add_inline_style استفاده کنید:

add_action( "wp_enqueue_scripts", function() {
    $color = get_theme_mod( "primary_color", "#0b8a5c" );
    $css = ":root { --primary-color: " . esc_attr( $color ) . "; }";
    wp_add_inline_style( "my-theme-style", $css );
} );

راهنمای کامل enqueue در افزودن کد سفارشی به وردپرس و افزودن کد بدون ویرایش هسته.

theme.json: تنظیمات مدرن قالب

از وردپرس ۵.۸ به بعد، فایل theme.json جایگزین بخشی از تنظیمات CSS و Customizer شده است. این فایل، پالت رنگ، تایپوگرافی و تنظیمات ویرایشگر را به‌صورت ساختاریافته تعریف می‌کند:

{
    "version": 2,
    "settings": {
        "color": {
            "palette": [
                { "slug": "primary", "color": "#0b8a5c", "name": "اصلی" },
                { "slug": "secondary", "color": "#f4a261", "name": "ثانویه" },
                { "slug": "dark", "color": "#222222", "name": "تیره" }
            ]
        },
        "typography": {
            "fontFamilies": [
                {
                    "fontFamily": "Vazirmatn, sans-serif",
                    "slug": "vazirmatn",
                    "name": "وزیرمتن"
                }
            ]
        }
    }
}

مزیت‌های theme.json: یک — پیش‌نمایش زنده در ویرایشگر. دو — پشتیبانی از طرح‌های تیره/روشن. سه — ساختار استاندارد و قابل انتقال. راهنمای کامل در گوتنبرگ و آینده ویرایش محتوا و ساختار فایل‌های قالب استاندارد. یک نکته از تجربه: در قالب‌های اختصاصی که از theme.json استفاده می‌کنند، نیاز به Customizer برای رنگ‌های پایه کم می‌شود؛ ولی برای تنظیمات خاص مثل شماره تماس یا لوگوی اختصاصی، Customizer همچنان جایگاه خودش را دارد.

ادغام با چایلد تم

در چایلد تم، تنظیمات قالب باید در چایلد اعمال شوند، نه والد. برای رنگ‌ها و فونت‌ها، از theme.json چایلد استفاده کنید؛ برای سایر تنظیمات، از functions.php چایلد:

// در functions.php چایلد
add_action( "after_setup_theme", function() {
    // حذف تنظیم والد (اگر نیاز باشد)
    remove_theme_support( "custom-header" );
    
    // افزودن تنظیم جدید
    add_theme_support( "editor-color-palette", array(
        array(
            "name"  => "اصلی چایلد",
            "slug"  => "child-primary",
            "color" => "#1e88e5",
        ),
    ) );
} );

راهنمای کامل در قالب چایلد چیست و توسعه با چایلد تم.

تنظیمات قالب و RTL / فارسی

در قالب‌های فارسی، تنظیمات ظاهری باید RTL-محور باشند. دو نکته کلیدی: یک — فونت پیش‌فرض فارسی. دو — تنظیم جهت متن.

add_action( "customize_register", function( $wp_customize ) {
    $wp_customize->add_setting( "body_font", array(
        "default"           => "Vazirmatn, sans-serif",
        "sanitize_callback" => "sanitize_text_field",
    ) );
    
    $wp_customize->add_control( "body_font", array(
        "label"   => "فونت متن",
        "section" => "my_theme_typography",
        "type"    => "select",
        "choices" => array(
            "Vazirmatn, sans-serif" => "وزیرمتن",
            "IRANSans, sans-serif"  => "ایران‌سنس",
            "Shabnam, sans-serif"   => "شبنم",
        ),
    ) );
} );

نکته مهم: در CSS، همیشه از propertyهای منطقی مثل margin-inline-start و padding-inline-end استفاده کنید تا RTL خودکار اعمال شود. راهنمای کامل در آماده‌سازی قالب برای فارسی، تفاوت قالب فارسی و انگلیسی و قالب ریسپانسیو چیست.

امنیت در تنظیمات قالب

هر تنظیم قالب، یک نقطه ورود بالقوه است. سه قاعده الزامی: یک — sanitize_callback در هر تنظیم. دو — escape خروجی در نمایش. سه — capability مناسب در ذخیره.

// ذخیره در Customizer - sanitize الزامی
$wp_customize->add_setting( "primary_color", array(
    "default"           => "#0b8a5c",
    "sanitize_callback" => "sanitize_hex_color",
) );

// نمایش در قالب - escape الزامی
echo esc_attr( get_theme_mod( "primary_color", "#0b8a5c" ) );

انواع sanitize_callback بر اساس نوع فیلد: sanitize_hex_color برای رنگ، sanitize_text_field برای متن، absint برای عدد، esc_url_raw برای URL، sanitize_email برای ایمیل. راهنمای کامل در پاک‌سازی داده‌ها، اعتبارسنجی داده‌ها و PHP امن در وردپرس.

اشتباهات رایج

جمع‌بندی

توابع تنظیمات قالب در وردپرس، سه لایه دارند: تنظیمات ظاهری با get_theme_mod و set_theme_mod، اعلام قابلیت‌ها با add_theme_support و current_theme_supports، و تنظیمات ساختاری با theme.json. سه اصل را در پایان تاکید می‌کنم: اول، همیشه مقدار پیش‌فرض در get_theme_mod بگذارید. دوم، sanitize_callback در تنظیمات و escape در نمایش را جدی بگیرید. سوم، تنظیمات ظاهری را با Customizer مدیریت کنید تا مشتری بدون دست‌زدن به کد، ظاهر را تغییر دهد.

اگر امروز یک کار در این مسیر انجام می‌دهید: در قالب فعلی خود، فهرستی از رنگ‌ها و فونت‌هایی که هاردکد شده‌اند تهیه کنید و آن‌ها را به Customizer منتقل کنید. همین یک کار، تجربه مدیریت سایت را برای مشتری چند برابر بهتر می‌کند. اگر تجربه‌ای از یک تنظیم قالب دارید که مدتی روی آن کار کرده‌اید یا باگی در این مسیر حل کرده‌اید، در دیدگاه‌ها بنویسید — همان گزارش‌های واقعی، این راهنما را برای توسعه‌دهنده بعدی دقیق‌تر می‌کند. 🎨