Voyager, le panneau d’administration Laravel (Partie 3) – Pour aller plus loin

Voyager, le panneau d’administration Laravel (Partie 3) – Pour aller plus loin

Tech web
|

  Pour ce tutoriel, j’ai utilisé la version 5.4 de Laravel, la version 0.11 de Voyager et Windows 10 ; il se peut qu’il y ait des différences si vous utilisez d’autres versions.

 

Nous avons vu comment installer Voyager et nous avons commencé à explorer les fonctionnalités qu’il propose. Continuons l'exploration 😎

  1. Partie 1 – Présentation et installation
    1. Voyager ? Késako ?
    2. Installation de Laravel
    3. Installation de Voyager
  2. Partie 2 – Premiers pas
    1. Les posts
    2. Les utilisateurs et les rôles
    3. La gestion de la base de données et du BREAD
  3. Partie 3 – Pour aller plus loin
    1. Les menus
    2. Les validations
    3. Les relations
    4. Les widgets

Les menus

Dans l’article précédent, nous avons créé une entité permettant de gérer des biens immobiliers. Malheureusement, via votre menu vous ne trouverez pas de lien vous menant à la page des biens immobiliers  Si nous voulons y ajouter cet onglet, nous devons le faire « manuellement ». Pour cela, allons dans « Tools » puis « Menu Builder ».

Gestion des menus dans Voyager

 

Nous allons modifier le menu existant, le menu « admin ». Cliquons sur « Builder », puis « New Menu Item ». Choisissons un nom, ajoutons le chemin de la page de gestion des biens immobiliers et, pour égayer ce panneau d’administration morne, choisissons une jolie petite icône (la liste des icônes est disponible ici).

Edition d'un menu Voyager

 

Notre onglet est dorénavant accessible via le menu « admin », vous pouvez le drag N drop si vous voulez le placer plus haut dans le menu.

Menu Builder

 

Si vous avez besoin d’ajouter ce menu dans une de vos views, il vous suffira d’écrire :

menu(‘admin’)

 

« admin » est bien entendu le nom de votre menu. Dans l'exemple ci-dessous, je vais donc afficher mon menu admin dans la vue ressources/views/welcome.blade.php.

Insérer le menu dans la view

 

Si je me dirige sur la page d’accueil (//localhost:3000/), je vois bel et bien mon menu (tout moche) à l’endroit où j’ai mis mon bout de code.

Affichage du menu en frontend

 

Si vous avez envie de customiser ce menu dans votre view, vous pouvez le faire de deux manières différentes. Soit en modifiant directement le menu actuel avec du CSS, soit en recréant vous-même le menu à l’aide de foreach.

Pour cette deuxième méthode, nous allons, pour l'exemple, nous rendre dans notre view welcome.blade.php et y ajouter la ligne suivante :

<? menu('admin', 'test') ?>

 

Rien ne se passe, car la view « test » n’existe pas encore. Nous devons la créer (test.blade.php) et y ajouter le code suivant :

<ul>
    @foreach($items as $menu_item)
        <li><a href="{{ $menu_item->url }}">{{ $menu_item->title }}</a></li>
    @endforeach
</ul>

 

Et comme par magie, notre menu s’affiche sur notre page d’accueil 😊 Si vous voulez modifier votre menu, vous pouvez le faire directement dans test.blade.php. Cette méthode est certes un peu plus compliquée que la première (qui consistait à seulement modifier le CSS), mais elle permet de faire des modifications plus complexes.

Pour plus d’informations sur les menus, je vous invite à lire la documentation officielle.

 

Les validations

Voyager permet d’ajouter des validations dans le BREAD, avec ce système vous pourrez avoir un meilleur contrôle sur les données.

Reprenons l’exemple des biens immobiliers. Si nous voulons que le name soit obligatoirement rempli, nous devons rajouter dans les « Optional Détails » :

{
    "validation": {
        "rule": "required"
    }
}

 

Si nous voulons que le name soit rempli et qu’il contienne 3 lettres au minimum, nous devons rajouter la condition suivante  :

{
    "validation": {
        "rule": "required|min:3"
    }
}

 

Bref, je suis sûr que vous avez compris comment ça fonctionne, on peut chaîner les conditions de validation. Si les messages d’erreur ne vous conviennent pas, vous pouvez les modifier directement dans ces validations. Voici un petit exemple.

{
    "validation": {
        "rule": "required|min:3",
        "messages": {
            "required": "Vous devez spécifier un nom.",
            "min": "Le nom doit contenir au moins trois caractères."
        }
    }
}

 

Essayons de modifier un de nos biens immobiliers et donnons-lui comme nom « TE ».

test d'une règle de validation

 

Parfait ! Le message d’erreur souhaité apparait ! Voilà, nous avons fait le tour des validations. Je ne peux que vous conseiller de ne pas les oublier, car si vous ne mettez pas un require sur un champ dont vous avez coché la case « Not Null » dans la base de données, et que par mégarde vous oubliez de le remplir, vous n’aurez pas un message d’erreur tout propre mais une erreur Laravel beaucoup moins esthétique ☹

 

Les relations

Savoir créer des entités c’est bien, mais pouvoir les lier entre-elles c’est encore mieux ! Reprenons l’exemple des biens immobiliers, et essayons de les lier à des catégories.

Nous allons commencer par créer une table « imocats » avec les champs suivants :

Relation - création d'une nouvelle table

 

Rien de bien fou, en plus de l’« id », nous avons un champ « name » qui va contenir le nom de la catégorie de biens immobiliers et les champs Timestamps de base (qu’on peut ajouter grâce au bouton du bas).

Nous allons créer deux catégories de biens immobiliers. Pour ce faire il faut créer un BREAD de la table « imocats ». Au niveau de la configuration du BREAD, nous allons juste changer le type de donnée pour le champ « name » et lui mettre un champ texte, nous pouvons laisser le reste par défaut.

Maintenant que le BREAD est fonctionnel, nous allons devoir changer les droits du rôle admin, afin que l'on puisse y accéder avec notre compte administrateur. Pour ce faire, dirigeons-nous dans la gestion des rôles, puis éditons le rôle admin en cochant les cases suivantes :

user roles

 

Pour accéder à la gestion des « imocats » (nom barbare de nos catégories de biens immobiliers), vous pouvez utiliser l’URL du slug : //localhost:3000/admin/imocats. Ajoutons deux catégories :

Ajout d'une nouvelle catégorie

 

Retournons dans le menu « database » et éditons la table « immobiliers ». Nous allons lui ajouter un champ « imocat_id » qui contiendra l’ID de la catégorie liée au bien immobilier.

Relation - Foreign Key

 

Pour ce type de relation (belongsTo), nous devons modifier le BREAD de la table « immobiliers » en configurant le champ « imocat_id ». Concernant son type de champ, nous allons choisir un « Select Dropdown » et dans les « Optional Details », nous allons lui spécifier la relation en y ajoutant le code suivant :

{
    "relationship": {
        "key": "id",
        "label": "name"
    }
}

BREAD

 

Il reste encore une dernière chose à faire, créer la relation dans le model. Rendons-nous dans le model «app\Immobilier.php » et ajoutons la fonction suivante :

public function imocatId(){
    return $this->belongsTo(Imocat::class);
}

 Modification du model

 

Essayons de créer un nouveau bien immobilier, le champ permettant de choisir la catégorie est bel et bien présent !

Relation - belongsTo

Voilà pour ce qui est des relations simples 😊 On attaque les relations multiples (belongsToMany) ?

Reprenons notre exemple de biens immobiliers. Actuellement, nous pouvons lier qu’une seule catégorie par bien immobilier. Nous allons changer le système afin qu’on puisse y lier plusieurs catégories par bien. Commençons par créer une nouvelle imocat que nous allons appeler « Avec jardin ».

Relation - belongsToMany

 

Créons la table intermédiaire entre « immobiliers » et « imocats », appelons-la « imocat_immobilier ». Cette table aura trois champs :

  •          immobilier_imocat_id – INTEGER – Auto Increment – PRIMARY
  •          immobilier_id – INTEGER – INDEX
  •          imocat_id – INTEGER - INDEX

Modification base de données - BelongsToMany

 

Avant de modifier le BREAD de « immobiliers », nous allons éditer la table « immobiliers » et remplacer le champ « imocat_id » par « imocats ».

Edition table immobiliers

 

Dans le BREAD de « immobiliers », choisissons un « Select Multiple » pour « imocats » et ajoutons-lui une relation avec le code suivant :

{
    "relationship": {
        "key": "id",
        "label": "name",
        "page_slug": "admin/imocats"
    }
}

 

BREAD - relations

Il ne nous reste plus qu’à créer la relation belongsToMany au sein des models.

Dans le model app/Imocat.php, on va lui ajouter la fonction immobiliers().

public function immobiliers(){
        $pivotTable = 'immobilier_imocat';
        return $this->belongsToMany(Immobilier::class, $pivotTable, 'imocat_id','immobilier_id');
 }

 

Et dans le model app/Immobilier, la fonction imocats().

public function imocats(){
        $pivotTable = 'immobilier_imocat';
        return $this->belongsToMany(Imocat::class, $pivotTable, 'immobilier_id', 'imocat_id');
}

 

belongsToMany - model laravel

 

On aurait pu ne pas ajouter la fonction « immobiliers() » dans le model Imocat, mais en le faisant, nous sommes prêt pour l’ajout d’une relation dans les deux sens.

Rendez-vous dans la gestion des biens immobiliers //localhost:3000/admin/immobiliers et éditez un des biens immobiliers. Vous pouvez maintenant lui enregistrer plusieurs catégories 😊

Ajouer plusieurs catégories pour un bien immobilier

 

Les widgets

Si nous ouvrons la page « Dashboard », nous verrons 3 widgets présentant diverses informations. Nous allons voir comment remplacer le widget des pages par un widget nous donnant des informations sur nos biens immobiliers.

Widgets par défaut

 

A l’aide de votre éditeur de texte, rendez-vous dans le fichier config/voyager.php. Dans ce fichier vous allez trouver plusieurs paramètres permettant de configurer votre Voyager. A la ligne 193, vous avez vos trois widgets. Remplacez le dernier ('TCG\\Voyager\\Widgets\\PageDimmer') par la ligne suivante :

'App\\Widgets\\ImmobilierDimmer',

 

Dans app, vous devez créer un répertoire « Widgets » dans lequel vous allez créer le fichier ImmobilierDimmer. Ajoutez-y le code suivant :

namespace App\Widgets;

use App\Immobilier;
use Arrilot\Widgets\AbstractWidget;
use TCG\Voyager\Facades\Voyager;

class ImmobilierDimmer extends AbstractWidget
{
    protected $config = [];

    public function run()
    {
        $count = Immobilier::count();    
        $string = $count == 1 ? 'bien immobilier' : 'biens immobiliers';

        return view('voyager::dimmer', array_merge($this->config, [
            'icon'   => 'voyager-group',
            'title'  => "{$count} {$string}",
            'text'   => "Vous avez {$count} {$string} dans votre base de données. Cliquez sur le bouton pour voir tous vos biens immobiliers.",
            'button' => [
                'text' => 'Voir les biens immobiliers',
                'link' => route('voyager.immobiliers.index'),
            ],
            'image' => voyager_asset('images/widget-backgrounds/03.png'),
        ]));
    }
}

 

Le code n’est pas très compliqué à déchiffrer. On commence par définir son namespace, puis à lister les classes dont nous avons besoin. On crée la classe « ImmobilierDimmer » qui hérite de « AbstractWidget » (une classe créée par Voyager qui permet de créer ces widgets). Puis, dans la fonction run(), on spécifie ce que doit faire le widget. Dans notre cas, on va simplement compter le nombre d’objets immobiliers, puis retourner un petit texte ainsi qu’un lien permettant d’accéder à la gestion des biens immobiliers.

Widget personnalisé

 

Et voilà, votre widget custom fonctionne ! Vous pouvez bien évidemment y ajouter d'autres modifications.

La série consacrée à Voyager est désormais terminée 😊 Je n’ai pas parlé de l’intégration frontend, mais celle-ci est tout à fait standard aux projets Laravel, aucune particuliarité de ce côté :)

  1. Partie 1 – Présentation et installation
    1. Voyager ? Késako ?
    2. Installation de Laravel
    3. Installation de Voyager
  2. Partie 2 – Premiers pas
    1. Les posts
    2. Les utilisateurs et les rôles
    3. La gestion de la base de données et du BREAD
  3. Partie 3 – Pour aller plus loin
    1. Les menus
    2. Les validations
    3. Les relations
    4. Les widgets

 

 Sources

Catégories :
Tech web

Tags :
PHP Laravel

Vous avez aimé cet article ? Suivez-nous sur Facebook pour ne rien manquer !