Przejdź do treści

Szablony witryny

Szablony witryny pozwalają motywom blokowym definiować źródła WordPress wp_template i wp_template_part przy użyciu tej samej składni opartej na plikach co Blockstudio strony i wzorce.

Używaj szablonów witryny, gdy chcesz kontrolować układ motywu wybierany przez WordPress za pomocą hierarchii szablonów Edytora witryny: strony głównej, pojedynczych wpisów, archiwów, wyników wyszukiwania, stron 404, nagłówków, stopek i innych części szablonu.

Strony, wzorce czy szablony witryny?

Funkcja Tworzy Najlepsze zastosowanie
Strony Wpisy lub elementy własnego typu wpisu Rzeczywiste strony z treścią, strony dokumentacji, strony docelowe i treści dostępne pod adresami URL.
Wzorce Wzorce bloków Wielokrotnego użytku sekcje wstawiane przez redaktorów.
Szablony witryny wp_template i źródła plików wp_template_part Układ motywu kontrolowany przez Edytor witryny i hierarchię szablonów WordPress.

Szablony witryny nie tworzą zwykłych stron. Dostarczają źródło plikowe używane przez WordPress podczas rozpoznawania szablonu motywu blokowego. Jeśli użytkownik dostosuje szablon w Edytorze witryny, WordPress zapisuje te zmiany w bazie danych i mają one pierwszeństwo przed źródłem plikowym do czasu zresetowania.

Struktura folderów

Umieść pełne szablony w templates/, a części szablonów w parts/:

Text
theme/
  templates/
    front-page/
      template.json
      index.php
    single/
      template.json
      index.twig
  parts/
    header/
      part.json
      index.php
    footer/
      part.json
      index.php

Każdy folder zawiera manifest i jeden plik źródłowy.

Plik Silnik
index.php Znaczniki bloków podobne do HTML, wczytywane bez zmian (kod PHP nie jest wykonywany)
index.blade.php Blade
index.twig Twig
index.html Znaczniki bloków podobne do HTML

Jeśli istnieje kilka plików źródłowych, Blockstudio stosuje następującą kolejność:

  1. index.php
  2. index.blade.php
  3. index.twig
  4. index.html

WordPress wykrywa także rekurencyjnie pliki .html i zwykle udostępnia zagnieżdżone index.html pod wynikającym ze ścieżki identyfikatorem, takim jak header/index. Gdy ten plik należy do manifestu Blockstudio, Blockstudio usuwa duplikat wynikający ze ścieżki i udostępnia tylko zadeklarowane w manifeście slug. Natywne zagnieżdżone szablony .html bez manifestu Blockstudio pozostają bez zmian.

Źródło jest kompilowane raz do natywnych znaczników bloków WordPress. Nie powinno zależeć od bieżącego żądania ani wpisu. Umieszczaj logikę środowiska uruchomieniowego w blokach dynamicznych.

template.json

template.json definiuje pełny szablon Edytora witryny.

JSON
{
  "slug": "front-page",
  "title": "Front Page",
  "description": "Homepage template",
  "postTypes": ["page"]
}

Właściwości

Właściwość Typ Domyślna wartość Opis
slug / name string Nazwa folderu Identyfikator szablonu WordPress. Używaj dokładnych identyfikatorów z hierarchii, takich jak front-page, single, archive-product lub 404.
title string Tytuł z identyfikatora Tytuł wyświetlany w Edytorze witryny.
description string "" Opis wyświetlany w Edytorze witryny.
postTypes string[] [] Typy wpisów dla szablonów własnych. Można pominąć wbudowane szablony hierarchii.
source / template / file string Automatycznie wykrywany plik indeksu Opcjonalna ścieżka do pliku źródłowego względem folderu szablonu.
status string "publish" Status szablonu.
sync boolean false Zarezerwowane na przyszłe zapisywanie w bazie danych. Zmiany użytkownika nigdy nie są nadpisywane w v1.
meta object {} Własne metadane dla API pomocniczych. Nieznane klucze manifestu są również przechowywane tutaj.

Identyfikatory szablonów nie mają prefiksów. WordPress wymaga dokładnych nazw na potrzeby hierarchii szablonów:

Text
index
home
front-page
single
single-post
single-product
archive
archive-product
page
page-about
404
search
taxonomy-product_cat

part.json

part.json definiuje część szablonu Edytora witryny.

JSON
{
  "slug": "header",
  "title": "Header",
  "description": "Main site header",
  "area": "header"
}

Właściwości

Właściwość Typ Domyślna wartość Opis
slug / name string Nazwa folderu Identyfikator części szablonu WordPress.
title string Tytuł z identyfikatora Tytuł wyświetlany w Edytorze witryny.
description string "" Opis wyświetlany w Edytorze witryny.
area string "uncategorized" Obszar części szablonu. Typowe wartości to header, footer i sidebar.
source / template / file string Automatycznie wykrywany plik indeksu Opcjonalna ścieżka do pliku źródłowego względem folderu części.
status string "publish" Status części szablonu.
meta object {} Własne metadane dla API pomocniczych. Nieznane klucze manifestu są również przechowywane tutaj.

Składnia znaczników

Źródła szablonów witryny korzystają z tego samego parsera co strony i wzorce:

PHP
<div class="site-shell">
  <block name="core/template-part" slug="header" />

  <main>
    <h1>Welcome</h1>
    <p>This template is compiled from Blockstudio files.</p>
    <block name="core/post-content" />
  </main>

  <block name="core/template-part" slug="footer" />
</div>

Element <main> staje się blokiem core/group renderowanym jako <main>, a jego elementy podrzędne, w tym znacznik bloku core/post-content, stają się blokami wewnętrznymi. Możesz używać:

  • standardowych elementów HTML, takich jak <h1>, <p>, <ul>, <div>, oraz elementów sekcyjnych <main>, <header>, <footer>, <article> i <aside>
  • <block name="namespace/block">
  • <bs:namespace-block>
  • skonfigurowanych prefiksów znaczników bloków
  • bloków i komponentów Blockstudio

Gdy WordPress renderuje skompilowany szablon, bloki części szablonu otrzymują atrybut aktywnego motywu.

Dostosowania w Edytorze witryny

Blockstudio dostarcza źródło plikowe. WordPress przechowuje zmiany użytkownika.

Kolejność wyszukiwania:

  1. Dostosowanie zapisane w bazie danych Edytora witryny
  2. Natywny plik motywu aktywnego .html
  3. Źródło plikowe Blockstudio
  4. Zapasowe źródła motywu nadrzędnego lub wtyczki

Gdy użytkownik zapisuje w Edytorze witryny szablon oparty na pliku Blockstudio, WordPress tworzy zwykły wpis wp_template lub wp_template_part w bazie danych. Ten zapisany wpis ma pierwszeństwo przed przyszłymi zmianami pliku. Zresetowanie lub usunięcie dostosowania ponownie udostępnia najnowsze źródło plikowe.

Blockstudio nie zapisuje zmian wprowadzonych w Edytorze witryny z powrotem do plików w v1.

Wydajność

Wykrywanie szablonów jest buforowane na czas żądania, a dane o obserwowanych plikach są utrwalane. Zmiana manifestu lub pliku źródłowego unieważnia buforowaną skompilowaną treść. Dostosowania zapisane w bazie danych nie są buforowane: WordPress nadal sprawdza je w pierwszej kolejności.

Integracje środowiska uruchomieniowego, które łączą pliki z kilku katalogów głównych, mogą dostarczyć logiczne źródło wykrywania szablonów i ich części. Manifesty i wybrane szablony źródłowe mogą znajdować się w różnych katalogach fizycznych, zachowując przy tym jedno logiczne drzewo motywu.

PHP API

PHP
$templates = Blockstudio\Site_Templates::templates();
$parts = Blockstudio\Site_Templates::parts();

$template = Blockstudio\Site_Templates::get_template('front-page');
$header = Blockstudio\Site_Templates::get_part('header');

$paths = Blockstudio\Site_Templates::get_paths();

Przekaż jawną listę, aby odczytać i skompilować tylko dokładne identyfikatory, ścieżki lub ścieżki źródłowe:

PHP
$templates = Blockstudio\Site_Templates::templates([
    'front-page',
]);

$parts = Blockstudio\Site_Templates::parts([
    'header',
]);

$errors = Blockstudio\Site_Templates::selection_errors('templates');

Pominięcie argumentu zachowuje pełne działanie rejestru. Przekazanie pustej listy zwraca zero elementów. Żądania ze standardowymi identyfikatorami i ścieżkami zawężają wykrywanie do pasujących katalogów; własne identyfikatory z manifestu mogą wymagać skanowania metadanych, ale niezwiązane źródła nadal nie są kompilowane ani zwracane.

Dostępne są również funkcje pomocnicze szablonów:

PHP
blockstudio_site_templates();
blockstudio_site_template_parts();
blockstudio_site_template('front-page');
blockstudio_site_template_part('header');

Hooki

Pełny zakres rozszerzeń szablonów witryny:

Hook Typ Opis
blockstudio/site_templates/template_paths Filtr Dostosowuje katalogi główne wykrywania pełnych szablonów.
blockstudio/site_templates/part_paths Filtr Dostosowuje katalogi główne wykrywania części szablonów.
blockstudio/site_templates/paths Filtr Dostosowuje obie listy ścieżek jako templates i parts.
blockstudio/site_templates/template_candidates Filtr Dostosowuje kandydatów na pliki źródłowe dla manifestu.
blockstudio/site_templates/templates Filtr Dostosowuje szablony zwracane przez metodę API rejestru.
blockstudio/site_templates/parts Filtr Dostosowuje części szablonów zwracane przez metodę API rejestru.
blockstudio/site_templates/template_content Filtr Dostosowuje skompilowane źródło pełnego szablonu przed analizą.
blockstudio/site_templates/part_content Filtr Dostosowuje skompilowane źródło części szablonu przed analizą.
blockstudio/site_templates/parser Filtr Zastępuje obiekt Html_Parser dla jednego elementu.
blockstudio/site_templates/source_compiled Akcja Uruchamia się bezpośrednio przed kompilacją jednego wybranego źródła.
blockstudio/site_templates/discovered Akcja Uruchamia się po pełnym przebiegu wykrywania i kompilacji bez użycia pamięci podręcznej.
blockstudio/site_templates/registered Akcja Uruchamia się po utrwaleniu odbudowanego rejestru.

Dodaj lub zastąp ścieżki wykrywania:

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;
});

add_filter('blockstudio/site_templates/paths', function ($paths) {
    return $paths;
});

Filtruj wykryte dane:

PHP
add_filter('blockstudio/site_templates/templates', function ($templates) {
    return $templates;
});

add_filter('blockstudio/site_templates/parts', function ($parts) {
    return $parts;
});

Filtruj źródło przed analizą:

PHP
add_filter('blockstudio/site_templates/template_content', function ($content, $template) {
    return $content;
}, 10, 2);

add_filter('blockstudio/site_templates/part_content', function ($content, $part) {
    return $content;
}, 10, 2);

Zmień kandydatów na źródła lub parser:

PHP
add_filter(
    'blockstudio/site_templates/template_candidates',
    function ($candidates, $directory, $manifest) {
        $candidates[] = $directory . '/template.custom.php';
        return $candidates;
    },
    10,
    3
);

add_filter(
    'blockstudio/site_templates/parser',
    function ($parser, $item) {
        return $parser;
    },
    10,
    2
);

discovered i registered to akcje cyklu życia odbudowy pamięci podręcznej. Nie uruchamiają się przy trafieniu w ciepłą pamięć podręczną rejestru.