Viso steko blokai
Blockstudio leidžia kurti ištisas programas vieno bloko aplanke. Viename kataloge gali būti UI, serverio logika, duomenų modelis, suplanuotos užduotys ir net patys duomenys.
Šiame vadove, siekiant parodyti šį metodą, kuriamos dvi veikiančios programos: kiekvienam naudotojui skirtas užduočių sąrašas ir vieša naujienlaiškio prenumeratos forma. Failų struktūra ta pati, prieigos modeliai skirtingi.
Toliau pateiktuose pavyzdžiuose naudojama masyvo sintaksė, nes ji kompaktiškiausia, tačiau visos trys PHP vietos turi ir PHP būdingų alternatyvų:
db.phpgali naudotiBlockstudio\\Db\\SchemairBlockstudio\\Db\\Fieldrpc.phpgali grąžinti objektą su#[Rpc]metodaiscron.phpgali grąžinti objektą su#[Cron]metodais
Užduočių programa
Užduočių tvarkyklė, skirta kiekvienam naudotojui. Kiekvienas prisijungęs naudotojas mato tik savo užduotis. Naudojama userScoped: true automatiniam naudotojų atskyrimui, SQLite perkeliamam saugojimui, bs.mutate() optimistiniams atnaujinimams, o tikralaikė apklausa automatiškai parodo pakeitimus iš kitų kortelių.
Failų struktūra
blockstudio/
todo/
block.json
index.php
script.inline.js
style.css
db.php
rpc.php
cron.php
Bloko apibrėžimas
{
"$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 įjungia WordPress direktyvų apdorojimą (SSR, skirtą data-wp-each, data-wp-bind ir t. t.). interactivity.enqueue įkelia @wordpress/interactivity modulį svetainės sąsajoje.
Duomenų modelis
userScoped: true automatiškai prideda stulpelį user_id, nustato jo reikšmę kuriant įrašą ir filtruoja visas užklausas pagal dabartinį naudotoją. realtime įjungia automatinę apklausą, todėl pakeitimai iš kitų kortelių ar įrenginių rodomi neatnaujinus puslapio.
<?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,
],
],
];
Naudojant SQLite saugyklą, duomenų bazės failas yra adresu todo/db/default.sqlite. Nukopijuokite bloko aplanką į kitą svetainę, ir kartu bus perkelti duomenys.
Konfigūracija realtime nurodo klientui kas 3 sekundes tikrinti, ar yra pakeitimų, naudojant lengvą maišos reikšmių palyginimą. Pasikeitus duomenims, atnaujinama state.todos, o UI automatiškai atvaizduojama iš naujo.
Tinkinta serverio logika
Kadangi userScoped automatiškai filtruoja pagal dabartinį naudotoją, integruota bs.db().list() jau grąžina tik dabartinio naudotojo įrašus. RPC reikalinga tik CRUD ribas peržengiančioms operacijoms: perjungimui ir masiniam išvalymui.
<?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'],
],
];
Suplanuotas valymas
Senos atliktos užduotys automatiškai išvalomos.
<?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']);
}
}
},
],
];
Šablonas
PHP serveryje per wp_interactivity_state() įkelia pradines užduotis; šis mechanizmas teikia duomenis ir SSR direktyvų apdorojimui, ir kliento pusės hidratacijai. Kiekvieno egzemplioriaus UI būsena (pavyzdžiui, įvesties lauko reikšmė) saugoma 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>
Pagrindiniai šablonai:
wp_interactivity_state()serverio duomenims (užduotims, skaičiams)data-wp-contexttrumpalaikei UI būsenai (įvestam tekstui)data-wp-each--todokiekvienam iteracijos elementui priskiria pavadintą kontekstą (context.todo)state.*nurodo visuotinę saugyklą,context.*– kiekvieno egzemplioriaus duomenis
Kliento logika
bs.mutate() tvarko visus įrašymo veiksmus, taikydama optimistinius atnaujinimus ir automatinį grąžinimą. UI atnaujinama iškart; jei serverio iškvietimas atmetamas, būsena atkuriama. Kaip aprašyta skiltyje Mutuoti, dėl patvirtinimo arba leidimų klaidos grąžinama klaidos turinio reikšmė, o ne atmetamas iškvietimas.
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',
});
},
},
});
Pagrindiniai šablonai:
bs.mutate()automatinis režimas kūrimui, atnaujinimui ir šalinimui: perduokitestate,key,actioniroptimisticduomenis. UI atnaujinama iškart, serverio iškvietimas vykdomas fone, o įvykus klaidai būsena atkuriama.bs.mutate()rankinis režimas, skirtasclearDone:before()padaro momentinę kopiją ir pritaiko pakeitimą, oonError()atkuria būseną iš kopijos.- Generatorių funkcijos (
*addTodo) suyieldasinchroninėms operacijoms interaktyvumo API. bs.db()tiesioginėms CRUD operacijoms,bs.fn()tinkintoms serverio funkcijoms.
Stiliai
.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
Naujienlaiškio prenumerata
Vieša prenumeratos forma. Prenumeruoti gali visi, o prenumeratorius peržiūrėti ir tvarkyti gali tik administratoriai. Pagrindiniam veiksmui nereikia nei userScoped, nei autentifikavimo. Gamybinėje aplinkoje naudojama MySQL lentelės saugykla.
Failų struktūra
blockstudio/
newsletter/
block.json
index.php
style.css
script.inline.js
db.php
rpc.php
cron.php
Bloko apibrėžimas
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "my-theme/newsletter",
"title": "Newsletter Signup",
"category": "widgets",
"icon": "email",
"supports": {
"interactivity": true
},
"blockstudio": {
"interactivity": {
"enqueue": true
}
}
}
Duomenų modelis
Viešas įrašų kūrimas su CSRF apsauga. Pasirinktinė patikra blokuoja vienkartinio naudojimo el. pašto adresus. Skaityti ir šalinti gali tik administratoriai.
<?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" : '') . '.'
);
},
],
];
Tinkinta logika
Viešas prenumeratos atsisakymo galinis taškas (veikia iš el. laiško nuorodų neprisijungus) ir tik administratoriams skirta statistika:
<?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',
],
];
Suplanuotas valymas
<?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']);
}
}
},
],
];
Šablonas
<?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>
Kliento logika
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;
},
},
});
Stiliai
.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
Palyginimas
| Ypatybė | Užduočių programa | Naujienlaiškis |
|---|---|---|
| Autentifikavimo modelis | userScoped: true |
Viešas kūrimas, administratoriaus peržiūra |
| Saugykla | SQLite (perkeliama) | MySQL lentelė (gamybinė aplinka) |
| Naudotojų filtravimas | Automatinis | Nereikalingas |
| CSRF | Per X-BS-Token |
Per X-BS-Token |
| Tinkinta RPC | Perjungimas, atliktų užduočių išvalymas | Prenumeratos atsisakymas, statistika |
| Cron | Senų atliktų užduočių šalinimas | Prenumeratos atsisakiusiųjų pašalinimas |
| Patikra | Ilgio apribojimai | El. pašto formatas ir domenų blokavimas |
| Tikralaikiškumas | Tikrinimas kas 3 s | Nereikalingas |
| Optimistinis UI | bs.mutate() automatinis režimas |
Tiesioginis bs.db().create() |
| Būsena | wp_interactivity_state() |
wp_interactivity_state() + kontekstas |
Metodas tas pats, prieigos modeliai skirtingi. Pagrindiniai komponentai identiški: db.php duomenų modeliui, rpc.php verslo logikai, cron.php foninėms užduotims, index.php + script.inline.js, skirti UI, ir style.css išvaizdai. Kiekvienas blokas yra savarankiška programa.