Liigu sisu juurde

Lehed ja mustrid

Blockstudio võimaldab määratleda WordPress lehti, plokimustreid ja saidiredaktori malle teemafailidena. Kirjuta HTML-laadseid malle ning Blockstudio parser teisendab need natiivseteks WordPress plokkideks.

  • Lehed sünkroonitakse andmebaasi WordPress postitustena, hoides failimallid ja lehe sisu sünkroonis.
  • Mustrid registreeritakse mällu funktsiooniga register_block_pattern() ning need on plokisisestajas saadaval, et kasutajad saaksid neid kõikjale lisada.
  • Saidi mallid pakuvad failipõhiseid wp_template ja wp_template_part allikaid WordPress saidiredaktori jaoks.

Kõik kolm funktsiooni kasutavad sama HTML parserit ja plokisüntaksit.

Failipõhiste lehtede loomine

Praktiline juhend failipõhiste lehemallide, sünkroonimise ja lukustamise kohta.

Kaustastruktuur

Kood
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

Igas alamkaustas on JSON konfiguratsioonifail (page.json, pattern.json, template.json või part.json) ja mallifail.

Mallimootorid

Malle saab kirjutada lihtmärgendusena failis index.php või kasutada Twig või Blade:

Fail Mootor Nõue
index.php Puudub (loetakse muutmata kujul, PHP koodi ei käivitata) Puudub
index.twig Twig Timber
index.blade.php Blade illuminate/view

Kui mallifaile on mitu, kehtib järgmine prioriteet: index.php > index.blade.php > index.twig.

Kuna mallid kompileeritakse käivitamise ajal (enne päringu konteksti loomist), pole Twig ja Blade mallidel dünaamilistele muutujatele ligipääsu. Need sobivad sisseehitatud funktsioonide ja filtrite jaoks, näiteks {{ "text"|upper }} või {{ strtoupper("text") }}.

HTML teisendamine plokkideks

Standardsed HTML elemendid teisendatakse automaatselt vastavateks WordPress plokkideks.

Tekst

HTML Plokk
<p> core/paragraph
<h1> – <h6> core/heading
<ul> core/list (järjestamata)
<ol> core/list (järjestatud)
<li> core/list-item
<blockquote> core/quote
<code> core/code
<pre> core/preformatted

Loendid säilitavad oma struktuuri. <ul> või <ol> elemendis <li> muutub selle core/list-item sisemiseks plokiks core/list — selliseks kujuks, mille redaktor salvestab, nii et loendeid saab piiramatu sügavuseni pesastada. Loendile või selle elemendile lisatud class muutub selle className-ks; nii määratakse lehefailis ploki stiil, näiteks is-style-checks. <block name="core/list" className="..."> teeb sama.

Meedia

HTML Plokk
<img> core/image
<figure> core/image (allkirjaga)
<audio> core/audio
<video> core/video

Paigutus

HTML Plokk
<div>, <section> core/group
<main>, <header>, <footer>, <article>, <aside> core/group, mis säilitab elemendi oma tagName-ina
<hr> core/separator
<details> core/details
<table> core/table

Plokisüntaks

Plokkide puhul, millel puudub otsene HTML vaste, kasutage elementi <block>:

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

Põhiplokid

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>

Kohandatud plokid

Sama süntaks töötab kõigi registreeritud plokkidega:

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>

Atribuudid

HTML atribuudid elementidel <block> edastatakse ploki atribuutidena. Toetatud on JSON väärtused:

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

Atribuutide väärtused dekodeeritakse üks kord, nii nagu brauser neid loeb, seega salvestavad data-animate="[&amp;>span]:fade" ja data-animate="[&>span]:fade" sama väärtuse.

Blockstudio plokiks teisendatud elemendil salvestatakse plokiga kõik atribuudid. Deklareeritud väljad jõuavad malli; globaalsed atribuudid, mida plokk ei deklareeri (id, style, role, title, lang, dir, hidden, tabindex, aria-* ja data-*), lisatakse ploki juurelemendile renderdamisel täpselt nii nagu plokisiltide puhul. Lehe- ja mustriallikates tähistab prefiks html- ainult üht neist globaalsetest atribuutidest, nii et html-role="note" edastatakse kujul role, samas kui sündmusekäsitlejaid, nagu html-onclick, kunagi ei renderdata. Kõik muu, sealhulgas deklareerimata class, jääb postituse sisusse ega jõua lehele ning wp bs pages sync annab sellest teada iga parsitava lehe puhul.

Kohandatud plokkide renderdajad

HTML parser kasutab registripõhist arhitektuuri. Kohandatud ploki koostaja lisamiseks kasutage 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 );

Seejärel kasutage seda mis tahes mallis:

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

Samuti saate muuta põhiplokkide renderdamist:

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

Koostaja tagasihelistused saavad parsitud atribuudid ja töötlemata sisuteksti. Need peavad tagastama WordPress plokimassiivi. Täielikku filtrite järjekorda ja konteineri näidet vaadake jaotisest Kohandatud renderdajad.

Koostajafunktsiooni signatuur

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

Elementide teisendamine

Vaikimisi teisendatakse standardsed HTML elemendid, näiteks <h1>, <p> ja <img>, põhilisteks WordPress plokkideks. Saate seda teisendust muuta, et suunata mis tahes HTML element teise plokki filtri blockstudio/parser/element_mapping abil:

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

Kui see filter on aktiivne, loob mallide iga <h1> elemendi custom/heading ploki, mitte core/heading. Elemendi atribuudid edastatakse sihtplokile. Kui sihtploki nimele on registreeritud renderdaja, kasutatakse seda. Vastasel juhul luuakse üldine plokistruktuur.

See on kasulik, kui teie teema või pistikprogramm pakub kohandatud plokitüüpe, mis peaksid kõigis lehe- ja mustrimallides vaikeplokid asendama.

Lihtsate <p> teisenduste korral saab Blockstudio suunata sisemise HTML otse registreeritud mitte-põhilise Blockstudio ploki content richtext-atribuuti. Sihtplokk peab deklareerima atribuudi väärtustega id: "content" ja type: "richtext". Reasisene vormindus (a, b, br, code, del, em, i, img, ins, mark, s, small, span, strong, sub, sup, u) jääb suunatud väärtusse alles ka siis, kui sama silt teisendatakse elemendiks, nagu seda vaikimisi tehakse elementide code ja img puhul. Kui lõigu ainus alamelement on pilt, saab see plokiks, milleks <img> selle teisendab; nii toimib ka Markdown eraldiseisva pildi puhul. Pesastatud plokisildid ja plokitaseme HTML parsitakse edasi sisemisteks plokkideks.

Teisenduse väärtused võivad olla ka funktsioonid, kui sihtplokk sõltub elemendi atribuutidest:

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

Konteinerielementidest, näiteks <section> ja <div>, teisendatud kohandatud plokkides parsitakse pesastatud HTML alamelemendid rekursiivselt, nii et sisemised pealkirjad, pildid, plokisildid ja lõigud muutuvad natiivseteks alamplokkideks.

Täielik näide

Täielik lehemall, mis ühendab mitu plokitüüpi:

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>