Μετάβαση στο περιεχόμενο

Μπλοκ πλήρους στοίβας

Το Blockstudio σάς επιτρέπει να δημιουργείτε ολοκληρωμένες εφαρμογές μέσα σε έναν φάκελο μπλοκ. Ένας μόνο κατάλογος μπορεί να περιέχει το UI, τη λογική διακομιστή, το μοντέλο δεδομένων, προγραμματισμένες εργασίες, ακόμα και τα ίδια τα δεδομένα.

Αυτός ο οδηγός δημιουργεί δύο πραγματικές εφαρμογές για να δείξει το μοτίβο: μια εφαρμογή εργασιών ανά χρήστη και μια δημόσια φόρμα εγγραφής σε ενημερωτικό δελτίο. Ίδια δομή αρχείων, διαφορετικά μοντέλα πρόσβασης.

Τα παρακάτω παραδείγματα χρησιμοποιούν τη σύνταξη πίνακα επειδή είναι η πιο σύντομη, αλλά και οι τρεις επιφάνειες PHP έχουν επίσης εναλλακτικές που ακολουθούν την εγγενή σύνταξη του PHP:

  • Το db.php μπορεί να χρησιμοποιεί τα Blockstudio\\Db\\Schema και Blockstudio\\Db\\Field
  • Το rpc.php μπορεί να επιστρέφει ένα αντικείμενο με μεθόδους #[Rpc]
  • Το cron.php μπορεί να επιστρέφει ένα αντικείμενο με μεθόδους #[Cron]

Εφαρμογή εργασιών

Ένας διαχειριστής εργασιών ανά χρήστη. Κάθε συνδεδεμένος χρήστης βλέπει μόνο τις δικές του εργασίες. Χρησιμοποιεί το userScoped: true για αυτόματη απομόνωση χρηστών, το SQLite για φορητή αποθήκευση, το bs.mutate() για αισιόδοξες ενημερώσεις και περιοδικό έλεγχο σε πραγματικό χρόνο, ώστε οι αλλαγές από άλλες καρτέλες να εμφανίζονται αυτόματα.

Δομή αρχείων

Κώδικας
blockstudio/
  todo/
    block.json
    index.php
    script.inline.js
    style.css
    db.php
    rpc.php
    cron.php

Ορισμός μπλοκ

JSON
{
  "$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 ενεργοποιεί την επεξεργασία οδηγιών του WordPress (SSR για data-wp-each, data-wp-bind κ.λπ.). Το interactivity.enqueue φορτώνει τη λειτουργική μονάδα @wordpress/interactivity στο frontend.

Μοντέλο δεδομένων

Το userScoped: true προσθέτει αυτόματα μια στήλη user_id, ορίζει την τιμή της κατά τη δημιουργία και φιλτράρει όλα τα ερωτήματα για τον τρέχοντα χρήστη. Το realtime ενεργοποιεί τον αυτόματο περιοδικό έλεγχο, ώστε οι αλλαγές από άλλες καρτέλες ή συσκευές να εμφανίζονται χωρίς ανανέωση της σελίδας.

PHP
<?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, το αρχείο της βάσης δεδομένων βρίσκεται στο todo/db/default.sqlite. Αντιγράψτε τον φάκελο του μπλοκ σε έναν άλλο ιστότοπο και τα δεδομένα μεταφέρονται μαζί του.

Η ρύθμιση realtime ενημερώνει τον πελάτη να ελέγχει για αλλαγές κάθε 3 δευτερόλεπτα, χρησιμοποιώντας μια ελαφριά σύγκριση κατακερματισμού. Όταν αλλάζουν τα δεδομένα, ενημερώνεται το state.todos και το UI αποδίδεται ξανά αυτόματα.

Προσαρμοσμένη λογική διακομιστή

Επειδή το userScoped φιλτράρει αυτόματα με βάση τον τρέχοντα χρήστη, το ενσωματωμένο bs.db().list() επιστρέφει ήδη μόνο τις εγγραφές του. Το RPC χρειάζεται μόνο για λειτουργίες πέρα από το CRUD: εναλλαγή κατάστασης και μαζική διαγραφή.

PHP
<?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'],
    ],
];

Προγραμματισμένη εκκαθάριση

Οι παλιές ολοκληρωμένες εργασίες εκκαθαρίζονται αυτόματα.

PHP
<?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']);
                }
            }
        },
    ],
];

Πρότυπο

Το PHP φορτώνει τις αρχικές εργασίες από την πλευρά του διακομιστή μέσω του wp_interactivity_state(), το οποίο παρέχει τα δεδομένα τόσο για την επεξεργασία οδηγιών SSR όσο και για την ενυδάτωση στην πλευρά του πελάτη. Η κατάσταση UI ανά στιγμιότυπο (όπως η τιμή του πεδίου εισαγωγής) ανήκει στο data-wp-context.

PHP
<?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"
                >&times;</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>

Βασικά μοτίβα:

  • Το wp_interactivity_state() για δεδομένα που προέρχονται από τον διακομιστή (εργασίες, μετρήσεις)
  • Το data-wp-context για εφήμερη κατάσταση UI (κείμενο εισαγωγής)
  • Το data-wp-each--todo παρέχει σε κάθε στοιχείο επανάληψης ένα ονομασμένο πλαίσιο (context.todo)
  • Το state.* αναφέρεται στο καθολικό store, ενώ το context.* στα δεδομένα ανά στιγμιότυπο

Λογική πελάτη

Το bs.mutate() χειρίζεται όλες τις εγγραφές με αισιόδοξες ενημερώσεις και αυτόματη επαναφορά. Το UI ενημερώνεται αμέσως· αν η κλήση διακομιστή απορριφθεί, η κατάσταση επανέρχεται. Ένα σφάλμα επικύρωσης ή δικαιωμάτων επιστρέφει σώμα απόκρισης με σφάλμα αντί να απορρίψει την κλήση, όπως περιγράφεται στην ενότητα Μεταβολή.

JavaScript
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',
            });
        },
    },
});

Βασικά μοτίβα:

  • Το bs.mutate() σε αυτόματη λειτουργία για δημιουργία/ενημέρωση/διαγραφή: περάστε τα δεδομένα state, key, action και optimistic. Το UI ενημερώνεται αμέσως, η κλήση διακομιστή εκτελείται στο παρασκήνιο και η κατάσταση επανέρχεται σε περίπτωση αποτυχίας.
  • Το bs.mutate() σε χειροκίνητη λειτουργία για clearDone: το before() αποθηκεύει ένα στιγμιότυπο και εφαρμόζει την αλλαγή, ενώ το onError() επαναφέρει το στιγμιότυπο.
  • Συναρτήσεις γεννήτριας (*addTodo) με yield για ασύγχρονες λειτουργίες στο API διαδραστικότητας.
  • Το bs.db() για άμεσο CRUD, το bs.fn() για προσαρμοσμένες συναρτήσεις διακομιστή.

Στυλ

CSS
.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

Εγγραφή στο ενημερωτικό δελτίο

Μια δημόσια φόρμα εγγραφής. Οποιοσδήποτε μπορεί να εγγραφεί, αλλά μόνο οι διαχειριστές μπορούν να βλέπουν και να διαχειρίζονται τους συνδρομητές. Χωρίς userScoped, χωρίς έλεγχο ταυτότητας για την κύρια ενέργεια. Χρησιμοποιεί αποθήκευση σε πίνακα MySQL για χρήση σε περιβάλλον παραγωγής.

Δομή αρχείων

Κώδικας
blockstudio/
  newsletter/
    block.json
    index.php
    style.css
    script.inline.js
    db.php
    rpc.php
    cron.php

Ορισμός μπλοκ

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "my-theme/newsletter",
  "title": "Newsletter Signup",
  "category": "widgets",
  "icon": "email",
  "supports": {
    "interactivity": true
  },
  "blockstudio": {
    "interactivity": {
      "enqueue": true
    }
  }
}

Μοντέλο δεδομένων

Δημόσια δημιουργία με προστασία CSRF. Η προσαρμοσμένη επικύρωση αποκλείει προσωρινές διευθύνσεις email. Μόνο οι διαχειριστές μπορούν να διαβάζουν και να διαγράφουν.

PHP
<?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" : '') . '.'
            );
        },
    ],
];

Προσαρμοσμένη λογική

Ένα δημόσιο endpoint διαγραφής εγγραφής (λειτουργεί μέσω συνδέσμων σε email χωρίς σύνδεση) και στατιστικά μόνο για διαχειριστές:

PHP
<?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',
    ],
];

Προγραμματισμένη εκκαθάριση

PHP
<?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']);
                }
            }
        },
    ],
];

Πρότυπο

PHP
<?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>

Λογική πελάτη

JavaScript
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;
        },
    },
});

Στυλ

CSS
.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

Σύγκριση δίπλα-δίπλα

Πτυχή Εφαρμογή εργασιών Ενημερωτικό δελτίο
Μοντέλο ελέγχου ταυτότητας userScoped: true Δημόσια δημιουργία, ανάγνωση από διαχειριστή
Αποθήκευση SQLite (φορητή) Πίνακας MySQL (παραγωγή)
Φιλτράρισμα χρηστών Αυτόματο Δεν χρειάζεται
CSRF Μέσω του X-BS-Token Μέσω του X-BS-Token
Προσαρμοσμένο RPC Εναλλαγή, εκκαθάριση ολοκληρωμένων Διαγραφή εγγραφής, στατιστικά
Cron Διαγραφή παλιών ολοκληρωμένων Αφαίρεση όσων διαγράφηκαν
Επικύρωση Περιορισμοί μήκους Μορφή email + αποκλεισμός τομέα
Ενημέρωση σε πραγματικό χρόνο Έλεγχος κάθε 3 δευτερόλεπτα Δεν χρειάζεται
Αισιόδοξο UI Αυτόματη λειτουργία bs.mutate() Άμεσο bs.db().create()
Κατάσταση wp_interactivity_state() wp_interactivity_state() + πλαίσιο

Ίδιο μοτίβο, διαφορετικά μοντέλα πρόσβασης. Τα δομικά στοιχεία είναι ίδια: db.php για το μοντέλο δεδομένων, rpc.php για την επιχειρηματική λογική, cron.php για εργασίες παρασκηνίου, index.php + script.inline.js για το UI, style.css για την εμφάνιση. Κάθε μπλοκ είναι μια αυτοτελής εφαρμογή.