2023.12.07

【Craft 4.5 の新機能】共有可能なエレメントフィルタで、管理画面をカスタマイズする（準備編）

Craft 4.4 以降、Element Index（一覧画面）を任意条件でフィルタリングした際の URL を共有できるようになりました。

正確には Craft 4.4 でキーワード検索の結果、Craft 4.5 からは更にエレメントフィルタによる絞り込み結果の URL を共有可能です。これによって、管理画面の操作に慣れないユーザーに複雑なフィルタ条件を設定することなく絞り込み後のエレメント一覧を表示させることができ、とても便利だなと感じています。

そこで、今回はエレメントフィルタの共有 URL を利用して管理画面を少し使いやすくしてみます。
これは Craft CMS Advent Calendar 2023 7日目の記事です。

エレメントフィルタとは

Craft 4 から搭載されたエレメントフィルタは、Element Index に表示するエレメントを特定の条件で絞り込むための機能です。

エレメントフィルタのサンプル（特定の投稿者で絞り込み）

キーワード入力欄の右側にある 結果をフィルター アイコンをクリックして表示されるモーダル内で、条件を設定できるようになっています。

フィルタ選択肢のサンプル

フィールドレイアウトに配置されたフィールドを条件としてセットできるため、柔軟な絞り込みが可能です。

条件を「適用」すると即座に URL パラメータに反映されます。
その URL を共有することで、同じ条件でエレメントを絞り込んだ状態を簡単に再現できるという仕組みです。

カスタムソースとの違いは？

Craft 4 では、エレメントフィルタの他にもカスタムソースを利用してエレメントを絞り込むことができます。

カスタムソースの設定サンプル

カスタムソースのメリットとして、次のような点が挙げられます。

Element Index のサブメニューとして常時表示できる
フィルタ条件を管理者が一元管理できる
ユーザーグループごとにアクセスの可否を設定できる
リレーション系フィールドのソースとして利用できる
「セクション（エントリ）」や「グループ（カテゴリなど）」を横断して一覧化できる
条件の値を指定する際、一部で環境変数や Twig テンプレートを利用できる

一方で、デメリットと言える点もあります。

カテゴリなど直接 ID を数値指定する条件の場合、カスタムソースを必要数だけ用意することになる
一覧表示にあたり、構造化テーブルで表示 （ストラクチャーの階層表示）が選択できない

共有された URL にアクセスしない限り、エレメントフィルタの条件指定は任意のタイミングでクリアされてしまうため、用途に応じて使い分けると良いでしょう。

エレメントフィルタの共有 URL の構造を確認

絞り込み後の共有 URL の構造を確認するにあたり、任意のセクションで投稿者を指定してフィルタします。

エレメントフィルタのサンプル（特定の投稿者で絞り込み）

このとき、ブラウザのアドレスバーは次のようになりました。

https://craft4.test/admin/entries/blog?source=section%3Abeadf99c-009f-431c-8fb0-4f996b148c95&filters=condition%255Bclass%255D%3Dcraft%255Celements%255Cconditions%255Centries%255CEntryCondition%26condition%255Bconfig%255D%3D%257B%2522elementType%2522%253A%2522craft%255C%255Celements%255C%255CEntry%2522%252C%2522fieldContext%2522%253A%2522global%2522%257D%26condition%255BconditionRules%255D%255B1%255D%255Buid%255D%3D1f06378d-9cfb-4012-bef7-37dbd06d7b7d%26condition%255BconditionRules%255D%255B1%255D%255Bclass%255D%3Dcraft%255Celements%255Cconditions%255Centries%255CAuthorConditionRule%26condition%255BconditionRules%255D%255B1%255D%255Btype%255D%3D%257B%2522class%2522%253A%2522craft%255C%255Celements%255C%255Cconditions%255C%255Centries%255C%255CAuthorConditionRule%2522%252C%2522uid%2522%253A%25221f06378d-9cfb-4012-bef7-37dbd06d7b7d%2522%252C%2522elementId%2522%253Anull%257D%26condition%255BconditionRules%255D%255B1%255D%255Boperator%255D%3D%26condition%255BconditionRules%255D%255B1%255D%255BelementId%255D%3D%26condition%255BconditionRules%255D%255B1%255D%255BelementId%255D%3D84%26condition%255Bnew-rule-type%255D%3D

URL パラメータごとに分けると、次のような値を持っていることがわかります。

パラメータ名	セットされる値
source	ソース情報（エントリのセクション、カテゴリのグループなど）
filters	フィルタ条件（モーダル内で設定した内容）
search	検索キーワードのテキスト（入力がある場合のみ、パラメータが追加）

これらの値を意図した内容でセットできれば、エレメントフィルタの共有 URL を自由に作成できそうです。

filters パラメータの構造を確認

では、具体的なフィルタ条件がセットされている filters パラメータを見てみましょう。

filters パラメータの値は、2回 URL エンコードされた文字列です。
それを踏まえてブラウザのコンソール上で次のコードを実行し、具体的な定義内容を把握しやすくします。

// URL パラメータから source, filters, search を取得
const params  = new URL(location.href).searchParams;
const source  = params.get('source');
const filters = params.get('filters');
const search  = params.get('search');

// filters を2回デコード
let filtersDecoded = decodeURIComponent(filters);
    filtersDecoded = decodeURIComponent(filtersDecoded);

// filtersDecoded の & のすぐ前に改行コードを追加して変数にセット
const filtersDecodedReplace = filtersDecoded.replace(/&/g, '\n&');

// console.warn で確認
console.warn(source);
console.warn(filtersDecodedReplace);
console.warn(search);

実行結果は、次の通りです。

ブラウザのコンソールで URL パラメータを整形

フィルターを変更しながら確認すると、condition[conditionRules][1] 配下の class や uid、elementId などが条件ごとに書き変わっていることがわかります。

また、複数条件であれば condition[conditionRules][2] の形で追加されます。

つまり、今回のサンプルでは condition[conditionRules][1] にセットされた内容が「投稿者」の指定に必要な定義ということになります。

&condition[conditionRules][1][uid]=1f06378d-9cfb-4012-bef7-37dbd06d7b7d
&condition[conditionRules][1][class]=craft\elements\conditions\entries\AuthorConditionRule
&condition[conditionRules][1][type]={"class":"craft\\elements\\conditions\\entries\\AuthorConditionRule","uid":"1f06378d-9cfb-4012-bef7-37dbd06d7b7d","elementId":"84"}
&condition[conditionRules][1][operator]=
&condition[conditionRules][1][elementId]=
&condition[conditionRules][1][elementId]=84

このうち、condition[conditionRules][1][elementId]=84 の数値部分が対象となるユーザー ID の指定になるため、別のユーザー ID に置き換えることでそのユーザーのエントリ一覧を表示できます。

ここまでのまとめ

「準備編」ということで、今回はエレメントフィルタを設定することでどのような共有 URL が生成されるのかを確認しました。

GUI 操作で必要な条件をセット後、ブラウザのコンソール上で実際にセットされる URL パラメータを確認すれば、共有 URL を効率的にカスタマイズできそうですね。

次回は「実践編」として、選択したカテゴリに応じてエレメントフィルタを適用するプルダウンを作成して見ようと思います。