Siirry sisältöön

Sivut ja mallit

Blockstudio-toiminnolla voit määrittää WordPress-sivuja, lohkomalleja ja sivustoeditorin malleja tiedostoina teemassasi. Kirjoita HTML-tyylisiä malleja, niin Blockstudio-jäsennin muuntaa ne natiiveiksi WordPress-lohkoiksi.

  • Sivut synkronoidaan tietokantaan WordPress-julkaisuina, jolloin tiedostopohjaiset mallit ja sivujen sisältö pysyvät synkronoituina.
  • Mallit rekisteröidään muistiin register_block_pattern()-toiminnolla, ja ne ovat käyttäjien lisättävissä mihin tahansa lohkojen lisäyksessä.
  • Sivustomallit tarjoavat tiedostopohjaiset wp_template– ja wp_template_part-lähteet WordPress-sivustoeditorille.

Kaikki kolme ominaisuutta käyttävät samaa HTML-jäsennintä ja lohkojen syntaksia.

Tiedostopohjaisten sivujen rakentaminen

Käytännön opas tiedostopohjaisiin sivupohjiin, synkronointiin ja lukitsemiseen.

Kansiorakenne

Koodi
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

Kukin alikansio sisältää JSON-asetustiedoston (page.json, pattern.json, template.json tai part.json) ja mallitiedoston.

Mallipohjamoottorit

Mallit voi kirjoittaa tavallisena merkintäkielenä muodossa index.php tai muodossa Twig tai Blade:

Tiedosto Moottori Vaatimus
index.php Ei mitään (luetaan sellaisenaan, PHP-koodia ei suoriteta) Ei mitään
index.twig Twig Timber
index.blade.php Blade illuminate/view

Jos mallitiedostoja on useita, niiden tärkeysjärjestys on: index.php > index.blade.php > index.twig.

Koska mallit käännetään alustuksen yhteydessä (ennen pyyntökontekstia), Twig- ja Blade-malleilla ei ole pääsyä dynaamisiin muuttujiin. Ne sopivat sisäänrakennetuille funktioille ja suodattimille, kuten {{ "text"|upper }} tai {{ strtoupper("text") }}.

HTML lohkokartoitukseen

Tavalliset HTML-elementit muunnetaan automaattisesti niitä vastaaviksi WordPress-lohkoiksi.

Teksti

HTML Lohko
<p> core/paragraph
<h1> – <h6> core/heading
<ul> core/list (järjestämätön)
<ol> core/list (järjestetty)
<li> core/list-item
<blockquote> core/quote
<code> core/code
<pre> core/preformatted

Luettelot säilyttävät rakenteensa. <li>-elementin sisällä oleva <ul> tai <ol> muuttuu kyseisen core/list-item-elementin sisemmäksi core/list-lohkoksi, eli rakenteeksi, jonka editori tallentaa. Näin luettelot voivat sisäkkäistyä rajattomasti. Luettelon tai kohdan class muuttuu sen className-määritykseksi. Näin lohkotyyli, kuten is-style-checks, asetetaan sivutiedostosta; <block name="core/list" className="..."> tekee saman.

Media

HTML Lohko
<img> core/image
<figure> core/image (kuvatekstin kanssa)
<audio> core/audio
<video> core/video

Asettelu

HTML Lohko
<div>, <section> core/group
<main>, <header>, <footer>, <article>, <aside> core/group, joka säilyttää elementin omana tagName-arvonaan
<hr> core/separator
<details> core/details
<table> core/table

Lohkojen syntaksi

Jos lohkolla ei ole suoraa HTML-vastinetta, käytä <block>-elementtiä:

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

Ydinlohkot

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>

Mukautetut lohkot

Sama syntaksi toimii kaikissa rekisteröidyissä lohkoissa:

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>

Attribuutit

<block>-elementtien HTML-määritteet välitetään lohkomääritteiksi. Myös JSON-arvoja tuetaan:

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

Määritearvot dekoodataan kerran, samalla tavalla kuin selain ne lukee, joten data-animate="[&amp;>span]:fade" ja data-animate="[&>span]:fade" tallentavat saman arvon.

Blockstudio-lohkoksi muunnetussa elementissä kaikki määritteet tallennetaan lohkon mukana. Mallipohja saa käyttöönsä määritetyt kentät; yleiset määritteet, joita lohko ei määritä (id, style, role, title, lang, dir, hidden, tabindex, aria-* ja data-*), lisätään lohkon juurielementtiin sen renderöityessä aivan kuten lohkomerkinnöissä. Sivu- ja mallilähteissä html--etuliite nimeää vain yhden näistä yleisistä määritteistä, joten html-role="note" välittyy muodossa role, kun taas tapahtumankäsittelijöitä, kuten html-onclick, ei koskaan renderöidä. Kaikki muu, myös määrittämätön class, jää julkaisun sisältöön päätymättä sivulle, ja wp bs pages sync ilmoittaa siitä jokaisen jäsentämänsä sivun kohdalla.

Mukautetut lohkohahmontajat

HTML-jäsennin käyttää rekisteripohjaista arkkitehtuuria. Lisää mukautetun lohkon rakentaja toiminnolla 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 );

Käytä sitä sitten missä tahansa mallissa:

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

Voit myös korvata ydinkielten lohkojen hahmontamistavan:

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

Rakentajan takaisinkutsut saavat jäsennetyt määritteet ja sisällön raakana. Niiden on palautettava WordPress-lohkomatriisi. Katso Mukautetut hahmontajat, jos tarvitset täydellisen tiedon suodattimien järjestyksestä ja säilöesimerkin.

Rakentajafunktion allekirjoitus

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

Elementtien kartoitus

Oletusarvoisesti tavalliset HTML-elementit, kuten <h1>, <p> ja <img>, yhdistetään ytimen WordPress-lohkoihin. Voit ohittaa tämän kartoituksen ja yhdistää minkä tahansa HTML-elementin toiseen lohkoon suodattimella 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 );

Kun tämä suodatin on käytössä, jokainen mallien <h1> tuottaa custom/heading-lohkon core/heading-lohkon sijaan. Elementin määritteet välitetään kohdelohkolle. Jos kohdelohkon nimelle on rekisteröity hahmontaja, sitä käytetään. Muussa tapauksessa luodaan yleinen lohkorakenne.

Tästä on hyötyä, kun teemasi tai lisäosasi tarjoaa mukautettuja lohkotyyppejä, joiden pitäisi korvata oletukset kaikissa sivu- ja mallipohjissa.

Yksinkertaisissa <p>-kartoituksissa Blockstudio voi ohjata sisemmän HTML-sisällön suoraan rekisteröidyn muun kuin ytimen Blockstudio-lohkon content-rikastekstimääritteeseen. Kohdelohkon on määritettävä määrite arvoilla id: "content" ja type: "richtext". Sisäinen muotoilu (a, b, br, code, del, em, i, img, ins, mark, s, small, span, strong, sub, sup, u) säilyy ohjatussa arvossa, vaikka sama tunniste olisi yhdistetty elementtiin, kuten code ja img ovat oletusarvoisesti. Kappale, jonka ainoa lapsielementti on kuva, muuttuu lohkoksi, johon <img> yhdistää sen; näin Markdown toimii irralliselle kuvalle. Sisäkkäiset lohkotunnisteet ja lohkotason HTML jäsennetään edelleen sisälohkoiksi.

Kohdelohkon elementtimääritteistä riippuvat kartoitusarvot voivat olla myös kutsuttavia:

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

Säilöelementeistä, kuten <section> ja <div>, mukautetuiksi lohkoiksi yhdistetyt elementit jäsentävät sisäkkäiset HTML-lapset rekursiivisesti, jolloin sisäotsikoista, kuvista, lohkotunnisteista ja kappaleista tulee natiiveja lapsilohkoja.

Täydellinen esimerkki

Kokonainen sivumalli, jossa yhdistyy useita lohkotyyppejä:

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>