Pāriet uz saturu

Lapas un rakstu paraugi

Blockstudio ļauj motīvā kā failus definēt WordPress lapas, bloku rakstu paraugus un Site Editor veidnes. Rakstiet HTML līdzīgas veidnes, un Blockstudio parsētājs tās pārveidos par vietējiem WordPress blokiem.

  • Lapas tiek sinhronizētas ar datubāzi kā WordPress ieraksti, uzturot failu veidnes un lapu saturu sinhronizācijā.
  • Rakstu paraugi tiek reģistrēti atmiņā, izmantojot register_block_pattern(), un ir pieejami bloku ievietotājā, lai lietotāji tos varētu ievietot jebkur.
  • Vietnes veidnes nodrošina failos glabātus wp_template un wp_template_part avotus WordPress vietnes redaktoram.

Visas trīs funkcijas izmanto vienu un to pašu HTML parsētāju un bloku sintaksi.

Uz failiem balstītu lapu izveide

Praktisks ceļvedis par uz failiem balstītām lapu veidnēm, sinhronizāciju un rediģēšanas bloķēšanu.

Mapju struktūra

Kods
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

Katrā apakšmapē ir JSON konfigurācijas fails (page.json, pattern.json, template.json vai part.json) un veidnes fails.

Veidņu dzinēji

Veidnes var rakstīt kā vienkāršu marķējumu index.php formātā vai izmantot Twig vai Blade:

Fails Dzinējs Prasība
index.php Nav (tiek nolasīts nemainīts, PHP kods netiek izpildīts) Nav
index.twig Twig Timber
index.blade.php Blade illuminate/view

Ja ir vairāki veidņu faili, prioritāšu secība ir šāda: index.php > index.blade.php > index.twig.

Tā kā veidnes tiek kompilētas inicializācijas laikā (pirms jebkāda pieprasījuma konteksta), Twig un Blade veidnēm nav piekļuves dinamiskiem mainīgajiem. Tās noder iebūvētajām funkcijām un filtriem, piemēram, {{ "text"|upper }} vai {{ strtoupper("text") }}.

HTML elementu kartēšana blokos

Standarta HTML elementi tiek automātiski pārveidoti par atbilstošajiem WordPress blokiem.

Teksts

HTML Bloks
<p> core/paragraph
<h1> – <h6> core/heading
<ul> core/list (nesakārtots)
<ol> core/list (sakārtots)
<li> core/list-item
<blockquote> core/quote
<code> core/code
<pre> core/preformatted

Saraksti saglabā savu struktūru. <li> iekšienē esošs <ul> vai <ol> kļūst par šī core/list-item iekšējo bloku core/list — tādu struktūru redaktors saglabā, tāpēc sarakstus var ligzdot jebkurā dziļumā. class sarakstā vai vienumā kļūst par tā className, kas ļauj no lapas faila iestatīt bloka stilu, piemēram, is-style-checks; to pašu dara arī <block name="core/list" className="...">.

Multivide

HTML Bloks
<img> core/image
<figure> core/image (ar parakstu)
<audio> core/audio
<video> core/video

Izkārtojums

HTML Bloks
<div>, <section> core/group
<main>, <header>, <footer>, <article>, <aside> core/group, kas saglabā elementu kā tā tagName
<hr> core/separator
<details> core/details
<table> core/table

Bloku sintakse

Blokiem, kuriem nav tieša HTML ekvivalenta, izmantojiet elementu <block>:

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

Pamata bloki

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>

Pielāgotie bloki

Tāda pati sintakse darbojas ar jebkuru reģistrētu bloku:

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>

Atribūti

HTML atribūti elementiem <block> tiek nodoti kā bloka atribūti. Tiek atbalstītas JSON vērtības:

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

Atribūtu vērtības tiek atkodētas vienu reizi, tāpat kā tās nolasa pārlūkprogramma, tāpēc data-animate="[&amp;>span]:fade" un data-animate="[&>span]:fade" saglabā vienu un to pašu vērtību.

Elementā, kas kartēts uz Blockstudio bloku, visi atribūti tiek saglabāti kopā ar bloku. Deklarētie lauki ir pieejami veidnei; globālie atribūti, ko bloks nedeklarē (id, style, role, title, lang, dir, hidden, tabindex, aria-* un data-*), renderēšanas laikā tiek pievienoti bloka saknes elementam, tāpat kā bloku tagos. Lapu un rakstu paraugu avotos prefikss html- apzīmē tikai vienu no šiem globālajiem atribūtiem, tāpēc html-role="note" tiek nodots tālāk kā role, bet notikumu apstrādātāji, piemēram, html-onclick, netiek renderēti. Viss pārējais, tostarp nedeklarēts class, paliek ieraksta saturā, nenonākot lapā, un wp bs pages sync to norāda katrai parsētajai lapai.

Pielāgotu bloku renderētāji

HTML parsētājam ir reģistrā balstīta arhitektūra. Pievienojiet pielāgota bloka veidotāju ar 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 );

Pēc tam izmantojiet to jebkurā veidnē:

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

Varat arī mainīt pamata bloku renderēšanas veidu:

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

Veidotāja atzvanfunkcijas saņem parsētos atribūtus un neapstrādāto iekšējo saturu. Tām jāatgriež WordPress bloku masīvs. Pilnu filtru secību un konteinera piemēru skatiet sadaļā Pielāgoti renderētāji.

Veidotāja funkcijas paraksts

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

Elementu kartēšana

Pēc noklusējuma standarta HTML elementi, piemēram, <h1>, <p> un <img>, tiek kartēti uz pamata WordPress blokiem. Varat mainīt šo kartējumu, lai jebkuru HTML elementu novirzītu uz citu bloku, izmantojot filtru 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 );

Ja šis filtrs ir aktīvs, katrs <h1> jūsu veidnēs izveidos custom/heading bloku, nevis core/heading. Elementa atribūti tiek nodoti mērķa blokam. Ja mērķa bloka nosaukumam ir reģistrēts renderētājs, tas tiks izmantots. Pretējā gadījumā tiek izveidota vispārīga bloka struktūra.

Tas noder, ja jūsu motīvs vai spraudnis nodrošina pielāgotus bloku veidus, kam jāaizstāj noklusējuma bloki visās lapu un rakstu paraugu veidnēs.

Vienkāršiem <p> kartējumiem Blockstudio var tieši novirzīt iekšējo HTML uz reģistrēta bloka, kas nav pamata bloks, Blockstudio atribūtu content richtext. Mērķa blokam jādeklarē atribūts ar id: "content" un type: "richtext". Iekļautais formatējums (a, b, br, code, del, em, i, img, ins, mark, s, small, span, strong, sub, sup, u) paliek novirzītajā vērtībā pat tad, ja tas pats tags pēc noklusējuma ir kartēts kā elements, kā tas ir code un img gadījumā. Rindkopa, kuras vienīgais bērnelements ir attēls, kļūst par bloku, uz kuru tiek kartēts <img>; tieši šādu bloku Markdown izveido atsevišķam attēlam. Ligzdotie bloku tagi un bloka līmeņa HTML joprojām tiek parsēti kā iekšējie bloki.

Kartējuma vērtības var būt arī izsaucamas funkcijas, ja mērķa bloks ir atkarīgs no elementa atribūtiem:

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

Pielāgoti bloki, kas kartēti no konteinera elementiem, piemēram, <section> un <div>, rekursīvi parsē ligzdotos HTML bērnelementus, tāpēc iekšējie virsraksti, attēli, bloku tagi un rindkopas kļūst par vietējiem bērnblokiem.

Pilns piemērs

Pilna lapas veidne, kurā apvienoti vairāki bloku veidi:

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>