Seiten erstellen

Das Erstellen eines Moduls erfordert häufig das Anlegen eines Abschnitts, in dem konfiguriert werden kann, wie das Modul funktioniert. NexoPOS wird mit einer Settings-API ausgeliefert, die darauf abzielt, die Erstellung von Einstellungen für Entwickler zu erleichtern. Bevor Sie mit dieser Anleitung fortfahren, gehen wir davon aus, dass Sie bereits wissen, wie man:

Die Settings-API interagiert mit der Options-API und validiert, speichert und ruft Ihre Einstellungen für Sie ab.

Eine Settings-Seitenklasse erstellen

Jede Einstellungsseite muss `App\Services\SettingsPage` erweitern. In deinem Modul speicherst du deine Einstellungsseite in einem Ordner namens „Settings“, „Forms“ oder in einem beliebigen Ordnernamen, der für dich sinnvoll ist, da dafür noch keine Konvention festgelegt wurde. Typischerweise sieht die Klasse so aus.


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

Hier definieren wir die Methode „getForm“, die die Struktur des Formulars festlegt.

Eine Einstellungsseite besteht normalerweise aus Tabs und Feldern, aber nicht nur. Ab NexoPOS >= 5.3 können Sie außerdem eine benutzerdefinierte Vue-Komponente für Tabs und Felder zuweisen.

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

Struktur eines Feldes

Die meisten Felder werden auf eine gemeinsame Weise definiert. Üblicherweise sieht ein Feld so aus.

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

Dies sind jedoch nicht alle Parameter, die für ein Feld verwendet werden können. So benötigt beispielsweise ein Feld wie „select“ weitere Attribute, die in dieser Liste der unterstützten Attribute erläutert werden.

Typ

Jede Felddefinition muss über einen „type“-Wert verfügen, der den Typ des Feldes definiert. Unterstützte Typen sind:

Text
Textfeld
Nummer
auswählen
Medien
Schalter
Mehrfachauswahl
Kontrollkästchen
CKEditor
Datumszeitauswahl
Passwort
E-Mail
tel
Datum

Bezeichnung

Die Bezeichnung ist das, was der Nutzer als Feldnamen sieht. Sie sollte beschreiben, worum es bei dem Feld geht.

Beschreibung

Die Beschreibung gibt mehr Hinweise auf das Feld. Das kann dabei helfen zu erklären, wie das Feld verwendet wird.

Validierung

Dies wird verwendet, um die Validierung für ein Feld durchzusetzen. Alle Laravel-Validierungs Strings werden als unterstützt (im Backend) validiert. Validierungen, die auf einem Objekt basieren, werden sowohl auf der Frontend-Seite ignoriert als auch Validierungen, die eine Prüfung in der Datenbank durchführen.

Name

Dies ist der Name des Feldes, aber auch der Name der Option. Falls Sie eine Einstellungsseite für Ihr Modul erstellen, sollten Sie allen Namen Ihrer Felder ein Präfix voranstellen. Beispielsweise verwendet NexoPOS „ns_“ als Präfix für alle Einstellungen, die für das System erstellt werden, daher ist es ein reserviertes Präfix. Beachten Sie jedoch, dass Ihr Wert für den Namen niemals einen Punkt als Trennzeichen verwenden darf. Beispielsweise ist „my.custom.field.name“ nicht zulässig.

Wert

Dies ist der gewünschte Wert, der im Feld angezeigt werden soll. In der Regel müssen Sie hier die Optionen verwenden, um die Option aus der Datenbank abzurufen, indem Sie „ns()->option->get( '[Ihr Feldname]' )“ verwenden. Dabei muss „[Ihr Feldname]“ durch den Feldnamen ersetzt werden, den Sie oben definiert haben.

Optionen

Dies wird nur für die Feldtypen „switch“, „select“ und „multiselect“ verwendet. Es besteht aus einem Array, das ein Array als Option enthält. Typischerweise ist es wie folgt aufgebaut.

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

Das lässt sich mit Hilfe von Array-Helpern verkürzen:

Verwenden von 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'
 *    ]
 * ]
 *
**/

Verwenden von toJsOptions

Dies sollte verwendet werden, wenn eine Sammlung in Optionen für ein Feld umgewandelt wird. Diese Funktion akzeptiert als ersten Parameter die Sammlung und als zweiten ein Array, dessen erster Index der „Wert“ und dessen zweiter Index die „Beschriftung“ ist.

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

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

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

Wenn Sie sich eine vollständige Einstellungsseite ansehen möchten, können Sie diese Datei aus dem Quellcode von NexoPOS überprüfen.

Rendern einer Vue-Komponente

Wenn Sie das Layout der Einstellungen vollständig ändern und eine benutzerdefinierte Einstellungsseite erstellen möchten, die tatsächlich eine Vue-Komponente ist, ist das ebenfalls möglich. Um zu beginnen, müssen Sie Ihre Vue-Komponente einbinden. Sobald das erledigt ist, geben Sie beim Definieren Ihres Formulars statt eines Attributs „fields“ das Attribut „component“ an.

Nehmen wir an, Sie haben Ihre View-Komponente wie folgt injiziert:

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

Wie Sie sehen können, ist der registrierte Name unserer Komponente „myCustomComponent“. Diesen Namen werden wir für das „component“-Attribut verwenden, so wie hier.

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

Wenn die Seite gerendert wird, versucht NexoPOS, die dynamische Komponente aufzulösen und den Inhalt des Einstellungsbereichs damit zu ersetzen.

Einstellungsseite registrieren

Ab NexoPOS 5.3 müssen Sie die Einstellungsseite nicht mehr registrieren. Wenn Sie möchten, dass eine Einstellungsseite ein Autoloader ist, sollten Sie in Ihrer Einstellungs-Klasse eine Konstante als AUTOLOAD = true definieren.

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

So rendern Sie die Einstellungsseite

Jetzt ist es an der Zeit, eine Einstellungsseite zu rendern. Was du dafür brauchst, ist, eine Route zu erstellen, die auf eine Controller-Methode zeigt, in der wir die Klasse verwenden, die wir bisher erstellt haben.

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