در وردپرس، Template Hierarchy (سلسله‌مراتب قالب) منطق انتخاب فایل PHP برای رندر هر درخواست را تعیین می‌کند و ستون فقرات معماری قالب سفارشی است. بدون شناخت دقیق اولویت فایل‌ها، توسعه‌دهنده نمی‌تواند پیش‌بینی کند کدام template در شرایط مختلف اجرا می‌شود و همین موضوع به خطاهای خاموش و رفتار غیرقابل‌تکرار منجر می‌شود. سلسله‌مراتب از مرحله‌به‌مرحله و از خاص‌ترین فایل تا عمومی‌ترین فایل را پیمایش می‌کند و در نهایت به index.php می‌رسد. شناخت این مسیر برای قالب‌های کلاسیک و بلاکی ضروری است و مستندسازی آن، هزینه نگهداشت پروژه را به‌شدت کاهش می‌دهد. در این راهنما از اصول پایه تا سناریوهای حرفه‌ای و تست عملی Template Hierarchy را با نگاه مهندسی پوشش می‌دهیم.

در پروژه‌های واقعی، بیشترین زمان دیباگ قالب صرف این پرسش می‌شود که چرا فایل مورد انتظار اجرا نمی‌شود. پاسخ تقریباً همیشه در Template Hierarchy پنهان است. این راهنما همان لایه‌ای است که باید پیش از هر تغییر قالب، در ذهن توسعه‌دهنده حاضر باشد.

Template Hierarchy چیست و چرا اهمیت دارد؟

Template Hierarchy مجموعه‌ای از قواعد است که وردپرس برای انتخاب فایل قالب در پاسخ به یک درخواست خاص استفاده می‌کند. هر بار که یک URL در سایت فراخوانی می‌شود، وردپرس ابتدا درخواست را تحلیل می‌کند، سپس Query مناسب را اجرا می‌کند و در نهایت با استفاده از Template Hierarchy، فایل PHP مناسب را انتخاب می‌کند.

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

تفاوت Template Hierarchy و Template Loader

Template Hierarchy فقط منطق انتخاب است؛ اجرای واقعی آن برعهده Template Loader است. تابع locate_template() و get_query_template() بخشی از این لودر هستند و فیلتر template_include امکان تغییر نهایی را می‌دهد.

جریان انتخاب قالب در هسته وردپرس

جریان کلی شامل چهار مرحله است: تحلیل URL، اجرای WP_Query، تحلیل نوع درخواست با Conditional Tags، و انتخاب فایل قالب. مرحله سوم نقطه اتصال با Conditional Tags است و مرحله چهارم نقطه اتصال با Template Hierarchy.

برای مطالعه بیشتر در مورد Conditional Tags، راهنمای Conditional Tags پیشرفته در قالب را ببینید.

نقش get_query_template در انتخاب قالب

هسته وردپرس از get_query_template() برای پیمایش لیست فایل‌ها استفاده می‌کند. این تابع با استفاده از نوع درخواست، لیست فایل‌های ممکن را می‌سازد و اولین فایل موجود را برمی‌گرداند.

اولویت قالب‌ها برای نمایش پست تکی

برای نمایش یک پست تکی، وردپرس این فایل‌ها را به ترتیب بررسی می‌کند:

  1. single-post-{slug}.php
  2. single-post-{id}.php
  3. single-post.php
  4. single.php
  5. singular.php
  6. index.php

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

استفاده از partial در single

توصیه می‌کنم به‌جای تکرار کد در فایل‌های single، از get_template_part() استفاده کنید. راهنمای تابع get_template_part نقطه شروع مناسبی است.

اولویت قالب‌ها برای آرشیو

برای آرشیو پست‌ها، ترتیب به این شکل است:

  1. archive-{post_type}.php
  2. archive.php
  3. index.php

آرشیو دسته‌بندی، برچسب و تاریخ نیز قواعد اختصاصی دارند. برای دسته، ابتدا category-{slug}.php سپس category-{id}.php و سپس category.php.

آرشیو نویسنده و تاریخ

برای نویسنده، author-{nicename}.php، author-{id}.php، author.php. برای تاریخ، date.php. آرشیو جستجو search.php و صفحه ۴۰۴ 404.php است.

Template Hierarchy و پست‌تایپ سفارشی

پست‌تایپ سفارشی از ساختار مشابه پست معمولی پیروی می‌کند اما با نام اختصاصی. برای مثال اگر slug پست‌تایپ portfolio باشد، ترتیب این است:

  1. single-portfolio-{slug}.php
  2. single-portfolio.php
  3. single.php
  4. singular.php
  5. index.php

الگوی پیشنهادی این است که برای هر پست‌تایپ، فایل single-{cpt}.php داشته باشید و منطق اختصاصی همان پست‌تایپ را در آن پیاده کنید.

نکات نام‌گذاری در CPT

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

سلسله‌مراتب تاکسونومی‌ها

برای تاکسونومی سفارشی، ترتیب عبارت است از:

  1. taxonomy-{taxonomy}-{term}.php
  2. taxonomy-{taxonomy}.php
  3. taxonomy.php
  4. archive.php
  5. index.php

برای تاکسونومی داخلی مثل دسته، ابتدا category-{slug}.php و سپس category.php. برای مطالعه بیشتر، راهنمای قالب تاکسونومی اختصاصی را ببینید.

تاکسونومی چندسطحی و ترم والد

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

ترکیب Template Hierarchy و Conditional Tags

Conditional Tags به شما اجازه می‌دهد در یک فایل مشترک، رفتار متفاوتی بر اساس نوع درخواست پیاده کنید. برای مثال، در index.php می‌توانید با is_category() بخش هدر را متفاوت کنید.

ترکیب این دو ابزار به شما امکان می‌دهد تعداد فایل‌های قالب را کاهش دهید و در عین حال کنترل کامل داشته باشید. راهنمای Conditional Tags پیشرفته در قالب نقطه شروع مناسبی است.

فیلتر template_include برای کنترل نهایی

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

دیباگ و تست Template Hierarchy

برای دیباگ، ابتدا باید بفهمید کدام فایل انتخاب شده است. ساده‌ترین راه، استفاده از هوک template_include و ثبت مسیر فایل است.

add_filter( "template_include", function( $template ) {
    if ( defined( "WP_DEBUG" ) && WP_DEBUG ) {
        error_log( "Template selected: " . $template );
    }
    return $template;
} );

برای مطالعه بیشتر در مورد دیباگ حرفه‌ای، راهنمای تست E2E وردپرس با Playwright را ببینید.

اشتباهات رایج در تست Template Hierarchy

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

عملکرد و کش در انتخاب قالب

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

برای مطالعه بیشتر، راهنمای Object Cache در وردپرس را ببینید. همچنین Transients API برای کش بخش‌های تکراری قالب مفید است.

کش خروجی بخش‌های قالب

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

امنیت و Escape در قالب‌ها

در همه فایل‌های قالب، داده‌های خروجی باید Escape شوند. برای متن از esc_html، برای URL از esc_url، برای Attributes از esc_attr و برای محتوای HTML از wp_kses_post استفاده کنید.

برای مطالعه بیشتر، راهنمای Escape کردن خروجی برای جلوگیری از XSS را ببینید. همچنین مفهوم Web Template System را در ویکی‌پدیا مرور کنید.

دسترسی‌پذیری و ساختار HTML

فایل‌های قالب باید ساختار HTML معنایی تولید کنند. برای مطالعه بیشتر، راهنمای ARIA در وردپرس و ناوبری با صفحه‌کلید را ببینید.

پرسش‌های پرتکرار درباره Template Hierarchy

آیا قالب فرزند اولویت را تغییر می‌دهد؟

بله، قالب فرزند در انتخاب قالب اولویت دارد. اگر فایل مشابه در قالب فرزند باشد، همان انتخاب می‌شود.

آیا می‌توانم ترتیب اولویت را تغییر دهم؟

ترتیب داخلی قابل تغییر نیست، اما با فیلتر template_include می‌توانید فایل نهایی را تغییر دهید.

آیا Template Hierarchy در قالب بلاکی هم اعمال می‌شود؟

بله، اما فایل‌های قالب در قالب بلاکی داخل HTML Template قرار دارند و از طریق Site Editor مدیریت می‌شوند.

چرا فایل single-{cpt}.php من اعمال نمی‌شود؟

احتمالاً slug پست‌تایپ با نام فایل مطابقت ندارد یا قالب فرزند فایل را override می‌کند.

آیا می‌توان از یک قالب مشترک برای چند نوع محتوا استفاده کرد؟

بله، با Conditional Tags می‌توان منطق را در یک فایل مدیریت کرد، اما توصیه استاندارد این است که فایل‌ها بر اساس نوع جدا باشند.

نتیجه و مسیر ادامه

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

پیشنهاد می‌کنم مسیر یادگیری را با Conditional Tags پیشرفته ادامه دهید و سپس قالب اختصاصی CPT را به‌عنوان تمرین عملی پیاده کنید.

اگر روی پروژه واقعی خود با Template Hierarchy مواجه شده‌اید، برایم جالب است بدانید کدام بخش — انتخاب فایل یا دیباگ — بیشترین زمان را از شما گرفته است. تجربه خودتان را در دیدگاه‌ها بنویسید.