Bloki s celotnim skladom
Blockstudio vam omogoča ustvarjanje celovitih aplikacij znotraj mape bloka. En imenik lahko vsebuje UI, strežniško logiko, podatkovni model, načrtovana opravila in celo same podatke.
Ta vodnik predstavi vzorec na dveh resničnih aplikacijah: aplikaciji za sezname opravil za posamezne uporabnike in javni prijavi na e-novice. Enaka struktura datotek, različna modela dostopa.
Spodnji primeri uporabljajo sintakso z nizi, ker je najkrajša, vendar imajo vsi trije vmesniki PHP tudi alternative, ki izvirajo iz PHP:
db.phplahko uporabljaBlockstudio\\Db\\SchemainBlockstudio\\Db\\Fieldrpc.phplahko vrne objekt z metodami#[Rpc]cron.phplahko vrne objekt z metodami#[Cron]
Aplikacija za opravila
Upravitelj opravil za posamezne uporabnike. Vsak prijavljeni uporabnik vidi samo svoja opravila. Uporablja userScoped: true za samodejno ločevanje podatkov po uporabnikih, SQLite za prenosljivo shranjevanje, bs.mutate() za optimistične posodobitve ter sprotno preverjanje, da se spremembe iz drugih zavihkov prikažejo samodejno.
Struktura datotek
blockstudio/
todo/
block.json
index.php
script.inline.js
style.css
db.php
rpc.php
cron.php
Definicija bloka
{
"$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 omogoči obdelavo direktiv v WordPress (SSR za data-wp-each, data-wp-bind itd.). interactivity.enqueue naloži modul @wordpress/interactivity v uporabniški vmesnik.
Podatkovni model
userScoped: true samodejno doda stolpec user_id, ga nastavi ob ustvarjanju in vse poizvedbe omeji na trenutnega uporabnika. realtime omogoči samodejno preverjanje, zato se spremembe iz drugih zavihkov ali naprav prikažejo brez osvežitve strani.
<?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,
],
],
];
Shramba SQLite pomeni, da je datoteka zbirke podatkov shranjena v todo/db/default.sqlite. Kopirajte mapo bloka na drugo spletno mesto in podatki bodo preneseni z njo.
Konfiguracija realtime naroči odjemalcu, naj vsake 3 sekunde preveri spremembe z lahkotno primerjavo zgoščenih vrednosti. Ko se podatki spremenijo, se posodobi state.todos, UI pa se samodejno znova upodobi.
Logika strežnika po meri
Ker userScoped samodejno filtrira podatke za trenutnega uporabnika, vgrajeni bs.db().list() že vrne samo njegove zapise. RPC je potreben samo za operacije zunaj CRUD: preklapljanje stanja in množično brisanje.
<?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'],
],
];
Načrtovano čiščenje
Stara dokončana opravila se samodejno počistijo.
<?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']);
}
}
},
],
];
Predloga
PHP prek wp_interactivity_state() na strani strežnika naloži začetna opravila. Tako zagotovi podatke za obdelavo direktiv SSR in hidracijo na strani odjemalca. Stanje UI za posamezni primerek (na primer vrednost vnosnega polja) sodi v 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>
Ključni vzorci:
wp_interactivity_state()za podatke s strežnika (opravila, števila)data-wp-contextza prehodno stanje UI (besedilo vnosnega polja)data-wp-each--todovsakemu elementu v ponovitvi dodeli poimenovani kontekst (context.todo)state.*se sklicuje na globalno shrambo,context.*pa na podatke posameznega primerka
Logika odjemalca
bs.mutate() obdela vse zapise z optimističnimi posodobitvami in samodejnim povrnitvenim postopkom. UI se posodobi takoj; če klic strežnika ni uspešen, se stanje povrne. Napaka pri preverjanju veljavnosti ali dovoljenj se vrne v telesu odgovora, namesto da bi bila zavrnjena, kot je opisano v razdelku Spreminjanje.
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',
});
},
},
});
Ključni vzorci:
bs.mutate()za samodejni način ustvarjanja, posodabljanja in brisanja: posredujte podatkestate,key,actioninoptimistic. UI se posodobi takoj, klic strežnika pa poteka v ozadju; ob napaki se stanje povrne.bs.mutate()za ročni način priclearDone:before()zajame posnetek in uveljavi spremembo,onError()pa obnovi stanje iz posnetka.- Generatorji (
*addTodo) zyieldza asinhrone operacije v API za interaktivnost. bs.db()za neposredni CRUD,bs.fn()za strežniške funkcije po meri.
Slogi
.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
Prijava na e-novice
Javni obrazec za naročanje. Naroči se lahko kdor koli, naročnike pa si lahko ogledujejo in upravljajo samo skrbniki. Za glavno dejanje ni userScoped in ne zahteva preverjanja pristnosti. Za produkcijsko uporabo uporablja shranjevanje v tabeli MySQL.
Struktura datotek
blockstudio/
newsletter/
block.json
index.php
style.css
script.inline.js
db.php
rpc.php
cron.php
Definicija bloka
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "my-theme/newsletter",
"title": "Newsletter Signup",
"category": "widgets",
"icon": "email",
"supports": {
"interactivity": true
},
"blockstudio": {
"interactivity": {
"enqueue": true
}
}
}
Podatkovni model
Javno ustvarjanje z zaščito CSRF. Preverjanje po meri zavrne e-poštne naslove za enkratno uporabo. Branje in brisanje sta dovoljena samo skrbnikom.
<?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" : '') . '.'
);
},
],
];
Logika po meri
Javna končna točka za odjavo (deluje prek povezav v e-pošti brez prijave) in statistika, dostopna samo skrbnikom:
<?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',
],
];
Načrtovano čiščenje
<?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']);
}
}
},
],
];
Predloga
<?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 odjemalca
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;
},
},
});
Slogi
.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
Primerjava vzporedno
| Vidik | Aplikacija za opravila | E-novice |
|---|---|---|
| Model preverjanja pristnosti | userScoped: true |
Javno ustvarjanje, skrbniški dostop za branje |
| Shramba | SQLite (prenosljiva) | tabela MySQL (produkcija) |
| Filtriranje po uporabniku | Samodejno | Ni potrebno |
| CSRF | Prek X-BS-Token |
Prek X-BS-Token |
| Logika po meri RPC | Preklapljanje, brisanje dokončanih | Odjava, statistika |
| Cron | Brisanje starih dokončanih | Odstranjevanje odjavljenih |
| Preverjanje veljavnosti | Omejitve dolžine | Oblika e-poštnega naslova + blokada domene |
| Sprotno posodabljanje | Preverjanje na 3 s | Ni potrebno |
| Optimistični UI | bs.mutate() samodejni način |
Neposredni bs.db().create() |
| Stanje | wp_interactivity_state() |
wp_interactivity_state() + kontekst |
Enak vzorec, različna modela dostopa. Gradniki so enaki: db.php za podatkovni model, rpc.php za poslovno logiko, cron.php za opravila v ozadju, index.php + script.inline.js za UI, style.css pa za videz. Vsak blok je samostojna aplikacija.