Δημιουργία οθόνης εφαρμογής με το ενσωματωμένο UI
Τα περισσότερα έργα WordPress χρειάζονται τελικά μια οθόνη που θυμίζει περισσότερο εφαρμογή παρά σελίδα: μια λίστα εγγραφών, ένα κουμπί που ανοίγει μια φόρμα και ενημέρωση όταν ολοκληρωθεί η αποθήκευση. Η συνηθισμένη λύση είναι ένα framework JavaScript, ένα σύνολο ελεγκτών REST και μια βιβλιοθήκη στοιχείων, που συντηρούνται όλα δίπλα στο θέμα.
Το Blockstudio παρέχει ήδη όλα αυτά τα μέρη. Το db.php προσφέρει αποθήκευση block, επικύρωση και endpoint CRUD. Το rpc.php προσθέτει προσαρμοσμένες ενέργειες διακομιστή. Τα ενσωματωμένα στοιχεία UI παρέχουν το παράθυρο διαλόγου, τα πεδία φόρμας, τα κουμπιά, τα σήματα και τις ειδοποιήσεις toast. Ένα store Interactivity API τα συνδέει. Αυτός ο οδηγός δημιουργεί μια ολόκληρη οθόνη, από την αρχή έως το τέλος, μέσα σε έναν φάκελο block:
- Ένας πίνακας έργων, που αποδίδεται στον διακομιστή και συγχρονίζεται στον πελάτη.
- Ένα παράθυρο διαλόγου Νέο έργο με φόρμα που επικυρώνεται βάσει του σχήματος.
- Κουμπιά Αρχειοθέτηση και Επαναφορά που καλούν μια συνάρτηση RPC με αισιόδοξη ενημέρωση και επαναφορά.
- Κουμπιά Διαγραφή που χρησιμοποιούν απευθείας το δεδομένων API.
- Μια ειδοποίηση toast μετά την επιτυχή δημιουργία και άλλη μία όταν δεν αποθηκεύεται μια αλλαγή.
Πριν ξεκινήσετε
Τα ενσωματωμένα στοιχεία είναι προαιρετικά. Ενεργοποιήστε τα στο blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"ui": {
"enabled": true
}
}
Η οθόνη βρίσκεται σε ένα block:
acme/
└── blockstudio/
└── projects/
├── block.json
├── db.php
├── rpc.php
├── index.php
├── script.inline.js
└── style.inline.css
Βήμα 1: Το μοντέλο δεδομένων
<?php
return [
'storage' => 'sqlite',
'capability' => [
'create' => 'edit_posts',
'read' => 'edit_posts',
'update' => 'edit_posts',
'delete' => 'edit_posts',
],
'fields' => [
'name' => [
'type' => 'string',
'required' => true,
'minLength' => 2,
'maxLength' => 80,
],
'owner' => [
'type' => 'string',
'format' => 'email',
'required' => true,
],
'status' => [
'type' => 'string',
'enum' => ['active', 'archived'],
'required' => true,
],
],
];
Κάθε λειτουργία απαιτεί τη δυνατότητα edit_posts, επομένως τα endpoint απαντούν με 401 σε αιτήματα αποσυνδεδεμένων χρηστών και μόνο οι συντάκτες και οι ανώτεροι ρόλοι μπορούν να αλλάξουν δεδομένα. Η αποθήκευση SQLite διατηρεί τις εγγραφές στο projects/db/default.sqlite, δίπλα στον κώδικα.
Το status είναι required αντί να έχει ένα default. Με SQLite και αποθήκευση σε πίνακα, το σχήμα δεν συμπληρώνει μια τιμή που λείπει κατά τη δημιουργία. Έτσι, μια εγγραφή που δημιουργείται χωρίς status αποθηκεύεται με κενή τιμή. Αν ορίσετε το πεδίο ως υποχρεωτικό και το στείλετε από τη φόρμα, κάθε γραμμή παραμένει έγκυρη.
Προσθέστε μερικές εγγραφές από τη γραμμή εντολών:
wp bs db create acme/projects --name="Website relaunch" --owner=ana@example.com --status=active
wp bs db create acme/projects --name="Q3 report" --owner=ben@example.com --status=archived
wp bs db list acme/projects
Success: Record created (ID: 1).
Success: Record created (ID: 2).
id name owner status created_at updated_at
2 Q3 report ben@example.com archived ...
1 Website relaunch ana@example.com active ...
Η λίστα επιστρέφεται με πρώτα τα νεότερα, όπως ακριβώς εμφανίζονται στον πίνακα.
Βήμα 2: Μια ενέργεια διακομιστή
Η αρχειοθέτηση δεν είναι μια απλή αλλαγή πεδίου από τη σκοπιά του χρήστη, γι’ αυτό ορίζεται ως επώνυμη συνάρτηση:
<?php
use Blockstudio\Db;
return [
'set_status' => [
'callback' => function (array $params) {
$id = (int) ($params['id'] ?? 0);
$status = (string) ($params['status'] ?? '');
$db = Db::get('acme/projects');
if (!$db->get_record($id)) {
return new \WP_Error('not_found', 'Project not found.', ['status' => 404]);
}
return $db->update($id, ['status' => $status]);
},
'capability' => 'edit_posts',
],
];
Το Db::update() επικυρώνει βάσει του σχήματος, επομένως το enum στο db.php εξακολουθεί να προστατεύει την τιμή. Αν καλέσετε τη συνάρτηση με άγνωστη κατάσταση, επιστρέφεται η ίδια μορφή σφάλματος με εκείνη του δεδομένων API:
{"code":"blockstudio_db_validation","message":"Validation failed.","data":{"status":400,"errors":{"status":["Must be one of: active, archived."]}}}
Η συνάρτηση μπορεί να κληθεί και από τη γραμμή εντολών:
wp bs rpc call acme/projects set_status --id=2 --status=active
{
"id": 2,
"name": "Q3 report",
"owner": "ben@example.com",
"status": "active",
...
}
Βήμα 3: Ο ορισμός του block
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/projects",
"title": "Projects",
"category": "widgets",
"icon": "list-view",
"supports": {
"interactivity": true
},
"blockstudio": {
"interactivity": {
"enqueue": true
}
}
}
Το supports.interactivity κάνει το WordPress να επεξεργάζεται τις οδηγίες του προτύπου στον διακομιστή, ώστε οι γραμμές του πίνακα να αποδίδονται πριν εκτελεστεί οποιοδήποτε JavaScript.
Βήμα 4: Το πρότυπο
<?php
$can_edit = current_user_can('edit_posts');
$projects = $can_edit ? \Blockstudio\Db::get('acme/projects')->list() : [];
wp_interactivity_state('acme/projects', [
'projects' => array_values($projects),
'hasProjects' => !empty($projects),
'notice' => '',
'isArchived' => function () {
$context = wp_interactivity_get_context();
return 'archived' === ($context['project']['status'] ?? '');
},
]);
?>
<div
useBlockProps
class="projects"
data-wp-interactive="acme/projects"
data-wp-on-document--formsuccess="actions.created"
>
<?php if (!$can_edit) : ?>
<p>Sign in with an editor account to manage projects.</p>
<?php else : ?>
<div class="projects__bar">
<bs:bsui-text content="Projects" variant="title" tag="h2" />
<bs:bsui-dialog>
<bs:bsui-dialog-trigger trigger_label="New project" />
<bs:bsui-dialog-backdrop />
<bs:bsui-dialog-popup>
<bs:bsui-dialog-header>
<bs:bsui-dialog-title content="New project" />
<bs:bsui-dialog-description content="Projects start out active." />
</bs:bsui-dialog-header>
<bs:bsui-dialog-content>
<bs:bsui-form block="acme/projects">
<bs:bsui-field name="name">
<bs:bsui-field-label text="Name" />
<bs:bsui-input name="name" placeholder="Spring campaign" required="true" />
<bs:bsui-field-error />
</bs:bsui-field>
<bs:bsui-field name="owner">
<bs:bsui-field-label text="Owner email" />
<bs:bsui-input name="owner" type="email" placeholder="owner@example.com" required="true" />
<bs:bsui-field-error />
</bs:bsui-field>
<input type="hidden" name="status" value="active" />
<bs:bsui-space size="2" />
<bs:bsui-button label="Create project" />
</bs:bsui-form>
</bs:bsui-dialog-content>
<bs:bsui-dialog-footer>
<bs:bsui-dialog-close label="Cancel" />
</bs:bsui-dialog-footer>
</bs:bsui-dialog-popup>
</bs:bsui-dialog>
</div>
<table class="projects__table">
<thead>
<tr>
<th scope="col">Name</th>
<th scope="col">Owner</th>
<th scope="col">Status</th>
<th scope="col">Actions</th>
</tr>
</thead>
<tbody>
<template data-wp-each--project="state.projects" data-wp-each-key="context.project.id">
<tr>
<td data-wp-text="context.project.name"></td>
<td data-wp-text="context.project.owner"></td>
<td>
<span data-wp-bind--hidden="state.isArchived"><bs:bsui-badge label="Active" variant="success" /></span>
<span data-wp-bind--hidden="!state.isArchived"><bs:bsui-badge label="Archived" variant="secondary" /></span>
</td>
<td class="projects__actions">
<span data-wp-on--click="actions.toggleArchived">
<span data-wp-bind--hidden="state.isArchived"><bs:bsui-button label="Archive" variant="outline" size="sm" /></span>
<span data-wp-bind--hidden="!state.isArchived"><bs:bsui-button label="Restore" variant="outline" size="sm" /></span>
</span>
<span data-wp-on--click="actions.remove"><bs:bsui-button label="Delete" variant="ghost" size="sm" /></span>
</td>
</tr>
</template>
</tbody>
</table>
<p class="projects__empty" data-wp-bind--hidden="state.hasProjects">No projects yet.</p>
<div class="projects__toasts">
<bs:bsui-toast-provider>
<div data-wp-interactive="acme/projects" data-wp-bind--hidden="!state.isCreatedNotice" data-wp-on--click="actions.dismissNotice">
<bs:bsui-toast message="Project created." />
</div>
<div data-wp-interactive="acme/projects" data-wp-bind--hidden="!state.isFailedNotice" data-wp-on--click="actions.dismissNotice">
<bs:bsui-toast message="That change was not saved." />
</div>
</bs:bsui-toast-provider>
</div>
<?php endif; ?>
</div>
Τέσσερα σημεία αυτού του προτύπου αξίζουν μια πιο προσεκτική ματιά.
Η κατάσταση διακομιστή προετοιμάζει την αρχική εμφάνιση. Το wp_interactivity_state() μεταβιβάζει τις εγγραφές τόσο στον επεξεργαστή οδηγιών του διακομιστή όσο και στο store του πελάτη. Το πρότυπο data-wp-each επεκτείνεται σε πραγματικές γραμμές στον διακομιστή, μία tr ανά εγγραφή. Το isArchived είναι closure: το WordPress το αξιολογεί για κάθε γραμμή κατά την επεξεργασία στον διακομιστή, με το wp_interactivity_get_context() να επιστρέφει το περιβάλλον της συγκεκριμένης γραμμής. Έτσι, οι αρχειοθετημένες γραμμές εμφανίζουν το σωστό σήμα και κουμπί πριν από την ενυδάτωση. Στο πρόγραμμα περιήγησης, τη θέση του αναλαμβάνει η getter του store με το ίδιο όνομα. Το hasProjects είναι απλή τιμή για τον ίδιο λόγο: χωρίς αυτό, ο διακομιστής δεν θα ήξερε αν πρέπει να κρύψει την παράγραφο κενής κατάστασης.
Το παράθυρο διαλόγου και η φόρμα είναι στοιχεία συστήματος. Το trigger_label προωθείται στο bsui/button μέσα στο trigger, όπως περιγράφεται στη Σύνθεση UI. Το bsui/form μαζί με το block="acme/projects" σειριοποιεί τα πεδία του με το FormData και τα στέλνει στο endpoint δημιουργίας του block. Κάθε bsui/field φέρει το όνομα της εισόδου του, ώστε τα σφάλματα ανά πεδίο από το σχήμα να εμφανίζονται κάτω από το σωστό στοιχείο ελέγχου. Αν υποβάλετε κενή φόρμα, κάτω από το Όνομα εμφανίζεται το «Πρέπει να έχει τουλάχιστον 2 χαρακτήρες.» και κάτω από το Email ιδιοκτήτη το «Πρέπει να είναι έγκυρη διεύθυνση email.», ενώ στο κάτω μέρος της φόρμας εμφανίζεται το «Η επικύρωση απέτυχε.». Το κρυφό πεδίο εισόδου status αποστέλλεται μαζί με τα δεδομένα της φόρμας και επιτρέπει στα νέα έργα να ικανοποιούν το υποχρεωτικό πεδίο.
Ο πίνακας είναι δική σας σήμανση. Το bsui/table είναι κατάλληλο για γραμμές που έχουν γραφτεί στο πρότυπο: οι κεφαλίδες του ταξινομούν μετακινώντας τα υπάρχοντα στοιχεία tr, κάτι που θα συγκρουόταν με το data-wp-each για τον έλεγχο των γραμμών. Πριν από την έκδοση Blockstudio 7.7, τα μέρη του τοποθετούσαν επίσης ένα div απευθείας μέσα σε table, thead, tbody και tr, οπότε τα προγράμματα περιήγησης το μετέφεραν έξω από τον πίνακα. Για γραμμές που προέρχονται από store, γράψτε μόνοι σας το στοιχείο table και τοποθετήστε τα στοιχεία συστήματος μέσα στα κελιά. Τα σήματα και τα κουμπιά στο πρότυπο γραμμής είναι συνηθισμένες ετικέτες bsui/badge και bsui/button. Κάθε κουμπί βρίσκεται μέσα σε ένα span που φέρει την οδηγία click, ώστε το κουμπί να παραμένει κουμπί συστήματος και η ενέργεια να ανήκει στο store σας.
Το toast είναι στοιχείο παρουσίασης. Το bsui/toast-provider αποδίδει μια ευγενική ζωντανή περιοχή και το bsui/toast αποδίδει ένα μήνυμα κατάστασης με κουμπί απόρριψης. Ο provider δεν τοποθετείται μόνος του στην οθόνη και το κουμπί απόρριψης δεν κρύβει ένα toast που αποδόθηκε από τη σήμανση. Επομένως, η οθόνη κάνει και τα δύο: ένα wrapper με position: fixed τοποθετεί την περιοχή και κάθε toast βρίσκεται σε ένα div, του οποίου η σύνδεση hidden και ο χειριστής click ανήκουν στο store της οθόνης. Το click στο κουμπί απόρριψης διαδίδεται προς αυτό το div.
Βήμα 5: Το store
import { store, getContext } from '@wordpress/interactivity';
const BLOCK = 'acme/projects';
let noticeTimer;
// bs.fn() and bs.db() resolve with the error body on a failed request.
// Throwing here is what lets bs.mutate() roll the optimistic change back.
const ok = (request) =>
request.then((result) => {
if (result?.code) {
throw result;
}
return result;
});
const notify = (notice) => {
state.notice = notice;
clearTimeout(noticeTimer);
noticeTimer = setTimeout(() => {
state.notice = '';
}, 4000);
};
const { state } = store(BLOCK, {
state: {
get hasProjects() {
return state.projects.length > 0;
},
get isArchived() {
return getContext().project.status === 'archived';
},
get isCreatedNotice() {
return state.notice === 'created';
},
get isFailedNotice() {
return state.notice === 'failed';
},
},
actions: {
created(event) {
const record = event.detail;
if (!record?.id || !('owner' in record)) {
return;
}
event.preventDefault();
state.projects = [record, ...state.projects];
store('bsui/dialog').actions.close();
notify('created');
},
dismissNotice() {
state.notice = '';
},
*toggleArchived() {
const project = getContext().project;
const status = project.status === 'archived' ? 'active' : 'archived';
try {
yield bs.mutate({
fn: () => ok(bs.fn('set_status', { id: project.id, status }, BLOCK)),
state,
key: 'projects',
action: 'update',
id: project.id,
optimistic: { status },
});
} catch (error) {
notify('failed');
}
},
*remove() {
const project = getContext().project;
try {
yield bs.mutate({
fn: () => ok(bs.db(BLOCK).delete(project.id)),
state,
key: 'projects',
action: 'delete',
id: project.id,
});
} catch (error) {
notify('failed');
}
},
},
});
Αντίδραση στη φόρμα. Μετά την επιτυχή αποθήκευση, το bsui/form αποστέλλει ένα συμβάν formsuccess που διαδίδεται, μπορεί να ακυρωθεί και περιέχει την εγγραφή που δημιουργήθηκε στο event.detail. Αν η αποθήκευση αποτύχει, αποστέλλεται το formerror με το σώμα του σφάλματος. Ο ακροατής βρίσκεται στο έγγραφο (data-wp-on-document--formsuccess) και όχι στο ριζικό στοιχείο της οθόνης, επειδή ένα αναδυόμενο παράθυρο ανοιχτού διαλόγου μεταφέρεται στο document.body και τα συμβάντά του παύουν να διαδίδονται μέσα από το block. Ο έλεγχος owner παραλείπει συμβάντα από άλλες φόρμες στην ίδια σελίδα.
Η κλήση του event.preventDefault() εμποδίζει τη φόρμα να αντικαταστήσει τα πεδία της με μήνυμα επιτυχίας· η φόρμα εξακολουθεί να επαναφέρεται. Στη συνέχεια, η ενέργεια προσθέτει την εγγραφή στην αρχή, κλείνει το παράθυρο διαλόγου με την ενέργεια close του store bsui/dialog και εμφανίζει την ειδοποίηση toast. Το close κλείνει το ανώτερο ανοιχτό παράθυρο διαλόγου και επαναφέρει την εστίαση στο trigger του, οπότε μετά τη δημιουργία η εστίαση του πληκτρολογίου επιστρέφει στο Νέο έργο.
Επαναφορά σε περίπτωση σφαλμάτων. Το bs.mutate() εφαρμόζει αμέσως την αισιόδοξη αλλαγή και επαναφέρει τις προηγούμενες τιμές όταν απορριφθεί το promise από το fn. Τα bs.fn() και bs.db() δεν απορρίπτουν promise σε περίπτωση σφαλμάτων HTTP: ένα WP_Error από τη συνάρτηση RPC, αποτυχία επικύρωσης ή ανύπαρκτη εγγραφή επιστρέφουν κανονικά με το σώμα του σφάλματος. Το βοηθητικό ok() μετατρέπει ένα αποτέλεσμα με code σε απόρριψη, οπότε η γραμμή επανέρχεται και εμφανίζεται η ειδοποίηση αποτυχίας. Χωρίς αυτό, μια αποτυχημένη ενημέρωση θα συγχώνευε το σώμα του σφάλματος στη γραμμή και μια αποτυχημένη διαγραφή θα άφηνε τη γραμμή αφαιρεμένη.
Ονομασία του block. Το Blockstudio εκτυπώνει τα inline scripts ως <script type="module"> και τα module scripts δεν έχουν document.currentScript, επομένως το bs.fn() δεν μπορεί να εντοπίσει ποιο block καλεί τη συνάρτηση. Περάστε το όνομα του block ως τρίτο όρισμα, όπως κάνει το store με το BLOCK.
Βήμα 6: Προσθήκη της οθόνης σε σελίδα
Μια σελίδα βάσει αρχείου τοποθετεί το block με την ετικέτα του:
{
"$schema": "https://blockstudio.dev/schema/page",
"name": "projects",
"title": "Projects",
"slug": "projects",
"postStatus": "private"
}
<h1>Projects</h1>
<bs:acme-projects />
Ο parser μετατρέπει την ετικέτα σε εγγενές block:
<!-- wp:heading {"level":1} --><h1 class="wp-block-heading">Projects</h1><!-- /wp:heading --><!-- wp:acme/projects /-->
Εκτελέστε το wp bs pages sync για να δημιουργήσετε τη σελίδα. Το postStatus: "private" δεν την εμφανίζει σε ανώνυμους επισκέπτες, οι οποίοι ούτως ή άλλως θα έβλεπαν μόνο το μήνυμα σύνδεσης.
Τι κάνει η οθόνη κατά την εκτέλεση
Με ανοιχτή τη σελίδα ως συντάκτης:
- Ο πίνακας εμφανίζεται με αποδομένες και τις δύο γραμμές· η αρχειοθετημένη γραμμή έχει το σήμα Αρχειοθετημένο και ένα κουμπί Επαναφορά.
- Το Νέο έργο ανοίγει το παράθυρο διαλόγου. Το αναδυόμενο παράθυρο και το φόντο μεταφέρονται στο
document.body, η εστίαση πηγαίνει στο πεδίο Όνομα και το Escape ή το Ακύρωση το κλείνει. - Η υποβολή έγκυρων τιμών στέλνει ένα
POSTστο/wp-json/blockstudio/v1/db/acme-projects/default. Το παράθυρο διαλόγου κλείνει, η νέα γραμμή εμφανίζεται στην κορυφή και για τέσσερα δευτερόλεπτα εμφανίζεται στη γωνία το «Το έργο δημιουργήθηκε.». - Η Αρχειοθέτηση αλλάζει αμέσως το σήμα και στέλνει το
set_statusμέσω του/wp-json/blockstudio/v1/fn/acme/projects/set_status. Αν στο μεταξύ διαγράφηκε η εγγραφή αλλού, η συνάρτηση επιστρέφει το σφάλμα404, η γραμμή επανέρχεται στην κατάσταση Ενεργό και εμφανίζεται το «Η αλλαγή δεν αποθηκεύτηκε.». - Η Διαγραφή αφαιρεί αμέσως τη γραμμή. Αν διαγράψετε και την τελευταία, εμφανίζεται το «Δεν υπάρχουν ακόμη έργα.».
Μορφοποίηση
Το CSS της οθόνης χρησιμοποιεί τα tokens της βιβλιοθήκης, ώστε ο πίνακας να ταιριάζει με τα γύρω στοιχεία και να ακολουθεί τυχόν παράκαμψη θέματος των ιδιοτήτων --bs-ui-*:
.projects__table {
width: 100%;
border-collapse: collapse;
font-size: var(--bs-ui-font-size);
}
.projects__table th,
.projects__table td {
padding: var(--bs-ui-space-2) var(--bs-ui-space-3);
border-bottom: 1px solid var(--bs-ui-border);
text-align: left;
}
/* ... */
.projects__toasts {
position: fixed;
right: var(--bs-ui-space-4);
bottom: var(--bs-ui-space-4);
z-index: 40;
}
Το z-index του 40 διατηρεί την περιοχή toast κάτω από το φόντο του παραθύρου διαλόγου, το οποίο βρίσκεται στο 50. Για να αλλάξετε το θέμα ολόκληρης της οθόνης, παρακάμψτε τα tokens όπως περιγράφεται στην ενότητα μορφοποίησης· τα στοιχεία και ο πίνακας θα ακολουθήσουν.
Επόμενα βήματα
- Στοιχεία UI: το σύστημα σχεδίασης, τα tokens και το πλήρες σύνολο στοιχείων.
- Σύνθεση UI: οικογένειες σύνθετων στοιχείων, προώθηση trigger και το μοντέλο επιπέδων πίσω από το παράθυρο διαλόγου.
- Βάση δεδομένων: τρόποι αποθήκευσης, έλεγχος πρόσβασης,
bs.db()καιbs.mutate(). - RPC: έλεγχος πρόσβασης, μέθοδοι HTTP και κλήσεις μεταξύ block.
- Full-Stack Blocks: τα ίδια δομικά στοιχεία σε μια εφαρμογή εργασιών και σε μια εγγραφή σε ενημερωτικό δελτίο.