Przejdź do treści

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:

Kod
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ęść:

JSON
{
  "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:

PHP
<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:

HTML
<!-- 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.

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:

JSON
{
  "slug": "footer",
  "title": "Footer",
  "area": "footer"
}
HTML
<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.

JSON
{
  "slug": "front-page",
  "title": "Front Page",
  "description": "Homepage template"
}
PHP
<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:

JSON
{
  "slug": "single",
  "title": "Single Post"
}
PHP
<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:

HTML
<!-- 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:

JSON
{
  "slug": "page-landing",
  "title": "Landing Page",
  "description": "Full-width page without a header",
  "postTypes": ["page"]
}
PHP
<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:

  1. Dostosowanie w Edytorze witryny zapisane w bazie danych.
  2. Natywny plik .html w aktywnym motywie.
  3. Źródło oparte na plikach Blockstudio.
  4. 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:

PHP
$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():

PHP
$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:

PHP
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