Täyden pinon lohkot
Blockstudio mahdollistaa kokonaisten sovellusten rakentamisen lohkokansion sisällä. Yhdessä hakemistossa voivat olla UI, palvelinlogiikka, tietomalli, ajastetut tehtävät ja jopa itse data.
Tässä oppaassa rakennetaan kaksi oikeaa sovellusta esimerkeiksi: käyttäjäkohtainen tehtäväsovellus ja julkinen uutiskirjeen tilauslomake. Tiedostorakenne on sama, mutta käyttöoikeusmallit eroavat.
Alla olevissa esimerkeissä käytetään taulukkosyntaksia, koska se on tiiviin. Kaikissa kolmessa PHP-rajapinnassa on kuitenkin myös PHP-natiivivaihtoehdot:
db.phpvoi käyttää kohteitaBlockstudio\\Db\\SchemajaBlockstudio\\Db\\Fieldrpc.phpvoi palauttaa olion, jossa on#[Rpc]-metodejacron.phpvoi palauttaa olion, jossa on#[Cron]-metodeja
Tehtäväsovellus
Käyttäjäkohtainen tehtävienhallinta. Jokainen sisäänkirjautunut käyttäjä näkee vain omat tehtävänsä. Käyttää asetusta userScoped: true käyttäjien automaattiseen eristämiseen, asetusta SQLite siirrettävään tallennukseen, asetusta bs.mutate() optimistisiin päivityksiin sekä reaaliaikaista kyselyä, jotta muutokset näkyvät automaattisesti muissa välilehdissä.
Tiedostorakenne
blockstudio/
todo/
block.json
index.php
script.inline.js
style.css
db.php
rpc.php
cron.php
Lohkon määritys
{
"$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 ottaa käyttöön WordPress-ohjeiden käsittelyn (SSR data-wp-each-, data-wp-bind-ohjeille jne.). interactivity.enqueue lataa @wordpress/interactivity-moduulin frontendissä.
Tietomalli
userScoped: true lisää automaattisesti user_id-sarakkeen, asettaa sen luotaessa ja suodattaa kaikki kyselyt nykyisen käyttäjän mukaan. realtime ottaa käyttöön automaattisen kyselyn, jolloin muutokset muista välilehdistä tai laitteista näkyvät ilman sivun päivittämistä.
<?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-tallennuksessa tietokantatiedosto sijaitsee polussa todo/db/default.sqlite. Kopioi lohkokansio toiselle sivustolle, niin data siirtyy sen mukana.
realtime-määritys käskee asiakasta kyselemään muutoksia 3 sekunnin välein kevyellä hajautusarvovertailulla. Kun data muuttuu, state.todos päivittyy ja UI renderöidään automaattisesti uudelleen.
Mukautettu palvelinlogiikka
Koska userScoped suodattaa tiedot automaattisesti nykyisen käyttäjän mukaan, sisäänrakennettu bs.db().list() palauttaa jo valmiiksi vain nykyisen käyttäjän tietueet. RPC tarvitaan vain CRUD-toimintoja laajempaan käsittelyyn: tehtävän merkitsemiseen ja kaikkien tehtävien poistamiseen.
<?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'],
],
];
Ajastettu siivous
Vanhat valmiit tehtävät siivotaan automaattisesti.
<?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']);
}
}
},
],
];
Mallipohja
PHP lataa alkuperäiset tehtävät palvelinpuolella toiminnon wp_interactivity_state() kautta, jotta data on käytettävissä sekä SSR-ohjeiden käsittelyssä että asiakaspuolen aktivoinnissa. Instanssikohtainen UI-tila (kuten syötekentän arvo) tallennetaan kohteeseen 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>
Keskeiset toimintatavat:
wp_interactivity_state()palvelimelta tulevalle datalle (tehtävät, määrät)data-wp-contextväliaikaiselle UI-tilalle (syötekentän teksti)data-wp-each--todoantaa jokaiselle iteraation alkiolle nimetyn kontekstin (context.todo)state.*viittaa yleiseen tilaan,context.*instanssikohtaiseen dataan
Asiakaspuolen logiikka
bs.mutate() hoitaa kaikki kirjoitukset optimistisilla päivityksillä ja automaattisella palautuksella. UI päivittyy heti; jos palvelinkutsu hylätään, tila palautuu ennalleen. Vahvistus- tai käyttöoikeusvirhe palauttaa virherungon hylkäyksen sijaan, kuten kohdassa Muuta kuvataan.
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',
});
},
},
});
Keskeiset toimintatavat:
bs.mutate()automaattinen tila luontiin, päivitykseen ja poistoon: annastate,key,actionjaoptimisticdata. UI päivittyy heti, palvelinkutsu suoritetaan taustalla ja tila palautetaan virheen sattuessa.bs.mutate()manuaalinen tila arvolleclearDone:before()ottaa tilannevedoksen ja tekee muutoksen,onError()palauttaa tilan vedoksen perusteella.- Generaattorifunktiot (
*addTodo), joissa onyieldasynkronisiin toimintoihin vuorovaikutteisuusAPI-toiminnossa. bs.db()suoraan CRUD-käsittelyyn,bs.fn()mukautettuihin palvelinfunktioihin.
Tyylit
.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
Uutiskirjeen tilaus
Julkinen tilauslomake. Kuka tahansa voi tilata, mutta vain ylläpitäjät voivat tarkastella ja hallita tilaajia. Ei asetusta userScoped eikä todennusta päätoiminnolle. Käyttää MySQL-taulukkotallennusta tuotantokäytössä.
Tiedostorakenne
blockstudio/
newsletter/
block.json
index.php
style.css
script.inline.js
db.php
rpc.php
cron.php
Lohkon määritys
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "my-theme/newsletter",
"title": "Newsletter Signup",
"category": "widgets",
"icon": "email",
"supports": {
"interactivity": true
},
"blockstudio": {
"interactivity": {
"enqueue": true
}
}
}
Tietomalli
Julkinen luonti CSRF-suojauksella. Mukautettu validointi estää kertakäyttöiset sähköpostiosoitteet. Luku- ja poisto-oikeus vain ylläpitäjillä.
<?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" : '') . '.'
);
},
],
];
Mukautettu logiikka
Julkinen tilauksen peruutuspäätepiste (toimii sähköpostilinkkien kautta ilman kirjautumista) ja vain ylläpitäjille näkyvät tilastot:
<?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',
],
];
Ajastettu siivous
<?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']);
}
}
},
],
];
Mallipohja
<?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>
Asiakaspuolen logiikka
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;
},
},
});
Tyylit
.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
Vertailu rinnakkain
| Ominaisuus | Tehtäväsovellus | Uutiskirje |
|---|---|---|
| Todennusmalli | userScoped: true |
Julkinen luonti, ylläpitäjän lukuoikeus |
| Tallennus | SQLite (siirrettävä) | MySQL-taulukko (tuotantokäyttö) |
| Käyttäjäsuodatus | Automaattinen | Ei tarvita |
| CSRF | X-BS-Token kautta |
X-BS-Token kautta |
| Mukautettu RPC | Merkitse valmiiksi, tyhjennä | Peruuta tilaus, tilastot |
| Cron | Poista vanhat valmiit | Poista tilauksen peruneet |
| Validointi | Pituusrajoitukset | Sähköpostin muoto + verkkotunnuksen esto |
| Reaaliaikaisuus | Kysely 3 sekunnin välein | Ei tarvita |
| Optimistiset UI | bs.mutate() automaattinen tila |
Suora bs.db().create() |
| Tila | wp_interactivity_state() |
wp_interactivity_state() + konteksti |
Sama toimintamalli, eri käyttöoikeusmallit. Rakennuspalikat ovat samat: db.php tietomalliin, rpc.php liiketoimintalogiikkaan, cron.php taustatehtäviin, index.php + script.inline.js kohteeseen UI ja style.css ulkoasuun. Jokainen lohko on itsenäinen sovellus.