Täispinu plokid
Blockstudio võimaldab luua terviklikke rakendusi ploki kaustas. Üks kataloog võib sisaldada UI, serveriloogikat, andmemudelit, ajastatud ülesandeid ja isegi andmeid.
See juhend koostab mustri näitamiseks kaks päris rakendust: kasutajapõhise ülesannete loendi rakenduse ja avaliku uudiskirjaga liitumise vormi. Sama failistruktuur, erinevad juurdepääsumudelid.
Allolevates näidetes kasutatakse massiivi süntaksit, sest see on kõige kompaktsem, kuid kõigi kolme PHP liidese jaoks on olemas ka PHP-i natiivsed alternatiivid:
db.phpsaab kasutadaBlockstudio\\Db\\Schema-i jaBlockstudio\\Db\\Field-irpc.phpsaab tagastada objekti#[Rpc]meetoditegacron.phpsaab tagastada objekti#[Cron]meetoditega
Ülesannete loend
Kasutajapõhine ülesannete haldur. Iga sisseloginud kasutaja näeb ainult enda ülesandeid. Kasutab automaatseks kasutajate eraldamiseks userScoped: true-i, teisaldatavaks salvestuseks SQLite-i, optimistlikeks uuendusteks bs.mutate()-i ning reaalajas küsitlust, nii et muudatused teistelt vahelehtedelt ilmuvad automaatselt.
Failistruktuur
blockstudio/
todo/
block.json
index.php
script.inline.js
style.css
db.php
rpc.php
cron.php
Ploki määratlus
{
"$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 lubab kasutada WordPress-i direktiivide töötlemist (SSR data-wp-each, data-wp-bind jne jaoks). interactivity.enqueue laadib kasutajaliideses mooduli @wordpress/interactivity.
Andmemudel
userScoped: true lisab automaatselt veeru user_id, määrab selle loomisel ja filtreerib kõik päringud praeguse kasutaja järgi. realtime lubab automaatse küsitluse, nii et muudatused teistelt vahelehtedelt või seadmetest ilmuvad lehte värskendamata.
<?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,
],
],
];
SQLite-i salvestus tähendab, et andmebaasifail asub kohas todo/db/default.sqlite. Kopeerige ploki kaust teisele saidile ja andmed tulevad sellega kaasa.
realtime-i seadistus käsib kliendil küsida muudatuste kohta iga 3 sekundi järel, kasutades kerget räsiväärtuste võrdlust. Kui andmed muutuvad, uuendatakse väärtust state.todos ja UI renderdatakse automaatselt uuesti.
Kohandatud serveriloogika
Kuna userScoped filtreerib automaatselt praeguse kasutaja andmete järgi, tagastab sisseehitatud bs.db().list() juba ainult praeguse kasutaja kirjed. RPC on vajalik üksnes CRUD-ist kaugemale ulatuvateks toiminguteks: oleku muutmiseks ja kõigi kustutamiseks.
<?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'],
],
];
Ajastatud puhastus
Vanad lõpetatud ülesanded puhastatakse automaatselt.
<?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']);
}
}
},
],
];
Mall
PHP laadib esialgsed ülesanded serveri poolel käsuga wp_interactivity_state(), mis edastab andmed nii SSR-direktiivide töötlemiseks kui ka kliendipoolseks hüdreerimiseks. Iga eksemplari UI olek (nt sisestusvälja väärtus) kuulub asukohta 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>
Võtmemustrid:
wp_interactivity_state()serverist tulevate andmete jaoks (ülesanded, arvud)data-wp-contextajutise UI oleku jaoks (sisestatud tekst)data-wp-each--todoannab igale iteratsiooniüksusele nimega konteksti (context.todo)state.*viitab globaalsele salvele,context.*viitab eksemplaripõhistele andmetele
Kliendiloogika
bs.mutate() käsitleb kõiki kirjutustoiminguid optimistlike uuenduste ja automaatse tagasipööramisega. UI uueneb kohe; kui serverikutse nurjub, taastatakse eelmine olek. Valideerimis- või õiguste viga tagastatakse veasisuna, mitte tagasilükkamisena, nagu kirjeldatud jaotises Muuda.
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',
});
},
},
});
Võtmemustrid:
bs.mutate()automaatrežiim loomiseks, uuendamiseks ja kustutamiseks: edastagestate,key,actionjaoptimisticandmed. UI uueneb kohe, serverikutse tehakse taustal ning tõrke korral taastatakse eelmine olek.bs.mutate()käsirežiim toiminguclearDonejaoks:before()teeb hetkeseisust koopia ja rakendab muudatuse,onError()taastab oleku koopiast.- Generaatorfunktsioonid (
*addTodo) koosyield-ga asünkroonsete toimingute jaoks Interactivity API-s. bs.db()otseseks CRUD-iks,bs.fn()kohandatud serverifunktsioonide jaoks.
Stiilid
.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
Uudiskirjaga liitumine
Avalik liitumisvorm. Igaüks saab tellida, kuid tellijaid saavad vaadata ja hallata ainult administraatorid. Põhitoimingu jaoks pole vaja userScoped-i ega autentimist. Tootmiskasutuseks kasutab see MySQL tabelisalvestust.
Failistruktuur
blockstudio/
newsletter/
block.json
index.php
style.css
script.inline.js
db.php
rpc.php
cron.php
Ploki määratlus
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "my-theme/newsletter",
"title": "Newsletter Signup",
"category": "widgets",
"icon": "email",
"supports": {
"interactivity": true
},
"blockstudio": {
"interactivity": {
"enqueue": true
}
}
}
Andmemudel
Avalik loomine CSRF-kaitsega. Kohandatud valideerimine tõkestab ajutised e-posti aadressid. Lugemine ja kustutamine on lubatud ainult administraatoritele.
<?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" : '') . '.'
);
},
],
];
Kohandatud loogika
Avalik tellimuse lõpetamise otspunkt (töötab e-kirja linkidest ilma sisselogimata) ja ainult administraatoritele mõeldud 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',
],
];
Ajastatud puhastus
<?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']);
}
}
},
],
];
Mall
<?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>
Kliendiloogika
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;
},
},
});
Stiilid
.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
Kõrvuti võrdlus
| Aspekt | Ülesannete loend | Uudiskiri |
|---|---|---|
| Autentimismudel | userScoped: true |
Avalik loomine, administraator saab lugeda |
| Salvestus | SQLite (teisaldatav) | MySQL tabel (tootmiskasutuseks) |
| Kasutajapõhine filtreerimine | Automaatne | Pole vaja |
| CSRF | X-BS-Token kaudu |
X-BS-Token kaudu |
| Kohandatud RPC | Oleku muutmine, lõpetatute kustutamine | Tellimuse lõpetamine, statistika |
| Cron | Vanade lõpetatute kustutamine | Tellimuse lõpetanute eemaldamine |
| Valideerimine | Pikkusepiirangud | E-posti vorming + domeeni tõkestus |
| Reaalajas | Küsitlus iga 3 s järel | Pole vaja |
| Optimistlik UI | bs.mutate() automaatrežiim |
Otsene bs.db().create() |
| Olek | wp_interactivity_state() |
wp_interactivity_state() + kontekst |
Sama muster, erinevad juurdepääsumudelid. Põhikomponendid on samad: db.php andmemudeli jaoks, rpc.php äriloogika jaoks, cron.php taustaülesannete jaoks, index.php + script.inline.js UI jaoks ning style.css välimuse jaoks. Iga plokk on iseseisev rakendus.