Desenvolvendo um módulo com CRUD para PrestasShop

Nesse artigo, desenvolveremos um módulo para ser utilizado no painel administrativo da loja. Esse módulo permitirá possuirá as quatro operações CRUD básicas, e mostrará como isso pode ser feito reaproveitando o código do core do PrestaShop. Dessa forma, nossos formulários e a listagem das informações cadastradas possuirão um visual compatível com o padrão da plataforma. Além disso, isso deve fazer com que o módulo seja compatível com futuras versões da loja, até um ponto em que o core seja modificado significativamente.

Os seguintes tópicos serão abordados:

  1. Criação automática do banco de dados;
  2. Reparação (até um certo ponto) automática do banco de dados na reinstalação do módulo;
  3. Listagem dos dados cadastrado no banco em uma grid seguindo o padrão da plataforma;
  4. Criação do formulário de cadastro/edição;
  5. Deleção de registros utilizando ação em massa e individual.

Para os itens 1. e 2., utilizarei a classe CustomObjectModel, que desenvolvi para adicionar alguns recursos à classe ObjectModel do Prestashop.  Para que essa classe funcione bem, os models precisam ser definidos da mesma forma que os models padrão do PrestaShop. Explicarei como fazer essa definição no decorrer do artigo.

Uma vez que os models foram definidos de maneira adequada, os itens 3., 4. e 5. são feitos de maneira praticamente automática pelo próprio PrestaShop. Portanto, nosso trabalho principal será a criação dos models com as definições corretas.

O código-fonte completo do módulo pode ser encontrado neste repositório no GitHub. Para vê-lo em funcionamento, basta extrair todo o código presente no repositório para a pasta /modules/crud/. Recomendo que você siga esse artigo visualizando o código completo do módulo, modificando alguns trechos de seu código para melhor visualização do significado de cada uma das configurações feitas.

Configuração do módulo

Logo no início do arquivo crud.php, temos a linha

A propriedade $models deve conter o nome de todos os models que serão utilizados no módulo. Isso não é um requisito do PrestaShop, mas será utilizado na criação automática do banco de dados. A seguir, temos a definição dasabas que serão criadas no menu do painel administrativo da loja.

Isso fará com que seja criado um menu no painel administrativo da loja com o nome Complete CRUD , com um submenu Custom Operation, conforme a imagem abaixo. Isso também não é feito automaticamente pelo PrestaShop, mas sim com a funçao addTab() que será apresentada a seguir.

Na linha 17, adicionamos o texto a ser exibido no menu (e no submenu) das abas em cada um dos idiomas da loja. Na linha 25, usamos a mesma função addTab() para criar o submenu Custom Operation. A função removeTab(), que será mostrada abaixo, remove os itens que foram criados no menu.

Com essas funções, podemos criar o construtor de nosso módulo, para depois fazer a sua instalação.

Os parâmetros configurados no construtor são auto-explicativos. Sendo assim, seguiremos adiante para a função que instalará o módulo na loja.

Primeiramente, criamos no banco de dados as tabelas referente a cada um dos models utilizados no módulo. Caso as tabelas já existam, a instalação verifica se há alguma coluna faltando nessas tabelas. Isso é util para corrigir eventuais erros provocados por alguma atualização mal-sucedida do módulo. A seguir, instalamos o módulo na loja, e, por fim, criamos o menu do painel referente ao módulo.

Por fim, segue a função uninstall(), que removerá o menu anteriormente criado.

Eu não costumo remover nenhuma informação do banco de dados (muito menos excluir tabelas) na desinstalação do módulo, para evitar perdas acidentais de dados. Ao invés disso, você pode adicionar um botão na tela de configurações do módulo para oferecer essa opção ao usuário, avisando-o das possíveis consequências. Isso não será abordado nesse artigo,

Criação do Model

Na criação do model, muito pouco precisa ser feito. Devemos, apenas, especificar todas as colunas que devem ser criadas no banco de dados, e criar um atributo para cada uma dessas colunas na classe CrudModel. Isso é feito com o código abaixo, que está no arquivo classes/CrudModel.php.

O parâmetro primary refere-se à chave primária da tabela utilizada, e é o campo que será utilizado para identificar unicamente cada registro dessa tabela pelo PrestaShop. As constantes TYPE_INTTYPE_STRING, etc, estão definidas no arquivo ObjectModel.php, dentro da pasta classes da sua loja. validate refere-se ao nome de uma das funções da classe Validate que será utilizada para validar os dados antes de serem salvos no banco de dados. Por fim, o parâmetro db_type não é padrão do PrestaShop, mas acrescentei ele para ser utilizado pela CrudCustomObjectModel, na criação automática do banco de dados.

Criação dos controllers

controller também é bastante simples, assim como foi o model. Devemos apenas configurar quais colunas desejamos que sejam apresentadas na tabela que apresentará os dados. A tabela em si será gerada automaticamente pelo PrestaShop. Do mesmo modo, especificaremos quais os campos presentes nos formulários de cadastro/edição, e o formulário será gerado automaticamente. Não escreveremos uma linha da camada de apresentação (view), nem da parte pesada do controller. O PrestaShop se encarregará de chamar os métodos adequados da classe CrudModel quando o usuário utilizar algum filtro na tabela, ou quando ele editar algum dos registros dela, ou até mesmo quando excluir uma de suas linhas do banco de dados.

As imagens abaixo mostram as telas de listagem e de cadastro que são geradas automaticamente pelo prestashop, no tema padrão do painel administrativo. Para que elas sejam geradas, devemos criar o arquivo controllers/admin/AdminCrudModels.php. Todos os parâmetros necessários para a geração das telas serão configurados no construtor da classe. Assim, comecemos a declaração básica do controller.

Na linha 7, dizemos que esse controller requer que o bootstrap seja carregado para que as views sejam exibidas corretamente. A seguir, especificamos os parâmetros do model cujos dados desejamos manipularPor fim, devemos especificar quais campos desejamos que sejam apresentados na listagem dos dados. Isso é feito através do código abaixo.

As chaves do array acima correspondem aos nomes dos campos que foram configurados no nosso model. Os parâmetros utilizados no código acima seguem a documentação da classe HelperList, então não farei maiores comentários. Na linha 14, fazemos com que a coluna active ganhe a funcionalidade de modificar o status do objeto apenas clicando nos ícones “v” ou “x“. Além disso, a tabela ganha automaticamente as ações em massa “Ativar Aelecionados” e “Desativar Selecionados”.

Para a ação em massa de deleção, devemos adicionar o código abaixo.

Para finalizar nossa listagem, vamos adicionar os botões de ação individual, como mostra a figura abaixo.

Isso é feito facilmente com o código abaixo.

Quando o usuário clicar em Editar, ele verá o formulário abaixo, já preenchido com os dados do objeto escolhido.

Ele pode, ainda, adicionar uma nova linha à tabela com o botão de Adicionar Novo, na parte de cima da tabela. Ele verá o mesmo formulário, mas sem nenhum dado preenchido.

btn_new

Para que esse formulário seja gerado automaticamente, devemos especificar todos os campos que serão exibidos, através do código abaixo.

Essa especificação é feita conforme a documentação da classe HelperForm.

Feito isso, nosso CRUD está finalizado, e totalmente funcional. Note que, como as telas são geradas automaticamente, alguns aspectos da interface não podem ser modificados tão facilmente. Para fazer qualquer modificação não coberta nesse artigo, recomendo uma análise da classe AdminController, bem como as classes HelperFormHelperList, que são as classes base para a geração das telas.