Laravel Nova 向けの、簡単かつ完全なフレキシブルフィールド。繰り返し可能で柔軟なフィールドグループに最適です。

クイックスタート

ここでは、すぐに始めるための非常に簡潔なガイドを紹介します。 完全なドキュメントはこちらをご覧ください: https://whitecube.github.io/nova-flexible-content

インストール

composer require whitecube/nova-flexible-content

使用方法

フレキシブルフィールドを使用すると、繰り返し可能で順序変更可能なフィールドグループを簡単に管理できます。Laravel Nova の既存のいくつかのソリューションとは異なり、このフィールドではグループ内で使用できるフィールドに制約がありません。つまり、すべての Laravel Nova フィールドタイプに加え、コミュニティ製のフィールドも使用できます。

レイアウトの追加

レイアウトは、フレキシブルフィールド内で繰り返し可能なフィールドグループを表します。必要な数のレイアウトを追加できます。レイアウトが1つだけ定義されている場合、フィールドは単純なリピーターのように動作し、複数のレイアウトを追加するとフレキシブルコンテンツが得られます。どちらの概念も、WordPress の ACF プラグインにある機能と似ています。

レイアウトは、Flexible フィールドで次のメソッドを使用して追加できます:

 addLayout(string $title, string $name, array $fields)

$name パラメータは、フィールドの値に選択したレイアウトを格納するために使用されます。慎重に選択してください。アプリケーション内でレイアウトを識別するために使用される可能性が高いです。

use Whitecube\NovaFlexibleContent\Flexible;

/**
 * リソースが表示するフィールドを取得します。
 *
 * @param  \Illuminate\Http\Request  $request
 * @return array
 */
public function fields(Request $request)
{
    return [
        // ...

        Flexible::make('Content')
            ->addLayout('シンプルなコンテンツセクション', 'wysiwyg', [
                Text::make('タイトル'),
                Markdown::make('コンテンツ')
            ])
            ->addLayout('動画セクション', 'video', [
                Text::make('タイトル'),
                Image::make('動画サムネイル', 'thumbnail'),
                Text::make('動画ID (YouTube)', 'video'),
                Text::make('動画キャプション', 'caption')
            ])
    ];
}

ボタンラベルのカスタマイズ

デフォルトの「レイアウトを追加」ボタンのテキストは次のように変更できます:

Flexible::make('Content')
    ->button('何か素晴らしいものを追加！');

ビューでのフレキシブル値の使用

Laravel 6 以下を使用している場合、またはキャストを使用したくない場合は、モデルに HasFlexible トレイトを適用してアクセサを使用してください。

Laravel 7 ではカスタムキャストが導入され、フレキシブルコンテンツフィールドはその完璧なユースケースです。このフィールドは値を単一の JSON 文字列として保存するため、アプリケーションで使用する前にこの文字列をパースする必要があります。これは、このパッケージの FlexibleCast クラスを使用して簡単に行えます:

namespace App;

use Illuminate\Database\Eloquent\Model;
use Whitecube\NovaFlexibleContent\Value\FlexibleCast;

class MyModel extends Model
{
    protected $casts = [
        'flexible-content' => FlexibleCast::class
    ];
}

デフォルトでは、FlexibleCast クラスは基本的な Layout インスタンスを収集します。レイアウトをカスタムレイアウトインスタンスにマッピングしたい場合も可能です。まず、php artisan flexible:cast MyFlexibleCast を実行してカスタムフレキシブルキャストを作成します。これにより App\Casts ディレクトリにファイルが作成されます。

次に、カスタムレイアウトクラスを適切なキーに簡単にマッピングします:

namespace App\Casts;

class MyFlexibleCast extends FlexibleCast
{
    protected $layouts = [
        'wysiwyg' => \App\Nova\Flexible\Layouts\WysiwygLayout::class,
        'video' => \App\Nova\Flexible\Layouts\VideoLayout::class,
    ]
}

さらに制御が必要な場合は、代わりにgetLayoutMappings メソッドをオーバーライドできます。

レイアウトコレクション

FlexibleCast キャストと HasFlexible トレイトから返されるコレクションは、元の Illuminate\Support\Collection を拡張しています。これらのカスタムレイアウトコレクションは find(string $name) メソッドを公開し、指定されたレイアウト $name を持つ最初のレイアウトを返します。

レイアウトインスタンス

レイアウトは一種の 擬似モデル です。Laravel の HasAttributes トレイトを使用しているため、レイアウトの属性にアクセサやミューテータを定義できます。さらに、以下のメソッドを使用してレイアウトのプロパティにアクセスすることも可能です:

name()

レイアウトの名前を返します。

title()

レイアウトのタイトル（Nova に表示されるもの）を返します。

key()

レイアウトのユニークキー（レイアウトの一意識別子）を返します。

さらに進む

フレキシブルコンテンツフィールドを使用していると、上記の基本では不十分なユースケースにすぐに遭遇するでしょう。そのため、このパッケージは拡張可能な方法で開発されており、フィールドとその出力にカスタム動作や機能を簡単に追加できます。

カスタムレイアウトクラス

addLayout の定義がかなり長くなることがあります。また、他の Flexible フィールドと共有したい場合もあるでしょう。その答えは、レイアウトを独自のクラスに抽出することです。詳細はドキュメントをご覧ください。

定義済みプリセットクラス

再利用可能なレイアウトクラスに加えて、Flexible フィールド用の Preset クラスを作成することもできます。これにより、Flexible フィールド全体をどこでも再利用できるようになります。また、条件付きでレイアウトを追加するなど、Flexible フィールドを動的にするのも容易になります。そして最後に、Flexible フィールドに多数の addLayout 定義がある場合、Nova リソースクラスをクリーンに保つこともできます。詳細はドキュメントをご覧ください。

カスタムリゾルバークラス

デフォルトでは、フィールドはモデルのテーブル上の JSON カラム を利用します。場合によっては、このフィールドを使用したいが、何らかの理由で JSON 属性が適切でないことがあります。たとえば、値を別のテーブルに保存したい場合（つまり、従来の BelongsToMany や HasMany フィールドの代わりに Flexible Content フィールドを使用する場合）などです。ご安心ください、対応しています！

独自のリゾルバークラスを作成して、フィールドにコンテンツの保存と取得方法を指示します。基本的には get と set の2つのシンプルなメソッドを含むだけです。詳細はドキュメントをご覧ください。

nova-page での使用法

当社の別のパッケージ、nova-page をご存知かもしれません。これは、個別にモデルを宣言せずに「概要」ページなどの静的ページを編集できる Nova ツールです。多くの場合、Flexible Content フィールドが役立ちます。ご心配なく、両方のパッケージは問題なく連携します！まず nova ページテンプレート を作成し、テンプレートのフィールドにフレキシブルコンテンツを追加します。

ドキュメントで説明されているように、blade ビューで {{ Page::get('attribute') }} を使用して nova-page の静的コンテンツにアクセスできます。このようにフレキシブルコンテンツを要求すると、生の JSON 文字列が返されますが、これはもちろんあまり役に立ちません。代わりに、ページテンプレートに Whitecube\NovaFlexibleContent\Concerns\HasFlexible トレイトを実装するだけで、Page::flexible('attribute') ファサードメソッドが公開され、フレキシブルコンテンツの変換が処理されます。

namespace App\Nova\Templates;

// ...
use Whitecube\NovaFlexibleContent\Concerns\HasFlexible;

class Home extends Template
{
    use HasFlexible;

    // ...
}

💖 スポンサーシップ

このパッケージを本番アプリケーションで利用している場合は、スポンサーになることをご検討ください！それが、私たちが愛することを続けるための最良の方法です。つまり、素晴らしいオープンソースソフトウェアを作り続けることです。

貢献

改善点の提案、新機能のリクエスト、バグ修正はお気軽にどうぞ。まだまだ改善の余地はたくさんあるはずです。便利なプルリクエストがあれば、ぜひマージさせていただきます。

ありがとう！

ユニットテスト

新機能の追加やバグ修正の際には、対応するユニットテストを追加してください。現在のテストセットは限られていますが、追加されるユニットテストごとにパッケージの品質が向上します。

PHPUnit を実行するには、composer test を呼び出してください。

❤️を込めてオープンソースのために

Whitecube では、日々の業務で多くのオープンソースソフトウェアを利用しています。そのため、何かをお返しする機会があれば、とても嬉しく思います！

このささやかな貢献を楽しんでいただき、プロジェクトで役立つようであれば、ぜひお知らせください。最新情報は Twitter をフォローしてください！