Inicio
NexoPOS

Crear páginas

Crear un módulo a menudo requiere crear una sección donde se pueda configurar cómo funciona el módulo. NexoPOS incluye una API de configuración que tiene como objetivo facilitar la creación de ajustes para los desarrolladores. Antes de continuar con esta guía, creemos que ya sabes cómo:

La API de configuración interactúa con la API de opciones y valida, almacena y recupera tus configuraciones por ti.

Creando una clase de página de configuración

Cada página de ajustes debe extender `App\Services\SettingsPage`. Dentro de tu módulo, almacenarás tu página de ajustes en una carpeta llamada "Settings", "Forms" o en cualquier otro nombre de carpeta que tenga sentido para ti, ya que no se ha decidido ninguna convención para ello. Típicamente, así es como debe verse la clase.


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

Aquí, definimos el método "getForm", que define la estructura del formulario.

Una página de configuración normalmente consta de pestañas y campos, pero no solo. Desde NexoPOS >= 5.3, también puedes asignar un componente Vue personalizado a las pestañas y los 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.
            )
        );
    }
}

Estructura de un campo

La mayoría de los campos tienen una forma común de definirse. Por lo general, un campo se ve así.

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

Sin embargo, estos no son todos los parámetros que se pueden usar para un campo. Por lo tanto, algunos campos, como «select», requieren más atributos que se explican en esta lista de atributos compatibles.

tipo

Cada definición de campo debe tener un «type» que defina el tipo del campo. Los tipos compatibles son:

  • texto
  • área de texto
  • número
  • seleccionar
  • medios
  • cambiar
  • selección múltiple
  • casilla de verificación
  • ckeditor
  • selector de fecha y hora
  • contraseña
  • correo electrónico
  • tel
  • fecha

etiqueta

La etiqueta es lo que el usuario verá como el nombre del campo. Debe ser descriptiva de lo que trata el campo.

descripción

La descripción ofrece más pistas sobre el campo. Esto puede ser útil para explicar cómo se utilizará el campo.

validación

Esto se usa para aplicar la validación de un campo. Todas las cadenas de validación de Laravel que sean compatibles (en el backend). Las validaciones basadas en un objeto se ignoran en el front end, así como la validación que realiza una comprobación en la base de datos.

nombre

Este es el nombre del campo, pero también el nombre de la opción. En caso de que crees una página de ajustes para tu módulo, debes anteponer a todos los nombres de tus campos. Por ejemplo, NexoPOS usa «ns_» como prefijo para todos los ajustes creados para el sistema, así que es un prefijo reservado. Sin embargo, debes tener en cuenta que el valor de tu nombre nunca debe usar un punto como separador. Por ejemplo, «my.custom.field.name» no está permitido.

valor

Este es el valor deseado que debe mostrarse en el campo. Por lo general, necesitarás usar las opciones aquí para obtener la opción de la base de datos usando «ns()->option->get( '[nombre de tu campo]' )», donde [nombre de tu campo] debe reemplazarse por el nombre del campo tal como lo definiste arriba.

opciones

Esto solo se utiliza para los tipos de campo "switch", "select" y "multiselect". Consiste en un array que contiene un array como opción. Normalmente, está diseñado de esta manera.

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

Esto se puede acortar usando helpers de arrays:

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

Esto debe usarse al convertir una colección en opciones para un campo. Esta función acepta como primer parámetro la colección y, como segundo, un arreglo cuyo primer índice debe ser el «valor» y el segundo índice debe ser la «etiqueta».

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

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

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

Si desea ver una página de configuración completa, puede consultar este archivo del código fuente de NexoPOS.

Renderizar un componente de Vue

Si quieres cambiar por completo el diseño de la configuración y crear una página de configuración personalizada que en realidad sea un componente de Vue, también es posible. Para empezar, tendrás que inyectar tu componente de Vue. Una vez hecho, al definir tu formulario, en lugar de proporcionar un atributo «fields», proporcionarás el atributo «component».

Supongamos que has inyectado tu componente de vista de la siguiente manera:

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

Puedes ver que el nombre registrado de nuestro componente es «myCustomComponent». Ese es el nombre que usaremos en el atributo «component» así.

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

Cuando se renderice la página, NexoPOS intentará resolver el componente dinámico y reemplazará el contenido del cuerpo de la configuración con ese.

Página de configuración de registro

A partir de NexoPOS 5.3, ya no necesitas registrar la página de configuración. Si quieres que una página de configuración sea un autoloader, debes definir una constante en tu clase de configuración 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.
            )
        );
    }
}

Cómo renderizar la página de configuración

Ahora es el momento de renderizar una página de configuración. Lo que necesitarás es crear una ruta que apunte a un método de controlador donde usaremos la clase que hemos creado hasta ahora.

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