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_templateirwp_template_partšaltinius, skirtus WordPress svetainės rengyklei.
Visos trys funkcijos naudoja tą patį HTML analizatorių ir blokų sintaksę.
Praktinis vadovas apie puslapių šablonus iš failų, sinchronizavimą ir užrakinimą.
Aplankų struktūra
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>:
<block name="core/cover" url="https://example.com/hero.jpg">
<h1>Welcome</h1>
<p>Content inside the cover block.</p>
</block>
Pagrindiniai blokai
<!-- 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:
<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:
<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="[&>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:
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:
<block name="acf/hero" background="dark">
<h1>Welcome</h1>
</block>
Taip pat galite pakeisti pagrindinių blokų atvaizdavimą:
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
/**
* @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:
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ų:
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:
<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>