ساختار فایل‌های یک قالب استاندارد وردپرس

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

فایل‌های هسته‌ای قالب

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

my-theme/
├── style.css              # هدر قالب + استایل اصلی
├── index.php              # فایل fallback اصلی
├── functions.php          # توابع قالب
├── screenshot.png         # تصویر پیش‌نمایش
├── header.php             # هدر
├── footer.php             # فوتر
├── sidebar.php            # نوار کناری
├── single.php             # نمایش تک‌نوشته
├── page.php               # نمایش برگه
├── archive.php            # نمایش آرشیو
├── search.php             # نتایج جستجو
├── 404.php                # صفحهٔ خطا
├── comments.php           # بخش دیدگاه‌ها
├── searchform.php         # فرم جستجو
├── inc/                   # فایل‌های منطق (include)
│   ├── customizer.php
│   ├── template-tags.php
│   └── widgets.php
├── assets/
│   ├── css/
│   ├── js/
│   └── images/
├── template-parts/        # بخش‌های قابل استفادهٔ مجدد
│   ├── content.php
│   ├── content-single.php
│   └── content-page.php
└── languages/
    └── my-theme.pot

تجربه‌ام: همین ساختار، در هر پروژه‌ای که با تیم کار می‌کنم، استاندارد است. دلیلش ساده است: هر توسعه‌دهندهٔ جدیدی که به پروژه اضافه شود، می‌داند کدام فایل کجاست.

قالب استاندارد، مثل یک کتابخانهٔ منظم است؛ هر کتاب سر جای خودش. تیم فنی، جای هر کتاب را می‌داند.

index.php و fallback chain

index.php، فایل نهایی fallback در template hierarchy است. اگر هیچ فایل دیگری برای یک نوع درخواست موجود نباشد، وردپرس این فایل را اجرا می‌کند. در قالب‌های مینیمال، گاهی همه‌چیز در همین یک فایل خلاصه می‌شود؛ ولی در قالب حرفه‌ای، این فایل معمولاً حلقهٔ عمومی و فراخوانی بخش‌های قابل استفادهٔ مجدد را انجام می‌دهد:

<?php get_header(); ?>
<main>
    <?php
    if ( have_posts() ) :
        while ( have_posts() ) : the_post();
            get_template_part( 'template-parts/content', get_post_type() );
        endwhile;
        the_posts_pagination();
    else :
        get_template_part( 'template-parts/content', 'none' );
    endif;
    ?>
</main>
<?php get_sidebar(); ?>
<?php get_footer(); ?>

single.php و page.php

single.php مسئول نمایش یک نوشتهٔ تکی است و page.php مسئول نمایش یک برگه. تفاوت اصلی: در single.php معمولاً متادیتا (نویسنده، تاریخ، دسته) هم نمایش داده می‌شود؛ در page.php معمولاً فقط محتوا. تجربه‌ام: بسیاری از قالب‌ها این تفکیک را نادیده می‌گیرند و همه‌چیز را در index.php رندر می‌کنند؛ نتیجه، UX ضعیف در هر دو حالت. الگوی استاندارد: در single.php حلقه و متادیتا، در page.php فقط محتوا. اگر نوشتهٔ شما انواع مختلف دارد (مثلاً ووکامرس محصول یا نوع‌نوشتهٔ سفارشی)، برای هر نوع فایل اختصاصی بسازید — single-product.php الگوی رایج ووکامرس است.

archive.php، category.php، tag.php

سه فایل برای آرشیوها: archive.php عمومی، category.php برای آرشیو دسته، tag.php برای آرشیو برچسب. اگر category.php موجود نباشد، از archive.php استفاده می‌شود؛ اگر آن هم نباشد، از index.php. در تجربه، بیشتر قالب‌ها یکی از این سه را دارند. توصیه: archive.php عمومی را داشته باشید؛ اگر برای دسته یا برچسب طراحی خاص می‌خواهید، فایل اختصاصی بسازید. برای انواع آرشیو دیگر: author.php (آرشیو نویسنده)، date.php (آرشیو تاریخ)، taxonomy-{name}.php (تاکسونومی سفارشی). جزئیات بیشتر در توابع وردپرس برای دسته‌بندی و ساخت تاکسونومی سفارشی.

search.php و 404.php

search.php برای نمایش نتایج جستجو و 404.php برای صفحهٔ خطا. تجربه‌ام: این دو فایل، بیشترین غفلت را در قالب‌های دست‌ساز می‌بینند و در نتیجه، تجربهٔ کاربری ضعیفی می‌سازند. توصیه: در search.php علاوه بر نمایش نتایج، فرم جستجوی مجدد و پیشنهادهای مرتبط را قرار دهید. در 404.php، یک پیام صمیمانه، جستجو، و لینک به بخش‌های پرترافیک سایت. نکتهٔ سئویی: صفحهٔ ۴۰۴ نباید redirect شود؛ باید وضعیت HTTP 404 برگرداند تا گوگل آن را ایندکس نکند. راهنمای مربوطه در رفع خطای ۴۰۴ وردپرس.

header، footer، sidebar

سه فایل مشترک که در تمام صفحات استفاده می‌شوند: header.php (شامل <head> و هدر بصری)، footer.php (شامل فوتر بصری و بستن تگ‌ها)، و sidebar.php (نوار کناری). الگوی استاندارد استفاده: در ابتدای هر فایل template، <?php get_header(); ?> و در انتها <?php get_footer(); ?>. تجربه‌ام: در header.php، همیشه <?php wp_head(); ?> قبل از </head> و در footer.php، <?php wp_footer(); ?> قبل از </body> باشد. نبود این دو، باعث می‌شود افزونه‌ها نتوانند استایل و اسکریپت اضافه کنند.

functions.php و پوشهٔ inc

functions.php، فایل ورود منطق قالب است. ولی توصیه می‌کنم کد را در پوشهٔ inc/ تقسیم کنید:

functions.php:
<?php
require_once get_template_directory() . '/inc/setup.php';
require_once get_template_directory() . '/inc/enqueue.php';
require_once get_template_directory() . '/inc/customizer.php';
require_once get_template_directory() . '/inc/template-tags.php';
require_once get_template_directory() . '/inc/widgets.php';

مزیت: خوانایی، نگهداری، و امکان همکاری تیمی. تجربه‌ام: هر تابعی که در functions.php بالای ۲۰۰ خط را رد می‌کند، باید در فایل جدا نقل مکان کند. الگوی کامل و هوک‌های پرکاربرد در استفادهٔ درست از هوک‌ها و توسعهٔ قالب از صفر.

پوشهٔ assets

پوشهٔ assets/ محل نگهداری CSS، JS، و تصاویر قالب است. الگوی استاندارد:

assets/
├── css/
│   ├── main.css
│   └── rtl.css
├── js/
│   ├── main.js
│   └── navigation.js
└── images/
    ├── logo.svg
    └── icon-arrow.svg

نکته: تمام این فایل‌ها باید با wp_enqueue_style و wp_enqueue_script لود شوند، نه با تگ مستقیم. تفصیل در توسعهٔ قالب از صفر و افزودن کد سفارشی به وردپرس. نسخهٔ rtl.css برای سایت‌های فارسی الزامی است — آماده‌سازی در آماده‌سازی قالب برای فارسی.

template-parts و reusability

پوشهٔ template-parts/، الگوی مدرن وردپرس برای بخش‌های قابل استفادهٔ مجدد. به‌جای تکرار کد در فایل‌های مختلف، یک بخش را در یک فایل می‌نویسید و با get_template_part() فراخوانی می‌کنید:

template-parts/
├── content.php
├── content-single.php
├── content-page.php
├── content-none.php
└── content-search.php

مزیت: نگهداری ساده‌تر، امکان override در چایلد تم. تجربه‌ام: در پروژه‌های تیمی، این الگو باعث می‌شود یک تغییر کوچک (مثلاً تغییر استایل کارت نوشته)، در یک نقطه انجام شود، نه در پنج فایل. مثال کاربردی: اگر قالب شما سه نوع محتوا دارد (نوشته، برگه، محصول)، سه فایل در template-parts/ داشته باشید و در فایل‌های template، به‌جای تکرار کد، همان‌ها را فراخوانی کنید.

جدول کامل template hierarchy

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

جزئیات بیشتر در مستندات رسمی وردپرس. یک نکتهٔ عملی از تجربه: اگر افزونه‌ای فایل template را در قالب override می‌کند (مثلاً ووکامرس در woocommerce/ پوشه)، اول آن override بررسی می‌شود، بعد قالب شما. بنابراین در پروژه‌های ووکامرسی، فایل‌های woocommerce/ در چایلد تم، اولویت بالاتری از فایل‌های قالب والد دارند.

جمع‌بندی

ساختار فایل‌های قالب استاندارد، شش لایه دارد: فایل‌های هسته، فایل‌های ویژهٔ template، فایل‌های مشترک، functions و inc، assets، و template-parts. اگر امروز فقط یک کار می‌کنید: قالب فعلی سایت خودتان را در FTP باز کنید و ببینید آیا فایل‌ها مطابق ساختار استاندارد مرتب‌اند یا پراکنده. تجربه‌تان از یک قالب با ساختار نامنظم که باعث باگ شد، در دیدگاه‌ها ارزشمند است. 📂