Preskoči na vsebino

Ustvarjanje strani na podlagi datotek

Tradicionalno ustvarjanje strani WordPress poteka v urejevalniku blokov: vlečenje blokov, nastavitev možnosti in klik na gumb za shranjevanje. To deluje za stranke, ki ustvarjajo lastne strani, vendar povzroča težave razvijalcem, ki gradijo strukturirane strani z upravljanjem različic. Postavitev strani je shranjena v zbirki podatkov, ne v kodi. V zahtevku za spremembe je ne morete pregledati, razveljaviti z git ali poustvariti pri novi namestitvi.

Strani na podlagi datotek v Blockstudio to rešujejo. Strani določite kot datoteke v svoji temi, napišete predloge HTML, ki se pretvorijo v bloke WordPress, in natančno določite, kaj stranke lahko urejajo in česa ne. Izrecen ukaz sinhronizira te datoteke v običajne objave WordPress, predloge pa ostanejo glavni vir resnice.

Ta vodnik po korakih pokaže, kako ustvariti strani od začetka, s podrobnim poudarkom na zaklepanju in nadzoru urejanja, zaradi katerih so strani na podlagi datotek praktične za projekte s strankami.

Vaša prva stran

V svoji temi ustvarite mapo pages, nato dodajte podmapo z dvema datotekama:

Koda
theme/
└── pages/
    └── about/
        ├── page.json
        └── index.php
JSON
{
  "name": "about",
  "title": "About Us",
  "postStatus": "publish"
}
HTML
<h1>About Us</h1>
<p>We build things for the web.</p>

Zaženite ukaz za sinhronizacijo strani:

Lupina
wp bs pages sync

Blockstudio razčleni HTML v bloke WordPress in ustvari stran z imenom »About Us« ter polžem about. Odprite jo v urejevalniku in videli boste naslov ter odstavek, prav tako, kot če bi ju dodali ročno.

Uredite index.php, spremenite besedilo in znova zaženite ukaz. Znova naložite urejevalnik, da vidite posodobitev. To je osnovni cikel: pišite HTML, sinhronizirajte po potrebi in dobite bloke.

Jezik predlog

Razčlenjevalnik HTML v Blockstudio pretvori standardne elemente HTML v bloke WordPress. Napišite <p> in dobili boste blok odstavka. Napišite <h2> in dobili boste naslovni blok. Preslikava je intuitivna:

HTML Blok
<p> Odstavek
<h1> do <h6> Naslov (raven ustreza oznaki)
<ul>, <ol> Seznam
<blockquote> Navedek
<img> Slika
<div>, <section> Skupina
<hr> Ločilo
<details> Podrobnosti
<table> Tabela

Za bloke brez neposredne ustreznice HTML uporabite element <block> z atributom name:

HTML
<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>

Atributi elementov <block> se posredujejo kot atributi bloka. Vrednosti se samodejno pretvorijo: "true" postane logična vrednost, "3" celo število, nizi JSON, kot je '{"type":"flex"}', pa se dekodirajo v objekte.

Postavitve

Skupine podpirajo različne načine postavitve prek atributa layout:

HTML
<!-- 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>

Bloki po meri

Sintaksa <block> deluje za vsak registriran blok, vključno z vašimi bloki Blockstudio:

HTML
<block name="my-theme/hero" title="Welcome" background="dark" />
<block name="my-theme/testimonial" quote="Great product." author="Jane" />

Atributi se samodejno preslikajo v vrednosti polj Blockstudio bloka.

Ustvarjanje pristajalne strani

Tukaj je celotna pristajalna stran, ki za strukturo in postavitev uporablja osnovne bloke:

JSON
{
  "name": "landing",
  "title": "Landing Page",
  "slug": "landing",
  "postStatus": "publish",
  "templateLock": "all"
}
HTML
<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>

Ta stran vsebuje uvodno pasico, mrežo funkcij v treh stolpcih, razdelek s predstavnostjo in besedilom, razdelke s pogostimi vprašanji v obliki harmonike ter CTA. Vse je v eni datoteki HTML. Vrednost templateLock: "all" v page.json pomeni, da stranka ne more ničesar spremeniti. Naslednji razdelek pojasnjuje, kako to omejitev omiliti.

Nadzor nad urejevalnikom

Tu postanejo strani, ki temeljijo na datotekah, zares zmogljive. Blockstudio vam omogoča dva neodvisna nadzora: zaklep predloge in način urejanja blokov. Skupaj vam omogočata natančno določiti, katere dele strani lahko stranke spreminjajo. Zaklenite strukturo, besedilo pa jim pustite urejati. Zamrznite nekatere razdelke, druge pa pustite povsem odprte. Ustvarite stran, na kateri lahko stranka vpiše besedilo samo v tri določene naslove.

Zaklep predloge

Lastnost templateLock v page.json nadzoruje strukturno urejanje: ali je mogoče bloke dodajati, odstranjevati ali prerazporejati.

"all" (privzeto)

JSON
{
  "name": "terms",
  "templateLock": "all"
}

Najstrožji zaklep. Stranke ne morejo dodajati, odstranjevati ali premikati blokov. Prav tako ne morejo urejati vsebine blokov (razen v kombinaciji z blockEditingMode). To je privzeta nastavitev, če vrednosti ne določite.

Kdaj uporabiti: Pravne strani, pogoji storitve, pravilniki o zasebnosti. Katera koli stran, katere vsebino je treba spreminjati samo prek kode.

"insert"

JSON
{
  "name": "about",
  "templateLock": "insert"
}

Stranke ne morejo dodajati ali odstranjevati blokov, lahko pa premikajo obstoječe bloke in urejajo njihovo vsebino. Število blokov ostane nespremenjeno, njihov vrstni red pa je prilagodljiv.

Kdaj uporabiti: Strani, na katerih želite določen nabor razdelkov, stranka pa naj jih lahko prerazporedi. Portfeljska stran z vnaprej določenim številom razdelkov, pri kateri stranka določi njihov vrstni red.

"contentOnly"

JSON
{
  "name": "homepage",
  "templateLock": "contentOnly"
}

Stranke lahko urejajo besedilno vsebino, ne morejo pa dodajati, odstranjevati ali premikati blokov. Razlika v primerjavi z "all" je, da "all" preprečuje tudi urejanje vsebine, medtem ko ga "contentOnly" izrecno omogoča.

Kdaj uporabiti: Najpogostejša izbira za strani, namenjene strankam. Razvijalec nadzoruje postavitev, stranka pa vnese besedilo.

false

JSON
{
  "name": "blog",
  "templateLock": false
}

Brez zaklepa. Stranke imajo popoln nadzor: dodajajo, odstranjujejo, premikajo in urejajo lahko kateri koli blok. Predloga zagotovi začetno strukturo, nato pa je stran v rokah stranke.

Kdaj uporabiti: Začetne strani spletnega dnevnika, strani s prosto oblikovano vsebino ali katero koli stran, na kateri naj ima stranka popolno uredniško svobodo.

Način urejanja blokov

Medtem ko templateLock nadzoruje strukturo (dodajanje, odstranjevanje, premikanje), blockEditingMode nadzoruje interakcijo na ravni posameznega bloka: ali je bloke sploh mogoče izbrati, konfigurirati ali urejati.

Privzeto nastavitev za stran določite v page.json:

JSON
{
  "name": "landing",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}

"default"

Popolno urejanje. Bloke je mogoče izbrati, spreminjati njihove nastavitve in urejati njihovo vsebino. To je običajna izkušnja pri urejanju.

"contentOnly"

Bloke je mogoče urejati, vendar samo njihovo besedilno vsebino. Nastavitev blokov ne morete odpreti, spreminjati barv, prilagajati odmikov ali spreminjati drugih atributov, ki niso povezani z vsebino. Orodna vrstica bloka prikazuje samo možnosti za oblikovanje besedila.

"disabled"

Bloki so povsem neinteraktivni. V urejevalniku so prikazani, vendar jih ni mogoče klikniti, izbrati ali kakor koli spreminjati. Stranka vidi vsebino, ne more pa je spreminjati.

Izjeme za posamezne elemente

Zanimivo postane tukaj. Nastavitev blockEditingMode na ravni strani določa privzeto vrednost za vsak blok na strani, vendar jo lahko preglasite pri posameznih elementih v predlogi:

JSON
{
  "name": "landing",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<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>

Privzeta nastavitev strani je "disabled", zato so vsi bloki sprva neinteraktivni. Nato pri posameznih elementih omogočite "contentOnly", da je mogoče urejati samo njihovo besedilo. Rezultat je stran, na kateri lahko stranka vpiše besedilo natanko v dve besedilni polji (naslov in odstavek v uvodnem pasu) ter en odstavek o funkciji. Vse drugo ostane zaklenjeno.

To deluje pri katerem koli elementu HTML (<h1>, <p>, <div> itd.) in pri elementih <block>. Pri posameznih elementih lahko nastavite tudi blockEditingMode="default", da omogočite popoln dostop za urejanje:

HTML
<block name="core/buttons" blockEditingMode="default">
  <block name="core/button" url="/contact">Fully editable button</block>
</block>

Stranka lahko zdaj spremeni besedilo gumba, URL, sloge in druge nastavitve. Vse drugo na strani ostane zamrznjeno.

Kaskadno spreminjanje nadrejenih elementov

Pomembna podrobnost je, kako izjeme za posamezne elemente delujejo z vsebnimi bloki. Če je privzeta nastavitev strani "disabled" in pri naslovu znotraj skupine nastavite blockEditingMode="contentOnly", mora biti naslov dosegljiv. Njegova nadrejena skupina pa je "disabled", zato vanjo sploh ni mogoče vstopiti.

Blockstudio to uredi samodejno. Ko ima podrejeni blok izjemo za način urejanja, se vsi njegovi nadrejeni bloki nastavijo na "contentOnly", da podrejeni blok ostane dostopen. Načinov za nadrejene vsebnike vam ni treba nastavljati ročno. Izjemo nastavite samo za blok, ki ga želite omogočiti za urejanje, in pot do njega se odpre.

HTML
<!-- 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>

Kaskadno spreminjanje nadrejenih elementov vsebnike nastavi največ na "contentOnly", nikoli pa na "default". Tako postanejo nadrejene skupine dostopne za krmarjenje (vanje lahko vstopite), ne pa tudi za polno urejanje (njihovih nastavitev ne morete spreminjati).

Preglednica možnosti

S kombiniranjem templateLock in blockEditingMode dobite širok nabor možnosti nadzora. Tukaj je nekaj najuporabnejših kombinacij:

Razvijalec nadzoruje vse

JSON
{ "templateLock": "all" }

blockEditingMode ni potreben. Privzeta nastavitev templateLock: "all" prepreči vse spremembe. Uporabite jo za strani, ki se urejajo izključno prek kode.

Stranka ureja vse besedilo

JSON
{ "templateLock": "contentOnly" }

Stranka lahko ureja besedilo v katerem koli bloku, ne more pa spreminjati strukture strani. Preprosto in prilagodljivo.

Stranka ureja samo določeno besedilo

JSON
{
  "templateLock": "all",
  "blockEditingMode": "disabled"
}

V kombinaciji z blockEditingMode="contentOnly" pri posameznih elementih v predlogi. To je najbolj natančna možnost: stranka lahko ureja samo bloke, ki jih izrecno označite.

Stranka prerazporeja določene razdelke

JSON
{ "templateLock": "insert" }

Stranka lahko prerazporedi razdelke in ureja vsebino, ne more pa dodajati ali brisati blokov. Primerno za strani z določenim naborom razdelkov, ki so lahko v poljubnem vrstnem redu.

Stranka ima popoln nadzor

JSON
{ "templateLock": false }

Predloga je izhodišče. Nato lahko stranka počne, kar želi.

Ohranjanje sprememb stranke

Ko posodobite datoteko predloge, Blockstudio privzeto zamenja celotno vsebino strani. Če je stranka v urejevalniku spremenila naslov, ta sprememba po naslednji sinhronizaciji izgine. To je ustrezno za strani pod nadzorom razvijalca, za strani z vsebino, ki jo prispevajo stranke, pa potrebujete način, da ohranite njihovo delo.

Ključi

Elementu dodajte atribut key, da ga označite za združevanje namesto zamenjave:

HTML
<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>

Ko se predloga spremeni in se stran znova sinhronizira:

  • Bloki s ključem ohranijo vsebino stranke (besedilo, notranje bloke, oblikovanje). Strukturni atributi predloge (na primer url naslovnega bloka) se še vedno posodobijo.
  • Bloki brez ključa se v celoti zamenjajo z različico iz predloge.

Ključ zaščiti celoten blok in vse njegove podrejene elemente. Posameznim odstavkom znotraj skupine, ki ima ključ, ni treba dodajati ključev. Ključ skupine pokriva vse elemente v njej.

Ključi morajo biti enolični

Ključi morajo biti enolični v celotni predlogi. Če imata dva elementa isti ključ, se drugi obravnava kot element brez ključa (in izda se opozorilo PHP). Uporabite opisna imena: "hero", "features", "cta", "testimonial-section".

Razvoj predlog

S ključi lahko predlogi dodajate nove razdelke, ne da bi posegli v obstoječo vsebino stranke:

HTML
<h1 key="title">Welcome</h1>
<div key="services">
  <h2>Our Services</h2>
  <p>We do great work.</p>
</div>
HTML
<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>

Ob sinhronizaciji naslov in storitve ohranijo spremembe stranke. Nov razdelek z mnenji strank se prikaže s privzeto vsebino iz predloge. Če pozneje iz predloge odstranite blok s ključem, se izbriše tudi s strani.

Celoten potek dela s stranko

Vse skupaj uporabimo v resničnem projektu:

JSON
{
  "name": "homepage",
  "title": "Home",
  "slug": "home",
  "postStatus": "publish",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<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>

Ta stran ima štiri razdelke s ključi. Stranka lahko ureja naslove in odstavke, označene z blockEditingMode="contentOnly", te spremembe pa se ohranijo pri posodobitvah predloge. Razvijalec nadzoruje postavitev, slike, URL-je gumbov in celotno strukturo. Če razvijalec pozneje doda razdelek z mnenji strank med »o nas« in »poziv k dejanju«, se ta prikaže ob naslednji sinhronizaciji, ne da bi vplival na besedilo stranke.

Povezave blokov: alternativa ključem

WordPress 6.5 je uvedla Block BindingsAPI, ki povezuje atribute blokov z metapodatki objave. Namesto da bi bila vsebina, ki jo je mogoče urejati, shranjena v oznakah bloka (kjer jo varujejo ključi), je shranjena v wp_postmeta (kjer je sinhronizacija predlog ne more spremeniti).

HTML
<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>

Metaključe je treba registrirati v PHP:

PHP
register_post_meta( 'page', 'hero_title', array(
    'show_in_rest' => true,
    'single'       => true,
    'type'         => 'string',
    'default'      => 'Default Title',
) );

Povezave blokov imajo v primerjavi s ključi dve prednosti: po podatkih je mogoče poizvedovati z WP_Query prek meta_query, na voljo pa so tudi v REST API. Slabost je, da morate vsak metaključ registrirati v PHP, povezave pa delujejo samo pri posameznih atributih blokov (ne pri kompleksni ugnezdeni vsebini).

Za razdelke z bogato vsebino, pri katerih je pomembna struktura blokov (skupina z naslovi, odstavki in slikami), uporabite ključe. Povezave uporabite za posamezne vrednosti besedila, po katerih morate tudi iskati ali jih prikazovati drugje.

Predloge za vrste objav

Uporabite templateFor za nastavitev privzete strukture blokov za vse nove objave določene vrste:

JSON
{
  "name": "product-template",
  "title": "Product Template",
  "templateFor": "product",
  "templateLock": "insert"
}
HTML
<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>

Vsaka nova objava vrste »product« se začne s to strukturo. templateLock: "insert" urednikom omogoča prerazporejanje razdelkov in urejanje vsebine, ne pa dodajanja ali odstranjevanja blokov.

Nasveti

Sinhronizirajte ob načrtovanem mejniku uvedbe. Zaženite wp bs pages sync po spremembi ali uvedbi virov strani. Obisk uporabniškega vmesnika in skrbniškega vmesnika strani nikoli ne sinhronizira. Orodja za uvedbo PHP lahko pokličejo Blockstudio\Pages::reconcile() in pregledajo njegovo strojno berljivo poročilo.

Pripnite pomembne ID-je objav. Za strani, na katere se sklicujejo meniji, statične povezave ali zunanji sistemi, uporabite postId v page.json. Če strani ne pripnete in jo izbrišete ter znova ustvarite, dobi nov ID, zato se sklici nanjo prekinejo.

Za ogrodja uporabite sync: false. Če želite stran ustvariti enkrat in jo nato v celoti prepustiti stranki, nastavite "sync": false in jo ustvarite z Blockstudio\Pages::force_sync(). Običajno usklajevanje jo nato prezre.

Zaklepanje in odklepanje z PHP. Pokličite Blockstudio\Pages::lock('about'), da preprečite sinhronizacijo določene strani (uporabno med intenzivnim obdobjem urejanja za stranko). Za ponovni vklop sinhronizacije pokličite Blockstudio\Pages::unlock('about').

Mehanizmi za predloge. Poleg PHP lahko predloge napišete v Twig (zahteva Timber) ali Blade (zahteva illuminate/view). To je uporabno za zanke in filtre, vendar se predloge strani prevedejo med izrecno sinhronizacijo, ne med zahtevo odjemalca. Uporabite PHP, če samo prevajanje izvorne kode potrebuje pomočnike, značilne za PHP.

Prisilna sinhronizacija prezre ključe. Klic Pages::force_sync('about') zamenja celotno vsebino strani in prezre ključe ter preverjanje časa spremembe. Uporabite ga, kadar želite stran namenoma ponastaviti v stanje predloge.

Naslednji koraki

  • Referenca za strani: podroben opis vseh lastnosti page.json, PHP API in algoritma za združevanje na podlagi ključev.
  • Pregled strani in vzorcev: razčlenjevalnik HTML, referenca za sintakso blokov, upodobitve po meri in preslikava elementov.
  • Vzorci: enaka sintaksa predlog za vzorce blokov za večkratno uporabo namesto strani.