Un champ Flexible simple et complet pour Laravel Nova, parfait pour des groupes de champs répétés et flexibles.

Démarrage rapide

Voici un guide très condensé pour démarrer au plus vite. Voir la documentation complète sur https://whitecube.github.io/nova-flexible-content

Installer

composer require whitecube/nova-flexible-content

Utilisation

Un champ flexible permet de gérer facilement des groupes de champs répétables et ordonnables. Contrairement à certaines solutions existantes pour Laravel Nova, celui-ci n'a pas de contraintes sur les types de champs que vous pouvez utiliser dans ces groupes. Cela signifie que vous pouvez utiliser tous les types de champs natifs de Laravel Nova, ainsi que les champs créés par la communauté.

Ajouter des layouts

Un layout représente un groupe de champs qui peut être répété à l'intérieur du champ Flexible. Vous pouvez ajouter autant de layouts que vous le souhaitez. Si un seul layout est défini, le champ se comportera comme un simple répéteur, et en ajoutant plusieurs layouts, vous obtiendrez un Contenu Flexible. Les deux concepts sont similaires à leurs cousins dans le plugin ACF de Wordpress.

Les layouts peuvent être ajoutés en utilisant la méthode suivante sur vos champs Flexible :

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

Le paramètre $name est utilisé pour stocker le layout choisi dans la valeur du champ. Choisissez-le judicieusement, vous l'utiliserez probablement pour identifier les layouts dans votre application.

use Whitecube\NovaFlexibleContent\Flexible;

/**
 * Get the fields displayed by the resource.
 *
 * @param  \Illuminate\Http\Request  $request
 * @return array
 */
public function fields(Request $request)
{
    return [
        // ...

        Flexible::make('Content')
            ->addLayout('Simple content section', 'wysiwyg', [
                Text::make('Title'),
                Markdown::make('Content')
            ])
            ->addLayout('Video section', 'video', [
                Text::make('Title'),
                Image::make('Video Thumbnail', 'thumbnail'),
                Text::make('Video ID (YouTube)', 'video'),
                Text::make('Video Caption', 'caption')
            ])
    ];
}

Personnaliser le libellé du bouton

Vous pouvez modifier le texte par défaut du bouton "Ajouter un layout" comme ceci :

Flexible::make('Content')
    ->button('Ajouter quelque chose d'extraordinaire !');

Utiliser les valeurs Flexible dans les vues

Si vous utilisez Laravel 6 et inférieur, ou si vous ne souhaitez pas utiliser les casts, veuillez utiliser un accesseur sur votre modèle avec le trait HasFlexible.

Laravel 7 apporte les casts personnalisés, et les champs de contenu flexible sont le cas d'utilisation parfait pour ceux-ci. Le champ stocke ses valeurs sous forme d'une seule chaîne JSON, ce qui signifie que cette chaîne doit être analysée avant de pouvoir être utilisée dans votre application. Cela peut être fait trivialement en utilisant la classe FlexibleCast de ce package :

namespace App;

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

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

Par défaut, la classe FlexibleCast collectera des instances de base de Layout. Si vous souhaitez mapper les layouts sur des instances de Layout personnalisées, c'est également possible. Créez d'abord un cast flexible personnalisé en exécutant php artisan flexible:cast MyFlexibleCast. Cela créera le fichier dans le répertoire App\Casts.

Ensuite, mappez facilement vos classes de layout personnalisées aux clés appropriées :

namespace App\Casts;

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

Si vous avez besoin de plus de contrôle, vous pouvez surcharger la méthode getLayoutMappings à la place.

La collection de Layouts

Les collections retournées par le cast FlexibleCast et le trait HasFlexible étendent la collection originale Illuminate\Support\Collection. Ces collections de layout personnalisées exposent une méthode find(string $name) qui retourne le premier layout ayant le nom de layout $name donné.

L'instance de Layout

Les Layouts sont une sorte de faux modèles. Ils utilisent le trait HasAttributes de Laravel, ce qui signifie que vous pouvez définir des accesseurs & mutateurs pour les attributs du layout. De plus, il est également possible d'accéder aux propriétés du Layout en utilisant les méthodes suivantes :

name()

Retourne le nom du layout.

title()

Retourne le titre du layout (tel qu'affiché dans Nova).

key()

Retourne la clé unique du layout (l'identifiant unique du layout).

Aller plus loin

Lorsque vous utilisez le champ Contenu Flexible, vous rencontrerez rapidement certains cas d'utilisation où les bases décrites ci-dessus ne suffisent pas. C'est pourquoi nous avons développé le package de manière extensible, permettant d'ajouter facilement des comportements et/ou capacités personnalisés au champ et à sa sortie.

Classes de Layout personnalisées

Parfois, les définitions addLayout peuvent devenir assez longues, ou vous voudrez peut-être les partager avec d'autres champs Flexible. La réponse à cela est d'extraire votre Layout dans sa propre classe. Consultez la documentation pour plus d'informations.

Classes de Preset prédéfinies

En plus des classes de Layout réutilisables, vous pouvez aller plus loin et créer des classes Preset pour vos champs Flexible. Celles-ci vous permettent de réutiliser l'ensemble de votre champ Flexible où vous le souhaitez. Elles facilitent également la création de champs Flexible dynamiques, par exemple si vous souhaitez ajouter des Layouts de manière conditionnelle. Et pour finir, elles ont aussi l'avantage supplémentaire de nettoyer vos classes de ressources Nova, si votre champ Flexible a beaucoup de définitions addLayout. Consultez la documentation pour plus d'informations.

Classes de Resolver personnalisées