Inicio
NexoPOS

Generando clase

CRUD es un estilo arquitectónico de software relacionado con las cuatro operaciones básicas del almacenamiento persistente (Crear, Leer, Actualizar, Eliminar). Esto es un atajo para poder manipular datos. NexoPOS incluye funcionalidades integradas que te ayudan a crear componentes CRUD.

Antes de continuar con esta guía, creemos que ya sabes cómo:

  • Crea un módulo para NexoPOS
  • Crea una ruta para un módulo en NexoPOS
  • Crea un menú para un módulo en NexoPOS
  • Crea una migración para un módulo en NexoPOS

Estos son necesarios para comprender lo que seguirá a lo largo de esta guía.

¿Cómo funciona eso?

Al crear un componente CRUD, NexoPOS creará una clase que extiende un servicio CRUD base. Este último es responsable de crear consultas SQL sin formato para la base de datos y, a veces, utiliza el modelo proporcionado cuando es necesario. Durante la generación, NexoPOS analizará la tabla (si existe) y creará las columnas para la tabla y los formularios. Más adelante, después de la generación, puedes personalizar tu componente CRUD restringiendo ciertas funciones, cambiando las etiquetas de las columnas, mutando los datos de post y put, y muchas más.

Cómo generar un componente CRUD

Para generar un componente CRUD, necesitamos usar la CLI. NexoPOS tiene un comando que ayuda a generar un componente CRUD para un módulo en poco tiempo. Usaremos el siguiente comando:

php artisan make:crud {identifier}

Donde {identifier} se reemplaza por su identificador de módulo real (namespace). Si se omite el identificador, el componente Crud se creará para NexoPOS en la carpeta «app/Crud».

Una vez que se inicie el proceso, se te harán algunas preguntas para crear tu componente CRUD:

Nombre de recurso único

El nombre de recurso único describe cómo se denomina una sola entidad de tu componente CRUD. Por ejemplo, si creas un componente CRUD para Books, el nombre de recurso único será “Book”.

image-2

Nombre de la tabla utilizada

Cada componente CRUD necesita una tabla donde opere. Aquí se te pide que proporciones un nombre para tu tabla. Debiste haber creado esa tabla usando la guía de migración.

Ruta principal hacia el recurso

Esta es la ruta relativa que lleva a las tablas. Debe ser relativa a la raíz del dominio. En nuestro caso, nos gustaría que nuestros libros estuvieran disponibles en /dashboard/foobar/books. Así que esa es la ruta principal que usaremos.

También debemos asegurarnos de haber creado esas rutas dentro de nuestros módulos w.

Namespace o identificador CRUD

El identificador CRUD ayuda a NexoPOS a reconocer el recurso y a saber cómo ponerlo a disposición cuando se solicite. Al crear el componente CRUD, se te pedirá que proporciones un nombre de identificador único. Ten en cuenta que todos los NexoPOS están prefijados con «ns.», por lo que este es un prefijo reservado. Para nuestro ejemplo actual, el identificador de nuestro componente CRUD puede ser:

foobar.books

Modelo

Debes crear un modelo para tu módulo dentro de la carpeta «Models». El nombre de ese modelo (incluyendo el espacio de nombres) debe proporcionarse como un valor para el modelo. Suponiendo que nuestro modelo «Book» está disponible bajo el siguiente espacio de nombres «Modules\FooBar\Models\Book», ese será el valor que proporcionaremos.

Al crear un modelo, asegúrate de que herede de la clase NsModel en lugar del modelo predeterminado de Laravel. El motivo es garantizar que tu módulo sea compatible con el módulo multitienda. Si no tienes previsto algo así, puedes usar el modelo de Laravel predeterminado.

Creando Relaciones

Si tu módulo tiene una relación con un módulo externo, puedes definir esa relación al generar tu componente CRUD. Las relaciones te exigen proporcionar (en este orden y separadas con coma):

  • en nuestro ejemplo, nuestra tabla puede estar relacionada con la tabla del usuario, por lo que «nexopos_users» es la tabla foránea.
  • foreign_key: es la clave en nuestro “foobar_books” que enlaza con “nexopos_users”. En nuestro ejemplo, es “author”, que es el ID de los usuarios que insertaron el libro en el sistema.
  • local_key: la clave en «nexopos_users» se utiliza como referencia para la unión. Usaremos aquí «id».

Puedes definir más relaciones; cuando termines, escribe "S" para omitir esa sección.

Columnas rellenables

Al insertar o actualizar una entrada, estas columnas se completarán explícitamente y las demás se ignorarán. Aquí puedes definir las columnas separadas por comas. Si no quieres imponer esa restricción, puedes escribir «S» para omitirla.

Después de esto, el archivo se generará dentro de su módulo.

Registro de componentes CRUD

Para que NexoPOS tenga conocimiento del componente CRUD que acaba de crearse, es necesario registrarlo. Registrar CRUD implica agregar tu CRUD a la pila de CRUD registrados. Eso se realizará utilizando el hook dentro del método «register» de tu proveedor de servicios, con el siguiente identificador:

<?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 **/ );
    }
}

La devolución de llamada que podemos usar puede apuntar a un archivo separado o a la misma clase. Usemos un método de la misma clase para registrar nuestro componente 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
        }
    }
}

Al comprobar si se proporciona nuestro identificador CRUD, si no hay una coincidencia, es necesario devolver el identificador tal como se proporcionó en un parámetro. Este podría ser el identificador de otro CRUD creado por otro módulo y, si no se devuelve el identificador, se romperá la pila de CRUD.

Tenga en cuenta que lo que se realiza es principalmente para la biblioteca de frontend (Vue). Ahora necesitamos crear una ruta y renderizar ya sea la tabla o el formulario.

Renderizando la tabla

Primero necesitamos crear una ruta y usar un controlador (o crear uno nuevo) para nuestra instancia de CRUD. En nuestro ejemplo, crearemos una ruta que se vea así.

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

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

Ahora necesitamos actualizar el método "bookList" en el controlador que hemos seleccionado para esta ruta. Dentro del método, simplemente devolveremos el resultado del método estático table así.

<?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();
    }
}

El método "table" acepta un arreglo que te permite personalizar la tabla. Por ejemplo, aquí tienes la lista de índices compatibles para tu arreglo:

  • Título: Asegurará que puedas personalizar el título de la tabla
  • Se utilizará para describir la tabla CRUD.
  • src: Si desea personalizar la URL de origen utilizada por la biblioteca del frontend para recuperar entradas.
  • createUrl: Se utilizará para sobrescribir la URL que lleva a los formularios de creación
  • queryParams: cualquier parámetro personalizado que te gustaría enviar a la instancia de Crud. Esto puede ser útil para aplicar filtros personalizados.

Renderizando un formulario para la creación

Puedes renderizar 2 tipos de formularios: un formulario que se usa al crear una nueva entrada y un formulario que se usa al editar una entrada existente. Esta sección se centra en cómo crear un formulario que se utiliza para crear una entrada. Al igual que al mostrar una tabla, aquí necesitarás crear una ruta que lleve al formulario. Usaremos la siguiente configuración de ruta:

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

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

Aquí, usaremos el slug: /dashboard/foobar/books/create, pero puede terminar con lo que quieras (new, add, etc.). En el método createBook, usaremos la instancia Crud y usaremos su método estático "form" para devolver un formulario como este:

<?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();
    }
}

Renderizando un formulario para la modificación

Un formulario para realizar una entrada de modificación es un poco diferente del formulario que se usa para crear una entrada. Aquí, al crear una ruta hacia el método del controlador que se encargará de ello, pasaremos un parámetro de ruta que es el identificador de la entrada, o también puede ser un model binding. Ahora, al usar el método “form”, necesitamos pasar el modelo que es la propia entrada. Así es como procederemos primero con respecto a la ruta.


<?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' ]);

Ahora, dentro del método "editBook", vincularemos el libro y se lo pasaremos al método "form" de BookCrud de la siguiente manera:

<?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 );
    }
}

Cuando no se proporciona un, el método "form" asigna "null" de forma predeterminada para el primer parámetro. En el segundo parámetro, un array para configurar el formulario. Estos son los índices admitidos para el array de configuración.

  • Para proporcionar un título para el formulario.
  • Descripción: Para describir la forma.
  • src: Para cambiar la URL de origen utilizada por la biblioteca del front-end para interactuar con la instancia de Crud.
  • returnUrl: Esta URL se utiliza como URL de retorno a la lista de entradas. También se utiliza para redirigir automáticamente al usuario cuando la modificación se ha realizado correctamente.
  • submitMethod: Si por alguna razón desea que NexoPOS cambie el método utilizado para actualizar o crear una entrada, puede definirlo aquí. Tenga en cuenta que se admiten “post” y “put”.

Estos parámetros también son efectivos al usar el método "form" sin proporcionar una entrada, pero allí necesitarás pasar como valor para el primer parámetro "null".

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

O también puedes usar parámetros con nombre como este:

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