Accueil
NexoPOS

Génération de classe

CRUD est un style d’architecture logicielle concernant les quatre opérations de base du stockage persistant (Créer, Lire, Mettre à jour, Supprimer). C’est un raccourci pour pouvoir manipuler des données. NexoPOS est livré avec des fonctionnalités intégrées qui vous aident à créer des composants CRUD.

Avant de poursuivre avec ce guide, nous pensons que vous savez déjà comment :

  • Créer un module pour NexoPOS
  • Créez un itinéraire pour un module sur NexoPOS
  • Créez un menu pour un module sur NexoPOS
  • Créer une migration pour un module sur NexoPOS

Ceux-ci sont nécessaires pour comprendre ce qui suivra tout au long de ce guide.

Comment ça marche ?

Lors de la création d’un composant CRUD, NexoPOS créera une classe qui étend un service CRUD de base. Celui-ci est chargé de générer des requêtes SQL brutes pour la base de données et utilise parfois le modèle fourni lorsque cela est nécessaire. Pendant la génération, NexoPOS analysera la table (si elle existe) et créera les colonnes pour la table et les formulaires. Ensuite, après la génération, vous pouvez personnaliser votre composant CRUD en limitant certaines fonctionnalités, en modifiant les libellés des colonnes, en transformant les données post et put, et bien plus encore.

Comment générer un composant CRUD

Pour générer un composant CRUD, nous devons utiliser la CLI. NexoPOS dispose d’une commande qui permet de générer rapidement un composant CRUD pour un module. Nous allons utiliser la commande suivante :

php artisan make:crud {identifier}

Là où {identifier} est remplacé par votre identifiant de module réel (espace de noms). Si l’identifiant est omis, le composant Crud sera créé pour NexoPOS dans le dossier « app/Crud ».

Une fois le processus lancé, on vous posera quelques questions afin de créer votre composant Crud :

Nom de la ressource unique

Le nom de ressource unique décrit comment une seule entité de votre composant CRUD est appelée. Par exemple, si vous créez un composant CRUD pour des Livres, le nom de ressource unique sera « Livre ».

image-2

Nom de la table utilisé

Chaque composant CRUD a besoin d’une table sur laquelle il opère. Ici, il vous est demandé de fournir un nom pour votre table. Vous auriez dû créer cette table à l’aide du guide de migration.

Route principale vers la ressource

Ceci est le chemin relatif qui mène aux tables. Il doit être relatif à la racine du domaine. Dans notre cas, nous souhaitons que nos livres soient accessibles à l’adresse /dashboard/foobar/books. C’est donc la route principale que nous utiliserons.

Nous devons également nous assurer d’avoir créé de telles routes w dans nos modules.

Espace de noms ou identifiant CRUD

L’identifiant CRUD aide NexoPOS à être conscient de la ressource et à savoir comment la rendre disponible lorsqu’elle est demandée. Lors de la création du composant CRUD, il vous sera demandé de fournir un nom d’identifiant unique. Notez que tous les NexoPOS sont préfixés par « ns. », ce qui constitue un préfixe réservé. Pour notre exemple actuel, l’identifiant de notre composant CRUD peut être :

foobar.books

Modèle

Vous devez créer un modèle pour votre module dans le dossier « Models ». Le nom de ce modèle (y compris l’espace de noms) doit être fourni comme valeur pour le modèle. En supposant que notre modèle « Book » est disponible sous l’espace de noms suivant « Modules\FooBar\Models\Book », c’est cette valeur que nous fournirons.

Lors de la création d’un modèle, veuillez vous assurer qu’il étend la classe NsModel au lieu du modèle Laravel par défaut. La raison en est de garantir que votre module est compatible avec le module multiboutique. Si ce n’est pas quelque chose que vous prévoyez, vous pouvez utiliser le modèle Laravel par défaut.

Créer des relations

Si votre module a une relation avec un module externe, vous pouvez définir cette relation lors de la génération de votre composant Crud. Les relations vous obligent à fournir (dans cet ordre, séparées par des virgules) :

  • dans notre exemple, notre table peut être liée à la table de l’utilisateur, donc « nexopos_users » est la table étrangère.
  • foreign_key : c’est la clé dans notre « foobar_books » qui fait le lien avec « nexopos_users ». Dans notre exemple, il s’agit de « author », qui correspond à l’ID des utilisateurs ayant inséré le livre dans le système.
  • local_key : la clé sur « nexopos_users » utilisée comme référence pour la jonction. Nous utiliserons ici « id ».

Vous pouvez définir d’autres relations une fois que vous avez terminé. Tapez « S » pour ignorer cette section.

Colonnes remplissables

Lors de l’insertion ou de la mise à jour d’une entrée, ces colonnes seront explicitement remplies, et les autres seront ignorées. Ici, vous pouvez définir les colonnes séparées par des virgules. Si vous ne souhaitez pas imposer cette restriction, vous pouvez saisir « S » pour ignorer.

Après cela, le fichier sera généré dans votre module.

Enregistrement du composant CRUD

Pour que NexoPOS soit informé du composant CRUD qui vient d’être créé, nous devons l’enregistrer. Enregistrer le CRUD implique d’ajouter votre CRUD à la pile des CRUD enregistrés. Cela sera fait à l’aide du hook dans la méthode « register » de votre fournisseur de services, avec l’identifiant suivant :

<?php
namespace Modules\FooBar\Providers;

use Illuminate\Support\ServiceProvider;
use App\Classes\Hook;

class ServiceProvider extends ServiceProvider
{
    public function register()
    {
        Hook::addFilter( 'ns-crud-resource', /** your callback here **/ );
    }
}

Le rappel que nous pouvons utiliser peut pointer vers un fichier distinct ou vers la même classe. Utilisons une méthode de la même classe pour enregistrer notre composant CRUD.

<?php
namespace Modules\FooBar\Providers;

use Illuminate\Support\ServiceProvider;
use App\Classes\Hook;
use Modules\FooBar\Crud\BookCrud;

class ModuleServiceProvider extends ServiceProvider
{
    public function register()
    {
        Hook::addFilter( 'ns-crud-resource', [ $this, 'registerCrud' ]);
    }
    
    public function registerCrud( $identifier )
    {
        switch( $identifier ) {
            case 'foobar.books': return BookCrud::class; 
            default: return $identifier; // required
        }
    }
}

Lors de la vérification si notre identifiant CRUD est fourni, s’il n’y a pas de correspondance, il est nécessaire de renvoyer l’identifiant tel qu’il a été fourni en paramètre. Il peut s’agir de l’identifiant d’un autre CRUD créé par un autre module, et ne pas renvoyer l’identifiant rompra la pile CRUD.

Notez que ce qui est effectué concerne principalement la bibliothèque frontend (Vue). Maintenant, nous devons créer une route et afficher soit le tableau, soit le formulaire.

Rendu du tableau

Nous devons d’abord créer une route et utiliser un contrôleur (ou en créer un nouveau) pour notre instance CRUD. Dans notre exemple, nous allons créer une route qui ressemble à ceci.

<?php
use Moduels\Http\Controllers\FooBarController;

Route::get( '/dashboard/foobar/books', [ FooBarController::class, 'bookList' ]);

Maintenant, nous devons mettre à jour la méthode « bookList » sur le contrôleur que nous avons sélectionné pour cette route. Dans la méthode, nous allons simplement renvoyer la sortie de la méthode statique table comme ceci.

<?php
namespace Modules\FooBar\Http\Controllers;

use App\Http\Controllers\DashboardController;
use Modules\FooBar\Crud\BookCrud;

class FooBarController extends DashboardController
{
    public function bookList()
    {
         return BookCrud::table();
    }
}

La méthode « table » accepte un tableau qui vous permet de personnaliser le tableau. Par exemple, voici la liste des index pris en charge pour votre tableau :

  • Titre : vous permettra de personnaliser le titre du tableau
  • Description : sera utilisé pour décrire le tableau des données.
  • src : Si vous souhaitez personnaliser l’URL source utilisée par la bibliothèque frontend pour récupérer les entrées.
  • createUrl : Sera utilisé pour remplacer l’URL qui mène aux formulaires de création
  • queryParams : paramètres personnalisés que vous souhaitez envoyer à l’instance Crud. Cela peut être utile pour appliquer des filtres personnalisés.

Rendu d’un formulaire pour la création

Vous pouvez afficher 2 types de formulaires : un formulaire utilisé lors de la création d’une nouvelle entrée et un formulaire utilisé lors de la modification d’une entrée existante. Cette section se concentre sur la manière de créer un formulaire utilisé pour créer une entrée. Comme pour l’affichage d’un tableau, vous devrez ici créer une route qui mène vers le formulaire. Nous utiliserons la configuration de route suivante :

<?php
use Moduels\Http\Controllers\FooBarController;

Route::get( '/dashboard/foobar/books', [ FooBarController::class, 'bookList' ]);
Route::get( '/dashboard/foobar/books/create', [ FooBarController::class, 'createBook' ]);

Ici, nous allons utiliser le slug : /dashboard/foobar/books/create, mais il peut se terminer comme vous voulez (new, add, etc.). Dans la méthode createBook, nous utiliserons l’instance Crud et sa méthode statique « form » pour renvoyer un formulaire comme ceci :

<?php
namespace Modules\FooBar\Http\Controllers;

use App\Http\Controllers\DashboardController;
use Modules\FooBar\Crud\BookCrud;

class FooBarController extends DashboardController
{
    public function createBook()
    {
         return BookCrud::form();
    }
}

Rendu d’un formulaire pour modification

Un formulaire permettant d’effectuer une entrée de modification est un peu différent du formulaire utilisé pour créer une entrée. Ici, lors de la création de l’itinéraire vers la méthode du contrôleur qui gérera cette opération, nous transmettrons un paramètre d’itinéraire qui correspond à l’identifiant de l’entrée, ou il peut également s’agir d’un liaison de modèle. Ensuite, lors de l’utilisation de la méthode « form », nous devons transmettre le modèle correspondant à l’entrée elle-même. Voici comment nous allons procéder d’abord concernant l’itinéraire.


<?php
use Moduels\Http\Controllers\FooBarController;

Route::get( '/dashboard/foobar/books', [ FooBarController::class, 'bookList' ]);
Route::get( '/dashboard/foobar/books/create', [ FooBarController::class, 'createBook' ]);
Route::get( '/dashboard/foobar/books/{book}', [ FooBarController::class, 'editBook' ]);

Désormais, dans la méthode « editBook », nous allons lier le livre et le transmettre à la méthode « form » de BookCrud comme suit :

<?php
namespace Modules\FooBar\Http\Controllers;

use App\Http\Controllers\DashboardController;
use Modules\FooBar\Crud\BookCrud;
use Modules\FooBar\Models\Book;

class FooBarController extends DashboardController
{
    public function editBook( Book $book )
    {
         return BookCrud::form( $book );
    }
}

Lorsque aucun « an » n’est fourni, la méthode « form » affecte par défaut « null » au premier paramètre. Pour le deuxième paramètre, il s’agit d’un tableau permettant de configurer le formulaire. Voici les index pris en charge pour le tableau de configuration.

  • Pour fournir un titre au formulaire.
  • Description : Pour décrire le formulaire.
  • src : Pour modifier l’URL source utilisée par la bibliothèque front-end pour interagir avec l’instance Crud.
  • returnUrl : Cette URL est utilisée comme URL de retour vers la liste des entrées. Elle sert également à rediriger automatiquement l’utilisateur lorsque la modification a été effectuée avec succès.
  • submitMethod : Si, pour une raison quelconque, vous souhaitez que NexoPOS modifie la méthode utilisée pour mettre à jour/créer une entrée, vous pouvez la définir ici. Notez que « post » et « put » sont pris en charge.

Ces paramètres sont également efficaces lors de l’utilisation de la méthode « form » sans entrée fournie, mais vous devrez alors passer comme valeur pour le premier paramètre « null ».

return BookCrud::form( null, $config );

Ou vous pouvez utiliser des paramètres nommés comme ceci :

return BookCrud::form(
    config: $config
);