Accueil
NexoPOS

Créer des pages

La création d’un module nécessite souvent de créer une section où 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 de paramètres interagit avec l’API d’options et valide, enregistre et récupère vos paramètres pour vous.

Créer une classe de page de paramètres

Chaque page de paramètres doit étendre `App\Services\SettingsPage`. Dans votre module, vous stockerez votre page de paramètres dans un dossier nommé « Settings », « Forms » ou tout autre nom de dossier qui vous convient, car aucune convention n’a encore été décidée à ce sujet. Typiquement, voici à quoi la classe doit ressembler.


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

Ici, nous définissons la méthode « getForm », qui définit la structure du formulaire.

Une page de paramètres se compose généralement d’onglets et de champs, mais pas uniquement. À partir de NexoPOS >= 5.3, vous pouvez également attribuer un composant Vue personnalisé aux onglets et aux champs.

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

Structure d’un champ

La plupart des champs ont une manière commune d’être définis. En général, un champ ressemble à ceci.

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

Cependant, ce ne sont pas tous les paramètres qui peuvent être utilisés pour un champ. Ainsi, certains champs, comme « select », nécessitent davantage d’attributs, expliqués dans cette liste d’attributs pris en charge.

type

Chaque définition de champ doit comporter un champ « type » qui définit le type du champ. Les types pris en charge sont :

  • texte
  • zone de texte
  • nombre
  • sélectionner
  • médias
  • commutateur
  • multisélection
  • case à cocher
  • ckeditor
  • sélecteur de date et d’heure
  • mot de passe
  • e-mail
  • tél
  • date

étiquette

L’étiquette correspond à ce que l’utilisateur verra comme nom de champ. Elle doit décrire de quoi parle ce champ.

description

La description fournit davantage d’indices sur le domaine. Cela peut être utile pour expliquer comment le domaine sera utilisé.

validation

Ceci est utilisé pour appliquer la validation d’un champ. Toutes les chaînes de la validation de Laravel prises en charge (côté serveur) sont acceptées. Les validations basées sur un objet sont ignorées côté front, tout comme celles qui effectuent une vérification dans la base de données.

nom

Il s’agit du nom du champ, mais aussi du nom de l’option. Si vous créez une page de paramètres pour votre module, vous devez préfixer tous les noms de vos champs. Par exemple, NexoPOS utilise « ns_ » comme préfixe pour tous les paramètres créés pour le système ; il s’agit donc d’un préfixe réservé. Toutefois, vous devez noter que la valeur de votre nom ne doit jamais utiliser de point comme séparateur. Par exemple, « my.custom.field.name » n’est pas autorisé.

valeur

C’est la valeur souhaitée qui doit être affichée dans le champ. En général, vous devrez utiliser les options ici pour récupérer l’option depuis la base de données en utilisant « ns()->option->get( '[nom_de_votre_champ]' ) », où [nom_de_votre_champ] doit être remplacé par le nom du champ tel que vous l’avez défini ci-dessus.

options

Ceci n’est utilisé que pour les types de champs « switch », « select » et « multiselect ». Il se compose d’un tableau contenant un tableau comme option. Typiquement, il est conçu comme ceci.

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

Cela peut être raccourci en utilisant des helpers de tableau :

En utilisant 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'
 *    ]
 * ]
 *
**/

En utilisant toJsOptions

Ceci doit être utilisé lors de la conversion d’une collection en options pour un champ. Cette fonction accepte, en premier paramètre, la collection, et, en second paramètre, un tableau dont le premier index doit correspondre à la « valeur » et le second index à l’« étiquette ».

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

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

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

Si vous souhaitez consulter une page de paramètres complète, vous pouvez consulter ce fichier depuis le code source de NexoPOS.

Rendre un composant Vue

Si vous souhaitez modifier complètement la mise en page des paramètres et créer une page de paramètres personnalisée qui est réellement un composant Vue, c’est également possible. Pour commencer, vous devrez injecter votre composant Vue. Une fois fait, lors de la définition de votre formulaire, au lieu de fournir un attribut « fields », vous fournirez l’attribut « component ».

Supposons que vous ayez injecté votre composant de vue comme suit :

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

Comme vous pouvez le voir, le nom enregistré de notre composant est « myCustomComponent ». C’est le nom que nous utiliserons sur l’attribut « component », comme ceci.

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

Au moment où la page sera rendue, NexoPOS tentera de résoudre le composant dynamique et remplacera le contenu du corps des paramètres par celui-ci.

Page des paramètres d’inscription

À partir de NexoPOS 5.3, vous n’avez plus besoin d’enregistrer la page de configuration. Si vous souhaitez qu’une page de configuration soit un chargeur automatique, vous devez définir une constante dans votre classe de configuration : 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.
            )
        );
    }
}

Comment afficher la page des paramètres

Il est maintenant temps de rendre une page de paramètres. Ce dont vous aurez besoin, c’est de créer une route qui pointe vers une méthode de contrôleur où nous utiliserons la classe que nous avons créée jusqu’ici.

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