bagisto-datagrid-development

DataGrid の開発

管理画面の一覧ページは、DataGrid のサブクラスと、3 行の配線コードで構成されます。エンジン（packages/Webkul/DataGrid）はページネーション、検索、フィルタリング、並べ替え、保存済みフィルター、エクスポートを担当し、サブクラスはクエリを指定して列を定義します。コードベースには 51 個あります。独自の形式を考えるのではなく、最も近いものをコピーしてください。

4 つのメソッド

Webkul\DataGrid\DataGrid は、2 つの抽象メソッドと 2 つの任意のフックを宣言します。

メソッド	必須	目的
prepareQueryBuilder()	はい	コレクションではなく、クエリビルダーを返します
prepareColumns()	はい	列ごとに addColumn([...]) を呼び出します
prepareActions()	いいえ	行ごとのアクション。各アクションに ACL チェックが必要です
prepareMassActions()	いいえ	チェックボックスのアクション。各アクションに ACL チェックが必要です

調整可能なプロパティです。デフォルト値で問題がある場合にのみオーバーライドしてください。$primaryColumn（デフォルトは 'id'）、$sortColumn、$sortOrder（'desc'）、$itemsPerPage（10）、$perPageOptions。

形式

class CurrencyDataGrid extends DataGrid
{
    /**
     * Prepare query builder.
     *
     * @return Builder
     */
    public function prepareQueryBuilder()
    {
        return DB::table('currencies')
            ->select('id', 'name', 'code');
    }

    /**
     * Add Columns.
     *
     * @return void
     */
    public function prepareColumns()
    {
        $this->addColumn([
            'index'      => 'name',
            'label'      => trans('admin::app.settings.currencies.index.datagrid.name'),
            'type'       => 'string',
            'searchable' => true,
            'filterable' => true,
            'sortable'   => true,
        ]);
    }

    /**
     * Prepare actions.
     *
     * @return void
     */
    public function prepareActions()
    {
        if (bouncer()->hasPermission('settings.currencies.edit')) {
            $this->addAction([
                'index'  => 'edit',
                'icon'   => 'icon-edit',
                'title'  => trans('admin::app.settings.currencies.index.datagrid.edit'),
                'method' => 'GET',
                'url'    => fn ($row) => route('admin.settings.currencies.edit', $row->id),
            ]);
        }
    }
}

addColumn／addAction の配列内で => を揃えるのは、編集対象のファイルがすでに揃えている場合に限ってください。Pint はどちらの形式も強制しません。また、コードベースには両方の形式があります。

配線

コントローラーは、AJAX リクエストには JSON を、それ以外にはビューを返します。1 つのルートで 2 種類のレスポンスを返します。

public function index()
{
    if (request()->ajax()) {
        return datagrid(CurrencyDataGrid::class)->process();
    }

    return view('admin::settings.currencies.index');
}

Blade 側では、同じルートを指定するタグを 1 つ記述します。

<x-admin::datagrid :src="route('admin.settings.currencies.index')" />

クラスが DataGrid を継承していない場合、datagrid() は InvalidDataGridException をスローするため、クラス名だけが契約となります。

参照ファイル

ファイル	参照するタイミング
columns.md	列の種類、検索／フィルター／並べ替えのフラグ、ドロップダウンの選択肢、クロージャー、結合、addFilter
actions.md	行アクション、複数行アクション、ACL チェック、エクスポート

必ず守ること

• prepareQueryBuilder() はビルダーを返します。 ->get()、->paginate() を呼び出したり、コレクションにマッピングしたりすると、ページネーション、フィルタリング、エクスポートが機能しなくなります。エンジンは返されたクエリに処理を追加するためです。
• DB:: を使うことが想定されるのは、クエリビルダーだけです。 Bagisto のそれ以外の箇所ではリポジトリを使いますが、DataGrid は設計上、クエリビルダーを基盤とします。
• すべてのアクションと複数行アクションは bouncer()->hasPermission(...) でラップします。 権限のない管理者にもアクションが表示されてしまいます。DataGrid は、この対応が最も忘れられやすい箇所です。
• すべての label は trans() を通し、キーを 23 のすべてのロケールに追加します。
• 結合したクエリでは、エイリアス付きの列ごとに addFilter() が必要です。詳しくは columns.md を参照してください。これがないと、その列のフィルタリングや並べ替えで、あいまいな列名に関する SQL エラーが発生します。
• クロージャーで埋め込む値は、すべてエスケープします。 セルは v-html を通じて描画されます。エンジンは生の値からタグを除去しますが、引用符は除去しません。そのため、属性内に値を配置すると、属性の外に抜け出せる可能性があります。詳しくは columns.md を参照してください。

必須のサブスキル： 変更を完了とする前に、bagisto-change-verification を使用してください。