Pereiti prie turinio

Puslapiai ir šablonai

Blockstudio leidžia apibrėžti WordPress puslapius, blokų šablonus ir svetainės rengyklės šablonus kaip failus temoje. Rašykite į HTML panašius šablonus, o Blockstudio analizatorius pavers juos vietiniais WordPress blokais.

  • Puslapiai sinchronizuojami su duomenų baze kaip WordPress įrašai, todėl failų šablonai ir puslapių turinys išlieka suderinti.
  • Šablonai registruojami atmintyje per register_block_pattern() ir pateikiami blokų įterpimo priemonėje, kad naudotojai galėtų juos įterpti bet kur.
  • Svetainės šablonai suteikia failais pagrįstus wp_template ir wp_template_part šaltinius, skirtus WordPress svetainės rengyklei.

Visos trys funkcijos naudoja tą patį HTML analizatorių ir blokų sintaksę.

Puslapių kūrimas iš failų

Praktinis vadovas apie puslapių šablonus iš failų, sinchronizavimą ir užrakinimą.

Aplankų struktūra

Kodas
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

Kiekviename poaplankyje yra JSON konfigūracijos failas (page.json, pattern.json, template.json arba part.json) ir šablono failas.

Šablonų varikliai

Šablonus galima rašyti kaip paprastą žymėjimą index.php faile arba naudoti Twig ar Blade:

Failas Variklis Reikalavimas
index.php Nėra (skaitomas toks, koks yra; PHP kodas nevykdomas) Nėra
index.twig Twig Timber
index.blade.php Blade illuminate/view

Jei yra keli šablonų failai, jų prioritetų tvarka tokia: index.php > index.blade.php > index.twig.

Kadangi šablonai kompiliuojami inicijavimo metu (prieš atsirandant užklausos kontekstui), Twig ir Blade šablonai negali pasiekti dinaminių kintamųjų. Jie naudingi naudojant integruotąsias funkcijas ir filtrus, pvz., {{ "text"|upper }} arba {{ strtoupper("text") }}.

HTML atvaizdavimas į blokus

Standartiniai HTML elementai automatiškai konvertuojami į atitinkamus WordPress blokus.

Tekstas

HTML Blokas
<p> core/paragraph
<h1> – <h6> core/heading
<ul> core/list (netvarkinis)
<ol> core/list (tvarkinis)
<li> core/list-item
<blockquote> core/quote
<code> core/code
<pre> core/preformatted

Sąrašai išlaiko savo struktūrą. <ul> arba <ol>, esantis <li> viduje, tampa to core/list-item core/list vidiniu bloku – tokia forma išsaugoma redaktoriuje, todėl sąrašai gali būti bet kokio gylio. class sąraše arba elemente tampa jo className – taip puslapio faile nustatomas bloko stilius, pvz., is-style-checks; tą patį atlieka ir <block name="core/list" className="...">.

Medija

HTML Blokas
<img> core/image
<figure> core/image (su antrašte)
<audio> core/audio
<video> core/video

Maketas

HTML Blokas
<div>, <section> core/group
<main>, <header>, <footer>, <article>, <aside> core/group, kuris išsaugo elementą kaip jo tagName
<hr> core/separator
<details> core/details
<table> core/table

Blokų sintaksė

Blokams, kurie neturi tiesioginio HTML atitikmens, naudokite elementą <block>:

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

Pagrindiniai blokai

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>

Tinkinti blokai

Ta pati sintaksė tinka bet kuriam registruotam blokui:

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>

Atributai

HTML elementų <block> atributai perduodami kaip bloko atributai. Palaikomos JSON reikšmės:

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" />

Atributų reikšmės dekoduojamos vieną kartą, kaip jas perskaitytų naršyklė, todėl data-animate="[&amp;>span]:fade" ir data-animate="[&>span]:fade" išsaugo tą pačią reikšmę.

Elemente, atvaizduojamame į Blockstudio bloką, visi atributai išsaugomi kartu su bloku. Deklaruoti laukai perduodami šablonui; visuotiniai atributai, kurių blokas nedeklaruoja (id, style, role, title, lang, dir, hidden, tabindex, aria-* ir data-*), atvaizduojant priskiriami bloko šakniniam elementui, kaip ir blokų žymoms. Puslapių ir šablonų šaltiniuose html- prefiksas nurodo tik vieną iš šių visuotinių atributų, todėl html-role="note" perduodamas kaip role, o įvykių apdorojimo priemonės, pvz., html-onclick, niekada neatvaizduojamos. Visa kita, įskaitant nedeklaruotą class, lieka įrašo turinyje ir nepasiekia puslapio, o wp bs pages sync apie tai praneša kiekvienam išanalizuotam puslapiui.

Tinkintų blokų atvaizduokliai

HTML analizatorius pagrįstas registru. Tinkinto bloko konstruktorių pridėkite naudodami 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 );

Tada naudokite jį bet kuriame šablone:

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

Taip pat galite pakeisti pagrindinių blokų atvaizdavimą:

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 );

Konstruktoriaus iškvietimai gauna išanalizuotus atributus ir neapdorotą vidinį turinį. Jie turi grąžinti WordPress blokų masyvą. Išsamų filtrų vykdymo eiliškumą ir konteinerio pavyzdį rasite Tinkinti atvaizduokliai.

Konstruktoriaus funkcijos signatūra

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 {}

Elementų atvaizdavimas

Pagal numatytuosius nustatymus standartiniai HTML elementai, pvz., <h1>, <p> ir <img>, atvaizduojami į pagrindinius WordPress blokus. Šį susiejimą galite pakeisti, kad bet kuris HTML elementas būtų susietas su kitu bloku, naudodami filtrą 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 );

Kai šis filtras aktyvus, kiekvienas jūsų šablonų <h1> elementas sukurs custom/heading bloką, o ne core/heading. Elemento atributai perduodami tiksliniam blokui. Jei tikslinio bloko pavadinimui užregistruotas atvaizduoklis, jis bus naudojamas. Priešingu atveju sukuriama bendroji bloko struktūra.

Tai naudinga, kai jūsų tema ar papildinys pateikia tinkintų blokų tipų, kurie turėtų pakeisti numatytuosius blokus visuose puslapių ir šablonų šablonuose.

Paprastam <p> susiejimui Blockstudio gali tiesiogiai nukreipti vidinį HTML į registruoto, branduoliui nepriklausančio Blockstudio bloko content raiškiojo teksto atributą. Tikslinis blokas turi deklaruoti atributą su id: "content" ir type: "richtext". Įterptasis formatavimas (a, b, br, code, del, em, i, img, ins, mark, s, small, span, strong, sub, sup, u) išlieka nukreiptoje reikšmėje, net jei ta pati žyma susieta su elementu, kaip pagal numatytuosius nustatymus yra susieta code ir img. Pastraipa, kurios vienintelis vaikinis elementas yra paveikslėlis, tampa bloku, į kurį susietas <img> – tokį bloką Markdown sukuria atskiram paveikslėliui. Įdėtosios blokų žymos ir blokinio lygmens HTML toliau analizuojami kaip vidiniai blokai.

Susiejimo reikšmės taip pat gali būti iškviečiamos funkcijos, kai tikslinis blokas priklauso nuo elemento atributų:

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;
} );

Tinkinti blokai, susieti su konteinerio elementais, pvz., <section> ir <div>, rekursyviai analizuoja įdėtus HTML elementus, todėl vidinės antraštės, paveikslėliai, blokų žymos ir pastraipos tampa vietiniais antriniais blokais.

Visas pavyzdys

Visas puslapio šablonas, kuriame derinami kelių tipų blokai:

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>