Início
NexoPOS

Criar Páginas

Criar um módulo muitas vezes exige criar uma seção em que seja possível configurar como o módulo funciona. O NexoPOS vem com uma API de configurações que tem como objetivo facilitar a criação das configurações para os desenvolvedores. Antes de prosseguir com este guia, acreditamos que você já saiba como:

A API de configurações interage com a API de opções e valida, armazena e busca suas configurações por você.

Criando uma classe de página de configurações

Toda página de configurações deve estender `App\Services\SettingsPage`. Dentro do seu módulo, você armazenará sua página de configurações em uma pasta chamada "Settings", "Forms" ou em qualquer outro nome de pasta que faça sentido para você, já que não foi definido nenhum padrão para isso. Tipicamente, é assim que a classe deve ficar.


<?php
namespace Modules\MyFooBarModule\Settings;

use App\Services\SettingsPage;
use App\Classes\SettingForm;

class MyFooBarSettings extends SettingsPage
{
    const IDENTIFIER = 'your-settings-identifier';
    const AUTOLOAD = true;
  
    public function __construct()
    {
        // do not perform any data load here
        // as during the registration and the built, the settings are intantiated twice
    }
    
    public function getForm(): array
    {
        return SettingForm::form(
            title: 'My Settings Page', 
            description: 'description page',
            tabs: SettingForm::tabs(
                SettingForm::tab(
                    identifier: 'general',
                    label: __( 'General' ),
                    fields: SettingForm::fields(
                        // fields goes here
                    )
                )
            )
        );
    }
}

Aqui, definimos o método "getForm", que define a estrutura do formulário.

Uma página de configurações normalmente consiste em abas e campos, mas não apenas. A partir do NexoPOS >= 5.3, você também pode atribuir um componente Vue personalizado a abas e campos.

<?php
namespace Modules\MyFooBarModule\Settings;

use App\Services\SettingsPage;
use App\Classes\SettingForm;

class MyFooBarSettings extends SettingsPage
{    
    const IDENTIIER = 'my-foo-bar-settings';
    const AUTOLOAD = true;
  
    public function getForm()
    {
        return SettingForm::form(
            title: __( 'My Settings Page' ),
            description: __( 'a sort settings description' ),
            tabs: SettingForm::tabs(
                // your tabs go there.
            )
        );
    }
}

Estrutura de um campo

A maioria dos campos tem uma forma comum de ser definida. Normalmente, um campo se parece com isto.

[
    'type'  =>  'text',
    'label' =>  __( 'My Field Name' ),
    'description'   =>  __( 'My field description' ),
    'validation'    =>  'required',
    'name'          =>  'my_field_name'
]

Estes, no entanto, não são todos os parâmetros que podem ser usados para um campo. Assim, alguns campos, como “select”, exigem mais atributos que são explicados nesta lista de atributos suportados.

tipo

Cada definição de campo deve ter um campo “type” que define o tipo do campo. Os tipos suportados são:

  • texto
  • área de texto
  • número
  • selecionar
  • mídia
  • alternar
  • seleção múltipla
  • caixa de seleção
  • ckeditor
  • seletor de data e hora
  • senha
  • e-mail
  • tel
  • data

etiqueta

O rótulo é o que o usuário verá como o nome do campo. Ele deve ser descritivo sobre o que o campo é.

descrição

A descrição fornece mais pistas sobre o campo. Isso pode ser útil para explicar como o campo será usado.

validação

Isso é usado para impor validação para um campo. Todas as strings de validação do Laravel são suportadas (no backend). Validações baseadas em um objeto são ignoradas no front-end, assim como validações que realizam uma verificação no banco de dados.

nome

Este é o nome do campo, mas também o nome da opção. Caso você crie uma página de configurações para o seu módulo, você deve prefixar todos os nomes dos seus campos. Por exemplo, o NexoPOS usa “ns_” como prefixo para todas as configurações criadas para o sistema, então é um prefixo reservado. No entanto, observe que o valor do seu nome nunca deve usar um ponto como separador. Por exemplo, “my.custom.field.name” não é permitido.

valor

Este é o valor desejado que precisa ser exibido no campo. Normalmente, você precisará usar as opções aqui para buscar a opção no banco de dados usando “ns()->option->get( '[nome_do_seu_campo]' )”, onde [nome_do_seu_campo] deve ser substituído pelo nome do campo conforme você definiu acima.

opções

Isto é usado apenas para os tipos de campo “switch”, “select” e “multiselect”. Consiste em um array que tem um array como opção. Normalmente, é projetado assim.

[
    [
        'label' =>  __( 'Choose Me' ),
        'value' =>  'choose_me'
    ], [
        'label' =>  __( 'No choose me' ),
        'value' =>  'no_choose_me'
    ]
]

Isso pode ser encurtado usando auxiliares de array:

Usando kvTojsOptions

<?php
use App\Services\Helper;

Helper::kvToJsOptions([
  'choose_me' =>  __( 'Choose Me' ),
  'no_choose_me'  =>  __( 'No choose me' ),
]);

// will convert into
/**
 * [
 *    [
 *       'label'  => __( 'Choose me' ),
 *       'value'  => 'choose_me',
 *    ], [
 *       'label'  =>  __( 'No choose me' ),
 *       'value'  =>  'no_choose_me'
 *    ]
 * ]
 *
**/

Usando toJsOptions

Isso deve ser usado ao converter uma coleção em opções para um campo. Esta função aceita como primeiro parâmetro a coleção e, como segundo, um array em que o primeiro índice deve ser o “value” e o segundo índice deve ser o “label”.

<?php
use App\Services\Helper;
use App\Models\User;

Helper::kvToJsOptions( User::get(), [ 'id', 'username' ]);

// will convert into
/**
 * [
 *    [
 *       'label'  => 'blair_jersyer',
 *       'value'  => 10,
 *    ], 
 *    // ...
 * ]
 *
**/

Se quiser dar uma olhada numa página completa de configurações, você pode verificar este arquivo no código-fonte do NexoPOS.

Renderizar um componente Vue

Se você quiser alterar completamente o layout das configurações e criar uma página de configurações personalizada que seja, na prática, um componente Vue, também é possível. Para começar, você terá que injetar seu componente Vue. Depois que isso estiver feito, ao definir seu formulário, em vez de fornecer um atributo “fields”, você fornecerá o atributo “component”.

Vamos supor que você tenha injetado seu componente de visualização da seguinte forma:

<script>
nsExtraComponents.myCustomComponent   = Vue.component( 'my-extra-component', {
    // your component here
});
</script>

Você pode ver que o nome registrado do nosso componente é “myCustomComponent”. Esse é o nome que usaremos no atributo “component”, assim.

[
    'tabs'  =>  [
        'general'   =>  [
            'component'    =>  'myCustomComponent', // here
            'label'     =>  __( 'My FooBar General Settings' )
        ],
    ]
]

Quando a página for renderizada, o NexoPOS tentará resolver o componente dinâmico e substituir o corpo das configurações por ele.

Página de Registro de Configurações

A partir do NexoPOS 5.3, você não precisa mais registrar a página de configurações. Se quiser que uma página de configurações seja um autoloader, você deve definir uma constante na sua classe de configurações como AUTOLOAD = true.

<?php
namespace Modules\MyFooBarModule\Settings;

use App\Services\SettingsPage;
use App\Classes\SettingForm;

class MyFooBarSettings extends SettingsPage
{    
    const IDENTIIER = 'my-foo-bar-settings';
    const AUTOLOAD = true; // autoload here
  
    public function getForm()
    {
        return SettingForm::form(
            title: __( 'My Settings Page' ),
            description: __( 'a sort settings description' ),
            tabs: SettingForm::tabs(
                // your tabs go there.
            )
        );
    }
}

Como Renderizar a Página de Configurações

Agora é hora de renderizar uma página de configurações. O que você vai precisar é criar uma rota que aponte para um método de controlador onde usaremos a classe que criamos até agora.

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

use Modules\MyFooBarModule\Settings\MyFooBarSettings;
use App\Http\Controllers\DashboardController;

class MyFooBarController extends DashboardController
{
    public function showSettingsPage()
    {
        return MyFooBarSettings::renderForm();
    }
}