Vytvoření knihovny bloků
Knihovna bloků je sada samostatných bloků sekcí, ze kterých se skládají celé stránky. Každý blok má vlastní schéma, šablonu a styly. Blockstudio poskytuje základ: zpracování Tailwind CSS, registraci atributů a synchronizaci stránek. Bloky dodáváte vy.
Tento průvodce vás provede vytvořením knihovny od začátku a využívá stejnou architekturu jako stovky produkčních šablon. Na konci budete mít funkční šablonu s úvodní sekcí, mřížkou výhod a sestavenou domovskou stránkou.
Struktura složek
Každá šablona Blockstudio má stejné rozvržení:
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
Bloky jsou v blockstudio/sections/. Každý blok tvoří složka se schématem block.json a šablonou index.php. Stránky jsou v pages/ a skládají bloky pomocí syntaxe <block>.
Základní soubory
blockstudio.json
Tento soubor určuje, jak Blockstudio zpracovává vaši šablonu. Konfigurace je stejná pro každou šablonu:
{
"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 odstraní výchozí styly bloků WordPress. fullWidth roztáhne vlastní typy příspěvků page na celou šířku. canvas zapne režim plátna editoru pro přehlednější úpravy.
Pole tailwind.config je záměrně prázdné. Při použití Tailwind v4 je veškerá konfigurace v style.css a používá přístup založený nejprve na CSS.
index.php
Hlavní šablona WordPress. Jde o standardní WordPress, bez specifik 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>
Pokud potřebujete navigaci, přidejte header.php a footer.php. Prozatím k vykreslení bloků stačí minimální šablona.
Návrhové tokeny
Veškeré motivy se definují v style.css pomocí direktivy @theme od Tailwind v4. Jde o základ vašeho návrhového systému.
/*
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;
}
Každé šabloně stačí alespoň:
| Token | Účel |
|---|---|
--font-sans nebo --font-serif |
Primární typ písma |
--color-bg |
Pozadí stránky |
--color-elevated |
Pozadí karty nebo plochy |
--color-subtle |
Ohraničení, oddělovače |
--color-muted |
Sekundární text |
--color-accent |
Primární barva značky |
Tyto tokeny automaticky generují nástroje Tailwind. Z --color-accent vznikne bg-accent, text-accent, border-accent atd.
Pro světlý motiv hodnoty obraťte:
@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;
}
Základní styly a nástroje
Pod blok @theme přidejte styly těla stránky, výchozí hodnoty základní vrstvy a vlastní nástroje.
Styly těla stránky musí být mimo blok @layer, aby je editor WordPress převzal:
body {
@apply bg-bg font-sans text-white antialiased;
}
Základní vrstva pro výchozí styly prvků:
@layer base {
section {
@apply relative overflow-hidden;
}
h1, h2, h3 {
text-wrap: balance;
}
p {
text-wrap: pretty;
}
}
Vlastní nástroje pro opakovaně použitelné vzory. Každá šablona definuje nástroj container pro jednotné rozestupy sekcí a obvykle také card, badge a nástroje pro tlačítka:
@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);
}
}
Pseudovýběry patří dovnitř bloku @utility a používají vnořování CSS (&:hover). Nikdy je nedávejte do názvu nástroje. @utility btn-primary:hover {} je neplatné a Tailwind ho odmítne.
@source vložené
Blockstudio automaticky prohledává šablony bloků a vyhledává třídy Tailwind. Třídy použité mimo šablony bloků (v functions.php, header.php, index.php) ale neprohledává. Deklarujte je pomocí @source inline:
@source inline("bg-bg bg-accent-tint container container-px container-no-pb");
Tím Tailwind určíte, aby tyto třídy zahrnul do výstupu, i když se nacházejí pouze v souborech PHP, které se neprohledávají.
Vzor sekce
Vzor sekce je nejdůležitější konvencí knihovny bloků Blockstudio. Pomocí dvou sdílených mechanismů zajišťuje jednotné rozestupy, přepínání pozadí a ovládání odsazení všech bloků: vlastního pole a pomocné funkce PHP.
Pole sekce
Vytvořte sdílenou definici pole, na kterou se mohou odkazovat všechny bloky:
{
"$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"
}
]
}
]
}
Toto pole se zobrazí v inspektoru každého bloku na kartě „Sekce“. Klienti dostanou dva ovládací prvky: přepnutí zvýrazněného pozadí a odebrání spodního odsazení (užitečné při skládání sekcí bez mezer).
Pomocná funkce sekce
V functions.php vytvořte pomocnou funkci, která převede tyto atributy na třídy CSS:
<?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 );
}
Každá šablona bloku volá tuto pomocnou funkci na prvním řádku. Funkce vrací dva řetězce tříd: jeden pro vnější prvek <section> a druhý pro vnitřní kontejner <div>.
Filtr konfigurace Tailwind
Také v functions.php přidejte filtr, který předá váš style.css procesoru Tailwind v Blockstudio:
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ím Blockstudio určíte, aby jako zdroj konfigurace Tailwind v4 používal váš style.css. Bez tohoto nastavení by v šablonách bloků nebyly dostupné vaše tokeny @theme a definice @utility.
První blok: úvodní sekce
Úvodní sekce ukazuje kompletní vzor bloku. Začněte schématem:
{
"$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" }
]
}
]
}
]
}
}
Důležité vzory:
Obal tabs vytvoří inspektor se dvěma kartami: „Obsah“ pro pole bloku a „Sekce“ pro sdílené ovládací prvky sekce. Tuto strukturu používá každý blok.
Pole jsou uspořádána do kontejnerů group. Skupiny v inspektoru vizuálně oddělují související pole. První skupina obsahuje textová pole, druhá pole odkazů.
Výchozí hodnoty poskytují smysluplný obsah, takže blok po vložení vypadá kompletně. To je zásadní při skládání stránek, kdy se bloky přidávají bez zásahu uživatele.
Nyní šablona:
<?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>
Šablona se řídí jednotným vzorem:
- Zavolejte pomocnou funkci sekce a získejte třídy CSS
- Vnější
<section>suseBlockPropsa třídami sekce - Vnitřní
<div>s třídami kontejneru - Vykreslení obsahu z
$a(zkrácený zápis atributů) - Podmíněné vykreslování nepovinných polí
- Správné escapování:
esc_html()pro text,esc_url()pro URL,esc_attr()pro atributy
Přidání opakovačů: mřížka funkcí
Opakovače umožňují klientům přidávat, odebírat a měnit pořadí položek. Klasickým příkladem je mřížka funkcí:
{
"$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" }
]
}
]
}
]
}
}
Vlastnost textMinimized určuje, jaký text se zobrazí při sbalení řádku opakovače. Načte hodnotu pole title, a pokud je prázdná, použije „Funkce“. Díky tomu se inspektor snadno používá i při větším počtu položek.
Pole default poskytuje počáteční položky. Zobrazí se po prvním vložení bloku. Vždy nastavte realistické výchozí hodnoty, aby blok vypadal kompletně hned po vložení.
<?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>
Položky opakovače jsou dostupné jako prosté pole PHP. Procházejte je pomocí foreach a k polím jednotlivých položek přistupujte přes jejich id.
Obrázky a zástupné prvky
Pro bloky s obrázky použijte typ pole files a komponentu MediaPlaceholder. Zástupný prvek zobrazí v editoru zónu pro přetažení souboru:
{
"id": "image",
"type": "files",
"label": "Image"
}
V šabloně vykreslete obrázek pomocí wp_get_attachment_image() a pokud není vybrán žádný obrázek, zobrazte SVG zástupného prvku:
<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() vrací vložené SVG, které používá currentColor s proměnnou --color-accent, takže se automaticky přizpůsobí vašemu motivu. U světlých motivů použijte blockstudio_placeholder_light(). Obě možnosti přijímají argument varianty:
blockstudio_placeholder_dark( 'dashboard' ) // Dashboard mockup
blockstudio_placeholder_dark( 'chart' ) // Chart illustration
blockstudio_placeholder_dark( 'product' ) // Product shot
Skládání stránek
Stránky skládají bloky do úplných rozvržení pomocí syntaxe <block>. Vytvořte domovskou stránku:
{
"name": "home",
"title": "Home",
"slug": "home",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
<block name="my-theme/hero"></block>
<block name="my-theme/features"></block>
Hotovo. Každý prvek <block> vloží blok s výchozími hodnotami atributů. Spuštěním wp bs pages sync použijete zdroj stránky v WordPress.
Chcete-li na konkrétní stránce přepsat výchozí hodnoty, zadejte atributy přímo:
<block name="my-theme/hero" heading="About Us" description="Our story and mission."></block>
<block name="my-theme/features" heading="Our Values"></block>
Je-li templateLock nastaveno na "all", klienti nemohou přidávat, odebírat ani přesouvat bloky. Struktura stránky je uzamčena podle vaší šablony. Další režimy uzamčení a možnosti úprav najdete v části Stránky.
Rozšiřování knihovny
Základní knihovna začíná se 3–5 bloky. Rozsáhlá knihovna jich má 8–14. Níže jsou běžné typy bloků, přibližně seřazené podle četnosti použití:
| Blok | Popis | Hlavní pole |
|---|---|---|
| Úvodní sekce | Velký nadpis s výzvami k akci | nadpis, popis, odkazy |
| Funkce | Mřížka výhod | nadpis, opakovač s názvem a popisem |
| Výzva k akci | Pruh s výzvou k akci | nadpis, popis, odkaz |
| Ceník | Porovnání tarifů | nadpis, opakovač s názvem, cenou a funkcemi |
| Reference | Citace zákazníků | opakovač s citací, jménem a rolí |
| Časté dotazy | Rozbalovací seznam otázek | nadpis, opakovač s otázkou a odpovědí |
| Loga | Přehled log klientů | nadpis (loga bývají pevně vložená jako SVG) |
| Obsah | Střídající se řádky textu a obrázků | opakovač s nadpisem, popisem a obrázkem |
| Ukázka | Obrázek přes celou šířku s popiskem | nadpis, popis, obrázek |
| Tým | Mřížka členů týmu | nadpis, opakovač se jménem, rolí a obrázkem |
| Statistiky | Klíčové metriky | opakovač s číslem a popiskem |
Každý blok používá stejný vzor: karty (Obsah + Sekce), skupiny pro uspořádání, opakovače seznamů a pomocnou funkci sekce pro jednotné rozestupy. Jakmile vytvoříte dva nebo tři bloky, přidávání dalších je už rutinní záležitost.
Přidání dalších stránek
S růstem knihovny skládejte z týchž bloků různé stránky:
<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>
Stejné bloky lze použít na více stránkách, na každé s jinými výchozími hodnotami. V tom spočívá síla přístupu založeného na knihovně: bloky vytvoříte jednou a skládáte z nich libovolný počet stránek.
Další kroky
- Registrace atributů: Úplný přehled typů polí a jejich vlastností
- Typy polí: Všechny dostupné typy polí
- Kuchařka vzorů polí: Podmíněné skupiny, chytré výběry a postupy pro opakovače
- Stránky: Zamykání šablon, režimy úprav a slučování podle klíčů
- Vytváření stránek ze souborů: Praktický návod k šablonám stránek a synchronizaci
- Interaktivita: Přidání chování na straně klienta do bloků