Treci la conținut

Pagini și modele

Blockstudio vă permite să definiți pagini WordPress, modele de blocuri și șabloane Site Editor ca fișiere în tema dvs. Scrieți șabloane de tip HTML, iar analizatorul Blockstudio le convertește în blocuri native WordPress.

  • Paginile sunt sincronizate cu baza de date ca articole WordPress, păstrând sincronizate șabloanele de fișiere și conținutul paginilor.
  • Modelele sunt înregistrate în memorie prin register_block_pattern() și sunt disponibile în inseratorul de blocuri, pentru a fi plasate oriunde de către utilizatori.
  • Șabloanele site-ului oferă surse wp_template și wp_template_part bazate pe fișiere pentru Site Editor-ul WordPress.

Toate cele trei funcționalități folosesc același analizator HTML și aceeași sintaxă pentru blocuri.

Crearea paginilor bazate pe fișiere

Un ghid practic pentru șabloanele de pagini bazate pe fișiere, sincronizare și blocare.

Structura folderelor

Cod
theme/
├── pages/
│   ├── about/
│   │   ├── page.json
│   │   └── index.php
│   └── contact/
│       ├── page.json
│       └── index.twig
├── patterns/
    ├── hero/
    │   ├── pattern.json
    │   └── index.php
    └── cta/
        ├── pattern.json
        └── index.blade.php
├── templates/
    └── front-page/
        ├── template.json
        └── index.php
└── parts/
    └── header/
        ├── part.json
        └── index.php

Fiecare subfolder conține un fișier de configurare JSON (page.json, pattern.json, template.json sau part.json) și un fișier șablon.

Motoare de șabloane

Șabloanele pot fi scrise ca marcaj simplu în index.php sau în Twig ori Blade:

Fișier Motor Cerință
index.php Niciunul (citit ca atare, codul PHP nu este executat) Niciuna
index.twig Twig Timber
index.blade.php Blade illuminate/view

Dacă există mai multe fișiere șablon, ordinea priorității este: index.php > index.blade.php > index.twig.

Deoarece șabloanele sunt compilate la inițializare (înainte de existența contextului oricărei cereri), șabloanele Twig și Blade nu au acces la variabile dinamice. Sunt utile pentru funcții și filtre încorporate, precum {{ "text"|upper }} sau {{ strtoupper("text") }}.

Maparea HTML la blocuri

Elementele standard HTML sunt convertite automat în blocurile WordPress corespunzătoare.

Text

HTML Bloc
<p> core/paragraph
<h1> – <h6> core/heading
<ul> core/list (neordonată)
<ol> core/list (ordonată)
<li> core/list-item
<blockquote> core/quote
<code> core/code
<pre> core/preformatted

Listele își păstrează structura. Un element <ul> sau <ol> dintr-un <li> devine un bloc intern core/list al acelui core/list-item, forma pe care o salvează editorul, astfel încât listele se pot imbrica la orice nivel. Un element class dintr-o listă sau dintr-un element al acesteia devine className, mod prin care se setează un stil de bloc precum is-style-checks dintr-un fișier de pagină; <block name="core/list" className="..."> face același lucru.

Media

HTML Bloc
<img> core/image
<figure> core/image (cu legendă)
<audio> core/audio
<video> core/video

Aspect

HTML Bloc
<div>, <section> core/group
<main>, <header>, <footer>, <article>, <aside> core/group care păstrează elementul drept tagName
<hr> core/separator
<details> core/details
<table> core/table

Sintaxa blocurilor

Pentru blocurile care nu au un echivalent direct HTML, folosiți elementul <block>:

HTML
<block name="core/cover" url="https://example.com/hero.jpg">
  <h1>Welcome</h1>
  <p>Content inside the cover block.</p>
</block>

Blocuri de bază

HTML
<!-- Pullquote -->
<block name="core/pullquote">
  <p>An important quote.</p>
</block>

<!-- Verse -->
<block name="core/verse">Roses are red,
Violets are blue.</block>

<!-- Cover -->
<block name="core/cover" url="https://example.com/image.jpg">
  <h2>Cover Title</h2>
</block>

<!-- Embed -->
<block name="core/embed" url="https://youtube.com/watch?v=..." providerNameSlug="youtube" />

<!-- Spacer -->
<block name="core/spacer" height="50px" />

<!-- Gallery -->
<block name="core/gallery">
  <img src="https://example.com/1.jpg" alt="Image 1" />
  <img src="https://example.com/2.jpg" alt="Image 2" />
</block>

<!-- Columns -->
<block name="core/columns">
  <block name="core/column">
    <h3>Column 1</h3>
  </block>
  <block name="core/column">
    <h3>Column 2</h3>
  </block>
</block>

<!-- Buttons -->
<block name="core/buttons">
  <block name="core/button" url="/get-started">Get Started</block>
</block>

<!-- Row (flex layout) -->
<block name="core/group" layout='{"type":"flex","flexWrap":"nowrap"}'>
  <p>Item 1</p>
  <p>Item 2</p>
</block>

Blocuri personalizate

Aceeași sintaxă funcționează pentru orice bloc înregistrat:

HTML
<block name="blockstudio/section">
  <h1>Welcome</h1>
</block>

<block name="acf/hero" title="Hero Title" background="dark">
  <p>Inner content becomes InnerBlocks.</p>
</block>

Atribute

Atributele HTML ale elementelor <block> sunt transmise ca atribute ale blocului. Sunt acceptate valorile JSON:

HTML
<block name="core/heading" level="3">Custom Heading</block>

<block name="core/group" layout='{"type":"flex","orientation":"vertical"}'>
  <p>Stacked content.</p>
</block>

<img src="https://example.com/photo.jpg" alt="Photo" width="800" height="400" />

Valorile atributelor sunt decodate o singură dată, așa cum le citește un browser, astfel încât data-animate="[&amp;>span]:fade" și data-animate="[&>span]:fade" stochează aceeași valoare.

Pe un element mapat la un bloc Blockstudio, fiecare atribut este stocat împreună cu blocul. Câmpurile declarate ajung în șablon; atributele globale pe care blocul nu le declară (id, style, role, title, lang, dir, hidden, tabindex, aria-* și data-*) sunt adăugate la elementul rădăcină al blocului la redare, exact ca în etichetele de bloc native. În sursele de pagini și modele, un prefix html- denumește doar unul dintre aceste atribute globale, astfel încât html-role="note" este transmis ca role, în timp ce gestionarele de evenimente precum html-onclick nu sunt niciodată redate. Orice altceva, inclusiv un class nedeclarat, rămâne în conținutul articolului fără să ajungă pe pagină, iar wp bs pages sync raportează acest lucru pentru fiecare pagină pe care o analizează.

Randere personalizate pentru blocuri

Analizatorul HTML folosește o arhitectură bazată pe registru. Adăugați un constructor pentru un bloc personalizat cu blockstudio/block_tags/builders:

PHP
add_filter( 'blockstudio/block_tags/builders', function( $builders, $parser ) {
    $builders['acf/hero'] = function( array $attrs, string $inner_content ) {
        $inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks( $inner_content );

        return array(
            'blockName'    => 'acf/hero',
            'attrs'        => $attrs,
            'innerBlocks'  => $inner_blocks,
            'innerHTML'    => '',
            'innerContent' => array_fill( 0, count( $inner_blocks ), null ),
        );
    };

    return $builders;
}, 10, 2 );

Apoi folosiți-l în orice șablon:

HTML
<block name="acf/hero" background="dark">
  <h1>Welcome</h1>
</block>

De asemenea, puteți suprascrie modul de redare a blocurilor de bază:

PHP
add_filter( 'blockstudio/parser/renderers', function( $renderers, $parser ) {
    $renderers['core/paragraph'] = function( array $attrs, string $inner_content ) {
        $content = trim( $inner_content );
        $attrs['align'] = $attrs['align'] ?? 'center';

        return array(
            'blockName'    => 'core/paragraph',
            'attrs'        => $attrs,
            'innerBlocks'  => array(),
            'innerHTML'    => '<p class="has-text-align-center">' . $content . '</p>',
            'innerContent' => array( '<p class="has-text-align-center">' . $content . '</p>' ),
        );
    };

    return $renderers;
}, 10, 2 );

Funcțiile callback ale constructorului primesc atributele analizate și conținutul intern brut. Acestea trebuie să returneze un tablou de blocuri WordPress. Consultați randerele personalizate pentru ordinea completă a filtrelor și un exemplu de container.

Semnătura funcției constructorului

PHP
/**
 * @param array  $attrs         Parsed element or block-tag attributes.
 * @param string $inner_content Raw inner content.
 * @return array WordPress block array.
 */
function my_builder( array $attrs, string $inner_content ): array {}

Maparea elementelor

În mod implicit, elementele standard HTML precum <h1>, <p> și <img> sunt mapate la blocurile de bază WordPress. Puteți suprascrie această mapare pentru a direcționa orice element HTML către un alt bloc folosind filtrul blockstudio/parser/element_mapping:

PHP
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
    $mapping['h1'] = 'custom/heading';
    $mapping['h2'] = 'custom/heading';
    $mapping['p']  = 'custom/paragraph';
    $mapping['img'] = 'custom/image';

    return $mapping;
}, 10, 2 );

Cu acest filtru activ, fiecare <h1> din șabloanele dvs. va genera un bloc custom/heading în loc de core/heading. Atributele elementului sunt transmise blocului țintă. Dacă este înregistrat un randor pentru numele blocului țintă, acesta va fi folosit. În caz contrar, se creează o structură generică de bloc.

Este util când tema sau pluginul dvs. oferă tipuri de blocuri personalizate care ar trebui să înlocuiască valorile implicite în toate șabloanele de pagini și modele.

Pentru mapări <p> simple, Blockstudio poate direcționa conținutul intern HTML direct către atributul richtext content al unui bloc Blockstudio înregistrat, care nu este de bază. Blocul țintă trebuie să declare un atribut cu id: "content" și type: "richtext". Formatarea în linie (a, b, br, code, del, em, i, img, ins, mark, s, small, span, strong, sub, sup, u) rămâne în valoarea direcționată chiar și atunci când aceeași etichetă este mapată la un element, așa cum sunt code și img în mod implicit. Un paragraf al cărui singur element copil este o imagine devine blocul la care mapează <img>, cel pe care îl generează Markdown pentru o imagine de sine stătătoare. Etichetele de bloc imbricate și elementele HTML de nivel bloc continuă să fie analizate ca blocuri interne.

Valorile mapării pot fi și funcții apelabile când blocul țintă depinde de atributele elementului:

PHP
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
    $mapping['div'] = function( array $attrs ) {
        if ( isset( $attrs['width'] ) ) {
            return 'theme/row';
        }

        if ( isset( $attrs['gap'] ) ) {
            return 'theme/flow';
        }

        return 'theme/div';
    };

    return $mapping;
} );

Blocurile personalizate mapate de la elemente container precum <section> și <div> analizează recursiv elementele copil HTML imbricate, astfel încât titlurile, imaginile, etichetele de bloc și paragrafele interne devin blocuri native copil.

Exemplu complet

Un șablon complet de pagină care combină mai multe tipuri de blocuri:

HTML
<div>
  <h1>Welcome to Our Site</h1>
  <p>This is an <strong>introduction</strong> with <em>formatting</em>.</p>

  <block name="core/columns">
    <block name="core/column">
      <h3>Feature One</h3>
      <p>First feature description.</p>
    </block>
    <block name="core/column">
      <h3>Feature Two</h3>
      <p>Second feature description.</p>
    </block>
  </block>

  <block name="core/cover" url="https://example.com/hero.jpg">
    <h2>Our Mission</h2>
    <p>Building amazing things together.</p>
  </block>

  <details>
    <summary>FAQ</summary>
    <p>Answers to common questions.</p>
  </details>

  <block name="core/buttons">
    <block name="core/button" url="/contact">Contact Us</block>
    <block name="core/button" url="/learn-more">Learn More</block>
  </block>
</div>