Lohkokirjaston rakentaminen
Lohkokirjasto on joukko itsenäisiä osiolohkoja, joista kootaan kokonaisia sivuja. Jokaisella lohkolla on oma skeema, mallipohja ja tyylitys. Blockstudio tarjoaa rungon: Tailwind CSS-käsittelyn, määritteiden rekisteröinnin ja sivujen synkronoinnin. Sinä toteutat lohkot.
Tässä oppaassa käydään läpi kirjaston rakentaminen alusta alkaen. Opas noudattaa samaa arkkitehtuuria, jota käytetään sadoissa tuotantoteemoissa. Lopputuloksena sinulla on toimiva teema, jossa on sankariosio, ominaisuusruudukko ja näistä koottu etusivu.
Kansiorakenne
Jokainen Blockstudio-teema noudattaa samaa rakennetta:
my-theme/
├── style.css # WordPress header + Tailwind v4 config
├── blockstudio.json # Blockstudio settings
├── functions.php # Section helper + Tailwind filter
├── index.php # Main WordPress template
├── blockstudio/
│ ├── fields/
│ │ └── section/
│ │ └── field.json # Shared section controls
│ └── sections/
│ ├── hero/
│ │ ├── block.json
│ │ └── index.php
│ └── features/
│ ├── block.json
│ └── index.php
└── pages/
└── home/
├── page.json
└── index.php
Lohkot sijaitsevat hakemistossa blockstudio/sections/. Jokainen lohko on kansio, jossa on block.json-skeema ja index.php-mallipohja. Sivut sijaitsevat hakemistossa pages/, ja niissä lohkot kootaan <block>-syntaksilla.
Perustiedostot
blockstudio.json
Tällä tiedostolla määritetään, miten Blockstudio käsittelee teemaasi. Määritys on sama kaikissa teemoissa:
{
"assets": {
"enqueue": true,
"reset": {
"enabled": true,
"fullWidth": ["page"]
},
"minify": { "css": true, "js": true },
"process": { "scss": false, "scssFiles": true }
},
"tailwind": {
"enabled": true,
"config": ""
},
"dev": {
"canvas": { "enabled": true }
},
"$schema": "https://blockstudio.dev/schema/blockstudio"
}
reset poistaa oletusarvoiset WordPress-lohkojen tyylit. fullWidth asettaa page-sisältötyypit koko sivun levyisiksi. canvas ottaa käyttöön editorin piirtoalustatilan, joka tekee muokkaamisesta selkeämpää.
Kenttä tailwind.config on tarkoituksella tyhjä. Kun käytössä on Tailwind v4, kaikki määritykset sijaitsevat kohteessa style.css CSS-ensisijaisella tavalla.
index.php
Päämallipohja WordPress. Tämä on tavallista WordPress-koodia, eikä liity erityisesti kohteeseen Blockstudio:
<!DOCTYPE html>
<html <?php language_attributes(); ?>>
<head>
<meta charset="<?php bloginfo( 'charset' ); ?>">
<meta name="viewport" content="width=device-width, initial-scale=1">
<?php wp_head(); ?>
</head>
<body <?php body_class(); ?>>
<?php wp_body_open(); ?>
<main>
<?php
if ( have_posts() ) {
while ( have_posts() ) {
the_post();
the_content();
}
}
?>
</main>
<?php wp_footer(); ?>
</body>
</html>
Lisää header.php ja footer.php, kun tarvitset navigointia. Toistaiseksi yksinkertainen mallipohja riittää lohkojen renderöintiin.
Suunnittelutunnisteet
Kaikki teeman tyylit määritetään kohteessa style.css käyttämällä Tailwind v4 -direktiiviä @theme. Tämä on suunnittelujärjestelmäsi ydin.
/*
Theme Name: My Theme
Theme URI: https://example.com
Description: A clean theme built with Blockstudio.
Version: 1.0.0
Requires at least: 6.0
Requires PHP: 8.2
Author: Your Name
Text Domain: my-theme
*/
@theme {
--font-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
--color-bg: #050505;
--color-elevated: #111111;
--color-subtle: rgb(255 255 255 / 0.06);
--color-muted: #888888;
--color-accent: #6366f1;
--color-accent-hover: #4f46e5;
}
Jokainen teema tarvitsee vähintään seuraavat tunnisteet:
| Tunniste | Käyttötarkoitus |
|---|---|
--font-sans tai --font-serif |
Ensisijainen kirjasintyyppi |
--color-bg |
Sivun tausta |
--color-elevated |
Kortin/pinnan tausta |
--color-subtle |
Reunat, erottimet |
--color-muted |
Toissijainen teksti |
--color-accent |
Brändin pääväri |
Nämä tunnisteet luovat Tailwind-apuohjelmaluokat automaattisesti. --color-accent muuttuu luokiksi bg-accent, text-accent, border-accent ja niin edelleen.
Vaaleaa teemaa varten vaihda arvot päinvastaisiksi:
@theme {
--font-serif: 'Zilla Slab', serif;
--font-sans: 'DM Sans', sans-serif;
--color-bg: #f5f0e8;
--color-elevated: #ece6da;
--color-heading: #2c1810;
--color-body: #6b5c4f;
--color-muted: #9a8b7d;
--color-accent: #2d5016;
--color-subtle: #d9d1c4;
}
Perustyylit ja apuluokat
Lisää @theme-lohkon jälkeen rungon tyylit, perustason oletukset ja mukautetut apuluokat.
Rungon tyylien on oltava @layer-lohkon ulkopuolella, jotta WordPress-editori poimii ne:
body {
@apply bg-bg font-sans text-white antialiased;
}
Perustaso elementtien oletusasetuksille:
@layer base {
section {
@apply relative overflow-hidden;
}
h1, h2, h3 {
text-wrap: balance;
}
p {
text-wrap: pretty;
}
}
Mukautetut apuluokat uudelleenkäytettäviä malleja varten. Jokaisessa teemassa määritetään container-apuohjelmaluokka osioiden yhtenäisiä välejä varten. Lisäksi määritetään tavallisesti card-, badge– ja painikeapuohjelmat:
@utility container-px {
@apply mx-auto max-w-5xl px-6;
}
@utility container {
@apply container-px py-24 sm:py-32;
}
@utility container-no-pb {
@apply pb-0 sm:pb-0;
}
@utility card {
@apply rounded-2xl border border-subtle bg-elevated/80 p-8 transition-all duration-300;
&:hover {
border-color: rgb(255 255 255 / 0.1);
}
}
@utility badge {
@apply inline-flex items-center gap-2 rounded-full border border-subtle bg-white/5 px-3.5 py-1.5 text-sm text-muted;
}
@utility btn-primary {
@apply inline-flex items-center gap-2 rounded-full bg-accent px-6 py-3 text-sm font-medium text-white transition-colors;
&:hover {
@apply bg-accent-hover;
}
}
@utility btn-secondary {
@apply inline-flex items-center gap-2 rounded-full border border-subtle px-6 py-3 text-sm font-medium text-white transition-all;
&:hover {
border-color: rgb(255 255 255 / 0.15);
background: rgb(255 255 255 / 0.04);
}
}
Pseudovalitsimet sijoitetaan @utility-lohkon sisään käyttämällä CSS-sisäkkäisyyttä (&:hover). Älä koskaan sijoita niitä apuluokan nimeen. @utility btn-primary:hover {} on virheellinen, ja Tailwind hylkää sen.
@source upotettuna
Blockstudio etsii lohkojesi mallipohjista automaattisesti Tailwind-luokat. Se ei kuitenkaan etsi luokkia, joita käytetään mallipohjien ulkopuolella (kohteissa functions.php, header.php ja index.php). Lisää ne määritykseen @source inline:
@source inline("bg-bg bg-accent-tint container container-px container-no-pb");
Tämä käskee Tailwind-työkalua sisällyttämään nämä luokat tulosteeseen, vaikka ne esiintyvät vain PHP-tiedostoissa, joita ei etsitä.
Osiomalli
Osiomalli on lohkokirjaston tärkein käytäntö kohteessa Blockstudio. Se varmistaa kaikissa lohkoissa yhtenäiset välit, taustan vaihdon ja sisennysten hallinnan kahdella jaetulla mekanismilla: mukautetulla kentällä ja PHP-apufunktiolla.
Osiokenttä
Luo yhteinen kenttämääritys, johon jokainen lohko voi viitata:
{
"$schema": "https://blockstudio.dev/schema/field",
"name": "section",
"title": "Section",
"attributes": [
{
"type": "group",
"attributes": [
{
"id": "removeBottomPadding",
"type": "toggle",
"label": "Remove bottom padding"
},
{
"id": "accentBg",
"type": "toggle",
"label": "Accent background"
}
]
}
]
}
Tämä kenttä näkyy jokaisen lohkon tarkastelupaneelissa Välilehdet-välilehden alla. Asiakkailla on kaksi säädintä: korostetaustan vaihtaminen ja alasisennyksen poistaminen (hyödyllistä, kun osiot pinotaan ilman välejä).
Osion apufunktio
Luo kohteeseen functions.php apufunktio, joka muuntaa nämä määritteet CSS-luokiksi:
<?php
/**
* My Theme functions.
*
* @package My_Theme
*/
/**
* Returns section and container class strings based on block attributes.
*
* @param array $a Block attributes.
* @param string $extra_section Additional classes for the section element.
* @param string $extra_container Additional classes for the container element.
* @return array Array of [ section_classes, container_classes ].
*/
function mytheme_section_classes( array $a, string $extra_section = '', string $extra_container = '' ): array {
$section = ! empty( $a['accentBg'] ) ? 'bg-accent-tint' : 'bg-bg';
$container = 'container';
if ( ! empty( $a['removeBottomPadding'] ) ) {
$container .= ' container-no-pb';
}
if ( $extra_section ) {
$section .= ' ' . $extra_section;
}
if ( $extra_container ) {
$container .= ' ' . $extra_container;
}
return array( $section, $container );
}
Jokaisen lohkon mallipohja kutsuu tätä apufunktiota ensimmäisellä rivillään. Apufunktio palauttaa kaksi luokkajonoa: yhden ulommalle <section>-elementille ja toisen sisemmälle <div>-säiliölle.
Tailwind-määrityksen suodatin
Lisää myös kohteeseen functions.php suodatin, joka välittää kohteesi style.css-määrityksen Blockstudio-työkalun Tailwind-käsittelijälle:
add_filter(
'blockstudio/settings/tailwind/config',
function () {
$style = get_stylesheet_directory() . '/style.css';
if ( file_exists( $style ) ) {
// phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents -- Reading local theme file.
return file_get_contents( $style );
}
return '';
}
);
Tällä Blockstudio määritetään käyttämään kohdetta style.css Tailwind-määrityksen lähteenä v4. Ilman tätä lohkojen mallipohjissa eivät olisi käytettävissä @theme-tunnisteet eivätkä @utility-määritykset.
Ensimmäinen lohko: sankariosio
Sankariosio havainnollistaa koko lohkomallin. Aloita skeemasta:
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "my-theme/hero",
"title": "Hero",
"category": "my-theme",
"icon": "star-filled",
"description": "Full-width hero section with heading, description, and buttons.",
"blockstudio": {
"attributes": [
{
"type": "tabs",
"tabs": [
{
"title": "Content",
"attributes": [
{
"type": "group",
"attributes": [
{
"id": "heading",
"type": "text",
"label": "Heading",
"default": "Build beautiful websites without the complexity"
},
{
"id": "description",
"type": "textarea",
"label": "Description",
"default": "A powerful framework that lets you create stunning designs using the WordPress editor."
}
]
},
{
"type": "group",
"attributes": [
{
"id": "primaryButton",
"type": "link",
"label": "Primary Button",
"default": {
"title": "Get Started",
"url": "#"
}
},
{
"id": "secondaryButton",
"type": "link",
"label": "Secondary Button",
"default": {
"title": "Learn More",
"url": "#"
}
}
]
}
]
},
{
"title": "Section",
"attributes": [
{ "type": "custom/section" }
]
}
]
}
]
}
}
Huomioitavia keskeisiä malleja:
tabs-kääre luo kaksivälilehtisen tarkastelupaneelin: Sisältö lohkon kentille ja Osio yhteisille osion säätimille. Jokainen lohko käyttää tätä rakennetta.
Kentät järjestetään group-säiliöihin. Ryhmät erottelevat tarkastelupaneelissa visuaalisesti toisiinsa liittyvät kentät. Ensimmäisessä ryhmässä ovat tekstikentät ja toisessa linkkikentät.
Oletusarvot tarjoavat mielekästä sisältöä, jotta lohko näyttää valmiilta heti lisäyksen jälkeen. Tämä on tärkeää sivujen sommittelussa, jossa lohkot lisätään ilman käyttäjän toimia.
Seuraavaksi mallipohja:
<?php list( $section_classes, $container_classes ) = mytheme_section_classes( $a, '', 'text-center' ); ?>
<section useBlockProps class="<?php echo esc_attr( $section_classes ); ?>">
<div class="<?php echo esc_attr( $container_classes ); ?>">
<h1 class="text-5xl font-medium tracking-tight sm:text-6xl lg:text-7xl">
<?php echo esc_html( $a['heading'] ); ?>
</h1>
<?php if ( ! empty( $a['description'] ) ) : ?>
<p class="mt-6 text-lg leading-relaxed text-muted max-w-xl mx-auto">
<?php echo esc_html( $a['description'] ); ?>
</p>
<?php endif; ?>
<div class="mt-10 flex items-center justify-center gap-x-4">
<?php if ( ! empty( $a['primaryButton']['url'] ) ) : ?>
<a href="<?php echo esc_url( $a['primaryButton']['url'] ); ?>" class="btn-primary">
<?php echo esc_html( $a['primaryButton']['title'] ); ?>
</a>
<?php endif; ?>
<?php if ( ! empty( $a['secondaryButton']['url'] ) ) : ?>
<a href="<?php echo esc_url( $a['secondaryButton']['url'] ); ?>" class="btn-secondary">
<?php echo esc_html( $a['secondaryButton']['title'] ); ?>
</a>
<?php endif; ?>
</div>
</div>
</section>
Mallipohja noudattaa yhtenäistä rakennetta:
- Kutsu osion apufunktiota saadaksesi luokat CSS
- Ulompi
<section>, jossa ovatuseBlockPropsja osion luokat - Sisempi
<div>, jossa ovat säiliön luokat - Renderöi sisältö kohteesta
$a(määritteiden lyhennysmerkintä) - Renderöi valinnaiset kentät ehdollisesti
- Käytä asianmukaista suojausta:
esc_html()tekstille,esc_url()URL-osoitteille jaesc_attr()määritteille
Toistimet: ominaisuusruudukko
Toistimilla asiakkaat voivat lisätä, poistaa ja järjestää kohteita uudelleen. Ominaisuusruudukko on tyypillinen esimerkki:
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "my-theme/features",
"title": "Features",
"category": "my-theme",
"icon": "grid-view",
"description": "Feature grid with titles and descriptions.",
"blockstudio": {
"attributes": [
{
"type": "tabs",
"tabs": [
{
"title": "Content",
"attributes": [
{
"type": "group",
"attributes": [
{
"id": "heading",
"type": "text",
"label": "Heading",
"default": "Everything you need"
},
{
"id": "description",
"type": "textarea",
"label": "Description",
"default": "Our toolkit gives you the building blocks to go from idea to production."
}
]
},
{
"type": "group",
"attributes": [
{
"id": "features",
"type": "repeater",
"label": "Features",
"textMinimized": {
"id": "title",
"fallback": "Feature"
},
"default": [
{
"title": "Lightning Fast",
"description": "Optimized for performance with minimal overhead."
},
{
"title": "Fully Responsive",
"description": "Every component adapts across all screen sizes."
},
{
"title": "Easy to Customize",
"description": "Adjust every detail to match your brand."
}
],
"attributes": [
{
"id": "title",
"type": "text",
"label": "Title"
},
{
"id": "description",
"type": "textarea",
"label": "Description"
}
]
}
]
}
]
},
{
"title": "Section",
"attributes": [
{ "type": "custom/section" }
]
}
]
}
]
}
}
textMinimized-ominaisuus määrittää, mitä tekstiä näytetään toistimen rivin ollessa kutistettuna. Se lukee kentän title arvon ja käyttää tyhjälle arvolle vaihtoehtona tekstiä ”Feature”. Näin tarkastelupaneeli pysyy käytettävänä, kun kohteita on paljon.
Taulukko default tarjoaa alkukohteet, jotka näkyvät, kun lohko lisätään ensimmäisen kerran. Anna aina realistiset oletusarvot, jotta lohko näyttää heti valmiilta.
<?php list( $section_classes, $container_classes ) = mytheme_section_classes( $a ); ?>
<section useBlockProps class="<?php echo esc_attr( $section_classes ); ?>">
<div class="<?php echo esc_attr( $container_classes ); ?>">
<?php if ( ! empty( $a['heading'] ) ) : ?>
<div class="text-center max-w-2xl mx-auto">
<h2 class="text-3xl font-medium tracking-tight sm:text-4xl">
<?php echo esc_html( $a['heading'] ); ?>
</h2>
<?php if ( ! empty( $a['description'] ) ) : ?>
<p class="mt-4 text-base leading-relaxed text-muted">
<?php echo esc_html( $a['description'] ); ?>
</p>
<?php endif; ?>
</div>
<?php endif; ?>
<?php if ( ! empty( $a['features'] ) ) : ?>
<div class="mt-16 grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
<?php foreach ( $a['features'] as $feature ) : ?>
<div class="card">
<h3 class="text-sm font-medium">
<?php echo esc_html( $feature['title'] ); ?>
</h3>
<p class="mt-2 text-sm leading-relaxed text-muted">
<?php echo esc_html( $feature['description'] ); ?>
</p>
</div>
<?php endforeach; ?>
</div>
<?php endif; ?>
</div>
</section>
Toistimen kohteita käsitellään tavallisena PHP-taulukkona. Käy se läpi komennolla foreach ja käytä kunkin kohteen kenttiä niiden id avulla.
Kuvat ja paikkamerkit
Kuvia sisältävissä lohkoissa käytetään kenttätyyppiä files ja komponenttia MediaPlaceholder. Paikkamerkki näyttää editorissa vedä ja pudota -alueen:
{
"id": "image",
"type": "files",
"label": "Image"
}
Renderöi mallipohjassa kuva komennolla wp_get_attachment_image() ja näytä paikkamerkki-SVG, kun kuvaa ei ole valittu:
<div class="overflow-hidden rounded-2xl bg-elevated">
<MediaPlaceholder attribute="image" allowedTypes="<?php echo esc_attr( wp_json_encode( array( 'image' ) ) ); ?>" />
<?php if ( ! empty( $a['image'] ) ) : ?>
<?php echo wp_get_attachment_image( $a['image'][0]['ID'], 'full', false, array( 'class' => 'block w-full' ) ); ?>
<?php else : ?>
<?php echo blockstudio_placeholder_dark(); ?>
<?php endif; ?>
</div>
blockstudio_placeholder_dark() palauttaa upotetun SVG:n, jossa käytetään currentColor-komponenttia ja muuttujaa --color-accent, joten se mukautuu teemaan automaattisesti. Vaaleissa teemoissa käytä arvoa blockstudio_placeholder_light(). Molemmat hyväksyvät varianttiargumentin:
blockstudio_placeholder_dark( 'dashboard' ) // Dashboard mockup
blockstudio_placeholder_dark( 'chart' ) // Chart illustration
blockstudio_placeholder_dark( 'product' ) // Product shot
Sivujen kokoaminen
Sivut koostetaan kokonaisiksi asetteluiksi lohkoista syntaksilla <block>. Luo etusivu:
{
"name": "home",
"title": "Home",
"slug": "home",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
<block name="my-theme/hero"></block>
<block name="my-theme/features"></block>
Siinä kaikki. Jokainen <block>-elementti lisää lohkon oletusmääritteineen. Suorita wp bs pages sync ottaaksesi sivun lähteen käyttöön kohteessa WordPress.
Voit ohittaa tietyn sivun oletusarvot antamalla määritteet suoraan:
<block name="my-theme/hero" heading="About Us" description="Our story and mission."></block>
<block name="my-theme/features" heading="Our Values"></block>
Kun templateLock-arvoksi on asetettu "all", asiakkaat eivät voi lisätä lohkoja, poistaa niitä tai järjestää niitä uudelleen. Sivun rakenne lukitaan mallipohjan mukaiseksi. Katso kohdasta Sivut lisätietoja muista lukitustiloista ja muokkaussäätimistä.
Laajentaminen
Pienessä kirjastossa on aluksi 3–5 lohkoa. Kattavassa kirjastossa niitä on 8–14. Tässä ovat yleiset lohkotyypit likimääräisessä esiintymistiheysjärjestyksessä:
| Lohko | Kuvaus | Keskeiset kentät |
|---|---|---|
| Hero | Suuri otsikko ja toimintakehotteet | otsikko, kuvaus, linkit |
| Features | Etujen ruudukko | otsikko, toistin, jossa on otsikko ja kuvaus |
| CTA | Toimintakehotebanneri | otsikko, kuvaus, linkki |
| Pricing | Pakettien vertailu | otsikko, toistin, jossa on nimi, hinta ja ominaisuudet |
| Testimonials | Asiakaslainaukset | toistin, jossa on lainaus, nimi ja rooli |
| FAQ | Kysymysten haitari | otsikko, toistin, jossa on kysymys ja vastaus |
| Logos | Asiakaslogojen kokoelma | otsikko (logot ovat yleensä kovakoodattuja SVG-tiedostoja) |
| Content | Vuorottelevia tekstin ja kuvan rivejä | toistin, jossa on otsikko, kuvaus ja kuva |
| Showcase | Koko sivun levyinen kuva ja kuvateksti | otsikko, kuvaus, kuva |
| Team | Tiimin jäsenten ruudukko | otsikko, toistin, jossa on nimi, rooli ja kuva |
| Stats | Keskeiset tunnusluvut | toistin, jossa on numero ja tunniste |
Jokainen lohko noudattaa samaa rakennetta: välilehdet (Sisältö ja Osio), ryhmät järjestelyä varten, toistimet luetteloita varten sekä osion apufunktio yhtenäisiä välejä varten. Kun olet rakentanut kaksi tai kolme lohkoa, uusien lisääminen on mekaanista.
Sivujen lisääminen
Kun kirjastosi kasvaa, kokoa samoista lohkoista erilaisia sivuja:
<block name="my-theme/hero" heading="Simple, Transparent Pricing" description="Choose the plan that fits."></block>
<block name="my-theme/pricing"></block>
<block name="my-theme/faq" heading="Pricing FAQ"></block>
<block name="my-theme/cta"></block>
<block name="my-theme/hero" heading="About Us" description="Our story."></block>
<block name="my-theme/team"></block>
<block name="my-theme/testimonials"></block>
<block name="my-theme/cta" heading="Join Our Team"></block>
Samat lohkot sopivat useille sivuille, joista jokaisella on omat oletusarvonsa. Tämä on kirjastomallin etu: rakenna lohkot kerran ja kokoa niistä niin monta sivua kuin tarvitset.
Seuraavat vaiheet
- Määritteiden rekisteröinti: kattava viite kenttätyypeistä ja ominaisuuksista
- Kenttätyypit: kaikki käytettävissä olevat kenttätyypit
- Kenttämallien ohjekirja: ehdolliset ryhmät, älykkäät valintaluettelot ja toistimien ohjeet
- Sivut: mallipohjien lukitus, muokkaustilat ja avainpohjainen yhdistäminen
- Tiedostopohjaisten sivujen rakentaminen: käytännön opas sivumallipohjien käyttöön ja synkronointiin
- Interaktiivisuus: asiakaspuolen toiminnan lisääminen lohkoihin