Vytváření stránek ze souborů
Tvorba tradičních stránek WordPress probíhá v editoru bloků: přetahujete bloky, nastavujete jejich možnosti a klikáte na Uložit. To vyhovuje klientům, kteří si vytvářejí vlastní stránky, ale vývojářům, kteří vytvářejí strukturované stránky se správou verzí, to přináší problémy. Rozvržení stránky je v databázi, ne v kódu. Nemůžete ho zkontrolovat v pull requestu, vrátit pomocí git ani znovu vytvořit při čisté instalaci.
Stránky založené na souborech v Blockstudio tento problém řeší. Stránky definujete jako soubory ve svém motivu, píšete šablony HTML, které se převádějí na bloky WordPress, a přesně určujete, co klienti mohou a nemohou upravovat. Výslovný příkaz synchronizuje tyto soubory s běžnými příspěvky WordPress a vaše šablony zůstávají hlavním zdrojem pravdy.
Tento průvodce vás provede tvorbou stránek od začátku. Podrobně se zaměřuje na ovládací prvky zamykání a úprav, díky nimž lze stránky založené na souborech prakticky využít v klientských projektech.
První stránka
Vytvořte ve svém motivu složku pages a přidejte do ní podsložku se dvěma soubory:
theme/
└── pages/
└── about/
├── page.json
└── index.php
{
"name": "about",
"title": "About Us",
"postStatus": "publish"
}
<h1>About Us</h1>
<p>We build things for the web.</p>
Spusťte příkaz pro synchronizaci stránek:
wp bs pages sync
Blockstudio zpracuje HTML na bloky WordPress a vytvoří stránku s názvem
„O nás“ a slugem about. Otevřete ji v editoru a uvidíte nadpis a odstavec,
přesně jako kdybyste je přidali ručně.
Upravte index.php, změňte text a příkaz spusťte znovu. Po obnovení editoru
uvidíte aktualizaci. Takto vypadá základní postup: napište HTML, synchronizujte záměrně a získejte bloky.
Jazyk šablon
Parser HTML v Blockstudio převádí standardní prvky HTML na bloky WordPress. Napište <p> a získáte blok odstavce. Napište <h2> a získáte blok nadpisu. Převod je intuitivní:
| HTML | Blok |
|---|---|
<p> |
Odstavec |
<h1> až <h6> |
Nadpis (úroveň odpovídá značce) |
<ul>, <ol> |
Seznam |
<blockquote> |
Citace |
<img> |
Obrázek |
<div>, <section> |
Skupina |
<hr> |
Oddělovač |
<details> |
Podrobnosti |
<table> |
Tabulka |
U bloků bez přímého ekvivalentu HTML použijte prvek <block> s atributem name:
<block name="core/cover" url="https://example.com/hero.jpg">
<h2>Hero Title</h2>
<p>Content over the background image.</p>
</block>
<block name="core/spacer" height="80px" />
<block name="core/buttons">
<block name="core/button" url="/contact">Get in Touch</block>
<block name="core/button" url="/work">See Our Work</block>
</block>
Atributy prvků <block> se předávají jako atributy bloku. Hodnoty se automaticky převádějí: "true" se změní na logickou hodnotu, "3" na celé číslo a řetězce JSON, například '{"type":"flex"}', se dekódují na objekty.
Rozvržení
Skupiny podporují různé režimy rozvržení pomocí atributu layout:
<!-- Default group (stacked) -->
<div>
<p>Stacked by default.</p>
</div>
<!-- Row (horizontal flex) -->
<block name="core/group" layout='{"type":"flex","flexWrap":"nowrap"}'>
<p>Side</p>
<p>by side</p>
</block>
<!-- Stack (vertical flex) -->
<block name="core/group" layout='{"type":"flex","orientation":"vertical"}'>
<p>Stacked</p>
<p>with flex</p>
</block>
<!-- Columns -->
<block name="core/columns">
<block name="core/column">
<p>Left column.</p>
</block>
<block name="core/column">
<p>Right column.</p>
</block>
</block>
Vlastní bloky
Zápis <block> funguje u libovolného registrovaného bloku, včetně vašich vlastních bloků Blockstudio:
<block name="my-theme/hero" title="Welcome" background="dark" />
<block name="my-theme/testimonial" quote="Great product." author="Jane" />
Atributy se automaticky přiřadí k hodnotám polí Blockstudio bloku.
Vytvoření vstupní stránky
Zde je kompletní vstupní stránka, která pro strukturu a rozvržení používá základní bloky:
{
"name": "landing",
"title": "Landing Page",
"slug": "landing",
"postStatus": "publish",
"templateLock": "all"
}
<block name="core/cover" url="https://images.unsplash.com/photo-1497366216548-37526070297c?w=1600">
<h1>Build faster with Blockstudio</h1>
<p>File-based blocks. Zero build step. Full editor integration.</p>
<block name="core/buttons">
<block name="core/button" url="/get-started">Get Started</block>
<block name="core/button" url="/docs">Documentation</block>
</block>
</block>
<div>
<h2>Why developers love it</h2>
<block name="core/columns">
<block name="core/column">
<h3>No build step</h3>
<p>Write PHP, CSS, and JavaScript. No webpack, no bundler, no transpiler.</p>
</block>
<block name="core/column">
<h3>File-based</h3>
<p>Every block is a folder. Every page is a template. Version control everything.</p>
</block>
<block name="core/column">
<h3>Full editor support</h3>
<p>Fields, previews, and InnerBlocks work in the block editor out of the box.</p>
</block>
</block>
</div>
<block name="core/media-text" mediaurl="https://images.unsplash.com/photo-1460925895917-afdab827c52f?w=800" mediatype="image">
<h2>Ship entire sites from your IDE</h2>
<p>Define pages, blocks, and patterns as files. Blockstudio handles the rest.</p>
</block>
<div>
<h2>Frequently asked questions</h2>
<details>
<summary>Do I need to learn React?</summary>
<p>No. Templates are PHP. Fields are JSON. Interactivity is optional.</p>
</details>
<details>
<summary>Does it work with my existing theme?</summary>
<p>Yes. Drop a blockstudio folder into any theme and start creating blocks.</p>
</details>
</div>
<div>
<block name="core/buttons">
<block name="core/button" url="/get-started">Start Building</block>
</block>
</div>
Tato stránka obsahuje úvodní oblast hero s překryvným obrázkem, mřížku funkcí se třemi sloupci, sekci s médii a textem, rozbalovací části s častými dotazy a CTA. To vše v jediném souboru HTML. Hodnota templateLock: "all" v page.json znamená, že klient nemůže nic měnit. Následující část vysvětluje, jak omezení uvolnit.
Ovládání editoru
Právě tady se stránky založené na souborech stávají opravdu užitečnými. Blockstudio vám nabízí dvě nezávislá nastavení: uzamčení šablony a režim úprav bloků. Společně vám umožňují přesně určit, které části stránky mohou klienti upravovat. Uzamkněte strukturu, ale povolte úpravy textu. Některé sekce zmrazte a jiné ponechte zcela otevřené. Vytvořte stránku, na které klient může pouze vyplnit tři konkrétní nadpisy.
Uzamčení šablony
Vlastnost templateLock v page.json řídí úpravy struktury: zda lze bloky přidávat, odebírat nebo přesouvat.
"all" (výchozí)
{
"name": "terms",
"templateLock": "all"
}
Nejpřísnější uzamčení. Klienti nemohou přidávat, odebírat ani přesouvat bloky. Nemohou ani upravovat obsah bloků (pokud není kombinováno s blockEditingMode). Toto je výchozí nastavení, pokud žádnou hodnotu neurčíte.
Kdy použít: Právní stránky, obchodní podmínky, zásady ochrany osobních údajů. Jakékoli stránky, jejichž obsah se má měnit pouze prostřednictvím kódu.
"insert"
{
"name": "about",
"templateLock": "insert"
}
Klienti nemohou bloky přidávat ani odebírat, ale mohou přesouvat stávající bloky a upravovat jejich obsah. Počet bloků zůstává stejný, jejich pořadí je však možné měnit.
Kdy použít: Stránky, na kterých chcete pevně danou sadu sekcí, ale klient by měl mít možnost měnit jejich pořadí. Například portfolio s předem stanoveným počtem sekcí, jejichž pořadí určuje klient.
"contentOnly"
{
"name": "homepage",
"templateLock": "contentOnly"
}
Klienti mohou upravovat textový obsah, ale nemohou přidávat, odebírat ani přesouvat bloky. Rozdíl oproti "all" spočívá v tom, že "all" také brání úpravám obsahu, zatímco "contentOnly" je výslovně povoluje.
Kdy použít: Nejčastější volba pro stránky určené klientům. Vývojář řídí rozvržení, klient doplňuje text.
false
{
"name": "blog",
"templateLock": false
}
Bez jakéhokoli uzamčení. Klienti mají plnou kontrolu: mohou přidávat, odebírat, přesouvat a upravovat libovolné bloky. Šablona poskytne počáteční strukturu, ale další úpravy jsou na klientovi.
Kdy použít: Stránky se seznamem článků, volně uspořádané obsahové stránky nebo jakékoli stránky, kde má mít klient úplnou redakční volnost.
Režim úprav bloků
Zatímco templateLock řídí strukturu (přidávání, odebírání, přesouvání), blockEditingMode řídí práci s jednotlivými bloky: zda je lze vybrat, nastavit nebo vůbec upravovat.
Nastavte výchozí hodnotu pro celou stránku v page.json:
{
"name": "landing",
"templateLock": "all",
"blockEditingMode": "disabled"
}
"default"
Plné úpravy. Bloky lze vybrat, měnit jejich nastavení a upravovat jejich obsah. Jde o běžné prostředí editoru.
"contentOnly"
Bloky lze upravovat, ale pouze jejich textový obsah. Nelze otevřít nastavení bloku, měnit barvy, upravovat vnitřní odsazení ani měnit jiné atributy než ty obsahové. Panel nástrojů bloku zobrazuje pouze možnosti formátování textu.
"disabled"
Bloky jsou zcela neinteraktivní. V editoru se zobrazují, ale nelze na ně kliknout, vybrat je ani jakkoli upravovat. Klient vidí obsah, ale nemůže s ním pracovat.
Přepsání nastavení jednotlivých prvků
A tady to začíná být zajímavé. Nastavení blockEditingMode pro celou stránku určuje výchozí režim pro každý blok, ale u jednotlivých prvků v šabloně ho můžete přepsat:
{
"name": "landing",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<block name="core/cover" url="https://example.com/hero.jpg">
<h1 blockEditingMode="contentOnly">Edit This Heading</h1>
<p blockEditingMode="contentOnly">Edit this paragraph too.</p>
</block>
<div>
<h2>Features</h2>
<p>This paragraph cannot be edited (inherits "disabled").</p>
<p blockEditingMode="contentOnly">But this one can.</p>
</div>
<block name="core/buttons">
<block name="core/button" url="/contact">This button is frozen</block>
</block>
Výchozí režim stránky je "disabled", takže každý blok je zpočátku neinteraktivní. Konkrétní prvky pak mohou výslovně povolit režim "contentOnly", který umožní upravovat pouze jejich text. Výsledkem je stránka, na níž klient může vyplnit přesně dvě textová pole (nadpis a odstavec úvodní části) a jeden odstavec s funkcemi. Vše ostatní je uzamčeno.
Funguje to u libovolného prvku HTML (<h1>, <p>, <div> atd.) i u prvků <block>. U konkrétních prvků můžete také nastavit blockEditingMode="default" a povolit plný přístup k úpravám:
<block name="core/buttons" blockEditingMode="default">
<block name="core/button" url="/contact">Fully editable button</block>
</block>
Klient teď může změnit text tlačítka, URL, styly i jakékoli další nastavení. Vše ostatní na stránce zůstane uzamčeno.
Kaskáda nadřazených bloků
Při přepisování nastavení jednotlivých prvků je důležité, jak tato nastavení spolupracují s bloky kontejnerů. Pokud je výchozí režim stránky "disabled" a u nadpisu ve skupině nastavíte blockEditingMode="contentOnly", musí být možné se k nadpisu dostat. Jeho nadřazená skupina je však "disabled", takže do ní vůbec nelze vstoupit.
Blockstudio to řeší automaticky. Když má podřízený blok přepsaný režim úprav, všechny jeho nadřazené bloky se nastaví na "contentOnly", aby podřízený blok zůstal přístupný. Režimy nadřazených kontejnerů nemusíte nastavovat ručně. Stačí přepsat nastavení bloku, který chcete upravovat, a otevře se k němu cesta.
<!-- page default: "disabled" -->
<div>
<!-- this group is auto-set to "contentOnly" because it contains an override -->
<div>
<!-- this group is also auto-set to "contentOnly" -->
<p blockEditingMode="contentOnly">Deeply nested but still editable.</p>
</div>
</div>
Kaskáda nadřazených bloků povyšuje kontejnery pouze na "contentOnly", nikdy na "default". Nadřazené skupiny tedy lze procházet (vstupovat do nich), ale nelze je plně upravovat (měnit jejich nastavení).
Matice rozhodování
Kombinací templateLock a blockEditingMode získáte různou míru kontroly. Tady jsou nejužitečnější kombinace:
Vývojář řídí vše
{ "templateLock": "all" }
blockEditingMode není potřeba. Výchozí templateLock: "all" brání všem změnám. Použijte pro stránky spravované výhradně prostřednictvím kódu.
Klient upravuje veškerý text
{ "templateLock": "contentOnly" }
Klient může upravovat text v libovolném bloku, ale nemůže měnit strukturu stránky. Jednoduché a vstřícné řešení.
Klient upravuje pouze konkrétní text
{
"templateLock": "all",
"blockEditingMode": "disabled"
}
V kombinaci s blockEditingMode="contentOnly" u konkrétních prvků šablony. Jde o nejpřesnější možnost: klient může upravovat jen bloky, které výslovně označíte.
Klient mění pořadí pevných sekcí
{ "templateLock": "insert" }
Klient může přesouvat sekce a upravovat obsah, ale nemůže bloky přidávat ani odstraňovat. Vhodné pro stránky s pevně danými sekcemi, jejichž pořadí lze měnit.
Klient má plnou kontrolu
{ "templateLock": false }
Šablona slouží jako výchozí bod. Klient pak může dělat cokoli.
Zachování úprav klienta
Ve výchozím nastavení Blockstudio při aktualizaci souboru šablony nahradí celý obsah stránky. Pokud klient upravil nadpis v editoru, po další synchronizaci o tuto změnu přijde. To je v pořádku u stránek řízených vývojářem, ale u stránek, na jejichž obsahu se podílejí klienti, je potřeba zachovat jejich práci.
Klíče
Přidejte k libovolnému prvku atribut key, aby se jeho obsah sloučil místo nahrazení:
<block name="core/cover" key="hero" url="https://example.com/hero.jpg">
<h1>Default Hero Title</h1>
<p>Default hero description.</p>
</block>
<div key="features">
<h2>Features</h2>
<p>Feature introduction text.</p>
</div>
<div>
<h2>Unkeyed Section</h2>
<p>This gets replaced on every sync.</p>
</div>
Když se šablona změní a stránka se znovu synchronizuje:
- Bloky s klíčem zachovají obsah klienta (text, vnořené bloky i formátování). Strukturální atributy šablony (například
urlu titulního bloku) se přesto aktualizují. - Bloky bez klíče se celé nahradí verzí ze šablony.
Klíč chrání celý blok i všechny jeho podřízené bloky. Jednotlivým odstavcům uvnitř skupiny s klíčem nemusíte přiřazovat vlastní klíče. Klíč skupiny pokrývá vše uvnitř.
Klíče musí být jedinečné
Klíče musí být jedinečné v rámci celé šablony. Pokud mají dva prvky stejný klíč, druhý se považuje za prvek bez klíče (a zobrazí se upozornění PHP). Používejte výstižné názvy: "hero", "features", "cta", "testimonial-section".
Vývoj šablon
Díky klíčům můžete do šablony přidávat nové sekce, aniž byste narušili stávající obsah klienta:
<h1 key="title">Welcome</h1>
<div key="services">
<h2>Our Services</h2>
<p>We do great work.</p>
</div>
<h1 key="title">Welcome</h1>
<div key="services">
<h2>Our Services</h2>
<p>We do great work.</p>
</div>
<div key="testimonials">
<h2>What Clients Say</h2>
<p>Default testimonial text.</p>
</div>
Při synchronizaci zůstanou název a služby s úpravami klienta. Nová sekce s referencemi se zobrazí s výchozím obsahem šablony. Pokud později blok s klíčem ze šablony odstraníte, smaže se i ze stránky.
Celý pracovní postup s klientem
Pojďme si to celé ukázat na skutečném projektu:
{
"name": "homepage",
"title": "Home",
"slug": "home",
"postStatus": "publish",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<block name="core/cover" key="hero" url="https://example.com/hero.jpg">
<h1 blockEditingMode="contentOnly">Your Company Name</h1>
<p blockEditingMode="contentOnly">Your tagline goes here.</p>
<block name="core/buttons">
<block name="core/button" url="/contact">Contact Us</block>
</block>
</block>
<div key="features">
<h2 blockEditingMode="contentOnly">What We Do</h2>
<block name="core/columns">
<block name="core/column">
<h3 blockEditingMode="contentOnly">Service One</h3>
<p blockEditingMode="contentOnly">Describe this service.</p>
</block>
<block name="core/column">
<h3 blockEditingMode="contentOnly">Service Two</h3>
<p blockEditingMode="contentOnly">Describe this service.</p>
</block>
<block name="core/column">
<h3 blockEditingMode="contentOnly">Service Three</h3>
<p blockEditingMode="contentOnly">Describe this service.</p>
</block>
</block>
</div>
<block name="core/media-text" key="about" mediaurl="https://example.com/team.jpg" mediatype="image">
<h2 blockEditingMode="contentOnly">About Us</h2>
<p blockEditingMode="contentOnly">Tell your story here.</p>
</block>
<div key="cta">
<h2 blockEditingMode="contentOnly">Ready to get started?</h2>
<block name="core/buttons">
<block name="core/button" url="/contact">Get in Touch</block>
</block>
</div>
Tato stránka má čtyři sekce s klíčem. Klient může upravovat nadpisy a odstavce označené pomocí blockEditingMode="contentOnly" a tyto úpravy se zachovají i po aktualizaci šablony. Vývojář řídí rozvržení, obrázky, adresy URL tlačítek a celkovou strukturu. Pokud vývojář později přidá sekci s referencemi mezi „about“ a „cta“, zobrazí se při další synchronizaci a text klienta zůstane nedotčený.
Vazby bloků: alternativa ke klíčům
V WordPress 6.5 byly představeny vazby bloků API, které propojují atributy bloků s metadaty příspěvku. Místo uložení upravitelného obsahu do značek bloku (kde ho chrání klíče) se obsah ukládá do wp_postmeta (kam synchronizace šablony nemůže zasáhnout).
<h1 metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_title"}}}}'>
Default Title
</h1>
<p metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_description"}}}}'>
Default description.
</p>
Meta klíče je nutné zaregistrovat v PHP:
register_post_meta( 'page', 'hero_title', array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'default' => 'Default Title',
) );
Vazby bloků mají oproti klíčům dvě výhody: data lze vyhledávat pomocí WP_Query přes meta_query a jsou dostupná v REST API. Nevýhodou je nutnost zaregistrovat každý meta klíč v PHP. Vazby navíc fungují pouze u jednotlivých atributů bloku, nikoli u složitého vnořeného obsahu.
Klíče použijte u sekcí s bohatým obsahem, kde záleží na struktuře bloku (skupina s nadpisy, odstavci a obrázky). Vazby použijte pro jednotlivé textové hodnoty, které potřebujete také vyhledávat nebo zobrazovat jinde.
Šablony typů příspěvků
Pomocí templateFor nastavíte výchozí strukturu bloků pro všechny nové příspěvky daného typu:
{
"name": "product-template",
"title": "Product Template",
"templateFor": "product",
"templateLock": "insert"
}
<h1>Product Name</h1>
<block name="core/columns">
<block name="core/column">
<img src="" alt="Product image" />
</block>
<block name="core/column">
<p>Product description goes here.</p>
<block name="core/buttons">
<block name="core/button" url="#">Buy Now</block>
</block>
</block>
</block>
<div>
<h2>Specifications</h2>
<table>
<thead>
<tr><th>Feature</th><th>Value</th></tr>
</thead>
<tbody>
<tr><td>Weight</td><td>1.2 kg</td></tr>
</tbody>
</table>
</div>
Každý nový příspěvek typu „product“ začne s touto strukturou. Nastavení templateLock: "insert" umožňuje editorům měnit pořadí sekcí a upravovat obsah, ale ne přidávat ani odebírat bloky.
Tipy
Synchronizujte v předem určeném bodě nasazení. Po změně nebo nasazení zdrojových souborů stránky spusťte wp bs pages sync. Návštěvy frontendu ani administrace stránky nesynchronizují. PHP Nástroje pro nasazení mohou zavolat Blockstudio\Pages::reconcile() a zkontrolovat jeho strojově čitelnou zprávu.
Připněte důležitá ID příspěvků. Pro stránky odkazované v nabídkách, pevných odkazech nebo externích systémech použijte v page.json hodnotu postId. Bez připnutí získá stránka po smazání a opětovném vytvoření nové ID, čímž se tyto odkazy poruší.
Pro pomocné stránky použijte sync: false. Pokud chcete stránku vytvořit jednou a pak ji zcela předat klientovi, nastavte "sync": false a vytvořte ji pomocí Blockstudio\Pages::force_sync(). Běžné odsouhlasení změn ji pak ignoruje.
Uzamkněte a odemkněte pomocí PHP. Zavolejte Blockstudio\Pages::lock('about'), chcete-li konkrétní stránce zabránit v synchronizaci (užitečné během intenzivních úprav klientem). Opětovnou synchronizaci povolíte zavoláním Blockstudio\Pages::unlock('about').
Šablonovací nástroje. Kromě PHP lze šablony psát v Twig (vyžaduje Timber) nebo Blade (vyžaduje illuminate/view). Hodí se to pro cykly a filtry, ale šablony stránek se kompilují během výslovné synchronizace, nikoli při požadavku na frontend. Pokud kompilace zdrojových souborů vyžaduje pomocné funkce dostupné pouze v PHP, zůstaňte u PHP.
Vynucená synchronizace ignoruje klíče. Volání Pages::force_sync('about') nahradí celý obsah stránky a ignoruje klíče i kontroly času změny. Použijte ho, pokud chcete stránku záměrně obnovit do stavu podle šablony.
Další kroky
- Přehled stránek: podrobnosti o všech vlastnostech
page.json, PHP API a algoritmu slučování podle klíčů. - Přehled stránek a vzorů: parser HTML, přehled syntaxe bloků, vlastní vykreslovače a mapování prvků.
- Vzory: stejná syntaxe šablon pro opakovaně použitelné vzory bloků místo stránek.