v0.21

リアクティビティ

はじめに

dframeworkはソケットレイヤーを介してユーザーインターフェースとサーバー状態の同期を維持する2つの相補的なリアクティビティシステムを提供します。クライアント側のレンダリングフレームワークは関与しません。サーバーがHTMLをレンダリングし、フレームワークがそれを適切なDOMターゲットに局所的かつ的確に配信します。

システムの選択

機能 d-wire d-live
トリガー 明示的なユーザー操作 データベース書き込み
最適な用途 カウンター、検索、モーダル、フォーム フィード、ダッシュボード、ライブリスト
必要要件 名前付きソケットハンドラー d-live属性(ハンドラー不要)
レンダリング ハンドラーがrenderを呼び出し フレームワークが自動再取得

意図的な操作から特定の結果をユーザーが期待する場合はd-wireを使用します。原因にかかわらずデータと領域の同期を維持する必要がある場合はd-liveを使用します。

d-wireイベント駆動リアクティビティ

任意のHTML要素にd-wireを付与します。トリガーされると要素はソケット経由で名前付きイベントをソケットハンドラーに送信します。ハンドラーがパーシャルをレンダリングし、フレームワークが対象コンテナーをその結果で置き換えます。

1<button d-wire="counter:increment" d-target="#counter">+1</button>

データの受け渡し

イベントとともにペイロードを送信するにはd-wire-dataを使用します。カンマ区切りのキーバリューペアまたは生のJSONを受け付けます。

1<button
2 d-wire="post:like"
3 d-wire-data="id:{{ post.id }}, type:'post'"
4 d-target="#likes-{{ post.id }}">
5 like
6</button>
7
8<button
9 d-wire="user:update"
10 d-wire-data='{"id": {{ user.id }}, "status": "active"}'
11 d-target="#user-status">
12 activate
13</button>

ペイロードは存在するフォームデータとマージされハンドラー内でリクエストボディとしてアクセスできます。

バックエンドハンドラー

d-wireハンドラーはrenderまたはjsonを呼び出す必要があります。レンダリングされたHTMLがクライアント上の対象要素を置き換えます。フレームワークはレンダリング結果をハッシュ化し、コンテンツに変更がない場合は更新を抑制して冗長なDOM操作を防ぎます。

IMPORTANT

任意のDOM注入を防ぐため、パーシャルをレンダリングするソケットルートは`.targets(['#target-id'])`をチェーンして許可されるクライアントターゲットを明示的に制限する必要があります。

1Socket.on('counter:increment', async (req, res) => {
2 const count = await Counter.increment(req.body.id);
3 return res.render('partials.counter', { count });
4}).targets(['#counter']);
5
6Socket.on('user:search', async (req, res) => {
7 const users = await User.where('name', 'LIKE', `%${req.body.q}%`).limit(10).get();
8 return res.render('partials.user-list', { users });
9}).targets(['#user-list']);

トリガータイプ

d-wireは各要素タイプに応じた自然なイベントにバインドされます。

要素 デフォルトトリガー
<button>, <a> click
<form> submit
<input>, <select> change

d-triggerで上書きできます。

1<input d-wire="user:search" d-target="#results" d-trigger="keyup" placeholder="search users">

特別なトリガー値も利用可能です。

値 挙動
load 要素がマウントされた直後に一度だけ発火
poll-{ms} nミリ秒ごとに継続的に発火(例: poll-5000)

プログラムによるディスパッチ

javascriptまたはフロントエンドコンポーネント内からd-wireイベントを送出します。

1Socket.emit('dashboard:refresh', {}, '#stats-panel');
2this.wire('notification:dismiss', { id: this.notificationId });

d-liveステート駆動リアクティビティ

d-liveはDOM要素をデータベーステーブルに購読させます。モデルの書き込みがそのテーブルに及ぶとフレームワークはアクティブな購読を評価し、一致するクライアントに通知して要素が自身のコンテンツを自動的に再取得して置き換えます。バックエンドハンドラーは不要です。

1<div d-live="posts">
2 @foreach(const post of await Post.where({ status: 'published' }).orderBy('created_at', 'DESC').get())
3 <article>
4 <h2>{{ post.title }}</h2>
5 <p>{{ post.excerpt }}</p>
6 </article>
7 @endforeach
8</div>

単一ページ上で複数の要素が同一または異なるテーブルを同時に購読できます。

フィルタリング

d-live-filterは更新対象を特定の条件に一致する行に制限します。サーバーはクライアントに通知する前に変更された行に対してフィルターを評価します。フィルターに一致しないクライアントにはメッセージが送信されず再取得も行われません。

1<div d-live="orders" d-live-filter="user_id:{{ user.id }}"></div>

サポートされている演算子は以下のとおりです。

演算子 例 意味
=(デフォルト) status:published 一致
!= status:!=archived 不一致
> price:>100 より大きい
< count:<5 未満
>= rating:>=4 以上
<= stock:<=10 以下

複数のフィルターはANDロジックを使用します。区切りにはカンマを使用します。

1<div d-live="messages" d-live-filter="room_id:{{ room.id }},status:visible"></div>

動作の仕組み

  1. マウント時に対象要素はソケット経由で購読メッセージを送信し、フィルター条件とともにそのテーブルに自身を登録します。
  2. クエリビルダーが書き込みを実行するとテーブル名と変更データをソケットルーターに通知します。
  3. ルーターはアクティブな購読を走査し変更データに対して各フィルターを評価し、フィルターが一致したクライアントにのみ通知を送信します。
  4. 購読要素は自身のコンテンツを再レンダリングします。一括操作を効率的に処理するため更新は100ミリ秒にデバウンスされます。二重取得を防ぐためフォーム送信の成功後250ミリ秒間は更新が抑制されます。

局所的ステート同期

テンプレートを再レンダリングすることなくコンポーネントのリアクティブメモリにステートを直接プッシュします。これは完全なHTML置換を必要としない軽量なステート更新に役立ちます。

1Socket.setState('#notification-badge', { unread: 14 });

対象コンポーネントは自動的に自身のsetStateメソッドを呼び出し、renderおよびeffectループをトリガーします。

エラーハンドリング

SPAとリアクティビティはabortヘルパーと統合されています。

フォーム送信は標準のfetchリクエストを使用します。abortメソッドを呼び出すと構造化されたJSONエラーオブジェクトが返され、フォームは関連する入力欄の直下にインラインでレンダリングします。

SPAナビゲーションはバックグラウンドリクエストを使用します。abortメソッドを呼び出すと完全なエラーページのHTMLがレンダリングされ、SPAレイヤーがそれを表示してURLに反映します。またソケットルーティングハンドラーはレンダリング時の例外を正常にキャッチしてログに記録し、必要に応じてクライアントに安全なエラーメッセージへとフォールバックします。