راهنمای توسعه قالب وردپرس از صفر

ساخت قالب وردپرس از صفر، یکی از آن کارهایی است که در ابتدا پیچیده به نظر می‌رسد ولی وقتی ساختار اصلی را فهمیدید، همه‌چیز جای خودش می‌نشیند. تجربه‌ام از پروژه‌های متعدد این است که بیشتر تازه‌واردها، از یک نقطه اشتباه شروع می‌کنند: مستقیم سراغ طراحی بصری می‌روند و بعد به دیوار template hierarchy می‌خورند. ترتیب درست این است که اول ساختار فایل‌ها و چرخهٔ رندر را بفهمید، بعد بصری‌سازی کنید. این مقاله، همان نقشهٔ درست است. اگر با مفاهیم پایه آشنا نیستید، قالب وردپرس چیست و توسعه وردپرس چیست را پیش از ادامه ببینید.

پیش‌نیازهای فنی

پیش از نوشتن کد قالب، سه پیش‌نیاز: یک — PHP در سطح پایه (متغیر، تابع، شرط، حلقه). دو — HTML و CSS مسلط. سه — آشنایی حداقلی با جاوااسکریپت و jQuery. اگر PHP نمی‌دانید، آموزش PHP از صفر و برای مفاهیم پیشرفته‌تر شی‌گرایی در PHP را شروع کنید. برای محیط توسعهٔ محلی، توسعه با محیط لوکال را یک بار مرور کنید. تجربه‌ام: ساختن قالب روی لوکال، صد برابر سریع‌تر از ساختن روی هاست است.

حداقل فایل‌های لازم قالب

یک قالب وردپرس، حداقل دو فایل لازم دارد: style.css (با هدر رسمی) و index.php (فایل اصلی). ولی یک قالب حرفه‌ای، فایل‌های بیشتری دارد که هرکدام مسئولیتی مشخص دارند:

my-theme/
├── style.css          # هدر قالب + استایل اصلی
├── index.php          # فایل fallback اصلی
├── header.php         # هدر سایت
├── footer.php         # فوتر سایت
├── sidebar.php        # نوار کناری
├── single.php         # نمایش تک‌نوشته
├── page.php           # نمایش برگه
├── archive.php        # نمایش آرشیو دسته و برچسب
├── search.php         # نمایش نتایج جستجو
├── 404.php            # صفحهٔ خطا
├── functions.php      # توابع قالب
└── screenshot.png     # تصویر پیش‌نمایش در پیشخوان

الگوی کامل فایل‌ها و مسئولیت هر کدام، در ساختار فایل‌های قالب استاندارد به تفصیل آمده است. تجربه‌ام: پیش از شروع کدنویسی، این ساختار را روی کاغذ بکشید. داشتن نقشهٔ فایل‌ها، سرعت کار را چند برابر می‌کند.

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

template hierarchy

قالب وردپرس، از یک سلسله‌مراتب دقیق برای انتخاب فایل استفاده می‌کند. برای هر نوع درخواست، وردپرس فهرست اولویتی از فایل‌ها را بررسی می‌کند و اولین فایل موجود را می‌گیرد. مثلاً برای «تک‌نوشته»: single-post-{slug}.php ← single-post.php ← single.php ← singular.php ← index.php. شناخت این سلسله‌مراتب، یکی از مهم‌ترین بخش‌های توسعهٔ قالب است. تفصیل کامل در همان ساختار فایل‌های قالب استاندارد آمده. یک نکتهٔ عملی: نیازی نیست همهٔ فایل‌ها را بسازید؛ فقط فایل‌هایی که رفتار متفاوت می‌خواهید. بقیه از index.php fallback می‌شوند.

حلقه (Loop) و رندر محتوا

حلقه، قلب قالب وردپرس است. الگوی استاندارد:

<?php
if ( have_posts() ) :
    while ( have_posts() ) :
        the_post();
        ?>
        <article>
            <h2><?php the_title(); ?></h2>
            <div><?php the_content(); ?></div>
        </article>
        <?php
    endwhile;
else :
    echo '<p>محتوایی یافت نشد.</p>';
endif;
?>

سه نکتهٔ مهم: یک — همیشه have_posts() را چک کنید؛ بدون آن، در صورت نبود محتوا، حلقه رفتار غیرعادی می‌شود. دو — the_post() متغیرهای جهانی ($post) را تنظیم می‌کند؛ توابع بعدی روی همان کار می‌کنند. سه — بعد از حلقه، wp_reset_postdata() را صدا بزنید، مخصوصاً اگر از WP_Query سفارشی استفاده کرده‌اید. الگوهای بیشتر در توابع وردپرس برای دریافت اطلاعات نوشته.

functions.php: قلب قالب

فایل functions.php، نقطهٔ اتصال قالب با هستهٔ وردپرس است. توابعی که در این فایل تعریف می‌شوند، در هر درخواست اجرا می‌شوند. الگوهای استاندارد: after_setup_theme برای تنظیمات پایه (اندازه‌های تصویر، پشتیبانی از featured image، منوها)، wp_enqueue_scripts برای لود استایل و اسکریپت، widgets_init برای ثبت نواحی ویجت. سه نکته: یک — تمام توابع را با پیشوند نام قالب بزنید تا با افزونه‌ها تعارض نکنند. دو — برای توابعی که ممکن است در چایلد تم بازنویسی شوند، از function_exists() استفاده کنید. سه — کدهای منطقی را در فایل‌های جدا (inc/) قرار دهید و در functions.php با require_once لود کنید. راهنمای تکمیلی در چایلد تم و استفادهٔ درست از هوک‌ها.

enqueue استایل و اسکریپت

روش درست لود CSS و JS در قالب وردپرس، استفاده از wp_enqueue_style و wp_enqueue_script است، نه @import یا <link> دستی. الگوی استاندارد:

function mytheme_assets() {
    wp_enqueue_style(
        'mytheme-style',
        get_stylesheet_uri(),
        array(),
        wp_get_theme()->get( 'Version' )
    );
    wp_enqueue_script(
        'mytheme-script',
        get_template_directory_uri() . '/assets/js/main.js',
        array( 'jquery' ),
        '1.0.0',
        true
    );
}
add_action( 'wp_enqueue_scripts', 'mytheme_assets' );

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

پشتیبانی از گوتنبرگ

قالب مدرن، باید از ویرایشگر بلوک پشتیبانی کند. سه لایه پشتیبانی: یک — add_theme_support( 'align-wide' ) برای عرض‌های گسترده. دو — استایل‌شیت theme.json برای تعریف پالت رنگ، تایپوگرافی، و تنظیمات editor. سه — استایل‌شیت editor-style.css برای هماهنگی پیش‌نمایش ویرایشگر با front-end. چشم‌انداز کلی در گوتنبرگ و آیندهٔ ویرایش محتوا و ساخت بلوک سفارشی در ساخت بلوک سفارشی گوتنبرگ. تجربه‌ام: قالبی که در گوتنبرگ تجربهٔ خوبی نداشته باشد، برای مشتری غیرفنی، تبدیل به دردسر می‌شود.

آماده‌سازی برای ترجمه

اگر قالب شما ممکن است در آینده ترجمه شود (و برای قالب‌های عمومی این الزامی است)، تمام رشته‌های متنی را با __()، _e()، یا esc_html__() بنویسید. سه نکته: یک — Text Domain در هدر style.css را با نام قالب یکسان کنید. دو — فایل languages/mytheme.pot را با ابزارهایی مثل Poedit بسازید. سه — از load_theme_textdomain() در after_setup_theme استفاده کنید. راهنمای تکمیلی در آماده‌سازی قالب برای فارسی و تشخیص قالب استاندارد.

دید مهندسی: از قالب تک‌منظوره تا معماری

برای توسعه‌دهنده‌های سطح بالا، سه الگوی معماری که تفاوت بین قالب خوب و قالب حرفه‌ای را می‌سازد: یک — جداسازی لایه‌ها. منطق نمایش، منطق کسب‌وکار، و منطق داده نباید در یک فایل قاطی شوند. ساده‌ترین الگو: منطق در inc/، نمایش در فایل‌های template، داده در توابع helper. تجربه‌ام: قالب‌هایی که این جداسازی را رعایت نکرده‌اند، در آپدیت سوم یا چهارم به دیوار می‌خورند. دو — Registry Pattern برای هوک‌ها. به‌جای add_action()های پراکنده در فایل‌های مختلف، یک کلاسِ Registry بسازید که تمام هوک‌ها را در یک نقطه ثبت می‌کند. مزیت: نگهداری و دیباگ آسان‌تر. الگوی دقیق در هوک‌های وردپرس. سه — لایهٔ abstraction برای منابع خارجی. اگر قالب شما به منابع خارجی (REST API، سرویس پشتیبانی، اپلیکیشن خارجی) وصل می‌شود، این اتصال‌ها را در یک کلاس جدا نگه دارید تا روزی که سرویس تغییر کرد، فقط یک فایل تغییر کند. این الگو در اتصال وردپرس به سرویس‌های خارجی توضیح داده شده.

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

جمع‌بندی

ساخت قالب وردپرس از صفر، هفت گام دارد: ساختار پایه، template hierarchy، حلقه، functions.php، enqueue assets، پشتیبانی گوتنبرگ، و آماده‌سازی ترجمه. اگر امروز فقط یک کار می‌کنید: یک قالب خالی با هدر style.css، index.php و functions.php بسازید و در آن، یک حلقهٔ ساده پیاده کنید. تجربه‌تان از ساخت اولین قالب، در دیدگاه‌ها ارزشمند است — به‌خصوص اگر با مشکلی در template hierarchy یا حلقه روبرو شدید. 🎨