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

Par défaut, le champ tire parti d'une colonne JSON sur la table de votre modèle. Dans certains cas, vous aimeriez vraiment utiliser ce champ, mais pour une raison quelconque, un attribut JSON n'est pas la solution. Par exemple, vous pourriez vouloir stocker les valeurs dans une autre table (ce qui signifie que vous utiliserez le champ Contenu Flexible au lieu d'un champ traditionnel BelongsToMany ou HasMany). Pas de souci, nous avons ce qu'il vous faut !

Indiquez au champ comment stocker et récupérer son contenu en créant votre propre classe Resolver, qui contient essentiellement deux méthodes simples : get et set. Consultez la documentation pour plus d'informations.

Utilisation avec nova-page

Vous avez peut-être entendu parler d'un de nos autres packages, nova-page, qui est un outil Nova permettant de modifier des pages statiques telles qu'une page "À propos" (ou similaire) sans avoir à déclarer un modèle pour celle-ci individuellement. Le plus souvent, le champ Contenu Flexible s'avère très utile. Ne vous inquiétez pas, les deux packages fonctionnent bien ensemble ! Créez d'abord un modèle de page nova et ajoutez un contenu flexible aux champs du modèle.

Comme expliqué dans la documentation, vous pouvez accéder au contenu statique de nova-page dans vos vues Blade en utilisant {{ Page::get('attribute') }}. En demandant le contenu flexible de cette manière, vous obtiendrez une chaîne JSON brute décrivant le contenu flexible, ce qui n'est évidemment pas très utile. À la place, vous pouvez simplement implémenter le trait Whitecube\NovaFlexibleContent\Concerns\HasFlexible sur vos modèles de page, ce qui exposera la méthode de façade Page::flexible('attribute') et prendra en charge la transformation du contenu flexible.

namespace App\Nova\Templates;

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

class Home extends Template
{
    use HasFlexible;

    // ...
}

💖 Sponsoring

Si vous dépendez de ce package dans vos applications de production, envisagez de nous parrainer ! C'est le meilleur moyen de nous aider à continuer à faire ce que nous aimons : créer des logiciels open source de qualité.

Contribuer

N'hésitez pas à suggérer des améliorations, demander de nouvelles fonctionnalités ou corriger vous-même des bugs. Nous sommes certains qu'il reste encore beaucoup d'améliorations à apporter, et nous serions ravis de fusionner des pull requests utiles.

Merci !

Tests unitaires

Lorsque vous ajoutez une nouvelle fonctionnalité ou corrigez un bug, veuillez ajouter les tests unitaires correspondants. L'ensemble actuel de tests est limité, mais chaque test unitaire ajouté améliorera la qualité du package.

Exécutez PHPUnit en appelant composer test.

Fait avec ❤️ pour l'open source

Chez Whitecube, nous utilisons beaucoup de logiciels open source dans notre travail quotidien. Alors quand nous avons l'opportunité de redonner quelque chose, nous sommes super excités !

Nous espérons que vous apprécierez cette petite contribution de notre part et nous serions ravis d'avoir de vos nouvelles ([email protected]) si vous la trouvez utile dans vos projets. Suivez-nous sur Twitter pour plus de mises à jour !