Szablony i części z plików w Edytorze witryny
Motyw blokowy opisuje układ w folderach templates/*.html i parts/*.html:
plikach pełnych zserializowanych komentarzy bloków, takich jak
<!-- wp:template-part {"slug":"header"} /-->. Nikt nie lubi pisać ich ręcznie,
więc zwykle tworzy się je w Edytorze witryny i eksportuje. To działa,
dopóki dwie osoby nie edytują tego samego szablonu albo recenzent nie musi czytać różnic w
zakodowanym JSON w komentarzach HTML.
Blockstudio pozwala tworzyć te same szablony tak jak strony oparte na plikach:
jako folder z niewielkim manifestem JSON i plikiem źródłowym ze znacznikami podobnymi do HTML, wykorzystującym zwykłe elementy, znaczniki <block> i własne bloki Blockstudio.
Blockstudio kompiluje źródło do natywnych znaczników bloków i przekazuje je do WordPress jako plik motywu. Edytor witryny nadal działa jak wcześniej: użytkownicy mogą dostosować szablon, a jego zresetowanie przywraca wersję z pliku.
W tym przewodniku utworzymy część nagłówka i stopki, szablony strony głównej i pojedynczego wpisu oraz własny szablon, który redaktorzy mogą wybierać dla stron, a następnie pokażemy, jak WordPress je wyszukuje.
Struktura folderów
Szablony umieszcza się w templates/, a części szablonów w parts/. Każdy z nich to folder zawierający manifest i jeden plik źródłowy:
theme/
├── templates/
│ ├── front-page/
│ │ ├── template.json
│ │ └── index.php
│ ├── single/
│ │ ├── template.json
│ │ └── index.php
│ └── page-landing/
│ ├── template.json
│ └── index.php
└── parts/
├── header/
│ ├── part.json
│ └── index.php
└── footer/
├── part.json
└── index.html
Są to te same foldery templates/ i parts/, które WordPress odczytuje dla motywu blokowego. Blockstudio najpierw przeszukuje aktywny motyw, a następnie motyw nadrzędny.
Foldery z plikiem template.json lub part.json są źródłami Blockstudio; zwykłe pliki .html obok nich pozostają natywnymi szablonami WordPress.
Plik źródłowy może być plikiem index.php, index.blade.php, index.twig lub index.html; są one sprawdzane w tej kolejności. Twig wymaga Timber, a Blade wymaga pakietu renderującego opisanego w sekcji Silniki szablonów.
Krok 1: Część nagłówka
Każda część wymaga part.json. area wskazuje Edytorowi witryny, gdzie należy umieścić tę część:
{
"slug": "header",
"title": "Header",
"description": "Site header with logo and navigation",
"area": "header"
}
Źródło korzysta z tej samej składni co strony i wzorce Blockstudio. Element <div> staje się blokiem grupy, atrybuty stają się atrybutami bloku, a elementy <block> tworzą dowolny zarejestrowany blok:
<div layout='{"type":"flex","justifyContent":"space-between"}'>
<block name="core/site-title" />
<block name="core/navigation" overlayMenu="mobile" />
</div>
Blockstudio kompiluje go do tych znaczników bloków:
<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} --><div class="wp-block-group is-layout-flex"><!-- wp:site-title /--><!-- wp:navigation {"overlayMenu":"mobile"} /--></div><!-- /wp:group -->
To właśnie w przeciwnym razie trzeba byłoby wpisać ręcznie. Własne bloki działają tak samo: <block name="acme/announcement" />, znacznik <bs:acme-announcement /> lub skonfigurowany prefiks znacznika kompilują się do komentarza bloku dla danego bloku.
Krok 2: Część stopki
Część może składać się nawet z jednego akapitu. Ta wykorzystuje index.html, aby pokazać, że źródło jest znacznikami, a nie programem:
{
"slug": "footer",
"title": "Footer",
"area": "footer"
}
<p>Built with Acme.</p>
Kompiluje się do <!-- wp:paragraph --><p>Built with Acme.</p><!-- /wp:paragraph -->.
Krok 3: Szablony strony głównej i pojedynczego wpisu
Szablony korzystają z template.json. Wartość slug musi być dokładną nazwą hierarchii szablonów WordPress, na przykład front-page, single, page, archive, 404 lub single-product. Blockstudio nigdy nie dodaje jej prefiksu.
{
"slug": "front-page",
"title": "Front Page",
"description": "Homepage template"
}
<block name="core/template-part" slug="header" tagName="header" />
<main>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
Szablon pojedynczego wpisu ma taką samą strukturę, ale wykorzystuje bloki wpisu:
{
"slug": "single",
"title": "Single Post"
}
<block name="core/template-part" slug="header" tagName="header" />
<main>
<block name="core/post-title" level="1" />
<block name="core/post-date" />
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
Skompilowany szablon pojedynczego wpisu:
<!-- wp:template-part {"slug":"header","tagName":"header"} /--><!-- wp:group {"tagName":"main"} --><main class="wp-block-group"><!-- wp:post-title {"level":1} /--><!-- wp:post-date /--><!-- wp:post-content /--></main><!-- /wp:group --><!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
<main> stał się blokiem grupy z tagName: "main", a bloki części szablonu odwołują się do części z kroków 1 i 2 za pomocą identyfikatorów slug. Gdy WordPress renderuje szablon, te odwołania wskazują części oparte na plikach, więc wynik strony głównej zaczyna się od <header class="wp-block-template-part"> zawierającego tytuł witryny i nawigację, a kończy na <footer class="wp-block-template-part"> zawierającym akapit stopki.
Krok 4: Własny szablon stron
Szablony, których identyfikatory slug nie należą do hierarchii, są szablonami własnymi. Wartością postTypes określ typy wpisów, do których mają zastosowanie, a redaktorzy będą mogli wybierać je w selektorze szablonów:
{
"slug": "page-landing",
"title": "Landing Page",
"description": "Full-width page without a header",
"postTypes": ["page"]
}
<main>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
get_block_templates( array( 'post_type' => 'page' ), 'wp_template' ) zawiera teraz page-landing, a obiekt szablonu ma właściwość post_types: ["page"].
Źródła są kompilowane tylko raz
Źródło jest odczytywane i kompilowane do znaczników bloków raz, a nie przy każdym żądaniu. Nie ma bieżącego wpisu ani kontekstu żądania. index.php jest odczytywane jako znaczniki: znajdujący się w nim kod PHP nie jest wykonywany, więc <?php echo get_bloginfo( 'name' ); ?> kompiluje się do pustego wyniku. Wszystko, co zależy od żądania, należy umieścić w bloku renderowanym w czasie działania: core/site-title zamiast wypisanej nazwy witryny, core/post-title zamiast the_title() albo we własnym dynamicznym bloku Blockstudio.
Skompilowane wyniki są buforowane wraz z metadanymi monitorowania plików. Edycja manifestu lub pliku źródłowego unieważnia buforowaną zawartość danego elementu, więc przy następnym żądaniu zmiana będzie widoczna bez osobnego kroku kompilacji.
Jak WordPress widzi pliki
Blockstudio korzysta z tych samych mechanizmów wyszukiwania co WordPress dla szablonów motywów. W get_block_templates() szablony oparte na plikach pojawiają się wraz z source: "theme" i origin: "theme", tak jak natywne pliki motywu, a get_block_template( 'acme//header', 'wp_template_part' ) zwraca część nagłówka wraz z jej area.
Kolejność wyszukiwania:
- Dostosowanie w Edytorze witryny zapisane w bazie danych.
- Natywny plik
.htmlw aktywnym motywie. - Źródło oparte na plikach Blockstudio.
- Zapasowe źródła z motywu nadrzędnego lub wtyczki.
Ta kolejność pozwala zachować dotychczasowy sposób pracy z Edytorem witryny. Gdy użytkownik edytuje stopkę i zapisuje zmiany, WordPress zapisuje wpis wp_template_part, a get_block_template() zwraca to dostosowanie wraz z source: "custom".
Późniejsze zmiany w parts/footer/index.html nie będą widoczne, dopóki istnieje to dostosowanie. Gdy użytkownik zresetuje część lub wpis zostanie usunięty, mechanizm wyszukiwania korzysta z pliku i ponownie zwraca najnowsze skompilowane źródło.
Blockstudio nie zapisuje zmian wprowadzonych w Edytorze witryny z powrotem do plików. Jeśli zmiana użytkownika ma stać się nową wartością domyślną, skopiuj ją do pliku źródłowego i zresetuj dostosowanie.
Zagnieżdżone index.html i identyfikatory slug
WordPress rekurencyjnie wyszukuje pliki .html w templates/ i parts/. Folder manifestu zawierający index.html, na przykład parts/footer/index.html, pojawi się więc także jako natywna część z identyfikatorem slug wynikającym ze ścieżki: footer/index. Ponieważ Blockstudio 7.6.6, część należąca do manifestu index.html jest widoczna wyłącznie pod zadeklarowanym identyfikatorem slug, dlatego Edytor witryny wyświetla jedną stopkę, a nie dwie. Zagnieżdżone pliki .html bez manifestu są pozostawiane bez zmian.
Sprawdzanie szablonów z PHP
Klasa Blockstudio\Site_Templates odczytuje i kompiluje źródła, co przydaje się w testach i podczas sprawdzania wdrożenia:
$templates = Blockstudio\Site_Templates::templates();
$header = Blockstudio\Site_Templates::get_part( 'header' );
echo $header['area']; // header
echo $header['content']; // compiled block markup
$errors = Blockstudio\Site_Templates::errors();
Każdy element zawiera slug, title, description, type (wp_template lub wp_template_part), status, source_type, postTypes w przypadku szablonów lub area w przypadku części, meta oraz skompilowane content. Przekaż listę, aby skompilować tylko wybrane elementy, i odczytaj problemy dotyczące tego wyboru za pomocą selection_errors():
$selected = Blockstudio\Site_Templates::templates( array( 'front-page' ) );
$errors = Blockstudio\Site_Templates::selection_errors( 'templates' );
Dodawanie innych folderów
Aby oddzielić źródła Blockstudio od natywnych szablonów lub dostarczać je z wtyczki, dodaj katalogi wyszukiwania z filtrami:
add_filter( 'blockstudio/site_templates/template_paths', function ( $paths ) {
$paths[] = get_stylesheet_directory() . '/site-templates';
return $paths;
} );
add_filter( 'blockstudio/site_templates/part_paths', function ( $paths ) {
$paths[] = get_stylesheet_directory() . '/site-parts';
return $paths;
} );
Filtry blockstudio/site_templates/template_content i part_content modyfikują źródło przed jego przetworzeniem, a blockstudio/site_templates/parser zastępuje parser dla jednego elementu. Pełną listę znajdziesz w tabeli hooków Szablonów witryny.
Kiedy użyć poszczególnych rozwiązań
| Czego potrzebujesz | Użyj |
|---|---|
| Układu motywu WordPress dla URL: nagłówka, stopki, pojedynczego wpisu lub archiwum | Szablonów i części witryny |
| Strony z własnym adresem, której treść znajduje się w plikach | Strony oparte na plikach |
| Wielokrotnego użytku sekcji wstawianej przez redaktorów | Wzorca |
Szablony nie tworzą wpisów. Robią to strony. Na przykład sekcja dokumentacji to zbiór stron, których wpisy są renderowane przy użyciu szablonu, który nadal możesz tworzyć tutaj.
Następne kroki
- Dokumentacja szablonów witryny: wszystkie właściwości manifestu, PHP API i wszystkie hooki.
- Przegląd stron i wzorców: parser HTML, znaczniki bloków i mapowanie elementów używane w źródłach szablonów.
- Tworzenie witryny dokumentacji: zbiory stron z użyciem Markdown, funkcji ładujących dane i układów.