Projektipäevik #5: PageHero – esimene pattern ja 4 lõksu

Sissejuhatus

Eelmises postituses lahkasime FSE filosoofiat ja otsustusmaatriksit – kus iga element kuulub (template, pattern, page sisu, CPT). Aeg on filosoofiast praktikasse.

Selles postituses ehitame esimese tõelise pattern’i: PageHero. Üks komponent, mis kuulub 5 erinevale lehele (Meist, Kontakt, Privaatsuspoliitika, Teenused-arhiivi, Blogi). Sama struktuur (H1 + alapealkiri tsentrissa, hall taust), erinev tekst igal lehel.

Ehitamise käigus avastasime 4 lõksu. Igaüks neist on lugu omaette – ja kõik on tüüpilised FSE-arendamise kogemused, mida tasub mäleda.

Plaan: dünaamiline pattern + post-title/post-excerpt

Otsustusmaatriksi järgi: 2+ kasutuskoht erineva sisuga = Pattern. Aga mille kaudu varieerub sisu?

Variante on kolm:

Dünaamiline – pattern sisaldab wp:post-title ja wp:post-excerpt blokke, mis loevad praeguse Page’i andmeid automaatselt
Staatiline placeholder’iga – pattern sisaldab tavalist Heading ja Paragraph blokke, klient kirjutab teksti otse Page editor’s
Hardcoded template’is – ei kasutagi pattern’it, igas template’is on oma H1+p inline

Valisime variandi 1 – dünaamiline. Põhjused:

WP Pages’il on niikuinii Title ja Excerpt väljad
Klient muudab ühes kohas (Page Title + Excerpt) → kajastub automaatselt H1-s ja subtitle’s
Arhiivilehtedel (`page_for_posts` = Blogi) sama loogika: post-title loeb Blogi Page’i title, post-excerpt selle excerpt’i

Ehitamine Site Editor’s

Ehitamise voog on lihtne:

Site Editor → Patterns → Create new pattern → “Page Hero”
Lisa Group blokk (HTML element: section, align: full)
Group’i sisse Post Title (Level: H1, center align)
Selle alla Post Excerpt (center align)
Lisa taust (bg-gray) ja vertikaalne padding (xxxxxl)
Salvesta → Create Block Theme → Save Patterns → eksport patterns/page-hero.php-sse

Aga niinii lihtne see polnud. Vaatame, mis valesti läks.

Lõks #1: `align:full` vs “Inner blocks use content width”

Pattern Editor’s nägi PageHero välja täislaiuses – hall taust ulatus äärtest ääreni. Loomulik järeldus: “banner ongi full-width”.

Vale. Pattern Editor avab pattern’i iseseisvas iframe’s – pole piiravat emakomponenti. Group koos default layout’iga täidab automaatselt iframe’i laiuse. Visuaalne illusioon. Päris template’s, kus on `<main>` constrained wrapper, pattern jääks ~1200px sisse.

Lisaks oli Layout panel’s toggle “Inner blocks use content width” – ja näis, et see ongi “full-width lüliti”. Vale jälle. Tegelikult on need kaks erinevat kontrolli sarnase sõnastusega:

align: "full" (toolbar) – kontrollib bloki enda laiust vanema suhtes. Ilma: blokk respekteerib parent contentSize’i (~1200px). With: blokk murrab välja viewport äärtest ääreni (100vw).
“Inner blocks use content width” (Layout panel) – kontrollib SISEMISTE blokkide käitumist Group’i sees. SISSE: lapsbokid constrained content-width sees. VÄLJAS: lapsbokid täidavad Group’i kogu laiuse.

Õige seadistus PageHero jaoks:

<!-- wp:group {"tagName":"section","align":"full","style":{...},"backgroundColor":"bg-gray","layout":{"type":"default"}} -->
<section class="wp-block-group alignfull has-bg-gray-background-color has-background">
  <!-- wp:post-title {"textAlign":"center","level":1} /-->
  <!-- wp:post-excerpt {"textAlign":"center","moreText":""} /-->
</section>
<!-- /wp:group -->

Reegel: Pattern Editor’s visuaalne täislaius ≠ align:"full" markup’is. Kirjuta atribuut eksplitsiitselt, ära lootu visuaalsele illusioonile.

Lõks #2: JSON atribuudid kaovad CBT-ekspordil

Esimene CBT eksport andis selle markup’i:

<!-- wp:group -->                                              ← !
<section class="wp-block-group alignfull has-bg-gray-background-color has-background">
  ...

Märkad mida? Group bloki JSON atribuudid on KÕIK kadunud. Rida on lihtsalt , mitte .

HTML element ise sisaldas õigeid klasse (alignfull, has-bg-gray-background-color) ja inline-style padding’ut. Frontend’s näitab õieti. Aga Block Editor’s on katki – kui keegi avab edit’iks, näeb tavalist Group blokki ilma seadeteta.

Ja boonus-katastroof: failinime typo (page-hetro.php page-hero.php asemel). Site Editor’s pattern’i nime ümbernimetamine + Code Editor manuaalne sekkumine + CBT export – kuskil ahelas tõlge JSON ↔ HTML läks rappa.

Lahendus: kustuta vigane fail, kirjuta uus pattern’i fail käsitsi, flush’i pattern cache:

ddev exec wp eval-file wp-content/themes/fse-theme/flush-pattern-cache.php

Reegel: pärast IGA CBT-eksporti loe pattern PHP fail üle. Kontrolli (1) failinimi ja slug, (2) JSON atribuudid säilinud, (3) inline-style ühel real, (4) ei muutuvad sõned mille pidanuks varikaadi olema.

Lõks #3: Post Excerpt’i automaatne “Read more” link

PageHero subtitle all ilmus frontend’s tundmatu link:

Projektipäevik
Mõtted, õppetunnid ja juhendid.
Read more                          ← MIKS?!

Põhjus: wp:post-excerpt blokk lisab vaikimisi “Read more” lingi excerpt’i järele. Mõte: postituste-listingul on see õige (link viib täispostitusele). Aga PageHero on lehe pealdis, mitte kaart – “Read more” pole siin mõttekas.

Lahendus: sea moreText atribuut tühjaks:

<!-- wp:post-excerpt {"textAlign":"center","moreText":""} /-->

Tühi sõne → WP ei renderda lingi üldse. Selle atribuudi seadmiseks Site Editor’s saab kasutada kahte teed:

Variant A – visuaalne: Block Settings → “Show link on new line” toggle VÄLJA, VÕI text input “Read more” tühjaks
Variant B – Code Editor: ⌃⇧⌥M (Mac) → muuda markup’i otse → Exit code editor → Save

Variant B on alati garanteeritud (mõnes WP versioonis Block Settings UI peidab atribuudid). Variant A on kiirem, kui leiad UI-st.

Lõks #4: Page’idel pole Excerpt-välja UI-d

PageHero’l on subtitle olemas tänu wp:post-excerpt blokile. Aga kuidas klient seda subtitle’i sisestab? Pages → Blogi → kust ma Excerpt-välja sisestan?

Vastus: vaikimisi mitte kuskilt. WP ei näita Excerpt paneeli Pages’idel. Andmebaasis veerg post_excerpt on olemas, aga UI on peidetud.

Lahendus: aktiveeri Excerpt UI functions.php-s:

function fse_theme_setup() {
    add_theme_support( 'post-thumbnails' );
    add_theme_support( 'html5', [...] );
    add_theme_support( 'wp-block-styles' );

    add_post_type_support( 'page', 'excerpt' );    // ← see rida
}
add_action( 'after_setup_theme', 'fse_theme_setup' );

Pärast aktiveerimist:

Klassikalises Block Editor’s (Pages → Blogi → Edit): parem sidebar’s tekib Excerpt paneel (kui peidetud, ⋮ → Preferences → Panels → Excerpt → SISSE)
Site Editor’s page-vaates: Excerpt EI tule paneelile (see on Site Editor’i piirang). Tuleb minna klassikalisele Pages menüüsse

Lõplik PageHero pattern

Pärast kõikide lõksude ületamist näeb patterns/page-hero.php välja nii:

<?php
/**
 * Title: Page Hero
 * Slug: fse-theme/page-hero
 * Categories: featured
 */
?>
<!-- wp:group {"tagName":"section","align":"full","style":{"spacing":{"padding":{"top":"var:preset|spacing|xxxxxl","bottom":"var:preset|spacing|xxxxxl","left":"var:preset|spacing|xxxxxxl","right":"var:preset|spacing|xxxxxxl"}}},"backgroundColor":"bg-gray","layout":{"type":"default"}} -->
<section class="wp-block-group alignfull has-bg-gray-background-color has-background" style="padding-top:var(--wp--preset--spacing--xxxxxl);padding-right:var(--wp--preset--spacing--xxxxxxl);padding-bottom:var(--wp--preset--spacing--xxxxxl);padding-left:var(--wp--preset--spacing--xxxxxxl)">
  <!-- wp:post-title {"textAlign":"center","level":1} /-->
  <!-- wp:post-excerpt {"textAlign":"center","moreText":""} /-->
</section>
<!-- /wp:group -->

5 lehte, üks pattern, dünaamiline sisu. Iga leht annab oma title + excerpt → pattern renderdab vastavalt.

Õppetundide kokkuvõte

align:full vs Inner blocks width on kaks erinevat asja sarnase sõnastusega – Pattern Editor visuaalne illusioon ei asenda eksplitsiitset atribuuti
CBT eksport ei ole alati puhas – JSON atribuudid võivad kaduda, failinimi võib typo’da; alati loe fail üle
Post Excerpt’il on automaatne “Read more” link – sobib kaartidele, mitte lehe-pealdistele; moreText:"" peidab
Pages’idel pole vaikimisi Excerpt UI-d – add_post_type_support('page', 'excerpt') aktiveerib

Järgmises postituses ehitame Blog Home template’i – kus PageHero pattern saab oma esimese reaalse kasutuskoha. Ja seal on omakorda 6 lõksu, mis on hoopis Query Loop’i ja template-part’idega seotud.

Sisukord: kõik need kogemused on talletatud project/casestudy.md failis (Case 10–12). Sellele projektile mõtleva arendaja jaoks: see fail on kuld.