Siirry sisältöön

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:

Koodi
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:

JSON
{
	"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:

PHP
<!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.

CSS
/*
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:

CSS
@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:

CSS
body {
	@apply bg-bg font-sans text-white antialiased;
}

Perustaso elementtien oletusasetuksille:

CSS
@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:

CSS
@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:

CSS
@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:

JSON
{
	"$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
<?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:

PHP
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:

JSON
{
	"$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
<?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:

  1. Kutsu osion apufunktiota saadaksesi luokat CSS
  2. Ulompi <section>, jossa ovat useBlockProps ja osion luokat
  3. Sisempi <div>, jossa ovat säiliön luokat
  4. Renderöi sisältö kohteesta $a (määritteiden lyhennysmerkintä)
  5. Renderöi valinnaiset kentät ehdollisesti
  6. Käytä asianmukaista suojausta: esc_html() tekstille, esc_url() URL-osoitteille ja esc_attr() määritteille

Toistimet: ominaisuusruudukko

Toistimilla asiakkaat voivat lisätä, poistaa ja järjestää kohteita uudelleen. Ominaisuusruudukko on tyypillinen esimerkki:

JSON
{
	"$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
<?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:

JSON
{
	"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:

PHP
<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:

PHP
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:

JSON
{
	"name": "home",
	"title": "Home",
	"slug": "home",
	"postType": "page",
	"postStatus": "publish",
	"templateLock": "all"
}
PHP
<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:

PHP
<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:

PHP
<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>
PHP
<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