قالب بلاکی وردپرس اعمال نمی‌شود؟ از پایگاه داده شروع کنید

فایل قالب شما تقریباً به‌طور قطع نادیده گرفته می‌شود چون یک نسخه در پایگاه داده برنده شده است. لحظه‌ای که قالبی را در ویرایشگر سایت باز کنید و ذخیره بزنید، وردپرس یک رکورد نوشتهٔ wp_template می‌نویسد و از آن به بعد همان رکورد را به‌جای فایل .html داخل پوشهٔ قالب سرو می‌کند — پس هر ویرایشی که بعد از آن روی فایل انجام دهید در سمت کاربر نامرئی است. پاک‌کردن آن رکورد راه‌حل است و اولین چیزی است که باید بررسی کنید، پیش از دست‌زدن به سلسله‌مراتب، نام فایل یا کش.

وجود نسخهٔ پایگاه داده را تأیید کنید

به نمایش ← ویرایشگر ← قالب‌ها بروید. هر قالبی که وردپرس از پایگاه داده سرو می‌کند در فهرست نشان‌دار است — بسته به نسخهٔ وردپرس، برچسب «سفارشی‌شده» می‌خورد یا زیر فیلتری با همین نام می‌آید. همان برچسب تمام پاسخ است. اگر هست، فایل شما استفاده نمی‌شود.

همین را از خط فرمان هم می‌شود بررسی کرد که سریع‌تر است و حتی وقتی ویرایشگر سایت درست کار نمی‌کند جواب می‌دهد:

wp post list --post_type=wp_template --fields=ID,post_name,post_status,post_title
wp post list --post_type=wp_template_part --fields=ID,post_name,post_status,post_title

هر سطر یک بازنویسی در پایگاه داده است. مقدار post_name با نامک قالب مطابقت دارد، پس سطری با نام single دارد templates/single.html را می‌پوشاند.

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

پاکش کنید

در ویرایشگر سایت، منوی گزینه‌های قالب (سه نقطهٔ کنارش) را باز کنید و پاک‌کردن سفارشی‌سازی‌ها را بزنید — در بعضی نسخه‌ها نامش بازنشانی است. این کار رکورد پایگاه داده را حذف می‌کند و کنترل به فایل روی دیسک برمی‌گردد.

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

از WP-CLI، با شناسه‌ای از فهرست بالا:

wp post delete 482 --force

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

وردپرس چطور قالب را انتخاب می‌کند

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

در حال نمایش	به این ترتیب بررسی می‌شود
یک نوشتهٔ تکی	single-post-{slug}.html ← single-post.html ← single.html ← singular.html ← index.html
یک برگه	page-{slug}.html ← page-{id}.html ← page.html ← singular.html ← index.html
بایگانی یک دسته	category-{slug}.html ← category-{id}.html ← category.html ← archive.html ← index.html
یک نوع محتوای سفارشی	single-{post-type}.html ← single.html ← singular.html ← index.html
صفحهٔ ۴۰۴	404.html ← index.html

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

قالب‌های مبتنی بر نامک به شکلی شکننده‌اند که ارزش دارد در ذهنتان بماند. فایل page-about.html فقط تا وقتی تطبیق می‌کند که نامک برگه about باشد. نام برگه را به about-us تغییر دهید و قالب بدون هیچ هشدار و خطایی از کار می‌افتد.

قالب در برابر بخش قالب

قالب یک نمای کامل را رندر می‌کند و سلسله‌مراتب انتخابش می‌کند. بخش قالب یک تکه است — هدر، فوتر، نوار کناری — که قالب‌ها آن را فرا می‌خوانند. بخش‌ها در parts/ زندگی می‌کنند، قالب‌ها در templates/، و در پایگاه داده جداگانه به شکل رکوردهای wp_template_part ذخیره می‌شوند.

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

عکسش هم پیش می‌آید. یک چیدمان کامل صفحه را داخل parts/ می‌گذارید و تعجب می‌کنید چرا سلسله‌مراتب هیچ‌وقت سراغش نمی‌رود. بخش‌ها اصلاً نامزد سلسله‌مراتب نیستند؛ هیچ درخواستی مستقیماً به آن‌ها مسیردهی نمی‌شود.

نام‌گذاری و محل فایل

پیش از اینکه سراغ فرضیه‌های عجیب‌تر بروید این‌ها را بررسی کنید:

• نام پوشه templates/ است، جمع، در ریشهٔ قالب. نه template/، نه block-templates/. نام block-templates/ در دوران افزونهٔ Gutenberg و پیش از ورود قالب‌های بلاکی به هسته درست بود و هنوز هم در آموزش‌های زیادی دیده می‌شود — در وردپرس امروز کار نمی‌کند.
• بخش‌های قالب در parts/ می‌روند، نه template-parts/ (که قرارداد قالب‌های کلاسیک برای تکه‌های PHP است).
• پسوند .html است. فایل .php داخل templates/ نادیده گرفته می‌شود.
• نام فایل‌ها با حروف کوچک و با خط تیره نوشته می‌شود. single-Post.html یا single_post.html تطبیق نمی‌کنند. روی فایل‌سیستمی که به کوچکی و بزرگی حروف حساس نیست مثل مک‌اواس، این حالت محلی کار می‌کند و روی سرور لینوکسی می‌شکند — نمونهٔ کلاسیک «روی سیستم من که کار می‌کرد».
• فایل templates/index.html باید وجود داشته باشد. بدون آن، وردپرس قالب را بلاکی حساب نمی‌کند و ممکن است ویرایشگر سایت اصلاً ظاهر نشود.
• اگر در قالب فرزند کار می‌کنید، قالب‌های آن بر قالب‌های مادر اولویت دارند. یک فایل جامانده در قالب فرزند بی‌سروصدا از فایلی که در مادر ویرایش می‌کنید جلو می‌زند.

قالب‌های سفارشی که باید در ویرایشگر نوشته قابل انتخاب باشند، لازم است در theme.json زیر customTemplates هم معرفی شوند، با نام پایهٔ فایل، یک عنوان خوانا و نوع‌های محتوایی که به آن‌ها اعمال می‌شوند. بدون این ورودی، فایل وجود دارد اما هرگز در پنل قالب ظاهر نمی‌شود.

کش — آخر از همه بررسی‌اش کنید

کش واقعی است اما کم‌احتمال‌ترین علت است، و شروع‌کردن از آن همان کاری است که یک بعدازظهر آدم را می‌بلعد.

کش صفحه را خالی کنید و اگر کش شیء ماندگاری مثل Redis یا Memcached دارید، آن را هم بشویید — نتیجهٔ تشخیص قالب می‌تواند آنجا نگه داشته شود. بعد صفحه را با دور زدن کش مرورگر دوباره بارگذاری کنید.

چیزی که کمکی نمی‌کند: پاک‌کردن OPcache. قالب‌های بلاکی فایل .html هستند و هرگز توسط PHP کامپایل نمی‌شوند، پس OPcache هیچ ربطی به آن‌ها ندارد. اگر یک بار خالی‌کردن OPcache به نظرتان این مشکل را حل کرد، هم‌زمان چیز دیگری عوض شده بود.

هنوز گیر کرده‌اید؟

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

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