Lewati ke konten

Membuat Layar Aplikasi dengan UI yang Disertakan

Sebagian besar proyek WordPress pada akhirnya membutuhkan layar yang lebih menyerupai aplikasi daripada halaman: daftar rekaman, tombol untuk membuka formulir, serta umpan balik saat penyimpanan berhasil. Solusi yang umum adalah framework JavaScript, sekumpulan controller REST, dan pustaka komponen, yang semuanya dikelola bersama tema.

Blockstudio sudah menyertakan semua bagian tersebut. db.php menyediakan penyimpanan blok, validasi, dan endpoint CRUD. rpc.php menambahkan aksi server kustom. Komponen UI bawaan menyediakan dialog, kolom formulir, tombol, lencana, dan notifikasi toast. Penyimpanan Interactivity API menghubungkan semuanya. Panduan ini membuat satu layar dari awal hingga akhir dalam satu folder blok:

  • Tabel proyek yang dirender di server dan tetap tersinkron di klien.
  • Dialog Proyek baru dengan formulir yang divalidasi berdasarkan skema.
  • Tombol Arsipkan dan Pulihkan yang memanggil fungsi RPC dengan pembaruan optimistis dan pengembalian ke keadaan sebelumnya.
  • Tombol Hapus yang menggunakan API data secara langsung.
  • Notifikasi toast setelah proyek berhasil dibuat dan notifikasi lain saat perubahan gagal disimpan.

Sebelum memulai

Komponen bawaan bersifat opsional. Aktifkan di blockstudio.json:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "ui": {
    "enabled": true
  }
}

Layar berada dalam satu blok:

Kode
acme/
└── blockstudio/
    └── projects/
        ├── block.json
        ├── db.php
        ├── rpc.php
        ├── index.php
        ├── script.inline.js
        └── style.inline.css

Langkah 1: Model data

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

Setiap operasi memerlukan kapabilitas edit_posts, sehingga endpoint menjawab 401 untuk permintaan pengguna yang belum masuk, dan hanya editor atau peran yang lebih tinggi yang dapat mengubah data. Penyimpanan SQLite menyimpan rekaman di projects/db/default.sqlite, berdampingan dengan kode.

status bertipe required, bukan membawa default. Dengan SQLite dan penyimpanan tabel, skema tidak mengisi nilai yang hilang saat pembuatan, sehingga rekaman yang dibuat tanpa status akan disimpan dengan nilai kosong. Mewajibkan kolom tersebut dan mengirim nilainya dari formulir akan memastikan setiap baris valid.

Tambahkan beberapa rekaman awal dari baris perintah:

Shell
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
Kode
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	...

Daftar ditampilkan dengan yang terbaru lebih dahulu, sesuai urutan yang digunakan tabel.

Langkah 2: Aksi server

Dari sudut pandang pengguna, mengarsipkan bukan sekadar mengubah kolom biasa, jadi tindakan ini diberi fungsi bernama:

PHP
<?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() memvalidasi berdasarkan skema, sehingga enum di db.php tetap memeriksa nilainya. Memanggil fungsi dengan status yang tidak dikenal menghasilkan bentuk kesalahan yang sama dengan API data:

JSON
{"code":"blockstudio_db_validation","message":"Validation failed.","data":{"status":400,"errors":{"status":["Must be one of: active, archived."]}}}

Fungsi ini juga dapat dipanggil dari baris perintah:

Shell
wp bs rpc call acme/projects set_status --id=2 --status=active
Kode
{
    "id": 2,
    "name": "Q3 report",
    "owner": "ben@example.com",
    "status": "active",
    ...
}

Langkah 3: Definisi blok

JSON
{
  "$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 membuat WordPress memproses direktif template di server, sehingga baris tabel dirender sebelum JavaScript apa pun dijalankan.

Langkah 4: Template

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

Ada empat bagian template ini yang perlu dicermati.

Status server menyiapkan tampilan awal. wp_interactivity_state() memberikan rekaman kepada pemroses direktif di sisi server dan penyimpanan klien. Template data-wp-each dikembangkan menjadi baris nyata di server, satu tr untuk setiap rekaman. isArchived adalah closure: WordPress mengevaluasinya untuk setiap baris selama pemrosesan server, dengan wp_interactivity_get_context() mengembalikan konteks baris tersebut, sehingga baris yang diarsipkan menampilkan lencana dan tombol yang tepat sebelum hidrasi. Di browser, getter penyimpanan dengan nama yang sama mengambil alih. hasProjects adalah nilai biasa karena alasan yang sama: tanpanya, server tidak tahu apakah paragraf status kosong perlu disembunyikan.

Dialog dan formulir adalah komponen sistem. trigger_label diteruskan ke bsui/button di dalam pemicu, seperti dijelaskan dalam Komposisi UI. bsui/form bersama block="acme/projects" menserialisasi kolomnya dengan FormData dan mengirimkannya ke endpoint pembuatan blok tersebut. Setiap bsui/field membawa nama inputnya, sehingga kesalahan per kolom dari skema muncul di bawah kontrol yang tepat. Saat formulir kosong dikirim, pesan “Must be at least 2 characters.” muncul di bawah Name dan “Must be a valid email address.” di bawah Owner email, serta “Validation failed.” di bagian bawah formulir. Input status tersembunyi ikut dikirim bersama data formulir, agar proyek baru memenuhi kolom wajib.

Tabel menggunakan markup Anda sendiri. bsui/table cocok untuk baris yang ditulis dalam template: sel headernya mengurutkan dengan memindahkan elemen tr yang sudah ada, sehingga kepemilikan baris oleh data-wp-each akan terganggu. Sebelum versi 7.7 dari Blockstudio, bagian-bagiannya juga menempatkan div langsung di dalam table, thead, tbody, dan tr, lalu browser memindahkannya ke luar tabel. Untuk baris yang berasal dari penyimpanan, tulis sendiri elemen table dan letakkan komponen sistem di dalam sel. Lencana dan tombol dalam template baris adalah tag bsui/badge dan bsui/button biasa. Setiap tombol berada dalam span yang membawa direktif klik, sehingga tombol tetap menjadi tombol sistem sementara aksinya dimiliki penyimpanan Anda.

Toast hanya untuk tampilan. bsui/toast-provider merender region live yang sopan, sementara bsui/toast merender pesan status dengan tombol tutup. Provider tidak memosisikan dirinya di layar, dan tombol tutup tidak menyembunyikan toast yang dirender dari markup. Karena itu, layar menangani keduanya: wrapper dengan position: fixed menempatkan region tersebut, dan setiap toast berada dalam div dengan binding hidden serta handler klik yang dimiliki penyimpanan layar. Klik tombol tutup diteruskan ke div tersebut.

Langkah 5: Penyimpanan

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

Merespons formulir. Setelah penyimpanan berhasil, bsui/form mengirimkan peristiwa formsuccess yang merambat, dapat dibatalkan, dan membawa rekaman yang dibuat dalam event.detail. Penyimpanan yang gagal mengirimkan formerror beserta isi kesalahannya. Listener dipasang pada dokumen (data-wp-on-document--formsuccess), bukan elemen akar layar, karena popup dialog yang terbuka dipindahkan ke document.body sehingga peristiwanya tidak lagi merambat melalui blok. Pemeriksaan owner melewati peristiwa dari formulir lain di halaman yang sama.

Memanggil event.preventDefault() mencegah formulir mengganti kolomnya dengan pesan sukses; formulir tetap direset. Aksi kemudian menambahkan rekaman di awal daftar, menutup dialog menggunakan aksi close dari penyimpanan bsui/dialog, lalu menampilkan toast. close menutup dialog terbuka paling atas dan mengembalikan fokus ke pemicunya, sehingga setelah pembuatan, fokus keyboard kembali ke Proyek baru.

Mengembalikan perubahan saat terjadi kesalahan. bs.mutate() langsung menerapkan perubahan optimistis dan memulihkan nilai sebelumnya saat promise dari fn ditolak. bs.fn() dan bs.db() tidak menolak pada kesalahan HTTP: WP_Error dari fungsi RPC, kegagalan validasi, atau rekaman yang tidak ditemukan semuanya menghasilkan isi kesalahan. Helper ok() mengubah hasil yang memiliki code menjadi penolakan, sehingga baris kembali ke keadaan semula dan toast kegagalan muncul. Tanpanya, pembaruan yang gagal akan menggabungkan isi kesalahan ke dalam baris, sedangkan penghapusan yang gagal akan membuat baris tetap terhapus.

Memberi nama blok. Blockstudio mencetak skrip inline sebagai <script type="module">, sedangkan skrip modul tidak memiliki document.currentScript, jadi bs.fn() tidak dapat mendeteksi blok mana yang memanggil. Berikan nama blok sebagai argumen ketiga, seperti yang dilakukan penyimpanan dengan BLOCK.

Langkah 6: Tempatkan layar di halaman

Halaman berbasis file menempatkan blok menggunakan tag-nya:

JSON
{
  "$schema": "https://blockstudio.dev/schema/page",
  "name": "projects",
  "title": "Projects",
  "slug": "projects",
  "postStatus": "private"
}
PHP
<h1>Projects</h1>
<bs:acme-projects />

Parser mengubah tag tersebut menjadi blok native:

HTML
<!-- wp:heading {"level":1} --><h1 class="wp-block-heading">Projects</h1><!-- /wp:heading --><!-- wp:acme/projects /-->

Jalankan wp bs pages sync untuk membuat halaman. postStatus: "private" menjaganya agar tidak dapat diakses pengunjung anonim, yang hanya akan melihat pesan masuk.

Cara kerja layar saat dijalankan

Saat halaman dibuka sebagai editor:

  1. Tabel ditampilkan dengan kedua baris sudah dirender; baris yang diarsipkan menampilkan lencana Diarsipkan dan tombol Pulihkan.
  2. Proyek baru membuka dialog. Popup dan backdrop dipindahkan ke document.body, fokus berada pada kolom Name, dan Escape atau Batal menutupnya kembali.
  3. Mengirim nilai yang valid akan mengirim satu POST ke /wp-json/blockstudio/v1/db/acme-projects/default. Dialog tertutup, baris baru muncul di paling atas, dan pesan "Project created." tampil di sudut selama empat detik.
  4. Arsipkan langsung mengubah lencana dan mengirim set_status melalui /wp-json/blockstudio/v1/fn/acme/projects/set_status. Jika rekaman sudah dihapus di tempat lain, fungsi mengembalikan kesalahan 404, baris kembali menjadi Aktif, dan pesan "That change was not saved." muncul.
  5. Hapus langsung menghapus baris. Menghapus baris terakhir akan menampilkan "No projects yet."

Gaya

CSS milik layar membaca token pustaka, sehingga tabel selaras dengan komponen di sekitarnya dan mengikuti penggantian tema pada properti --bs-ui-*:

CSS
.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 pada 40 menjaga region toast berada di bawah backdrop dialog, yang berada pada 50. Untuk mengubah tema seluruh layar, ganti token seperti dijelaskan pada bagian gaya; komponen dan tabel akan mengikuti.

Langkah berikutnya

  • Komponen UI: sistem desain, token, dan seluruh rangkaian komponen.
  • Komposisi UI: kelompok komponen, penerusan pemicu, dan model pelapisan di balik dialog.
  • Basis Data: mode penyimpanan, kontrol akses, bs.db(), dan bs.mutate().
  • RPC: kontrol akses, metode HTTP, dan pemanggilan lintas blok.
  • Blok Full-Stack: blok penyusun yang sama dalam aplikasi todo dan pendaftaran buletin.