Bloky s kompletným zásobníkom
Blockstudio umožňuje vytvárať kompletné aplikácie v priečinku bloku. Jeden adresár môže obsahovať UI, logiku servera, dátový model, naplánované úlohy a dokonca aj samotné údaje.
Táto príručka vytvára dve skutočné aplikácie, aby ukázala tento vzor: aplikáciu na správu úloh jednotlivých používateľov a verejnú registráciu na odber noviniek. Rovnaká štruktúra súborov, odlišné modely prístupu.
Nasledujúce príklady používajú zápis pomocou polí, pretože je najstručnejší, no všetky tri rozhrania PHP majú aj alternatívy v štýle PHP:
db.phpmôže používaťBlockstudio\\Db\\SchemaaBlockstudio\\Db\\Fieldrpc.phpmôže vrátiť objekt s metódami#[Rpc]cron.phpmôže vrátiť objekt s metódami#[Cron]
Aplikácia na správu úloh
Správca úloh pre jednotlivých používateľov. Každý prihlásený používateľ vidí iba svoje úlohy. Využíva userScoped: true na automatické oddelenie používateľov, SQLite na prenosné ukladanie, bs.mutate() na optimistické aktualizácie a priebežné zisťovanie zmien, aby sa zmeny z iných kariet automaticky zobrazili.
Štruktúra súborov
blockstudio/
todo/
block.json
index.php
script.inline.js
style.css
db.php
rpc.php
cron.php
Definícia bloku
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "my-theme/todo",
"title": "Todo App",
"category": "widgets",
"icon": "editor-ul",
"supports": {
"interactivity": true
},
"blockstudio": {
"interactivity": {
"enqueue": true
}
}
}
supports.interactivity povoľuje spracovanie direktív WordPress (SSR pre
data-wp-each, data-wp-bind atď.). interactivity.enqueue načíta modul @wordpress/interactivity na frontende.
Dátový model
userScoped: true automaticky pridá stĺpec user_id, nastaví ho pri vytvorení
a všetky dotazy filtruje podľa aktuálneho používateľa. realtime povoľuje automatické
zisťovanie zmien, takže zmeny z iných kariet alebo zariadení sa zobrazia bez obnovy stránky.
<?php
return [
'storage' => 'sqlite',
'userScoped' => true,
'realtime' => [
'key' => 'todos',
'interval' => 3000,
],
'capability' => [
'create' => true,
'read' => true,
'update' => true,
'delete' => true,
],
'fields' => [
'text' => [
'type' => 'string',
'required' => true,
'minLength' => 1,
'maxLength' => 500,
],
'done' => [
'type' => 'boolean',
'default' => false,
],
],
];
Ukladanie pomocou SQLite znamená, že súbor databázy sa nachádza v todo/db/default.sqlite. Skopírujte priečinok bloku na inú stránku a prenesú sa aj údaje.
Konfigurácia realtime prikazuje klientovi zisťovať zmeny každé 3 sekundy pomocou
jednoduchého porovnania hashov. Keď sa údaje zmenia, aktualizuje sa state.todos a
UI sa automaticky znova vykreslí.
Vlastná logika servera
Keďže userScoped automaticky filtruje údaje podľa aktuálneho používateľa, vstavaný
bs.db().list() už vracia iba záznamy aktuálneho používateľa. RPC je potrebné iba
pre operácie nad rámec CRUD: prepínanie a hromadné vymazanie.
<?php
use Blockstudio\Db;
return [
'toggle' => [
'callback' => function (array $params) {
$id = (int) ($params['id'] ?? 0);
if (!$id) {
return new \WP_Error('missing_id', 'ID is required.', ['status' => 400]);
}
$db = Db::get('my-theme/todo');
$todo = $db->get_record($id);
if (!$todo) {
return new \WP_Error('not_found', 'Not found.', ['status' => 404]);
}
return $db->update($id, ['done' => !$todo['done']]);
},
'public' => true,
'methods' => ['POST'],
],
'clear_done' => [
'callback' => function () {
$db = Db::get('my-theme/todo');
$todos = $db->list();
$count = 0;
foreach ($todos as $todo) {
if (!empty($todo['done'])) {
$db->delete((int) $todo['id']);
++$count;
}
}
return ['deleted' => $count];
},
'public' => true,
'methods' => ['POST'],
],
];
Naplánované čistenie
Staré dokončené úlohy sa automaticky odstraňujú.
<?php
use Blockstudio\Db;
return [
'cleanup_old_todos' => [
'schedule' => 'daily',
'callback' => function () {
$db = Db::get('my-theme/todo');
$todos = $db->list();
foreach ($todos as $todo) {
$is_done = $todo['done'];
$is_old = strtotime($todo['updated_at']) < strtotime('-30 days');
if ($is_done && $is_old) {
$db->delete((int) $todo['id']);
}
}
},
],
];
Šablóna
PHP načíta počiatočné úlohy na serveri prostredníctvom wp_interactivity_state(), ktorý
poskytuje údaje na spracovanie direktív SSR aj hydratáciu na strane klienta.
Stav UI pre jednotlivé inštancie (napríklad hodnota vstupného poľa) patrí do data-wp-context.
<?php
$db = \Blockstudio\Db::get('my-theme/todo');
$todos = $db ? $db->list() : [];
$items_left = count(array_filter($todos, fn($t) => empty($t['done'])));
wp_interactivity_state('my-theme/todo', [
'todos' => array_values($todos),
'hasTodos' => !empty($todos),
'hasDone' => count($todos) !== $items_left,
'itemsLeft' => $items_left . ($items_left === 1 ? ' item left' : ' items left'),
]);
?>
<div
data-wp-interactive="my-theme/todo"
data-wp-context='<?php echo esc_attr(wp_json_encode(['newText' => ''])); ?>'
useBlockProps
class="todo-app"
>
<h2>Todos</h2>
<div class="todo-input">
<input
type="text"
placeholder="What needs to be done?"
data-wp-bind--value="context.newText"
data-wp-on--input="my-theme/todo::actions.updateNewText"
data-wp-on--keydown="my-theme/todo::actions.handleKeyDown"
/>
<button
data-wp-on--click="my-theme/todo::actions.addTodo"
data-wp-bind--disabled="!state.canAdd"
>Add</button>
</div>
<ul class="todo-list">
<template data-wp-each--todo="state.todos" data-wp-each-key="context.todo.id">
<li>
<label>
<input
type="checkbox"
data-wp-bind--checked="context.todo.done"
data-wp-on--change="actions.toggleTodo"
/>
<span
data-wp-text="context.todo.text"
data-wp-class--done="context.todo.done"
></span>
</label>
<button
class="todo-delete"
data-wp-on--click="actions.deleteTodo"
>×</button>
</li>
</template>
</ul>
<div class="todo-footer" data-wp-bind--hidden="!state.hasTodos">
<span data-wp-text="state.itemsLeft"></span>
<button
data-wp-on--click="my-theme/todo::actions.clearDone"
data-wp-bind--hidden="!state.hasDone"
>Clear done</button>
</div>
</div>
Kľúčové vzory:
wp_interactivity_state()pre údaje zo servera (úlohy, počty)data-wp-contextpre dočasný stav UI (text vo vstupnom poli)data-wp-each--todopriradí každej položke iterácie pomenovaný kontext (context.todo)state.*odkazuje na globálne úložisko,context.*na údaje konkrétnej inštancie
Logika klienta
bs.mutate() spracúva všetky zápisy pomocou optimistických aktualizácií a automatického vrátenia zmien.
UI sa aktualizuje okamžite; ak volanie servera zlyhá, stav sa obnoví.
Chyba overenia alebo oprávnení vráti telo odpovede s chybou namiesto zamietnutia,
ako je opísané v časti Mutate.
import { store, getContext } from '@wordpress/interactivity';
const { state } = store('my-theme/todo', {
state: {
get canAdd() {
return getContext().newText.trim() !== '';
},
get hasTodos() {
return state.todos.length > 0;
},
get hasDone() {
return state.todos.some(t => t.done);
},
get itemsLeft() {
const count = state.todos.filter(t => !t.done).length;
return count + (count === 1 ? ' item left' : ' items left');
},
},
actions: {
updateNewText(event) {
getContext().newText = event.target.value;
},
handleKeyDown(event) {
if (event.key === 'Enter') {
event.preventDefault();
store('my-theme/todo').actions.addTodo();
}
},
*addTodo() {
const ctx = getContext();
const text = ctx.newText.trim();
if (!text) return;
ctx.newText = '';
yield bs.mutate({
fn: () => bs.db('my-theme/todo').create({ text, done: false }),
state, key: 'todos', action: 'create',
optimistic: { text, done: false },
});
},
*toggleTodo() {
const todo = getContext().todo;
yield bs.mutate({
fn: () => bs.fn('toggle', { id: todo.id }, 'my-theme/todo'),
state, key: 'todos', action: 'update', id: todo.id,
optimistic: { ...todo, done: !todo.done },
});
},
*deleteTodo() {
const todo = getContext().todo;
yield bs.mutate({
fn: () => bs.db('my-theme/todo').delete(todo.id),
state, key: 'todos', action: 'delete', id: todo.id,
});
},
*clearDone() {
yield bs.mutate({
fn: () => bs.fn('clear_done', {}, 'my-theme/todo'),
before() {
const snap = state.todos.slice();
state.todos = state.todos.filter(t => !t.done);
return snap;
},
onError(err, snap) { state.todos = snap; },
invalidate: 'todos',
});
},
},
});
Kľúčové vzory:
bs.mutate()automatický režim pre vytvorenie/aktualizáciu/odstránenie: odovzdajtestate,key,actiona údajeoptimistic. UI sa aktualizuje okamžite, volanie servera prebehne na pozadí a pri zlyhaní sa stav obnoví.bs.mutate()manuálny režim preclearDone:before()vytvorí snímku a aplikuje zmenu,onError()obnoví stav zo snímky.- Funkcie generátora (
*addTodo) syieldpre asynchrónne operácie v API Interactivity. bs.db()pre priame CRUD operácie,bs.fn()pre vlastné funkcie servera.
Štýly
.todo-app {
max-width: 500px;
margin: 0 auto;
font-family: system-ui, sans-serif;
}
.todo-input {
display: flex;
gap: 0.5rem;
margin-bottom: 1rem;
}
.todo-input input {
flex: 1;
padding: 0.5rem 0.75rem;
border: 1px solid #d1d5db;
border-radius: 0.375rem;
}
.todo-input button {
padding: 0.5rem 1rem;
background: #3b82f6;
color: white;
border: none;
border-radius: 0.375rem;
cursor: pointer;
}
.todo-list {
list-style: none;
padding: 0;
}
.todo-list li {
display: flex;
align-items: center;
justify-content: space-between;
padding: 0.75rem 0;
border-bottom: 1px solid #f3f4f6;
}
.todo-list label {
display: flex;
align-items: center;
gap: 0.5rem;
flex: 1;
cursor: pointer;
}
.todo-list .done {
text-decoration: line-through;
color: #9ca3af;
}
.todo-delete {
background: none;
border: none;
color: #ef4444;
font-size: 1.25rem;
cursor: pointer;
opacity: 0;
transition: opacity 0.15s;
}
.todo-list li:hover .todo-delete {
opacity: 1;
}
.todo-footer {
display: flex;
justify-content: space-between;
align-items: center;
padding: 0.75rem 0;
font-size: 0.875rem;
color: #6b7280;
}
.todo-footer button {
background: none;
border: none;
color: #6b7280;
cursor: pointer;
text-decoration: underline;
}
CLI
wp bs db list my-theme/todo
wp bs db create my-theme/todo --text="Buy milk" --user_id=1
wp bs cron run my-theme/todo cleanup_old_todos
wp bs rpc call my-theme/todo toggle --id=1
Registrácia na odber noviniek
Verejný formulár na odber. Prihlásiť sa môže ktokoľvek, odberateľov môžu zobrazovať
a spravovať iba správcovia. Bez userScoped a bez overovania pri hlavnej akcii.
Na produkčné použitie sa využíva ukladanie do tabuľky MySQL.
Štruktúra súborov
blockstudio/
newsletter/
block.json
index.php
style.css
script.inline.js
db.php
rpc.php
cron.php
Definícia bloku
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "my-theme/newsletter",
"title": "Newsletter Signup",
"category": "widgets",
"icon": "email",
"supports": {
"interactivity": true
},
"blockstudio": {
"interactivity": {
"enqueue": true
}
}
}
Dátový model
Verejné vytváranie záznamov s ochranou CSRF. Vlastná validácia blokuje jednorazové e-mailové adresy. Čítanie a odstraňovanie sú povolené iba správcom.
<?php
return [
'storage' => 'table',
'capability' => [
'create' => true,
'read' => 'manage_options',
'update' => 'manage_options',
'delete' => 'manage_options',
],
'fields' => [
'email' => [
'type' => 'string',
'format' => 'email',
'required' => true,
'validate' => function ($value) {
$blocked = ['mailinator.com', 'tempmail.com', 'throwaway.email'];
$domain = substr($value, strpos($value, '@') + 1);
if (in_array($domain, $blocked, true)) {
return 'Please use a permanent email address.';
}
return true;
},
],
'name' => [
'type' => 'string',
'maxLength' => 100,
],
'status' => [
'type' => 'string',
'enum' => ['active', 'unsubscribed'],
'default' => 'active',
],
],
'hooks' => [
'after_create' => function ($params) {
$name = $params['record']['name'];
wp_mail(
$params['record']['email'],
'Welcome!',
'Thanks for subscribing' . ($name ? ", $name" : '') . '.'
);
},
],
];
Vlastná logika
Verejný koncový bod na odhlásenie z odberu (funguje cez odkazy v e-mailoch bez prihlásenia) a štatistiky dostupné iba správcom:
<?php
use Blockstudio\Db;
return [
'unsubscribe' => [
'callback' => function (array $params): array {
$email = sanitize_email($params['email'] ?? '');
$db = Db::get('my-theme/newsletter');
$subs = $db->list(['email' => $email]);
if (empty($subs)) {
return ['error' => 'Email not found.'];
}
$db->update((int) $subs[0]['id'], ['status' => 'unsubscribed']);
return ['success' => true];
},
'public' => true,
],
'stats' => [
'callback' => function (array $params): array {
$db = Db::get('my-theme/newsletter');
return [
'total' => count($db->list()),
'active' => count($db->list(['status' => 'active'])),
];
},
'capability' => 'manage_options',
],
];
Naplánované čistenie
<?php
use Blockstudio\Db;
return [
'cleanup' => [
'schedule' => 'weekly',
'callback' => function () {
$db = Db::get('my-theme/newsletter');
$unsub = $db->list(['status' => 'unsubscribed']);
foreach ($unsub as $row) {
if (strtotime($row['updated_at']) < strtotime('-90 days')) {
$db->delete((int) $row['id']);
}
}
},
],
];
Šablóna
<?php
wp_interactivity_state('my-theme/newsletter', [
'submitted' => false,
]);
?>
<div
data-wp-interactive="my-theme/newsletter"
data-wp-context='<?php echo esc_attr(wp_json_encode([
'email' => '',
'name' => '',
'loading' => false,
'error' => '',
])); ?>'
useBlockProps
class="newsletter"
>
<div data-wp-bind--hidden="state.submitted">
<h3>Stay in the loop</h3>
<div class="newsletter-form">
<input
type="text"
placeholder="Name (optional)"
data-wp-bind--value="context.name"
data-wp-on--input="actions.setName"
/>
<input
type="email"
placeholder="Email address"
data-wp-bind--value="context.email"
data-wp-on--input="actions.setEmail"
data-wp-on--keydown="actions.handleKeydown"
/>
<button
data-wp-on--click="actions.subscribe"
data-wp-bind--disabled="context.loading"
>
<span data-wp-text="context.loading ? 'Subscribing...' : 'Subscribe'"></span>
</button>
</div>
<p data-wp-bind--hidden="!context.error" class="newsletter-error" data-wp-text="context.error"></p>
</div>
<div data-wp-bind--hidden="!state.submitted">
<p class="newsletter-success">You're in! Check your email.</p>
</div>
</div>
Logika klienta
import { store, getContext } from '@wordpress/interactivity';
const { state } = store('my-theme/newsletter', {
actions: {
setName(event) {
getContext().name = event.target.value;
},
setEmail(event) {
getContext().email = event.target.value;
},
handleKeydown(event) {
if (event.key === 'Enter') {
store('my-theme/newsletter').actions.subscribe();
}
},
*subscribe() {
const ctx = getContext();
const email = ctx.email.trim();
if (!email) return;
ctx.loading = true;
ctx.error = '';
const result = yield bs.db('my-theme/newsletter').create({
email,
name: ctx.name.trim(),
});
if (result.data?.errors) {
ctx.error = Object.values(result.data.errors)[0][0];
ctx.loading = false;
return;
}
if (result.code) {
ctx.error = result.message || 'Something went wrong.';
ctx.loading = false;
return;
}
state.submitted = true;
ctx.loading = false;
},
},
});
Štýly
.newsletter {
max-width: 480px;
margin: 0 auto;
padding: 2rem;
text-align: center;
}
.newsletter h3 {
margin: 0 0 1rem;
}
.newsletter-form {
display: flex;
flex-direction: column;
gap: 0.5rem;
}
.newsletter-form input {
padding: 0.625rem 0.75rem;
border: 1px solid #d1d5db;
border-radius: 0.375rem;
font-size: 1rem;
}
.newsletter-form button {
padding: 0.625rem 1rem;
background: #3b82f6;
color: white;
border: none;
border-radius: 0.375rem;
font-size: 1rem;
cursor: pointer;
}
.newsletter-form button:disabled {
opacity: 0.6;
cursor: not-allowed;
}
.newsletter-error {
color: #ef4444;
font-size: 0.875rem;
margin: 0.5rem 0 0;
}
.newsletter-success {
color: #10b981;
font-size: 1.125rem;
}
CLI
wp bs db list my-theme/newsletter --format=table
wp bs rpc call my-theme/newsletter stats
wp bs rpc call my-theme/newsletter unsubscribe --email=user@example.com
wp bs cron run my-theme/newsletter cleanup
Porovnanie vedľa seba
| Aspekt | Aplikácia na správu úloh | Novinky |
|---|---|---|
| Model overovania | userScoped: true |
Verejné vytváranie, správca číta |
| Ukladanie | SQLite (prenosné) | tabuľka MySQL (produkčné použitie) |
| Filtrovanie používateľov | Automatické | Nie je potrebné |
| CSRF | Prostredníctvom X-BS-Token |
Prostredníctvom X-BS-Token |
| Vlastné RPC | Prepínanie, vymazanie dokončených | Odhlásenie, štatistiky |
| Cron | Odstránenie starých dokončených | Odstránenie odhlásených |
| Validácia | Obmedzenia dĺžky | Formát e-mailu + blokovanie domén |
| Aktualizácie v reálnom čase | Zisťovanie každé 3 s | Nie sú potrebné |
| Optimistické UI | bs.mutate() automatický režim |
Priame bs.db().create() |
| Stav | wp_interactivity_state() |
wp_interactivity_state() + kontext |
Rovnaký vzor, odlišné modely prístupu. Základné stavebné prvky sú rovnaké:
db.php pre dátový model, rpc.php pre obchodnú logiku, cron.php pre
úlohy na pozadí, index.php + script.inline.js pre UI, style.css
pre vzhľad. Každý blok je samostatná aplikácia.