Szablon blokowy WordPress nie działa? Zacznij od bazy danych

Twój plik szablonu jest niemal na pewno pomijany, bo wygrywa z nim kopia w bazie danych. W chwili, w której otwierasz szablon w edytorze witryny i naciskasz Zapisz, WordPress tworzy wpis typu wp_template i od tego momentu serwuje ten wpis zamiast pliku .html z katalogu motywu — więc każda późniejsza zmiana w pliku jest na stronie niewidoczna. Usunięcie tego rekordu to rozwiązanie i pierwsza rzecz do sprawdzenia, zanim ruszysz hierarchię, nazwę pliku czy bufor.

Potwierdź, że kopia w bazie danych istnieje

Przejdź do Wygląd → Edytor → Szablony. Każdy szablon serwowany przez WordPressa z bazy danych jest na liście oznaczony — w zależności od wersji WordPressa etykieta brzmi „Dostosowany” albo szablon pojawia się pod filtrem „Dostosowane”. Ta etykieta to cała odpowiedź. Jeśli tam jest, Twój plik nie jest używany.

To samo sprawdzisz z wiersza poleceń, co jest szybsze i działa nawet wtedy, gdy edytor witryny zachowuje się dziwnie:

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

Każdy wiersz to nadpisanie z bazy danych. post_name odpowiada slugowi szablonu, więc wiersz o nazwie single przesłania templates/single.html.

Jeden szczegół, na którym ludzie się potykają: te rekordy są powiązane z motywem przez element taksonomii, a nie przez ścieżkę. Jeśli zmienisz nazwę katalogu motywu, zapisane szablony zostaną w bazie danych, ale przestaną pasować do aktywnego motywu, a witryna nagle wróci do plików. Wygląda to wtedy na „moje personalizacje zniknęły”, a nie na „mój plik jest ignorowany” — ten sam mechanizm, odwrotny objaw.

Usuń ją

W edytorze witryny otwórz menu opcji szablonu (trzy kropki obok niego) i wybierz Wyczyść personalizacje — w niektórych wersjach opcja nazywa się Resetuj. Usuwa to rekord z bazy danych i zwraca kontrolę plikowi na dysku.

Jeśli menu proponuje Usuń zamiast Wyczyść personalizacje lub Resetuj, to znaczy, że ten szablon istnieje wyłącznie w bazie danych i nie stoi za nim żaden plik. Usunięcie go kasuje szablon całkowicie, a WordPress schodzi niżej po hierarchii.

Z poziomu WP-CLI, używając identyfikatora z powyższej listy:

wp post delete 482 --force

Bądź wobec siebie uczciwy co do kosztu: wyczyszczenie personalizacji trwale kasuje wszystko, co zbudowałeś w edytorze witryny dla tego szablonu, i nie da się tego cofnąć. Jeśli w wersji z edytora jest realna praca, najpierw skopiuj z niej znaczniki blokowe — otwórz szablon w edytorze, przełącz się na widok kodu i wklej wynik do swojego pliku .html. Dzięki temu plik stanie się źródłem prawdy i nic nie przepadnie.

Jak WordPress wybiera szablon

Motywy blokowe używają tej samej logiki hierarchii co klasyczne, tylko z plikami .html w katalogu templates/ zamiast plików .php w katalogu głównym motywu. WordPress idzie od najbardziej szczegółowego do najbardziej ogólnego i używa pierwszego pliku, który istnieje.

Wyświetlane	Sprawdzane w tej kolejności
Pojedynczy wpis	single-post-{slug}.html → single-post.html → single.html → singular.html → index.html
Strona	page-{slug}.html → page-{id}.html → page.html → singular.html → index.html
Archiwum kategorii	category-{slug}.html → category-{id}.html → category.html → archive.html → index.html
Własny typ treści	single-{post-type}.html → single.html → singular.html → index.html
Strona 404	404.html → index.html

Dwie rzeczy całkowicie to unieważniają. Po pierwsze, opisany wyżej rekord w bazie danych. Po drugie, szablon przypisany bezpośrednio do wpisu lub strony — otwórz edytor wpisu, poszukaj panelu Szablon w bocznym pasku i sprawdź, czy nie jest tam wybrane coś konkretnego. Jawne przypisanie za każdym razem bije hierarchię, a jest niewidoczne, dopóki go nie poszukasz.

Szablony oparte na slugu są kruche w sposób, który warto sobie przyswoić. page-about.html pasuje tylko dopóty, dopóki slug strony to about. Zmień nazwę strony na about-us, a szablon przestanie być stosowany — bez ostrzeżenia i bez błędu.

Szablon a część szablonu

Szablon renderuje cały widok i jest wybierany przez hierarchię. Część szablonu to fragment — nagłówek, stopka, panel boczny — który szablony do siebie wciągają. Części leżą w parts/, szablony w templates/, a w bazie danych przechowywane są osobno, jako rekordy wp_template_part.

Typowe nieporozumienie: edytujesz nagłówek, a zmiana pojawia się na stronach, których nie zamierzałeś ruszać. To poprawne zachowanie. Jedną część współdzieli każdy szablon, który ją zawiera. Jeśli chcesz mieć inny nagłówek w jednym szablonie, potrzebujesz drugiego pliku części i szablonu, który się do niego odwołuje — edytowanie współdzielonej części nigdy nie da Ci zróżnicowania między szablonami.

Zdarza się też odwrotnie. Wrzucasz pełny układ strony do parts/ i zastanawiasz się, czemu hierarchia nigdy po niego nie sięga. Części w ogóle nie biorą udziału w hierarchii; nic nigdy nie trafi do nich bezpośrednio.

Nazewnictwo i lokalizacja plików

Sprawdź to, zanim zaczniesz zakładać coś bardziej egzotycznego:

• Katalog nazywa się templates/, w liczbie mnogiej, w katalogu głównym motywu. Nie template/, nie block-templates/. Nazwa block-templates/ była poprawna w czasach wtyczki Gutenberg, zanim motywy blokowe trafiły do rdzenia, i wiele poradników nadal ją pokazuje — w aktualnym WordPressie nie działa.
• Części szablonów trafiają do parts/, a nie do template-parts/ (to konwencja motywów klasycznych dla fragmentów PHP).
• Rozszerzenie to .html. Plik .php w katalogu templates/ jest pomijany.
• Nazwy plików pisze się małymi literami i z myślnikami. single-Post.html ani single_post.html nie zostaną dopasowane. W systemie plików nierozróżniającym wielkości liter, takim jak w macOS, zadziała to lokalnie i wysypie się na serwerze z Linuksem — klasyczna awaria typu „u mnie działa”.
• Plik templates/index.html musi istnieć. Bez niego WordPress nie zaklasyfikuje motywu jako blokowego, a edytor witryny może się w ogóle nie pojawić.
• Jeśli pracujesz w motywie potomnym, jego szablony mają pierwszeństwo przed szablonami motywu nadrzędnego. Zapomniany plik w motywie potomnym po cichu wygra z plikiem nadrzędnym, który właśnie edytujesz.

Szablony własne, które mają być wybieralne w edytorze wpisów, trzeba dodatkowo zadeklarować w theme.json w sekcji customTemplates — z nazwą bazową pliku, czytelnym tytułem i typami treści, których dotyczą. Bez tego wpisu plik istnieje, ale nigdy nie pojawi się w panelu Szablon.

Buforowanie — sprawdzaj na końcu

Buforowanie to realny problem, ale najmniej prawdopodobna przyczyna, a sięganie po nie w pierwszej kolejności to sposób na stracenie popołudnia.

Wyczyść bufor stron, a jeśli używasz trwałego bufora obiektów, takiego jak Redis czy Memcached, wyczyść również jego — wyniki rozstrzygania szablonów potrafią tam siedzieć. Potem przeładuj stronę z pominięciem bufora przeglądarki.

Co nie pomoże: czyszczenie OPcache. Szablony blokowe to pliki .html, których PHP nigdy nie kompiluje, więc OPcache nie ma z nimi nic wspólnego. Jeśli kiedyś wyczyszczenie OPcache pozornie to naprawiło, w tym samym momencie zmieniło się coś jeszcze.

Nadal nie działa?

Jeśli nie ma rekordu w bazie danych, nazwa pliku jest poprawna, wpis nie ma jawnie przypisanego szablonu, a bufory zostały wyczyszczone, przyjrzyj się wtyczkom. Wszystko, co filtruje rozstrzyganie szablonów — kreator stron, wtyczka członkowska, wtyczka wielojęzyczna, LMS — może podstawić własny szablon późno w trakcie żądania. Przełącz się na domyślny motyw blokowy i przetestuj z wyłączonymi wtyczkami, a potem włączaj je pojedynczo.

A jeśli szablon jest stosowany, ale renderuje się pusty, to już inny problem: sprawdź, czy znaczniki blokowe w pliku są poprawne, bo błędnie zapisany komentarz bloku potrafi sprawić, że edytor po cichu usunie treść, zamiast zgłosić błąd.