Failipõhiste lehekülgede loomine
Traditsiooniliselt luuakse WordPress-i lehekülgi plokiredaktoris: plokke lohistades, sätteid seadistades ja salvestades. See sobib klientidele, kes loovad ise lehekülgi, kuid arendajatele, kes loovad struktureeritud ja versioonihallatavaid lehekülgi, tekitab see probleeme. Lehekülje paigutus asub andmebaasis, mitte koodis. Seda ei saa koodimuudatuste taotluses üle vaadata, giti abil tagasi pöörata ega uuel installil uuesti luua.
Blockstudio failipõhised leheküljed lahendavad selle probleemi. Määratle leheküljed teemafailidena, kirjuta HTML mallid, mis teisendatakse WordPress plokkideks, ja määra täpselt, mida kliendid saavad muuta ja mida mitte. Selgesõnaline käsk sünkroonib failid tavalisteks WordPress postitusteks; mallid jäävad tõeallikaks.
See juhend käsitleb lehekülgede loomist algusest peale ning keskendub põhjalikult lukustus- ja redigeerimisjuhtelementidele, mis muudavad failipõhised leheküljed kliendiprojektides praktiliseks.
Esimene lehekülg
Loo teemasse kaust pages ja lisa sinna alamkaust kahe failiga:
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>
Käivita lehekülgede sünkroonimise käsk:
wp bs pages sync
Blockstudio parsib faili HTML WordPress plokkideks ja loob lehekülje nimega
„About Us”, mille aadressilühend on about. Ava see redaktoris ja näed pealkirja
ning lõiku, täpselt nagu oleksid need ise lisanud.
Muuda faili index.php teksti ja käivita käsk uuesti. Värskenduse nägemiseks laadi redaktor uuesti. See on põhitsükkel: kirjuta HTML, sünkrooni teadlikult ja saa plokid.
Mallikeel
Blockstudio HTML parser teisendab standardsed HTML elemendid WordPress plokkideks. Kirjuta <p> ja saad lõiguploki. Kirjuta <h2> ja saad pealkirjaploki. Vastendus on loogiline:
| HTML | Plokk |
|---|---|
<p> |
Lõik |
<h1> kuni <h6> |
Pealkiri (tase vastab märgendile) |
<ul>, <ol> |
Loend |
<blockquote> |
Tsitaat |
<img> |
Pilt |
<div>, <section> |
Rühm |
<hr> |
Eraldaja |
<details> |
Üksikasjad |
<table> |
Tabel |
Plokkide puhul, millel puudub otsene HTML vaste, kasuta elementi <block> koos atribuudiga 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>
Elementide <block> atribuudid edastatakse plokiatribuutidena. Väärtuste tüübid teisendatakse automaatselt: "true" muutub tõeväärtuseks, "3" täisarvuks ning stringid nagu '{"type":"flex"}' teisendatakse objektideks JSON.
Paigutused
Rühmad toetavad atribuudi layout abil eri paigutusrežiime:
<!-- 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>
Kohandatud plokid
Süntaks <block> töötab kõigi registreeritud plokkidega, sealhulgas sinu enda Blockstudio plokkidega:
<block name="my-theme/hero" title="Welcome" background="dark" />
<block name="my-theme/testimonial" quote="Great product." author="Jane" />
Atribuudid seotakse automaatselt ploki Blockstudio väljaväärtustega.
Maandumislehe loomine
Siin on täielik maandumisleht, mille struktuur ja paigutus kasutavad põhiplokke:
{
"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>
Sellel lehel on kaanepildiga esiosa, kolmeveeruline omaduste ruudustik, meedia ja tekstiga jaotis, korduma kippuvate küsimuste akordionid ning CTA. Kõik ühest failist HTML. Atribuut templateLock: "all" asukohas page.json tähendab, et klient ei saa midagi muuta. Järgmine jaotis selgitab, kuidas piiranguid leevendada.
Redaktori juhtimine
Siin saavad failipõhised lehed tõeliselt võimsaks. Blockstudio pakub kahte sõltumatut juhtimisvõimalust: malli lukustus ja plokkide redigeerimisrežiim. Koos võimaldavad need täpselt määrata, milliseid lehe osi kliendid muuta saavad. Lukustage struktuur, kuid lubage neil teksti redigeerida. Külmutage mõned jaotised, jättes teised täiesti vabaks. Looge leht, kus klient saab sisestada teksti ainult kolme kindlasse pealkirja.
Malli lukustus
Atribuut templateLock asukohas page.json juhib struktuuri muutmist: kas plokke saab lisada, eemaldada või ümber paigutada.
"all" (vaikimisi)
{
"name": "terms",
"templateLock": "all"
}
Kõige rangem lukustus. Kliendid ei saa plokke lisada, eemaldada ega liigutada. Samuti ei saa nad plokkide sisu muuta (välja arvatud juhul, kui see on ühendatud valikuga blockEditingMode). See on vaikeväärtus, kui te väärtust ei määra.
Millal kasutada: juriidilised lehed, kasutustingimused, privaatsuspoliitikad. Kõik lehed, mille sisu peaks muutuma ainult koodi kaudu.
"insert"
{
"name": "about",
"templateLock": "insert"
}
Kliendid ei saa plokke lisada ega eemaldada, kuid saavad olemasolevaid plokke ümber paigutada ja nende sisu muuta. Plokkide arv jääb samaks, kuid järjekorda saab muuta.
Millal kasutada: lehed, mille jaotiste komplekt on fikseeritud, kuid klient peaks saama nende järjekorda muuta. Näiteks portfoolioleht, mille jaotiste arv on ette määratud, kuid klient otsustab nende järjekorra.
"contentOnly"
{
"name": "homepage",
"templateLock": "contentOnly"
}
Kliendid saavad teksti redigeerida, kuid ei saa plokke lisada, eemaldada ega liigutada. Erinevus valikust "all" seisneb selles, et "all" takistab ka sisu muutmist, samas kui "contentOnly" lubab seda selgesõnaliselt.
Millal kasutada: kõige tavalisem valik klientidele mõeldud lehtede puhul. Arendaja juhib paigutust. Klient sisestab teksti.
false
{
"name": "blog",
"templateLock": false
}
Lukustust pole. Klientidel on täielik kontroll: nad saavad lisada, eemaldada, liigutada ja redigeerida mis tahes plokki. Mall annab algse struktuuri, kuid edaspidi kuulub leht kliendile.
Millal kasutada: blogi avalehed, vabas vormis sisulehed või mis tahes leht, kus kliendil peaks olema täielik toimetamisvabadus.
Plokkide redigeerimisrežiim
Kui templateLock juhib struktuuri (lisamine, eemaldamine, liigutamine), siis blockEditingMode määrab üksikute plokkide tasandil suhtluse: kas plokke saab üldse valida, seadistada või redigeerida.
Määrake lehe tasemel vaikeväärtus asukohas page.json:
{
"name": "landing",
"templateLock": "all",
"blockEditingMode": "disabled"
}
"default"
Täielik redigeerimine. Plokke saab valida, nende seadeid muuta ja sisu redigeerida. See on tavapärane redaktori kasutuskogemus.
"contentOnly"
Plokke saab redigeerida, kuid ainult nende teksti. Ploki seadeid ei saa avada, värve muuta, polsterdust kohandada ega muid sisu hulka mittekuuluvaid atribuute muuta. Ploki tööriistaribal kuvatakse ainult teksti vormindamise valikud.
"disabled"
Plokid on täiesti mittesuhtluslikud. Need kuvatakse redaktoris, kuid neid ei saa klõpsata, valida ega mingil viisil muuta. Klient näeb sisu, kuid ei saa seda puudutada.
Üksikelemendi ülekirjutused
Siin läheb asi huvitavaks. Lehe taseme blockEditingMode määrab vaikeväärtuse igale lehe plokile, kuid malli üksikelementide puhul saate selle üle kirjutada:
{
"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>
Lehe vaikeväärtus on "disabled", seega on kõik plokid algselt mittesuhtluslikud. Seejärel lubavad kindlad elemendid kasutada režiimi "contentOnly", mis teeb redigeeritavaks ainult nende teksti. Tulemuseks on leht, kus klient saab sisestada teksti täpselt kahte tekstivälja (esiletõstetud jaotise pealkirja ja lõiku) ning ühte funktsiooni kirjeldavasse lõiku. Kõik muu on lukus.
See toimib mis tahes HTML elemendiga (<h1>, <p>, <div> jne) ja elementidega <block>. Samuti saate määrata kindlatele elementidele blockEditingMode="default", et anda täielik redigeerimisõigus:
<block name="core/buttons" blockEditingMode="default">
<block name="core/button" url="/contact">Fully editable button</block>
</block>
Nüüd saab klient muuta nupu teksti, URL, stiile ja muid seadeid. Kõik muu lehel jääb külmutatuks.
Eellaste kaskaad
Üksikelemendi ülekirjutuste ja konteinerplokkide koosmõjus on üks oluline nüanss. Kui lehe vaikeväärtus on "disabled" ja määrate rühma sees olevale pealkirjale blockEditingMode="contentOnly", peab pealkirjale pääsema ligi. Kuid selle emarühm on "disabled", mis tähendab, et seda ei saa üldse avada.
Blockstudio lahendab selle automaatselt. Kui alampilgul on redigeerimisrežiimi ülekirjutus, määratakse kõik selle eellaspilud režiimi "contentOnly", et alampilk jääks ligipääsetavaks. Emakonteinerite režiime pole vaja käsitsi määrata. Määrake ülekirjutus lihtsalt plokile, mida soovite redigeeritavaks teha, ja selleni viiv tee avaneb.
<!-- 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>
Eellaste kaskaad tõstab konteinerid ainult režiimi "contentOnly", mitte kunagi režiimi "default". See tähendab, et eellasrühmi saab avada ja neis liikuda, kuid neid ei saa täielikult redigeerida (nende seadeid ei saa muuta).
Otsustusmaatriks
Valikute templateLock ja blockEditingMode ühendamine annab teile eri tasemel kontrolli. Siin on kõige kasulikumad kombinatsioonid:
Arendaja juhib kõike
{ "templateLock": "all" }
blockEditingMode pole vaja. Vaikimisi templateLock: "all" takistab kõiki muudatusi. Kasutage seda lehtede puhul, mida hallatakse täielikult koodi kaudu.
Klient saab kogu teksti redigeerida
{ "templateLock": "contentOnly" }
Klient saab redigeerida teksti mis tahes plokis, kuid ei saa lehe struktuuri muuta. Lihtne ja lubav lahendus.
Klient saab redigeerida ainult kindlat teksti
{
"templateLock": "all",
"blockEditingMode": "disabled"
}
Ühendage see valikuga blockEditingMode="contentOnly" malli kindlatel elementidel. See on kõige täpsem valik: klient saab redigeerida ainult neid plokke, mille olete märkinud.
Klient saab kindlaid jaotisi ümber järjestada
{ "templateLock": "insert" }
Klient saab jaotisi ümber paigutada ja sisu redigeerida, kuid ei saa plokke lisada ega kustutada. Sobib lehtedele, mille jaotiste komplekt on fikseeritud, kuid järjekord paindlik.
Kliendil on täielik kontroll
{ "templateLock": false }
Mall on lähtepunkt. Seejärel saab klient teha mida iganes.
Kliendi muudatuste säilitamine
Vaikimisi asendab Blockstudio mallifaili uuendamisel kogu lehe sisu. Kui klient redigeeris redaktoris pealkirja, läheb see muudatus järgmise sünkroonimise järel kaotsi. Arendaja juhitavate lehtede puhul sobib see hästi, kuid lehtedel, kuhu kliendid sisu lisavad, on vaja võimalust nende tööd säilitada.
Võtmed
Lisage mis tahes elemendile atribuut key, et märkida see asendamise asemel ühendamiseks:
<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>
Kui mall muutub ja leht sünkroonitakse uuesti:
- Võtmega plokid säilitavad kliendi sisu (teksti, sisemised plokid, vormingu). Malli struktuuriatribuute (nt kaanepildi
url) uuendatakse siiski. - Võtmeta plokid asendatakse täielikult malliversiooniga.
Võti kaitseb tervet plokki ja kõiki selle alampilke. Võtmega rühmas olevaid üksikuid lõike pole vaja eraldi võtmega märkida. Rühma võti katab kõik selle sees.
Võtmed peavad olema unikaalsed
Võtmed peavad olema kogu malli ulatuses unikaalsed. Kui kahel elemendil on sama võti, käsitletakse teist võtmeta elemendina (ja väljastatakse hoiatus PHP). Kasutage kirjeldavaid nimesid: "hero", "features", "cta", "testimonial-section".
Mallide edasiarendamine
Võtmed võimaldavad lisada mallile uusi jaotisi olemasolevat kliendi sisu häirimata:
<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>
Sünkroonimisel säilivad pealkirja ja teenuste kliendipoolsed muudatused. Uus iseloomustuste jaotis kuvatakse malli vaikesisuga. Kui eemaldate hiljem mallist võtmega ploki, kustutatakse see lehelt.
Kliendi täielik töövoog
Paneme kõik päris projekti puhul kokku:
{
"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>
Sellel lehel on neli võtmega jaotist. Klient saab redigeerida pealkirju ja lõike, mis on märgitud blockEditingMode="contentOnly"-ga; need muudatused säilivad malliuuenduste järel. Arendaja juhib paigutust, pilte, nuppude URL-e ja üldist struktuuri. Kui arendaja lisab hiljem jaotise iseloomustustele „about” ja „cta” vahele, kuvatakse see järgmisel sünkroonimisel ilma kliendi teksti muutmata.
Plokkide sidumised: võtmete alternatiiv
WordPress 6.5 tõi sisse Plokkide sidumised API, mis seovad ploki atribuudid postituse metaandmetega. Selle asemel et salvestada redigeeritav sisu ploki märgendusse (kus võtmed seda kaitsevad), asub sisu wp_postmeta-s, kus mallide sünkroonimine seda muuta ei saa.
<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 võtmed tuleb registreerida asukohas PHP:
register_post_meta( 'page', 'hero_title', array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'default' => 'Default Title',
) );
Plokkide sidumistel on võtmete ees kaks eelist: andmeid saab pärida WP_Query abil, kasutades meta_query, ning need on saadaval kohas REST API. Kompromiss on see, et peate registreerima iga meta võtme asukohas PHP ja sidumised toimivad ainult üksikute plokiatribuutidega (mitte keeruka pesastatud sisuga).
Kasutage võtmeid sisurikaste jaotiste puhul, kus ploki struktuur on oluline (rühm pealkirjade, lõikude ja piltidega). Kasutage sidumisi üksikute tekstiväärtuste puhul, mida peate ka pärima või mujal kuvama.
Sisupostituse tüübi mallid
Kasutage valikut templateFor, et määrata kõigile uut tüüpi postitustele plokkide vaikestruktuur:
{
"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>
Iga uus „product” postitus algab selle struktuuriga. templateLock: "insert" võimaldab toimetajatel jaotisi ümber järjestada ja sisu redigeerida, kuid mitte plokke lisada ega eemaldada.
Nõuanded
Sünkroonige teadlikult valitud juurutamise hetkel. Käivitage wp bs pages sync pärast lehe allikate muutmist või juurutamist. Esikülje ja halduspaneeli külastused ei sünkrooni lehti kunagi. PHP juurutustööriistad saavad käivitada käsu Blockstudio\Pages::reconcile() ja kontrollida selle masinloetavat aruannet.
Kinnitage oluliste postituste ID-d. Kasutage valikut postId asukohas page.json menüüdes, kõvakodeeritud linkides või välissüsteemides viidatud lehtede puhul. Kinnitamiseta saab kustutatud ja uuesti loodud leht uue ID, mis rikub need viited.
Kasutage sync: false-i karkasside jaoks. Kui soovite luua lehe üks kord ja seejärel anda selle täielikult kliendile üle, määrake "sync": false ja looge leht käsuga Blockstudio\Pages::force_sync(). Tavapärane kooskõlastamine eirab seda seejärel.
Lukustage ja avage käsuga PHP. Käivitage Blockstudio\Pages::lock('about'), et takistada kindla lehe sünkroonimist (kasulik kliendi intensiivsete redigeerimisperioodide ajal). Sünkroonimise taaslubamiseks käivitage Blockstudio\Pages::unlock('about').
Mallimootorid. Lisaks valikule PHP saab malle kirjutada ka keeles Twig (vajab Timber) või Blade (vajab illuminate/view). See on kasulik tsüklite ja filtrite puhul, kuid lehemallid kompileeritakse selgesõnalise sünkroonimise ajal, mitte esikülje päringu käigus. Kasutage valikut PHP, kui lähtekoodi kompileerimine ise vajab ainult PHP-i jaoks mõeldud abifunktsioone.
Jõuga sünkroonimine eirab võtmeid. Käsu Pages::force_sync('about') käivitamine asendab kogu lehe sisu ning eirab võtmeid ja muutmisaja kontrolle. Kasutage seda, kui soovite lehe tahtlikult malli olekusse lähtestada.
Järgmised sammud
- Lehtede viide: kõik
page.jsonatribuudid, PHP API ja võtmetega ühendamise algoritmi üksikasjalik kirjeldus. - Lehtede ja mustrite ülevaade: HTML parser, plokkide süntaksi viide, kohandatud renderdajad ja elementide vastendamine.
- Mustrid: sama mallisüntaks korduvkasutatavate plokimustrite jaoks lehtede asemel.