Home
NexoPOS

Crea pagine

La création d’un module nécessite souvent la création d’une section dans laquelle le fonctionnement du module peut être configuré. NexoPOS est livré avec une API de paramètres qui vise à faciliter la création des paramètres pour les développeurs. Avant de poursuivre ce guide, nous pensons que vous savez déjà comment :

L’API delle impostazioni interagisce con l’API delle opzioni e convalida, salva e recupera le impostazioni per te.

Creazione di una classe di pagina delle impostazioni

Ogni pagina delle impostazioni deve estendere `App\Services\SettingsPage`. All’interno del tuo modulo, memorizzerai la tua pagina delle impostazioni in una cartella chiamata “Settings”, “Forms” o in qualsiasi altro nome di cartella che abbia senso per te, poiché non è stata ancora definita alcuna convenzione. In genere, ecco come deve apparire la classe.


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

Qui definiamo la funzione “getForm”, che definisce la struttura del modulo.

Una pagina delle impostazioni di solito è composta da schede e campi, ma non solo. Da NexoPOS >= 5.3, puoi anche assegnare un componente Vue personalizzato a schede e campi.

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

Struttura di un campo

La maggior parte dei campi ha un modo comune di essere definiti. Di solito, un campo appare così.

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

Tuttavia, questi non sono tutti i parametri che possono essere utilizzati per un campo. Pertanto, alcuni campi, come "select", richiedono ulteriori attributi che sono spiegati in questo elenco di attributi supportati.

tipo

Ogni definizione di campo deve avere un campo "type" che definisce il tipo del campo. I tipi supportati sono:

  • testo
  • textarea
  • numero
  • seleziona
  • media
  • interruttore
  • multiselezione
  • casella di controllo
  • ckeditor
  • selettore data e ora
  • parola d’ordine
  • email
  • tel
  • data

etichetta

L’etichetta è ciò che l’utente vedrà come nome del campo. Dovrebbe descrivere in modo chiaro l’argomento del campo.

descrizione

La description fournit más indicazioni sul campo. Questo può essere utile per spiegare come verrà utilizzato il campo.

validazione

Questo viene utilizzato per applicare la validazione a un campo. Tutte le stringhe di validazione di Laravel supportate (sul backend) vengono considerate. Le validazioni basate su un oggetto vengono ignorate anche lato front-end, così come le validazioni che eseguono un controllo sul database.

nome

Questo è il nome del campo ma anche il nome dell’opzione. Nel caso in cui tu crei una pagina delle impostazioni per il tuo modulo, dovresti anteporre a tutti i nomi dei campi. Ad esempio, NexoPOS usa “ns_” come prefisso per tutte le impostazioni create per il sistema, quindi è un prefisso riservato. Tuttavia, dovresti notare che il valore del tuo nome non deve mai usare un punto come separatore. Ad esempio, “my.custom.field.name” non è consentito.

valore

Questo è il valore desiderato che deve essere visualizzato nel campo. Di solito, dovrai usare le opzioni qui per recuperare l’opzione dal database tramite “ns()->option->get( '[nome del tuo campo]' )”, dove [nome del tuo campo] deve essere sostituito con il nome del campo come lo hai definito sopra.

opzioni

Questo viene utilizzato solo per i tipi di campo "switch", "select" e "multiselect". È costituito da un array che contiene un array come opzione. In genere, è progettato in questo modo.

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

Questo può essere abbreviato usando gli helper di array:

Utilizzando 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

Questo dovrebbe essere utilizzato durante la conversione di una raccolta in opzioni per un campo. Questa funzione accetta come primo parametro la raccolta e come secondo un array il cui primo indice deve essere il “valore” e il secondo indice deve essere l’“etichetta”.

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

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

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

Se desideri dare un’occhiata a una pagina completa delle impostazioni, puoi consultare questo file dal codice sorgente di NexoPOS.

Rendere un componente Vue

Se desideri cambiare completamente il layout delle impostazioni e creare una pagina delle impostazioni personalizzata che sia effettivamente un componente Vue, è anche possibile. Per iniziare, dovrai iniettare il tuo componente Vue. Una volta fatto, durante la definizione del modulo, invece di fornire l’attributo “fields”, fornirai l’attributo “component”.

Supponiamo que tu abbia iniettato il tuo componente di visualizzazione come segue:

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

Come puoi vedere, il nome registrato del nostro componente è "myCustomComponent". Questo è il nome che useremo sull’attributo "component" in questo modo.

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

Quando la pagina verrà renderizzata, NexoPOS proverà a risolvere il componente dinamico e sostituirà il contenuto del corpo delle impostazioni con quello.

Pagina Impostazioni di Registrazione

A partire da NexoPOS 5.3 non è più necessario registrare la pagina delle impostazioni. Se desideri che una pagina delle impostazioni sia un autocaricatore, devi definire una costante nella tua classe di impostazioni come 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.
            )
        );
    }
}

Come visualizzare la pagina delle impostazioni

Ora è il momento di eseguire il rendering di una pagina delle impostazioni. Quello di cui avrai bisogno è creare una route che punti a un metodo del controller in cui useremo la classe che abbiamo creato finora.

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