Tvorba stránok zo súborov
Tradičná tvorba stránok WordPress prebieha v editore blokov: presúvate bloky, nastavujete ich a klikáte na tlačidlo Uložiť. Klientom, ktorí si vytvárajú vlastné stránky, tento postup vyhovuje, vývojárom vytvárajúcim štruktúrované stránky so správou verzií však spôsobuje problémy. Rozloženie stránky je uložené v databáze, nie v kóde. V požiadavke na stiahnutie zmien si ho nemôžete skontrolovať, vrátiť späť pomocou git ani reprodukovať pri novej inštalácii.
Stránky zo súborov Blockstudio tento problém riešia. Stránky definujete ako súbory vo svojej téme, píšete šablóny HTML, ktoré sa konvertujú na bloky WordPress, a presne určujete, čo klienti môžu a nemôžu upravovať. Výslovným príkazom tieto súbory synchronizujete s bežnými príspevkami WordPress a vaše šablóny zostávajú jediným zdrojom pravdy.
Táto príručka vás prevedie tvorbou stránok od začiatku a podrobne sa zameria na ovládacie prvky uzamykania a úprav, vďaka ktorým sú stránky zo súborov praktické pre klientske projekty.
Vaša prvá stránka
Vytvorte priečinok pages vo svojej téme a potom doň pridajte podpriečinok s dvoma súbormi:
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>
Spustite príkaz na synchronizáciu stránok:
wp bs pages sync
Blockstudio spracuje HTML na bloky WordPress a vytvorí stránku s názvom
„About Us“ a slugom about. Otvorte ju v editore a uvidíte nadpis
aj odsek, presne ako keby ste ich pridali ručne.
Upravte index.php, zmeňte text a znova spustite príkaz. Po obnovení editora
uvidíte aktualizáciu. Takto vyzerá základný postup: píšete do HTML, synchronizujete
zámerne a získate bloky.
Jazyk šablón
Parser Blockstudio pre HTML prevádza štandardné prvky HTML na bloky WordPress. Napíšte <p> a získate blok odseku. Napíšte <h2> a získate blok nadpisu. Mapovanie je intuitívne:
| HTML | Blok |
|---|---|
<p> |
Odsek |
<h1> až <h6> |
Nadpis (úroveň zodpovedá značke) |
<ul>, <ol> |
Zoznam |
<blockquote> |
Citát |
<img> |
Obrázok |
<div>, <section> |
Skupina |
<hr> |
Oddeľovač |
<details> |
Podrobnosti |
<table> |
Tabuľka |
Pre bloky bez priameho ekvivalentu HTML použite prvok <block> s atribútom 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>
Atribúty prvkov <block> sa odovzdávajú ako atribúty bloku. Hodnoty sa automaticky prevedú: "true" sa zmení na logickú hodnotu, "3" na celé číslo a reťazce JSON, ako napríklad '{"type":"flex"}', sa dekódujú na objekty.
Rozloženia
Skupiny podporujú rôzne režimy rozloženia prostredníctvom atribútu 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
Syntax <block> funguje s každým zaregistrovaným blokom vrátane vašich vlastných blokov Blockstudio:
<block name="my-theme/hero" title="Welcome" background="dark" />
<block name="my-theme/testimonial" quote="Great product." author="Jane" />
Atribúty sa automaticky namapujú na hodnoty polí Blockstudio daného bloku.
Tvorba vstupnej stránky
Tu je kompletná vstupná stránka, ktorá na vytvorenie štruktúry a rozloženia používa 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>
Táto stránka obsahuje úvodnú sekciu s titulným obrázkom, mriežku funkcií s tromi stĺpcami, sekciu s médiami a textom, rozbaľovacie otázky a odpovede aj CTA. Všetko pochádza z jedného súboru HTML. Hodnota templateLock: "all" v page.json znamená, že klient nemôže nič meniť. V nasledujúcej časti sa dozviete, ako toto obmedzenie zmierniť.
Ovládanie editora
Práve tu sa stránky založené na súboroch stávajú skutočne výkonnými. Blockstudio vám poskytuje dve nezávislé možnosti ovládania: uzamknutie šablóny a režim úprav blokov. Spoločne vám umožňujú presne určiť, ktoré časti stránky môžu klienti upravovať. Uzamknite štruktúru, ale povoľte úpravy textu. Zmrazte niektoré sekcie a ostatné ponechajte úplne otvorené. Vytvorte stránku, na ktorej klient môže iba zadávať text do troch konkrétnych nadpisov.
Uzamknutie šablóny
Vlastnosť templateLock v page.json ovláda úpravy štruktúry: či možno bloky pridávať, odstraňovať alebo presúvať.
"all" (predvolené)
{
"name": "terms",
"templateLock": "all"
}
Najprísnejšie uzamknutie. Klienti nemôžu pridávať, odstraňovať ani presúvať bloky. Nemôžu upravovať ani ich obsah (pokiaľ sa nekombinuje s blockEditingMode). Ide o predvolenú hodnotu, ak žiadnu nezadáte.
Kedy ho použiť: Právne stránky, podmienky používania, zásady ochrany osobných údajov. Akákoľvek stránka, ktorej obsah sa má meniť iba prostredníctvom kódu.
"insert"
{
"name": "about",
"templateLock": "insert"
}
Klienti nemôžu pridávať ani odstraňovať bloky, ale môžu presúvať existujúce bloky a upravovať ich obsah. Počet blokov zostáva pevný, ich poradie sa však môže meniť.
Kedy ho použiť: Stránky, na ktorých chcete mať pevne danú množinu sekcií, ale klient ich môže zoradiť podľa seba. Napríklad portfóliová stránka s vopred určeným počtom sekcií, ktorých poradie si klient vyberie.
"contentOnly"
{
"name": "homepage",
"templateLock": "contentOnly"
}
Klienti môžu upravovať text, ale nemôžu pridávať, odstraňovať ani presúvať bloky. Rozdiel oproti "all" je v tom, že "all" bráni aj úpravám obsahu, zatiaľ čo "contentOnly" ich výslovne povoľuje.
Kedy ho použiť: Najčastejšia voľba pre stránky určené klientom. Vývojár riadi rozloženie a klient dopĺňa text.
false
{
"name": "blog",
"templateLock": false
}
Bez akéhokoľvek uzamknutia. Klienti majú úplnú kontrolu: môžu pridávať, odstraňovať, presúvať a upravovať ľubovoľné bloky. Šablóna poskytuje východiskovú štruktúru, o zvyšok sa postará klient.
Kedy ho použiť: Stránky s prehľadom článkov na blogu, stránky s voľným obsahom alebo akékoľvek stránky, na ktorých má mať klient úplnú redakčnú slobodu.
Režim úprav blokov
Kým templateLock riadi štruktúru (pridávanie, odstraňovanie, presúvanie), blockEditingMode riadi správanie jednotlivých blokov: či možno bloky vyberať, nastavovať alebo vôbec upravovať.
Nastavte predvolenú hodnotu pre stránku v page.json:
{
"name": "landing",
"templateLock": "all",
"blockEditingMode": "disabled"
}
"default"
Úplné úpravy. Bloky možno vyberať, meniť ich nastavenia a upravovať ich obsah. Ide o bežné prostredie editora.
"contentOnly"
Bloky možno upravovať, ale iba ich textový obsah. Nemožno otvárať nastavenia blokov, meniť farby, upravovať vnútorné odsadenie ani meniť iné atribúty než obsahové. Panel nástrojov bloku zobrazuje iba možnosti formátovania textu.
"disabled"
Bloky sú úplne neinteraktívne. V editore sa zobrazujú, ale nemožno na ne kliknúť, vybrať ich ani ich akokoľvek upravovať. Klient vidí obsah, ale nemôže s ním nič robiť.
Prepísanie nastavení jednotlivých prvkov
Tu to začína byť zaujímavé. Nastavenie blockEditingMode na úrovni stránky určuje predvolenú hodnotu pre každý blok na stránke, no v šablóne ho môžete prepísať pre jednotlivé prvky:
{
"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>
Predvolená hodnota stránky je "disabled", takže každý blok je spočiatku neinteraktívny. Potom sa pri konkrétnych prvkoch povolí "contentOnly", vďaka čomu možno upravovať iba ich text. Výsledkom je stránka, na ktorej môže klient zadávať text presne do dvoch textových polí (nadpisu hlavnej sekcie a odseku) a jedného odseku s informáciami o výhodách. Všetko ostatné zostáva uzamknuté.
Funguje to pri ľubovoľnom prvku HTML (<h1>, <p>, <div> atď.) aj pri prvkoch <block>. Na konkrétnych prvkoch môžete nastaviť aj blockEditingMode="default", aby ste povolili úplné úpravy:
<block name="core/buttons" blockEditingMode="default">
<block name="core/button" url="/contact">Fully editable button</block>
</block>
Klient teraz môže zmeniť text tlačidla, URL, štýly a všetky ostatné nastavenia. Všetko ostatné na stránke zostane zmrazené.
Kaskádové sprístupnenie predkov
Je tu jeden dôležitý detail týkajúci sa vzájomného pôsobenia nastavení jednotlivých prvkov a blokov kontajnerov. Ak je predvolená hodnota stránky "disabled" a nadpisu vo vnútri skupiny nastavíte blockEditingMode="contentOnly", k nadpisu musí byť možné dostať sa. Jeho nadradená skupina je však "disabled", čo znamená, že do nej nemožno vôbec vstúpiť.
Blockstudio to rieši automaticky. Keď sa režim úprav podradeného bloku prepíše, všetky jeho nadradené bloky sa nastavia na "contentOnly", aby podradený blok zostal prístupný. Režimy nadradených kontajnerov nemusíte nastavovať ručne. Stačí prepísať nastavenie bloku, ktorý chcete sprístupniť na úpravy, a otvorí sa k nemu 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 predkov povyšuje kontajnery iba na "contentOnly", nikdy na "default". Nadradené skupiny teda možno navigovať (vstúpiť do nich), ale nemožno ich úplne upravovať (meniť ich nastavenia).
Rozhodovacia matica
Kombináciou templateLock a blockEditingMode získate celé spektrum možností ovládania. Tu sú najužitočnejšie kombinácie:
Vývojár má všetko pod kontrolou
{ "templateLock": "all" }
blockEditingMode netreba. Predvolené templateLock: "all" zabraňuje všetkým zmenám. Použite ho pre stránky spravované výhradne prostredníctvom kódu.
Klient upravuje všetok text
{ "templateLock": "contentOnly" }
Klient môže upravovať text v ľubovoľnom bloku, ale nemôže meniť štruktúru stránky. Jednoduché a ústretové riešenie.
Klient upravuje iba vybraný text
{
"templateLock": "all",
"blockEditingMode": "disabled"
}
Kombinuje sa s blockEditingMode="contentOnly" na konkrétnych prvkoch v šablóne. Ide o najpresnejšiu možnosť: klient môže upravovať iba tie bloky, ktoré označíte.
Klient mení poradie pevných sekcií
{ "templateLock": "insert" }
Klient môže meniť poradie sekcií a upravovať obsah, ale nemôže pridávať ani odstraňovať bloky. Vhodné pre stránky s pevne danou množinou sekcií, ktorých poradie možno meniť.
Klient má úplnú kontrolu
{ "templateLock": false }
Šablóna slúži ako východiskový bod. Potom môže klient robiť čokoľvek.
Zachovanie úprav klienta
Štandardne platí, že pri aktualizácii súboru šablóny Blockstudio nahradí celý obsah stránky. Ak klient upravil nadpis v editore, po ďalšej synchronizácii sa táto úprava stratí. Pri stránkach riadených vývojárom je to v poriadku, ale ak na stránkach prispievajú aj klienti, potrebujete spôsob, ako zachovať ich prácu.
Kľúče
Pridajte ľubovoľnému prvku atribút key, aby sa pri zlúčení namiesto nahradenia zachoval:
<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>
Keď sa šablóna zmení a stránka sa znova synchronizuje:
- Bloky s kľúčom si zachovajú obsah klienta (text, vnorené bloky, formátovanie). Štrukturálne atribúty šablóny (napríklad
urlpri titulnom obrázku) sa naďalej aktualizujú. - Bloky bez kľúča sa celé nahradia verziou zo šablóny.
Kľúč chráni celý blok aj všetky jeho podradené prvky. Odsekom vo vnútri skupiny s kľúčom nemusíte priradiť vlastné kľúče. Kľúč skupiny pokrýva všetko, čo obsahuje.
Kľúče musia byť jedinečné
Kľúče musia byť jedinečné v rámci celej šablóny. Ak majú dva prvky rovnaký kľúč, druhý sa bude považovať za prvok bez kľúča (a zobrazí sa upozornenie PHP). Používajte výstižné názvy: "hero", "features", "cta", "testimonial-section".
Vývoj šablón
Kľúče umožňujú pridávať do šablóny nové sekcie bez narušenia existujúceho obsahu 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>
Pri synchronizácii sa zachovajú úpravy klienta v nadpise a službách. Nová sekcia s referenciami klientov sa zobrazí s predvoleným obsahom zo šablóny. Ak neskôr odstránite blok s kľúčom zo šablóny, odstráni sa aj zo stránky.
Kompletný pracovný postup klienta
Pozrime sa na celý postup na reálnom projekte:
{
"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>
Táto stránka má štyri sekcie s kľúčmi. Klient môže upravovať nadpisy a odseky označené značkou blockEditingMode="contentOnly" a tieto úpravy sa zachovajú aj po aktualizácii šablóny. Vývojár riadi rozloženie, obrázky, adresy URL tlačidiel a celkovú štruktúru. Ak vývojár neskôr pridá sekciu s referenciami klientov medzi „o nás“ a „cta“, zobrazí sa pri ďalšej synchronizácii bez narušenia textov klienta.
Väzby blokov: alternatíva ku kľúčom
WordPress 6.5 prinieslo Väzby blokov API, ktoré prepájajú atribúty blokov s metaúdajmi príspevku. Namiesto ukladania upraviteľného obsahu do značiek bloku (kde ho chránia kľúče) sa obsah ukladá do wp_postmeta (kam synchronizácia šablóny nemôže zasiahnuť).
<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 kľúče musia byť zaregistrované v PHP:
register_post_meta( 'page', 'hero_title', array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'default' => 'Default Title',
) );
Väzby blokov majú oproti kľúčom dve výhody: údaje možno vyhľadávať pomocou WP_Query cez meta_query a sú dostupné v REST API. Nevýhodou je, že každý meta kľúč treba zaregistrovať v PHP a väzby fungujú iba pre jednotlivé atribúty blokov (nie pre zložitý vnorený obsah).
Kľúče použite pre sekcie s bohatým obsahom, v ktorých záleží na štruktúre blokov (skupina s nadpismi, odsekmi a obrázkami). Väzby použite pre jednotlivé textové hodnoty, ktoré potrebujete aj vyhľadávať alebo zobrazovať inde.
Šablóny typov príspevkov
Pomocou templateFor nastavte predvolenú štruktúru blokov pre všetky nové príspevky 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ý príspevok typu „product“ začína touto štruktúrou. templateLock: "insert" umožňuje redaktorom meniť poradie sekcií a upravovať obsah, ale nie pridávať ani odstraňovať bloky.
Tipy
Synchronizujte na vopred určenom mieste nasadenia. Spustite wp bs pages sync po
zmene alebo nasadení zdrojov stránok. Návštevy frontendu ani administrácie stránky nesynchronizujú.
PHP Nástroje na nasadenie môžu zavolať Blockstudio\Pages::reconcile() a
skontrolovať jeho strojovo čitateľnú správu.
Pripnite dôležité ID príspevkov. Pre stránky, na ktoré odkazujú ponuky, pevne zakódované odkazy alebo externé systémy, použite postId v page.json. Bez pripnutia dostane odstránená a znovu vytvorená stránka nové ID a tieto odkazy prestanú fungovať.
Na vytvorenie základných stránok použite sync: false. Ak chcete stránku vytvoriť raz a potom ju úplne odovzdať klientovi, nastavte "sync": false a vytvorte ju pomocou Blockstudio\Pages::force_sync(). Bežné zosúlaďovanie ju potom ignoruje.
Uzamknite a odomknite pomocou PHP. Zavolajte Blockstudio\Pages::lock('about'), aby ste zabránili synchronizácii konkrétnej stránky (užitočné počas intenzívnych úprav klientom). Opätovnú synchronizáciu povolíte zavolaním Blockstudio\Pages::unlock('about').
Šablónovacie nástroje. Okrem PHP možno šablóny písať v Twig (vyžaduje Timber) alebo v Blade (vyžaduje illuminate/view). Hodí sa to pre cykly a filtre, no šablóny stránok sa kompilujú počas výslovnej synchronizácie, nie počas požiadavky na frontend. Ak samotná kompilácia zdroja potrebuje pomocné funkcie dostupné iba v PHP, použite PHP.
Vynútená synchronizácia ignoruje kľúče. Zavolaním Pages::force_sync('about') sa nahradí celý obsah stránky a ignorujú sa kľúče aj kontroly času úpravy. Použite ju, keď chcete stránku zámerne obnoviť do stavu podľa šablóny.
Ďalšie kroky
- Referenčná príručka stránok: podrobný opis všetkých vlastností
page.json, PHP API a algoritmu zlučovania podľa kľúčov. - Prehľad stránok a vzorov: parser HTML, referencia syntaxe blokov, vlastné vykresľovače a mapovanie prvkov.
- Vzory: rovnaká syntax šablón pre opakovane použiteľné vzory blokov namiesto stránok.