Skabeloner og dele til Site Editor fra filer
Et bloktema beskriver sit layout i templates/*.html og parts/*.html:
filer fulde af serialiserede blokkommentarer som
<!-- wp:template-part {"slug":"header"} /-->. Ingen har lyst til at skrive dem i hånden, så de bliver som regel oprettet i Site Editor og eksporteret. Det fungerer, indtil to personer redigerer den samme skabelon, eller en anmelder skal læse en diff med escape-behandlet JSON i kommentarer fra HTML.
Blockstudio lader dig skrive de samme skabeloner på den måde, du skriver filbaserede sider: en mappe med et lille JSON-manifest og en kildefil med markup i stil med HTML, der bruger almindelige elementer, tags fra <block> og dine egne Blockstudio-blokke.
Blockstudio kompilerer kilden til native blokmarkup og giver den til WordPress som en temafil. Site Editor fungerer stadig præcis som før: Brugere kan tilpasse en skabelon, og når den nulstilles, gendannes filversionen.
Denne vejledning opretter en header- og footerdel, skabeloner til forsiden og enkeltvisninger samt en brugerdefineret skabelon, som redaktører kan vælge til sider. Derefter viser den, hvordan WordPress finder dem.
Mappestruktur
Skabeloner placeres i templates/, og skabelondele i parts/. Hver er en mappe med et manifest og én kildefil:
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
Det er de samme mapper templates/ og parts/, som WordPress læser til et bloktema. Blockstudio gennemgår først det aktive tema og derefter det overordnede tema.
Mapper med template.json eller part.json er Blockstudio-kilder; almindelige .html-filer ved siden af dem forbliver native WordPress-skabeloner.
Kildefilen kan være index.php, index.blade.php, index.twig eller
index.html, i den rækkefølge. Twig kræver Timber, og Blade kræver sin renderer-pakke, som beskrevet i
Skabelonmotorer.
Trin 1: Headerdelen
Hver del kræver et part.json. area fortæller Site Editor, hvor delen hører til:
{
"slug": "header",
"title": "Header",
"description": "Site header with logo and navigation",
"area": "header"
}
Kilden bruger samme syntaks som Blockstudio-sider og mønstre. Et <div> bliver til en gruppeblok, attributter bliver til blokattributter, og <block>-elementer opretter den registrerede blok:
<div layout='{"type":"flex","justifyContent":"space-between"}'>
<block name="core/site-title" />
<block name="core/navigation" overlayMenu="mobile" />
</div>
Blockstudio kompilerer den til denne blokmarkup:
<!-- 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 -->
Det er det, du ellers skulle have skrevet i hånden. Dine egne blokke fungerer på samme måde: <block name="acme/announcement" />, et <bs:acme-announcement />-tag eller et konfigureret tagpræfiks kompileres alle til blokkommentaren for den pågældende blok.
Trin 2: Footerdelen
En del kan være så lille som ét afsnit. Denne bruger index.html til at understrege, at kilden er markup og ikke et program:
{
"slug": "footer",
"title": "Footer",
"area": "footer"
}
<p>Built with Acme.</p>
Den kompileres til <!-- wp:paragraph --><p>Built with Acme.</p><!-- /wp:paragraph -->.
Trin 3: Forside- og enkeltvisningsskabeloner
Skabeloner bruger template.json. slug skal være et præcist hierarkinavn for en WordPress-skabelon, f.eks. front-page, single, page, archive, 404 eller single-product. Blockstudio tilføjer aldrig præfiks til navnet.
{
"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" />
Skabelonen til enkeltindlæg følger samme struktur med indlægsblokke:
{
"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" />
Den kompilerede skabelon til enkeltindlæg:
<!-- 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> blev til en gruppeblok med tagName: "main", og skabelondelsblokkene henviser til delene fra trin 1 og 2 via slug. Når WordPress gengiver skabelonen, finder referencerne de filbaserede dele, så outputtet fra forsiden begynder med <header class="wp-block-template-part"> med webstedets titel og navigation og slutter med <footer class="wp-block-template-part"> med footerafsnittet.
Trin 4: En brugerdefineret skabelon til sider
Skabeloner med en slug, der ikke indgår i hierarkiet, er brugerdefinerede skabeloner. Angiv de indlægstyper, de gælder for, med postTypes, så kan redaktører vælge dem i skabelonvælgeren:
{
"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' ) omfatter nu page-landing, og skabelonobjektet indeholder post_types: ["page"].
Kilder kompileres én gang
Kilden læses og kompileres til blokmarkup én gang, ikke pr. anmodning. Den har intet aktuelt indlæg og ingen anmodningskontekst. index.php læses som markup: PHP-kode deri udføres ikke, så <?php echo get_bloginfo( 'name' ); ?> kompileres til ingenting. Alt, der afhænger af anmodningen, hører hjemme i en blok, der gengives ved kørsel: core/site-title i stedet for et udskrevet webstedsnavn, core/post-title i stedet for the_title() eller din egen dynamiske Blockstudio-blok.
De kompilerede resultater caches sammen med metadata til filovervågning. Redigering af et manifest eller en kildefil ugyldiggør det cachede indhold for det pågældende element, så den næste anmodning ser ændringen uden et separat buildtrin.
Sådan finder WordPress filerne
Blockstudio kobler sig på de samme opslag, som WordPress bruger til temaskabeloner. I get_block_templates() vises de filbaserede skabeloner med source: "theme" og origin: "theme", ligesom native temafiler, og get_block_template( 'acme//header', 'wp_template_part' ) returnerer headerdelen med dens area.
Opslagsrækkefølgen er:
- En tilpasning i Site Editor, som er gemt i databasen.
- En native
.html-fil i det aktive tema. - Den filbaserede kilde Blockstudio.
- Fallbacks fra overordnet tema eller plugin.
Denne rækkefølge bevarer arbejdsgangen i Site Editor. Når en bruger redigerer footeren og gemmer, gemmer WordPress et wp_template_part-indlæg, og get_block_template() returnerer tilpasningen med source: "custom".
Senere ændringer af parts/footer/index.html vises ikke, mens tilpasningen findes. Når brugeren nulstiller delen, eller indlægget slettes, falder opslaget tilbage til filen og returnerer den nyeste kompilerede kilde igen.
Blockstudio skriver ikke ændringer fra Site Editor tilbage til filer. Hvis en brugers ændring skal være den nye standard, skal du kopiere den til kildefilen og nulstille tilpasningen.
Indlejrede index.html og slugs
WordPress finder .html-filer rekursivt i templates/ og parts/. En manifestmappe, der bruger index.html, f.eks. parts/footer/index.html, vises derfor også som en native del med den stiafledte slug footer/index. Da Blockstudio 7.6.6, vises en manifestejet index.html kun under sin angivne slug, så Site Editor viser én footer, ikke to. Indlejrede .html-filer uden manifest lades urørte.
Kontrol af skabeloner fra PHP
Klassen Blockstudio\Site_Templates læser og kompilerer kilderne, hvilket er nyttigt ved test og udrulningskontrol:
$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();
Hvert element indeholder slug, title, description, type (wp_template eller wp_template_part), status, source_type, postTypes for skabeloner eller area for dele, meta og den kompilerede content. Angiv en liste for kun at kompilere udvalgte elementer, og læs problemerne for det udvalg med selection_errors():
$selected = Blockstudio\Site_Templates::templates( array( 'front-page' ) );
$errors = Blockstudio\Site_Templates::selection_errors( 'templates' );
Tilføjelse af andre mapper
Hvis du vil holde Blockstudio-kilder adskilt fra native skabeloner eller levere dem fra et plugin, kan du tilføje mapper til søgningen med filtre:
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;
} );
Filtrene blockstudio/site_templates/template_content og part_content justerer en kilde, før den fortolkes, og blockstudio/site_templates/parser udskifter fortolkeren for ét element. Den fulde liste findes i tabellen over hooks for Site Templates.
Hvornår skal du bruge hvad?
| Du ønsker | Brug |
|---|---|
| Det temalayout, som WordPress vælger til en URL: header, footer, enkeltvisning, arkiv | Webstedsskabeloner og dele |
| En webside med egen URL, hvis indhold ligger i filer | Filbaserede sider |
| En genanvendelig sektion, som redaktører indsætter | Mønstre |
Skabeloner opretter ikke indlæg. Det gør sider. En dokumentationssektion er for eksempel en samling sider, hvis indlæg gengives med en skabelon, du stadig kan oprette her.
Næste trin
- Reference til Site Templates: alle manifestegenskaber, PHP API og alle hooks.
- Oversigt over sider og mønstre: fortolkeren HTML, bloktags og elementtilknytningen, der bruges af skabelonkilder.
- Opbygning af et dokumentationswebsted: sidesamlinger med Markdown, loaders og layouts.