Início
NexoPOS

Gerando Classe

CRUD é um estilo de arquitetura de software relacionado às quatro operações básicas de armazenamento persistente (Criar, Ler, Atualizar, Excluir). Isso é um atalho para permitir a manipulação de dados. O NexoPOS vem com funcionalidades integradas que ajudam você a criar componentes de CRUD.

Antes de prosseguir com este guia, acreditamos que você já sabe como:

  • Crie um módulo para o NexoPOS
  • Crie uma rota para um módulo no NexoPOS
  • Crie um menu para um módulo no NexoPOS
  • Crie uma migração para um módulo no NexoPOS

Estes são necessários para entender o que seguirá ao longo deste guia.

Como isso funciona?

Ao criar um componente CRUD, o NexoPOS criará uma classe que estende um serviço base de CRUD. Este último é responsável por criar consultas SQL brutas para o banco de dados e, às vezes, utiliza o modelo fornecido quando necessário. Durante a geração, o NexoPOS irá analisar a tabela (se ela existir) e criar as colunas para a tabela e para os formulários. Depois da geração, você pode personalizar seu componente CRUD restringindo alguns recursos, alterando os rótulos das colunas, mutando os dados de post e put e muito mais.

Como Gerar um Componente CRUD

Para gerar um componente Crud, precisamos usar a CLI. O NexoPOS tem um comando que ajuda a gerar um componente Crud para um módulo em pouco tempo. Vamos usar o seguinte comando:

php artisan make:crud {identifier}

Onde {identifier} é substituído pelo seu identificador de módulo real (namespace). Se o identificador for omitido, o componente Crud será criado para o NexoPOS dentro da pasta “app/Crud”.

Assim que o processo for iniciado, você será solicitado(a) a responder algumas perguntas para criar seu componente Crud:

Nome do Recurso Único

O nome do recurso único descreve como uma única entidade do seu componente CRUD é chamada. Por exemplo, se você criar um componente CRUD para Books, o nome do recurso único será “Book”.

image-2

Nome da Tabela Usado

Cada componente CRUD precisa de uma tabela onde opera. Aqui, você é solicitado a fornecer um nome para sua tabela. Você deveria ter criado essa tabela usando o guia de migração.

Rota Principal Para o Recurso

Este é o caminho relativo que leva às tabelas. Ele deve ser relativo à raiz do domínio. No nosso caso, gostaríamos que nossos Livros estivessem acessíveis em /dashboard/foobar/books. Portanto, essa é a rota principal que usaremos.

Devemos também garantir que criamos essas rotas w dentro dos nossos módulos.

Namespace ou identificador CRUD

O identificador CRUD ajuda o NexoPOS a estar ciente do recurso e a saber como disponibilizá-lo quando ele for solicitado. Ao criar o componente CRUD, você será solicitado a fornecer um nome de identificador exclusivo. Observe que todos os NexoPOS são prefixados com “ns.”, portanto este é um prefixo reservado. Para nosso exemplo atual, o identificador do nosso componente CRUD pode ser:

foobar.books

Modelo

Você deve criar um modelo para o seu módulo dentro da pasta “Models”. O nome desse modelo (incluindo o namespace) deve ser fornecido como valor para o modelo. Supondo que nosso modelo “Book” esteja disponível no namespace a seguir “Modules\FooBar\Models\Book”, esse será o valor que forneceremos.

Ao criar um modelo, certifique-se de que ele estenda a classe NsModel em vez do modelo padrão do Laravel. O motivo é garantir que seu módulo seja compatível com o módulo multistore. Se você não pretende algo assim, pode usar o modelo do Laravel padrão.

Criando Relações

Se o seu módulo tiver uma relação com um módulo externo, você pode definir essa relação ao gerar o seu componente CRUD. As relações exigem que você forneça (na ordem, separadas por vírgula):

  • No nosso exemplo, nossa tabela pode ser relacionada à tabela do usuário, portanto o “nexopos_users” é a tabela estrangeira.
  • foreign_key: é a chave em nosso “foobar_books” que faz a ligação com “nexopos_users”. No nosso exemplo, é “author”, que é o ID dos usuários que inseriram o livro no sistema.
  • local_key: a chave em “nexopos_users” usada como referência para o junction. Vamos usar aqui “id”.

Você pode definir relações adicionais; quando terminar, digite "S" para pular essa seção.

Colunas Preenchíveis

Ao inserir ou atualizar uma entrada, essas colunas serão preenchidas explicitamente e as outras serão ignoradas. Aqui você pode definir as colunas separadas por vírgula. Se você não quiser adicionar essa restrição, pode digitar “S” para pular.

Depois disso, o arquivo será gerado dentro do seu módulo.

Registro de Componente CRUD

Para o NexoPOS estar ciente do componente CRUD que acabou de ser criado, precisamos registrá-lo. Registrar CRUD implica adicionar seu CRUD à pilha de CRUDs registrados. Isso será feito usando o hook dentro do método “register” do seu service provider, com o seguinte 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 **/ );
    }
}

O callback que podemos usar pode apontar para um arquivo separado ou para a mesma classe. Vamos usar um método da própria classe para registrar nosso 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
        }
    }
}

Ao verificar se nosso identificador CRUD é fornecido, se não houver uma correspondência, é necessário retornar o identificador exatamente como foi fornecido em um parâmetro. Isso pode ser o identificador de outro CRUD criado por outro módulo e, não retornando o identificador, a pilha de CRUD será interrompida.

Observe que o que é realizado é principalmente para a biblioteca de frontend (Vue). Agora precisamos criar uma rota e renderizar ou a tabela ou o formulário.

Renderizando a Tabela

Primeiro, precisamos criar uma rota e usar um controller (ou criar um novo) para nossa instância de CRUD. No nosso exemplo, vamos criar uma rota que fica assim.

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

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

Agora precisamos atualizar o método "bookList" no controller que selecionamos para esta rota. Dentro do método, vamos apenas retornar a saída do método estático table assim.

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

O método “table” aceita um array que permite personalizar a tabela. Por exemplo, aqui está a lista de índices suportados para o seu array:

  • título: Garantirá que você possa personalizar o título da tabela
  • Será usado para descrever a tabela CRUD.
  • Se você quiser personalizar a URL de origem usada pela biblioteca de front-end para buscar entradas.
  • createUrl: Será usado para substituir a URL que leva aos formulários de criação
  • queryParams: quaisquer parâmetros personalizados que você gostaria de enviar para a instância do Crud. Isso pode ser útil para aplicar filtros personalizados.

Renderizando um Formulário para Criação

Você pode renderizar 2 tipos de formulários: um formulário usado ao criar uma nova entrada e um formulário usado ao editar uma entrada existente. Esta seção se concentra em como criar um formulário que é usado para criar uma entrada. Assim como ao exibir uma tabela, aqui você precisará criar uma rota que leve ao formulário. Vamos usar a seguinte configuração de rota:

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

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

Aqui, vamos usar o slug: /dashboard/foobar/books/create, mas ele pode terminar com o que você quiser (new, add, etc.). No método createBook, vamos usar a instância Crud e utilizar o seu método estático "form" para retornar um formulário 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 um Formulário para Modificação

Um formulário para executar uma entrada de modificação é um pouco diferente do formulário usado para criar uma entrada. Aqui, ao criar uma rota para o método do controlador que irá lidar com isso, passaremos um parâmetro de rota que é o identificador da entrada, ou também pode ser um model binding. Agora, ao usar o método “form”, precisamos passar o modelo que é a própria entrada. Veja como vamos proceder primeiro em relação à rota.


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

Agora, dentro do método “editBook”, vamos vincular o livro e passá-lo para o método “form” do BookCrud, assim:

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

Quando um não é fornecido, o método “form” atribui “null” por padrão para o primeiro parâmetro. No segundo parâmetro, um array para configurar o formulário. Aqui estão os índices suportados para o array de configuração.

  • Para fornecer um título para o formulário.
  • Descrição: Para descrever a forma.
  • Para alterar a URL de origem usada pela biblioteca front-end para interagir com a instância Crud.
  • returnUrl: Esta URL é usada como URL de retorno para a lista de entradas. Ela também é usada para redirecionar automaticamente o usuário quando a modificação tiver sido feita com sucesso.
  • submitMethod: Se, por algum motivo, você quiser que o NexoPOS altere o método usado para atualizar/criar uma entrada, você pode defini-lo aqui. Observe que “post” e “put” são suportados.

Esses parâmetros também são eficazes ao usar o método “form” sem uma entrada fornecida, mas nesse caso você precisará passar como valor para o primeiro parâmetro “null”.

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

Ou você pode usar parâmetros nomeados como este:

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