Treci la conținut

Crearea paginilor bazate pe fișiere

În mod tradițional, paginile WordPress sunt create în editorul de blocuri: trageți blocuri, configurați setările, apoi salvați. Această abordare funcționează pentru clienții care își creează propriile pagini, dar creează probleme dezvoltatorilor care construiesc pagini structurate și urmărite în sistemul de versiuni. Aspectul paginii este stocat în baza de date, nu în cod. Nu îl puteți analiza într-o cerere de integrare, reveni la o versiune anterioară cu git sau reproduce într-o instalare nouă.

Paginile bazate pe fișiere ale Blockstudio rezolvă această problemă. Definiți paginile în fișiere din tema dumneavoastră, scrieți șabloane HTML care se convertesc în blocuri WordPress și controlați exact ce pot și ce nu pot edita clienții. O comandă explicită sincronizează aceste fișiere cu articole WordPress obișnuite, iar șabloanele rămân sursa de adevăr.

Acest ghid vă îndrumă să creați pagini de la zero și se concentrează în detaliu asupra comenzilor de blocare și editare care fac paginile bazate pe fișiere practice pentru proiectele clienților.

Prima pagină

Creați un folder pages în tema dumneavoastră, apoi adăugați un subfolder cu două fișiere:

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

Rulați comanda de sincronizare a paginilor:

Shell
wp bs pages sync

Blockstudio analizează HTML în blocuri WordPress și creează o pagină numită “About Us”, cu slug-ul about. Deschideți pagina în editor și veți vedea un antet și un paragraf, exact ca și cum le-ați fi adăugat manual.

Editați index.php, schimbați textul și rulați din nou comanda. Reîncărcați editorul pentru a vedea actualizarea. Acesta este fluxul de lucru de bază: scrieți HTML, sincronizați intenționat și obțineți blocuri.

Limbajul șabloanelor

Parserul HTML al Blockstudio convertește elementele standard HTML în blocuri WordPress. Scrieți un <p> pentru a obține un bloc paragraf. Scrieți un <h2> pentru a obține un bloc titlu. Corespondența este intuitivă:

HTML Bloc
<p> Paragraf
<h1> până la <h6> Titlu (nivelul corespunde etichetei)
<ul>, <ol> Listă
<blockquote> Citat
<img> Imagine
<div>, <section> Grup
<hr> Separator
<details> Detalii
<table> Tabel

Pentru blocurile fără un echivalent direct HTML, folosiți elementul <block> cu un atribut 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>

Atributele elementelor <block> sunt transmise ca atribute ale blocului. Valorile sunt convertite automat: "true" devine o valoare booleană, "3" devine un număr întreg, iar șirurile JSON precum '{"type":"flex"}' sunt decodificate în obiecte.

Aspecte

Grupurile acceptă diferite moduri de aspect prin atributul 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>

Blocuri personalizate

Sintaxa <block> funcționează pentru orice bloc înregistrat, inclusiv pentru blocurile Blockstudio proprii:

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

Atributele sunt asociate automat valorilor câmpurilor Blockstudio ale blocului.

Crearea unei pagini de destinație

Iată o pagină de destinație completă care folosește blocuri de bază pentru structură și aspect:

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>

Această pagină are o secțiune hero de copertă, o grilă cu trei coloane pentru caracteristici, o secțiune media-text, acordeoane FAQ și un CTA. Totul provine dintr-un singur fișier HTML. Valoarea templateLock: "all" din page.json înseamnă că clientul nu poate schimba nimic. Secțiunea următoare explică cum puteți relaxa această restricție.

Controlul editorului

Aici paginile bazate pe fișiere devin cu adevărat puternice. Blockstudio vă oferă două controale independente: blocarea șablonului și modul de editare a blocurilor. Împreună, vă permit să definiți exact ce părți ale unei pagini pot modifica clienții. Blocați structura, dar permiteți editarea textului. Înghețați unele secțiuni, lăsându-le pe celelalte complet libere. Creați o pagină în care singurul lucru pe care îl poate face clientul este să completeze trei titluri specifice.

Blocarea șablonului

Proprietatea templateLock din page.json controlează editarea structurii: dacă blocurile pot fi adăugate, eliminate sau rearanjate.

"all" (implicit)

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

Cea mai strictă blocare. Clienții nu pot adăuga, elimina sau muta blocuri. De asemenea, nu pot edita conținutul blocurilor (decât dacă este combinată cu blockEditingMode). Aceasta este valoarea implicită dacă nu specificați o valoare.

Când să o folosiți: pagini juridice, termeni de utilizare, politici de confidențialitate. Orice pagină al cărei conținut ar trebui să se schimbe numai prin cod.

"insert"

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

Clienții nu pot adăuga sau elimina blocuri, dar pot muta blocurile existente și le pot edita conținutul. Numărul blocurilor rămâne fix, dar ordinea este flexibilă.

Când să o folosiți: pagini cu un set fix de secțiuni pe care clientul le poate reordona. De exemplu, o pagină de portofoliu în care numărul secțiunilor este prestabilit, dar clientul decide ordinea.

"contentOnly"

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

Clienții pot edita conținutul text, dar nu pot adăuga, elimina sau muta blocuri. Diferența față de "all" este că "all" împiedică și editarea conținutului, în timp ce "contentOnly" o permite explicit.

Când să o folosiți: cea mai frecventă alegere pentru paginile destinate clienților. Dezvoltatorul controlează aspectul. Clientul completează textul.

false

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

Fără nicio blocare. Clienții au control deplin: pot adăuga, elimina, muta și edita orice bloc. Șablonul oferă o structură de pornire, iar apoi clientul o gestionează.

Când să o folosiți: pagini de index ale blogului, pagini cu conținut liber sau orice pagină în care clientul ar trebui să aibă libertate editorială deplină.

Modul de editare a blocurilor

În timp ce templateLock controlează structura (adăugare, eliminare, mutare), blockEditingMode controlează interacțiunea la nivelul fiecărui bloc: dacă blocurile pot fi selectate, configurate sau editate.

Setați o valoare implicită la nivel de pagină în page.json:

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

"default"

Editare completă. Blocurile pot fi selectate, setările lor pot fi modificate, iar conținutul poate fi editat. Aceasta este experiența obișnuită în editor.

"contentOnly"

Blocurile pot fi editate, dar numai pentru conținutul text. Nu puteți deschide setările blocurilor, schimba culorile, ajusta spațierea interioară sau modifica alte atribute decât cele de conținut. Bara de instrumente a blocului afișează doar opțiuni de formatare a textului.

"disabled"

Blocurile sunt complet lipsite de interactivitate. Se afișează în editor, dar nu pot fi accesate prin clic, selectate sau modificate în niciun fel. Clientul vede conținutul, dar nu îl poate modifica.

Excepții pentru fiecare element

Aici lucrurile devin interesante. blockEditingMode la nivel de pagină stabilește o valoare implicită pentru fiecare bloc de pe pagină, dar o puteți suprascrie pentru elemente individuale din șablon:

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>

Valoarea implicită a paginii este "disabled", așa că fiecare bloc este inițial lipsit de interactivitate. Apoi, anumite elemente activează "contentOnly", permițând editarea doar a textului lor. Rezultatul: o pagină în care clientul poate completa exact două câmpuri text (titlul principal și paragraful) și un paragraf despre o funcționalitate. Tot restul este blocat.

Acest lucru funcționează pentru orice element HTML (<h1>, <p>, <div> etc.) și pentru elementele <block>. De asemenea, puteți seta blockEditingMode="default" pentru anumite elemente, pentru a oferi acces complet la editare:

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

Acum clientul poate schimba textul butonului, URL, stilurile și orice altă setare. Tot restul paginii rămâne blocat.

Cascada elementelor strămoșești

Există un detaliu important privind modul în care excepțiile pentru fiecare element interacționează cu blocurile container. Dacă valoarea implicită a paginii este "disabled" și setați blockEditingMode="contentOnly" pentru un titlu dintr-un grup, titlul trebuie să poată fi accesat. Dar grupul părinte are valoarea "disabled", ceea ce înseamnă că nu poate fi accesat deloc.

Blockstudio gestionează automat acest lucru. Când un bloc copil are o excepție pentru modul de editare, toate blocurile sale strămoșești sunt setate la "contentOnly", astfel încât copilul să rămână accesibil. Nu trebuie să setați manual modurile pentru containerele părinte. Setați excepția doar pentru blocul pe care doriți să îl faceți editabil, iar calea către el se va deschide.

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>

Cascada elementelor strămoșești ridică nivelul containerelor doar la "contentOnly", niciodată la "default". Astfel, grupurile strămoșești pot fi parcurse (le puteți accesa), dar nu pot fi editate complet (nu le puteți schimba setările).

Matricea deciziilor

Combinarea valorilor templateLock și blockEditingMode vă oferă o gamă largă de opțiuni de control. Iată cele mai utile combinații:

Dezvoltatorul controlează totul

JSON
{ "templateLock": "all" }

Nu este nevoie de blockEditingMode. Valoarea implicită templateLock: "all" împiedică toate modificările. Folosiți-o pentru pagini gestionate în întregime prin cod.

Clientul editează tot textul

JSON
{ "templateLock": "contentOnly" }

Clientul poate edita textul din orice bloc, dar nu poate schimba structura paginii. Simplu și permisiv.

Clientul editează doar anumite texte

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

Combinat cu blockEditingMode="contentOnly" pentru elemente specifice din șablon. Aceasta este opțiunea cea mai precisă: clientul poate edita doar blocurile pe care le marcați.

Clientul reordonează secțiuni fixe

JSON
{ "templateLock": "insert" }

Clientul poate rearanja secțiunile și edita conținutul, dar nu poate adăuga sau șterge blocuri. Potrivită pentru pagini cu un set fix de secțiuni, a căror ordine poate fi schimbată.

Clientul are control deplin

JSON
{ "templateLock": false }

Șablonul este un punct de pornire. De acolo, clientul poate face orice.

Păstrarea modificărilor clientului

În mod implicit, când actualizați un fișier șablon, Blockstudio înlocuiește întregul conținut al paginii. Dacă clientul a editat un titlu în editor, modificarea se pierde după următoarea sincronizare. Acest lucru este în regulă pentru paginile controlate de dezvoltator, dar pentru paginile la care contribuie clienții aveți nevoie de o modalitate de a le păstra modificările.

Chei

Adăugați atributul key oricărui element pentru a-l marca în vederea îmbinării, nu a înlocuirii:

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>

Când șablonul se modifică și pagina se sincronizează din nou:

  • Blocurile cu cheie păstrează conținutul clientului (text, blocuri interioare, formatare). Atributele structurale ale șablonului (precum url al imaginii de copertă) se actualizează în continuare.
  • Blocurile fără cheie sunt înlocuite în întregime cu versiunea din șablon.

O cheie protejează întregul bloc și toți copiii săi. Nu trebuie să atribuiți chei paragrafelor individuale dintr-un grup care are deja o cheie. Cheia grupului acoperă tot ce se află în el.

Cheile trebuie să fie unice

Cheile trebuie să fie unice în întregul șablon. Dacă două elemente au aceeași cheie, al doilea este tratat ca și cum nu ar avea cheie (și se emite un avertisment PHP). Folosiți nume descriptive: "hero", "features", "cta", "testimonial-section".

Șabloane în evoluție

Cheile vă permit să adăugați secțiuni noi la un șablon fără a afecta conținutul existent al clientului:

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>

La sincronizare, titlul și serviciile păstrează modificările clientului. Noua secțiune de mărturii apare cu conținutul implicit din șablon. Dacă ulterior eliminați din șablon un bloc cu cheie, acesta este șters din pagină.

Fluxul complet de lucru al clientului

Iată cum se aplică toate acestea unui proiect real:

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>

Această pagină are patru secțiuni cu chei. Clientul poate edita titlurile și paragrafele marcate cu blockEditingMode="contentOnly", iar modificările se păstrează la actualizarea șabloanelor. Dezvoltatorul controlează aspectul, imaginile, URL-urile butoanelor și structura generală. Dacă dezvoltatorul adaugă ulterior o secțiune de mărturii între „about” și „cta”, aceasta apare la următoarea sincronizare fără să afecteze niciun text al clientului.

Asocierea blocurilor: o alternativă la chei

WordPress 6.5 a introdus Asocierile de blocuriAPI , care conectează atributele blocurilor la metadatele postărilor. În loc să stocați conținutul editabil în marcajul blocului (unde cheile îl protejează), conținutul se află în wp_postmeta (unde sincronizările șabloanelor nu îl pot modifica).

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>

Cheile meta trebuie înregistrate în PHP:

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

Asocierile blocurilor au două avantaje față de chei: datele pot fi interogate cu WP_Query prin meta_query și sunt disponibile în REST API. Compromisul este că trebuie să înregistrați fiecare cheie meta în PHP, iar asocierile funcționează doar pentru atributele individuale ale blocurilor (nu și pentru conținutul imbricat complex).

Folosiți cheile pentru secțiunile cu conținut bogat, unde structura blocurilor contează (un grup cu titluri, paragrafe și imagini). Folosiți asocierile pentru valori text individuale pe care trebuie să le interogați sau să le afișați și în altă parte.

Șabloane pentru tipuri de articole

Folosiți templateFor pentru a seta o structură implicită de blocuri pentru toate articolele noi de un anumit tip:

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>

Fiecare articol nou de tip „product” începe cu această structură. templateLock: "insert" le permite editorilor să rearanjeze secțiunile și să editeze conținutul, dar nu să adauge sau să elimine blocuri.

Sfaturi

Sincronizați la un moment ales în mod intenționat în procesul de implementare. Rulați wp bs pages sync după modificarea sau implementarea surselor paginilor. Accesările interfeței publice și ale panoului de administrare nu sincronizează paginile. Instrumentele de implementare PHP pot apela Blockstudio\Pages::reconcile() și inspecta raportul într-un format lizibil automat.

Fixați ID-urile importante ale articolelor. Folosiți postId în page.json pentru paginile menționate în meniuri, linkuri hardcodate sau sisteme externe. Fără fixarea ID-ului, o pagină ștearsă și creată din nou primește un ID nou, ceea ce întrerupe acele referințe.

Folosiți sync: false pentru pagini schelet. Dacă doriți să creați o pagină o singură dată, apoi să o predați în întregime clientului, setați "sync": false și creați-o cu Blockstudio\Pages::force_sync(). Reconcilierea obișnuită o va ignora.

Blocați și deblocați prin PHP. Apelați Blockstudio\Pages::lock('about') pentru a împiedica sincronizarea unei anumite pagini (util în perioadele în care clientul editează intens). Apelați Blockstudio\Pages::unlock('about') pentru a reactiva sincronizarea.

Motoare de șabloane. Pe lângă PHP, șabloanele pot fi scrise în Twig (necesită Timber) sau Blade (necesită illuminate/view). Acest lucru este util pentru bucle și filtre, dar șabloanele de pagină sunt compilate în timpul sincronizării explicite, nu în timpul solicitării interfeței publice. Folosiți PHP dacă însuși procesul de compilare a sursei are nevoie de funcții auxiliare specifice PHP.

Sincronizarea forțată ignoră cheile. Apelarea Pages::force_sync('about') înlocuiește întregul conținut al paginii, ignorând cheile și verificările datei modificării. Folosiți-o când doriți în mod intenționat să readuceți o pagină la starea din șablon.

Pașii următori

  • Referința paginilor: toate proprietățile page.json, PHP API și algoritmul de îmbinare pe bază de chei, explicate în detaliu.
  • Prezentare generală a paginilor și modelelor: analizatorul HTML, referința sintaxei blocurilor, randerele personalizate și maparea elementelor.
  • Modele: aceeași sintaxă de șablon pentru modele de blocuri reutilizabile în locul paginilor.