コンテンツへスキップ

バンドルされたUIでアプリ画面を構築する

多くのWordPressプロジェクトでは、いずれページというよりアプリに近い画面が必要になります。レコードの一覧、フォームを開くボタン、保存完了時のフィードバックなどです。一般的には、JavaScriptフレームワーク、RESTコントローラー一式、コンポーネントライブラリを用意し、テーマと並行して保守します。

Blockstudioには、これらすべての要素がすでに含まれています。db.phpはブロックのストレージ、バリデーション、CRUDエンドポイントを提供します。rpc.phpはカスタムサーバーアクションを追加します。バンドルされたUIコンポーネントには、ダイアログ、フォームフィールド、ボタン、バッジ、トーストが含まれています。Interactivity APIストアでそれらを連携させます。このガイドでは、1つのブロックフォルダーだけを使って、画面を最初から最後まで構築します。

  • サーバーでレンダリングされ、クライアント側と同期されるプロジェクト一覧テーブル。
  • スキーマに沿って入力を検証するフォーム付きの新しいプロジェクトダイアログ。
  • 楽観的更新とロールバックを伴い、RPC関数を呼び出すアーカイブボタンと復元ボタン。
  • データAPIを直接使う削除ボタン。
  • 作成成功時と変更を保存できなかった時に表示するトースト。

始める前に

バンドルされたコンポーネントは、オプトイン方式です。blockstudio.jsonで有効にしてください。

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

画面は1つのブロックに配置します。

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

ステップ1:データモデル

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

すべての操作でedit_posts権限が必要なため、ログアウト状態でのリクエストにはエンドポイントが401を返し、データを変更できるのは編集者以上に限られます。SQLiteストレージではレコードがコードの隣にあるprojects/db/default.sqliteに保存されます。

statusはrequiredであり、defaultを持ちません。SQLiteとテーブルストレージでは、作成時にスキーマが欠落値を補わないため、statusなしで作成されたレコードには空の値が保存されます。このフィールドを必須にしてフォームから値を送信すれば、すべての行が有効な状態に保たれます。

コマンドラインからレコードを2件ほど登録します。

シェル
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
<?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()はスキーマに照らして検証するため、db.php内のenumで引き続き値をチェックします。不明なステータスを指定して関数を呼び出すと、データAPIと同じ形式のエラーが返されます。

JSON
{"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:ブロック定義

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を使うと、WordPressがサーバー上でテンプレートのディレクティブを処理します。これにより、JavaScriptが実行される前にテーブルの行がレンダリングされます。

ステップ4:テンプレート

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>

このテンプレートには、詳しく見ておきたい点が4つあります。

サーバー状態で初回表示を準備します。 wp_interactivity_state()はレコードをサーバー側のディレクティブ処理とクライアントストアの両方に渡します。data-wp-eachテンプレートはサーバー上で実際の行に展開され、レコードごとにtrが1つ生成されます。isArchivedはクロージャーです。WordPressがサーバー処理中に各行に対して評価し、wp_interactivity_get_context()でその行のコンテキストを返すため、ハイドレーション前からアーカイブ済みの行には正しいバッジとボタンが表示されます。ブラウザーでは、同じ名前のストアゲッターが引き継ぎます。hasProjectsも同じ理由で単純な値です。これがないと、サーバーは空状態の段落を隠すべきか判断できません。

ダイアログとフォームにはシステムコンポーネントを使います。 trigger_labelはトリガー内のbsui/buttonに転送されます。詳しくはUIの合成を参照してください。bsui/formとblock="acme/projects"を使うと、フィールドがFormDataでシリアライズされ、このブロックの作成エンドポイントに送信されます。各bsui/fieldには入力名が指定されているため、スキーマから返されるフィールドごとのエラーが対応するコントロールの下に表示されます。空のフォームを送信すると、Nameの下に「2文字以上で入力してください。」、Owner emailの下に「有効なメールアドレスを入力してください。」と表示され、フォームの下部には「検証に失敗しました。」と表示されます。非表示のstatus入力もフォームデータとともに送信され、新しいプロジェクトが必須フィールドを満たせるようになります。

テーブルには独自のマークアップを使います。 bsui/tableはテンプレート内に記述した行に適しています。ヘッダーセルは既存のtr要素を並べ替えてソートするため、行の管理権限をdata-wp-eachと競合します。Blockstudio 7.7より前のバージョンでは、各パーツがtable、thead、tbody、trの直下にdivも配置しており、ブラウザーがそれをテーブルの外に移動させていました。ストアから生成する行では、table要素を自分で記述し、システムコンポーネントはセルの中に配置してください。行テンプレート内のバッジとボタンには通常のbsui/badgeタグとbsui/buttonタグを使います。各ボタンはクリックディレクティブを持つspan内に置くため、ボタンはシステムボタンのまま、アクションはストア側で管理できます。

トーストは表示専用です。 bsui/toast-providerはポライトなライブリージョンを、bsui/toastは閉じるボタン付きのステータスメッセージを描画します。プロバイダーは画面上の位置を調整せず、閉じるボタンもマークアップから描画されたトーストを隠しません。そのため、この画面では両方を行います。position: fixedを使ったラッパーでリージョンを配置し、各トーストはdivに入れて、そのhiddenバインディングとクリックハンドラーを画面のストアに紐付けます。閉じるボタンのクリックは、そのdivまでバブリングします。

ステップ5:ストア

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

フォームへの反応。 保存に成功するとbsui/formは、バブリングし、キャンセル可能で、作成されたレコードをevent.detailに含むformsuccessイベントを送出します。保存に失敗すると、エラーボディを含むformerrorを送出します。イベントリスナーは画面のルート要素ではなくドキュメント(data-wp-on-document--formsuccess)に配置します。開いたダイアログのポップアップはdocument.bodyに移動するため、そのイベントはブロック内をバブリングしなくなるからです。ownerチェックにより、同じページ上にある他のフォームのイベントを無視します。

event.preventDefault()を呼び出すと、フォームのフィールドが成功メッセージに置き換わらず、フォーム自体はリセットされます。次にアクションがレコードを先頭に追加し、bsui/dialogストアのcloseアクションでダイアログを閉じて、トーストを表示します。closeは最前面の開いたダイアログを閉じ、トリガーにフォーカスを戻すため、作成後はキーボードフォーカスが新しいプロジェクトに戻ります。

エラー時のロールバック。 bs.mutate()は楽観的な変更をすぐに適用し、fnのPromiseが拒否された場合は以前の値に戻します。bs.fn()とbs.db()は、HTTPエラーが発生してもPromiseを拒否しません。RPC関数からのWP_Error、バリデーション失敗、レコードが見つからない場合のいずれも、エラーボディを含む結果が返されます。ok()ヘルパーは結果にcodeがある場合に拒否へ変換するため、行が元に戻り、失敗のトーストが表示されます。これがないと、更新失敗時にはエラーボディが行にマージされ、削除失敗時には行が削除されたままになります。

ブロック名の指定。 Blockstudioはインラインスクリプトを<script type="module">として出力します。また、モジュールスクリプトにはdocument.currentScriptがないため、bs.fn()では呼び出し元のブロックを判別できません。ストアでBLOCKを使っているように、3番目の引数としてブロック名を渡してください。

ステップ6:画面をページに配置する

ファイルベースのページでは、タグを使ってブロックを配置します。

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

パーサーはタグをネイティブブロックに変換します。

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

wp bs pages syncを実行してページを作成します。postStatus: "private"によって匿名の訪問者にはページを表示しません。訪問者にはいずれにせよサインインメッセージしか見えないためです。

実行時の画面の動作

編集者としてページを開くと、次のように動作します。

  1. テーブルには2行ともレンダリングされて表示され、アーカイブ済みの行にはアーカイブ済みバッジと復元ボタンが表示されます。
  2. 新しいプロジェクトをクリックするとダイアログが開きます。ポップアップと背景幕がdocument.bodyに移動し、Nameフィールドにフォーカスが移ります。Escapeキーまたはキャンセルを押すとダイアログが閉じます。
  3. 有効な値を送信すると、/wp-json/blockstudio/v1/db/acme-projects/defaultにPOSTが1回送信されます。ダイアログが閉じ、新しい行が先頭に表示され、画面の隅に「プロジェクトを作成しました。」が4秒間表示されます。
  4. アーカイブをクリックすると、バッジがすぐに切り替わり、/wp-json/blockstudio/v1/fn/acme/projects/set_statusを通じてset_statusが送信されます。その間に別の場所でレコードが削除されていた場合、関数は404エラーを返します。行は有効に戻り、「変更を保存できませんでした。」と表示されます。
  5. 削除すると行はすぐに消えます。最後の行を削除すると、「プロジェクトはまだありません。」と表示されます。

スタイル設定

画面独自のCSSがライブラリのトークンを参照するため、テーブルは周囲のコンポーネントと統一され、--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;
}

40のz-indexによって、トースト領域がダイアログの背景幕(50)より下に配置されます。画面全体のテーマを変更するには、スタイル設定に記載の方法でトークンを上書きしてください。コンポーネントとテーブルの両方に反映されます。

次のステップ

  • UIコンポーネント:デザインシステム、トークン、全コンポーネント。
  • UIの合成:複合コンポーネント群、トリガーへのプロパティ転送、ダイアログの背後にあるレイヤー構成。
  • データベース:ストレージ方式、アクセス制御、bs.db()、bs.mutate()。
  • RPC:アクセス制御、HTTPメソッド、ブロック間呼び出し。
  • フルスタックブロック:ToDoアプリとニュースレター登録で使う、同じ構成要素。