admin-theme-development

管理画面テーマの開発

概要

Bagisto での管理画面テーマの開発では、Laravel パッケージとしてパッケージ化したカスタム管理画面テーマを作成します。最終的には、独立して配布および保守できる自己完結型パッケージになります。

適用する場面

次のような場合にこのスキルを使用します：

• カスタム管理画面テーマをパッケージとして作成する
• 配布用の管理画面テーマパッケージを構築する
• 管理画面のスタイルをカスタマイズする
• デフォルトの管理画面テンプレートをオーバーライドする

Bagisto の管理画面テーマアーキテクチャ

主なコンポーネント

コンポーネント	目的	場所
テーマ設定	利用可能な管理画面テーマを定義します	config/themes.php
ビューのパス	Blade テンプレートファイル	テーマ設定で定義
アセットのパス	CSS、JS、画像	テーマ設定で定義
管理画面サービスプロバイダー	ビューとコンポーネントを読み込みます	packages/Webkul/Admin/src/Providers/AdminServiceProvider.php

主な設定プロパティ

// config/themes.php
'admin-default' => 'default',

'admin' => [
    'default' => [
        'name' => 'Default',
        'assets_path' => 'public/themes/admin/default',
        'views_path' => 'resources/admin-themes/default/views',
        'vite' => [
            'hot_file' => 'admin-default-vite.hot',
            'build_directory' => 'themes/admin/default/build',
            'package_assets_directory' => 'src/Resources/assets',
        ],
    ],
],

管理画面テーマパッケージの作成

目標：完全な自己完結型パッケージ

最終的なパッケージには、次のすべてが含まれている必要があります：

• パッケージ内のすべてのビュー
• パッケージ内のすべてのアセット
• 公開用サービスプロバイダー
• アセットコンパイル用の Vite 設定

ステップ 1：パッケージ構成を作成する

mkdir -p packages/Webkul/CustomAdminTheme/src/{Providers,Resources/views}

ステップ 2：管理画面アセット一式をコピーする

完全に制御できるように、管理画面アセットをすべてパッケージにコピーします：

# Copy complete admin assets folder
cp -r packages/Webkul/Admin/src/Resources/assets/* packages/Webkul/CustomAdminTheme/src/Resources/assets/

# Copy complete admin views folder
cp -r packages/Webkul/Admin/src/Resources/views/* packages/Webkul/CustomAdminTheme/src/Resources/views/

# Copy admin package.json for dependencies
cp packages/Webkul/Admin/package.json packages/Webkul/CustomAdminTheme/

これにより、次のものが揃います：

• Tailwind を使用した完全な CSS 基盤
• すべての JavaScript 機能
• 管理画面のコンポーネントとレイアウト
• 画像、フォント、静的アセット
• 完全な Blade テンプレート構成
• アセットコンパイル用の依存関係

ステップ 3：カスタムダッシュボードページを追加する（ひな形）

コピーした後、新しいテーマであることを示すカスタムダッシュボードページを作成します：

ファイル： packages/Webkul/CustomAdminTheme/src/Resources/views/dashboard/index.blade.php

<x-admin::layouts>
    <x-slot:title>
        Custom Admin Dashboard
    </x-slot>

    <div class="flex gap-4 justify-between max-sm:flex-wrap">
        <h1 class="py-[11px] text-xl text-gray-800 dark:text-white font-bold">
            Custom Theme Dashboard
        </h1>

        <div class="flex gap-x-2.5 items-center">
            <button class="secondary-button">
                Reset to Defaults
            </button>
            
            <button class="primary-button">
                Save Settings
            </button>
        </div>
    </div>

    {{-- Dashboard Content --}}
    <div class="mt-8 bg-white dark:bg-gray-900 rounded-lg shadow p-6">
        <h1 class="text-3xl font-bold text-gray-800 dark:text-white mb-6">
            Welcome to Custom Admin Theme
        </h1>
        
        <p class="text-lg text-gray-600 dark:text-gray-300 mb-8">
            Your customized Bagisto admin panel!
        </p>
        
        <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
            <div class="bg-blue-50 p-4 rounded-lg border border-blue-200">
                <h3 class="text-xl font-semibold text-blue-800 mb-2">
                    Analytics
                </h3>
                <p class="text-blue-600">
                    Enhanced dashboard analytics and reporting
                </p>
            </div>
            
            <div class="bg-green-50 p-4 rounded-lg border border-green-200">
                <h3 class="text-xl font-semibold text-green-800 mb-2">
                    Orders
                </h3>
                <p class="text-green-600">
                    Streamlined order management interface
                </p>
            </div>
            
            <div class="bg-purple-50 p-4 rounded-lg border border-purple-200">
                <h3 class="text-xl font-semibold text-purple-800 mb-2">
                    Customers
                </h3>
                <p class="text-purple-600">
                    Enhanced customer management tools
                </p>
            </div>
        </div>
    </div>
</x-admin::layouts>

ステップ 4：カスタムレイアウトを作成する（任意）

完全に制御できるように、独自のマスターレイアウトを作成します：

ファイル： packages/Webkul/CustomAdminTheme/src/Resources/views/layouts/master.blade.php

<!DOCTYPE html>
<html lang="{{ app()->getLocale() }}">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ $title ?? config('app.name') }}</title>
    
    {{-- Load assets manually for custom layouts --}}
    @bagistoVite([
        'src/Resources/assets/css/app.css',
        'src/Resources/assets/js/app.js'
    ])
</head>
<body class="dark:bg-gray-900">
    {{-- Custom sidebar --}}
    @include('custom-admin-theme::layouts.sidebar')
    
    <div class="flex">
        {{-- Main content area --}}
        <main class="flex-1 p-6">
            {{ $slot }}
        </main>
    </div>
</body>
</html>

ステップ 5：サービスプロバイダーを作成する

ファイル： packages/Webkul/CustomAdminTheme/src/Providers/CustomAdminThemeServiceProvider.php

<?php

namespace Webkul\CustomAdminTheme\Providers;

use Illuminate\Support\ServiceProvider;

class CustomAdminThemeServiceProvider extends ServiceProvider
{
    /**
     * Register services.
     */
    public function register(): void
    {
        //
    }

    /**
     * Bootstrap services.
     */
    public function boot(): void
    {
        // Publish views to resources/admin-themes/custom-admin-theme/views
        $this->publishes([
            __DIR__ . '/../Resources/views' => resource_path('admin-themes/custom-admin-theme/views'),
        ], 'custom-admin-theme-views');
    }
}

ステップ 6：オートロードを設定する

composer.json を更新します：

"autoload": {
    "psr-4": {
        "Webkul\\CustomAdminTheme\\": "packages/Webkul/CustomAdminTheme/src"
    }
}

実行します：composer dump-autoload

ステップ 7：サービスプロバイダーを登録する

bootstrap/providers.php に追加します：

Webkul\CustomAdminTheme\Providers\CustomAdminThemeServiceProvider::class,

ステップ 8：テーマ設定を更新する

ファイル： config/themes.php

'admin-default' => 'custom-admin-theme',

'admin' => [
    'default' => [
        'name' => 'Default',
        'assets_path' => 'public/themes/admin/default',
        'views_path' => 'resources/admin-themes/default/views',
        'vite' => [
            'hot_file' => 'admin-default-vite.hot',
            'build_directory' => 'themes/admin/default/build',
            'package_assets_directory' => 'src/Resources/assets',
        ],
    ],
    'custom-admin-theme' => [
        'name' => 'Custom Admin Theme',
        'assets_path' => 'public/themes/admin/custom-admin-theme',
        'views_path' => 'resources/admin-themes/custom-admin-theme/views',
        'vite' => [
            'hot_file' => 'admin-custom-vite.hot',
            'build_directory' => 'themes/admin/custom-admin/build',
            'package_assets_directory' => 'src/Resources/assets',
        ],
    ],
],

ステップ 9：ビューを公開する

php artisan vendor:publish --provider="Webkul\CustomAdminTheme\Providers\CustomAdminThemeServiceProvider"

ステップ 10：キャッシュをクリアする

php artisan optimize:clear

ステップ 11：アセットをビルドする

# Navigate to package
cd packages/Webkul/CustomAdminTheme

# Install dependencies
npm install

# Build assets for production
npm run build

これにより、管理画面テーマのアセットがコンパイルされ、ビルドディレクトリが作成されます。ビルドが完了すると、作成したカスタムダッシュボードを含むカスタム管理画面テーマを使用できるようになります。

Vite を使用したアセット

ステップ 1：アセット設定ファイルを作成する

パッケージのルートに作成します：

ファイル： package.json

{
    "name": "custom-admin-theme",
    "private": true,
    "description": "Custom Admin Theme Package for Bagisto",
    "scripts": {
        "dev": "vite",
        "build": "vite build"
    },
    "devDependencies": {
        "autoprefixer": "^10.4.14",
        "axios": "^1.1.2",
        "laravel-vite-plugin": "^0.7.2",
        "postcss": "^8.4.23",
        "tailwindcss": "^3.3.2",
        "vite": "^4.0.0"
    }
}

ファイル： vite.config.js

import { defineConfig, loadEnv } from "vite";
import laravel from "laravel-vite-plugin";
import path from "path";

export default defineConfig(({ mode }) => {
    const envDir = "../../../";

    Object.assign(process.env, loadEnv(mode, envDir));

    return {
        build: {
            emptyOutDir: true,
        },
        envDir,
        server: {
            host: process.env.VITE_HOST || "localhost",
            port: process.env.VITE_ADMIN_PORT || 5174,
            cors: true,
        },
        plugins: [
            laravel({
                hotFile: "../../../public/admin-custom-vite.hot",
                publicDirectory: "../../../public",
                buildDirectory: "themes/admin/custom-admin/build",
                input: [
                    "src/Resources/assets/css/app.css",
                    "src/Resources/assets/js/app.js",
                ],
                refresh: true,
            }),
        ],
    };
});

ファイル： tailwind.config.js

module.exports = {
    content: [
        "./src/Resources/**/*.blade.php",
        "../../../resources/admin-themes/custom-admin-theme/**/*.blade.php"
    ],
    theme: {
        extend: {
            colors: {
                navyBlue: "#060C3B",
            },
        },
    },
    plugins: [],
};

ファイル： postcss.config.js

module.exports = {
    plugins: {
        tailwindcss: {},
        autoprefixer: {},
    },
}

ステップ 2：Bagisto の Vite 設定に追加する

ファイル： config/bagisto-vite.php

'admin-custom-theme' => [
    'hot_file' => 'admin-custom-vite.hot',
    'build_directory' => 'themes/admin/custom-admin/build',
    'package_assets_directory' => 'src/Resources/assets',
],

開発コマンド

# Navigate to package
cd packages/Webkul/CustomAdminTheme

# Install dependencies
npm install

# Start dev server with hot reload
npm run dev

# Build for production
npm run build

開発ワークフロー

オプション A：シンボリックリンク（推奨）

再公開せずにリアルタイムで開発できるよう、シンボリックリンクを作成します：

# Remove published views
rm -rf resources/admin-themes/custom-admin-theme/views

# Create symlink from package to resources
ln -s $(pwd)/packages/Webkul/CustomAdminTheme/src/Resources/views resources/admin-themes/custom-admin-theme/views

オプション B：パッケージを直接開発する

パッケージで直接作業し、必要に応じて再公開します：

# After making changes
php artisan vendor:publish --provider="Webkul\CustomAdminTheme\Providers\CustomAdminThemeServiceProvider" --force

管理画面のレイアウト

Blade 自体を記述しますか？ マークアップのルールについては blade-conventions スキルを参照してください。 : と :: の属性バインディング、匿名コンポーネントと Vue を使用したコンポーネント、インデント、コメントのスタイル、 翻訳と view_render_event フックの配置場所について説明しています。

管理画面レイアウトの使用

<x-admin::layouts>
    <x-slot:title>
        Page Title
    </x-slot>

    {{-- Page Header --}}
    <div class="flex gap-4 justify-between max-sm:flex-wrap">
        <p class="py-[11px] text-xl text-gray-800 dark:text-white font-bold">
            Page Heading
        </p>
        <div class="flex gap-x-2.5 items-center">
            <button class="primary-button">
                Action Button
            </button>
        </div>
    </div>

    {{-- Page content --}}
    <div class="mt-8">
        Content goes here
    </div>
</x-admin::layouts>

レイアウト機能

管理レイアウトでは、以下が自動的に提供されます。

• サイドバーナビゲーション：折りたたみ可能なセクションを備えた管理メニュー
• ヘッダー：ユーザーメニューと通知を含む上部ナビゲーション
• レスポンシブデザイン：モバイルに対応したレイアウト
• ダークモード：組み込みのダークモード対応
• パンくずリスト：パンくずリストの自動生成

管理レイアウトのベストプラクティス

• SEO とユーザーエクスペリエンスのために、必ず title スロットを使用してください
• Bagisto の管理画面のデザインパターンに従ってください
• 用意されている CSS クラス（例：primary-button、secondary-button）を使用してください
• レイアウト構造を整理し、セマンティックに保ってください

管理用 Blade コンポーネント

利用可能なコンポーネント

コンポーネント	用途	説明
<x-admin::accordion>	折りたたみ可能なセクション	コンテンツの表示を切り替えます
<x-admin::button>	アクションボタン	ローディング状態に対応しています
<x-admin::charts.bar>	棒グラフ	Chart.js に基づいています
<x-admin::charts.line>	折れ線グラフ	Chart.js に基づいています
<x-admin::datagrid>	データテーブル	並べ替え、フィルタリング、ページネーション
<x-admin::drawer>	スライドパネル	位置：上／下／左／右
<x-admin::dropdown>	ドロップダウンメニュー	位置を指定できます
<x-admin::flat-picker.date>	日付ピッカー	Flatpickr に基づいています
<x-admin::flat-picker.datetime>	日時ピッカー	Flatpickr に基づいています
<x-admin::media.images>	画像アップロード	複数の画像に対応しています
<x-admin::media.videos>	動画アップロード	動画に対応しています
<x-admin::modal>	ダイアログボックス	ヘッダー、コンテンツ、フッターのスロット
<x-admin::quantity-changer>	数量入力	+/- ボタン
<x-admin::seo>	SEO メタデータ	メタタイトルと説明
<x-admin::table>	データテーブル	thead/tbody をカスタマイズできます
<x-admin::tabs>	タブナビゲーション	位置：左／右／中央
<x-admin::shimmer.*>	ローディングエフェクト	スケルトンローダー

カスタムレイアウト

カスタムレイアウトの作成

ファイル： packages/Webkul/CustomAdminTheme/src/Resources/views/layouts/master.blade.php

<!DOCTYPE html>
<html lang="{{ app()->getLocale() }}">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ $title ?? config('app.name') }}</title>
    
    {{-- Load assets manually for custom layouts --}}
    @bagistoVite([
        'src/Resources/assets/css/app.css',
        'src/Resources/assets/js/app.js'
    ])
</head>
<body class="dark:bg-gray-900">
    {{-- Custom sidebar --}}
    @include('custom-admin-theme::layouts.sidebar')
    
    <div class="flex">
        {{-- Main content area --}}
        <main class="flex-1 p-6">
            {{ $slot }}
        </main>
    </div>
</body>
</html>

完全なパッケージ構成

packages/Webkul/CustomAdminTheme/
├── src/
│   ├── Providers/
│   │   └── CustomAdminThemeServiceProvider.php
│   └── Resources/
│       ├── assets/
│       │   ├── css/
│       │   │   └── app.css
│       │   ├── js/
│       │   │   └── app.js
│       │   ├── images/
│       │   └── fonts/
│       └── views/
│           ├── layouts/
│           │   └── master.blade.php
│           ├── dashboard/
│           │   └── index.blade.php
│           ├── components/
│           └── ...
├── package.json
├── vite.config.js
├── tailwind.config.js
└── postcss.config.js

主要ファイルのリファレンス

ファイル	目的
config/themes.php	テーマ設定
config/bagisto-vite.php	Vite アセット設定
packages/Webkul/Admin/src/Providers/AdminServiceProvider.php	管理パッケージの登録
packages/Webkul/Admin/src/Resources/views/components/*	管理コンポーネント
packages/Webkul/Theme/src/Themes.php	テーマファサード

よくある落とし穴

• テーマ設定を変更した後にキャッシュをクリアしない
• パッケージ登録後に composer dump-autoload を実行し忘れる
• 管理アセット（ビューとアセット）をすべてコピーしない
• @bagistoVite アセットを手動で読み込まずにカスタムレイアウトを使用する
• パッケージのソースファイルではなく、公開済みファイルを編集する
• 開発ワークフロー用のシンボリックリンクを設定していない

テスト

以下の手順で管理テーマをテストします。

1. config/themes.php で admin-default を設定する
2. 管理パネルにログインする
3. ダッシュボードと各種管理ページを確認する
4. レスポンシブデザインを確認する
5. すべての管理機能が動作することを確認する
6. 開発中にホットリロードをテストする