blocs/admin: 一覧表示機能のカスタマイズ（検索・ソート・ページネーション）

自動生成された管理画面の一覧表示機能をカスタマイズする方法を説明します。テンプレートやコントローラーの編集により、検索・ソート・ページネーションを柔軟に調整できます。

前提条件: 自動生成ツールで管理画面を生成済みであること

テンプレートの一覧

共通テンプレートは resources/views/admin/base/index に格納されています。

テンプレート名	用途
header.html	画面上部のヘッダー部分
footer.html	画面下部のフッター部分
pagination.blade.php	ページネーション（ページ送り）
search.html	検索フォームの表示
index.blocs.html	一覧表示画面のメインテンプレート

処理フロー

index, search
  ├─ prepareIndex .............. 表示データ準備
  │    ├─ prepareIndexSearch ... データ検索 ★
  │    └─ prepareIndexPaginate . ページネーション ★
  └─ outputIndex ............... 一覧画面表示

★ はオーバーライドによるカスタマイズポイントです。

ベースコントローラーのメソッド

可視性	メソッド名	処理内容
public	index	登録データの一覧を表示
public	search	条件を指定してデータを検索し、結果を一覧表示
protected	prepareIndex	出力のためのデータ処理
protected	prepareIndexSearch	条件指定・ソート処理 ★
protected	prepareIndexPaginate	ページネーション処理 ★
protected	outputIndex	ビューの出力処理

ベースコントローラーの主な変数

変数名	説明
`$this->loopItem`	一覧表示で使用するテーブル名
`$this->paginateNum`	1ページあたりの表示件数（0でページングなし）
`$this->paginateName`	ページネーションのパラメータ名（デフォルトは page）
`$this->searchItems`	検索条件の配列

index と search の違い

index() と search() はどちらも prepareIndex → outputIndex を呼び出しますが、以下の違いがあります。

メソッド	リクエスト	用途
`index()`	GET	初回表示。セッションに保存された検索条件を復元
`search()`	POST	検索フォーム送信。`$this->request` に POST データをセットし、検索条件をセッションに保存

search() が呼ばれると、検索条件が変わったとみなされ、ページ番号が1にリセットされます。

keepItem() の優先順位

$this->keepItem($keyItem) はページ遷移時にデータを引き継ぐためのメソッドです。値の取得には以下の優先順位があります。

POST リクエストの値
GET パラメータの値
セッションに保存された値

$this->viewPrefix が変更された場合、セッションの値はクリアされます。

検索条件の自動処理

検索キーワードは $this->searchItems に自動的に以下の処理が適用されます。

半角スペース・全角スペース・カンマで分割（AND検索）
SQLワイルドカード文字（%, _）の自動エスケープ

検索窓を設置する方法

テンプレート内で $searchPlaceholder を指定すると検索窓が表示されます。searchFilter を上書きすることで追加の検索フォームをカスタマイズできます。

テンプレートのサンプル（index.blocs.html）

$searchPlaceholder="Search by code"
data-bloc="searchFilter"

Year セレクトボックスなどを設置可能

コントローラーのサンプル

protected function prepareIndexSearch(&$mainTable)
{
    empty($this->val['year']) || $mainTable->where('year', $this->val['year']);

    foreach ($this->searchItems as $searchItem) {
        $mainTable->where(function ($query) use ($searchItem) {
            $query->where('code', 'LIKE', '%'.$searchItem.'%');
        });
    }
}

ソート機能の設定方法

一覧画面の カラムソート（列ヘッダーをクリックして asc/desc で並べ替え）の設定方法です。ドラッグ＆ドロップによる 表示順並び替え（order_by の更新）は No.5.6 を参照してください。

テンプレート内で sortHeader と sortHref を data-include で指定します。ソート不要な項目には data-include を外してください。

テンプレートで使用できる変数

変数名	説明
`$sortItem`	ソート対象の項目名（例：year）
`$sortOrder`	ソート順序（asc または desc）
`$sortClass`	ソート対象列に付与するクラス名

テンプレートのサンプル

data-include="sortHeader" $sortItem="year" $sortOrder="desc" $sortClass="d-none d-md-table-cell"

コントローラーのサンプル

protected function prepareIndexSearch(&$mainTable)
{
    $this->keepItem('sort');

    // ソート条件の初期化とバリデーション
    if (empty($this->val['sort']) || !is_array($this->val['sort'])) {
        $this->val['sort'] = [];
    } else {
        $this->val['sort'] = array_filter($this->val['sort'], 'strlen');
    }

    // ソート条件が空の場合、デフォルト値を設定
    if (empty($this->val['sort'])) {
        $this->val['sort'] = ['year' => 'desc', 'code' => 'asc'];
    }

    // 指定された条件でソート
    $allowedSortItems = ['year', 'code'];
    foreach ($allowedSortItems as $sortItem) {
        if (!empty($this->val['sort'][$sortItem])) {
            $mainTable->orderBy($sortItem, $this->val['sort'][$sortItem]);
        }
    }
}