Erstellen eines benutzerdefinierten Formularfeldtyps in Joomla anhand des Modal Select-Beispiels

Verwendung des ModalSelect-Formularfeldtyps in Joomla 5, um das Finden des richtigen Produkts aus Tausenden zu vereinfachen, indem bei der Entwicklung einer Erweiterung in einem modalen Fenster nach Kategorie, Hersteller und Suche gefiltert wird.

Einführung

Bei der Arbeit mit Kunden gibt es Aufgaben auf verschiedenen Ebenen: Jemand braucht eine einfache Website mit 5-6 Seiten. Jemand benötigt einen großen Warenkatalog oder einen Online-Shop mit Integrationen in Drittsysteme über die REST-API. Jemand anderes benötigt nicht standardmäßige Funktionen, für die es keine gängigen Lösungen gibt.

Joomla eignet sich gut für die Entwicklung und ermöglicht die Erstellung leicht zu wartenden Codes. Wenn die Anforderung dem CMS-Kern folgt, gibt es für alle diese Fälle eine Antwort.

Um ein großes Projekt abzuschließen, müssen wir es in kleinere Aufgaben aufteilen, und ich möchte in diesem Artikel über die Lösung einer dieser Aufgaben sprechen.

Ausgangsdaten

Kunden haben bereits einen Produktkatalog auf einer der beliebten Komponenten des Online-Shops für Joomla (JoomShopping) erstellt. Sie können die Parameter des Produkts auswählen, es in den Warenkorb legen und einen Kauf tätigen. Alles ist wie immer. Jetzt müssen Sie jedoch die Möglichkeit hinzufügen, ein grafisches Layout für Produkte zu erstellen. Ihr Produkt ist beispielsweise eine Tasse oder ein T-Shirt. Und vor dem Kauf können Sie zum Produktdesigner gehen, Ihr Logo oder Foto hochladen, einen Text schreiben und dieses Layout wird der Bestellung im Online-Shop beigefügt. Nach der Bezahlung geht das Layout direkt in die Produktion, wo das Bild und der Text auf deine Tasse aufgebracht und an die Adresse verschickt werden.

Da die Implementierung dieser Funktionalität recht zeitaufwändig ist, wird sie als separate Produktdesigner-Komponente erstellt. Und es werden bereits Plugins für Datenanbieter erstellt, die es Ihnen ermöglichen, mit der einen oder anderen E-Commerce-Komponente zu arbeiten.

Eine der kleinen, angewandten Aufgaben besteht darin, Verbindungen zwischen den Waren der Online-Shop-Komponente und den Waren in der Produktdesigner-Komponente herzustellen. Dies sollte für Content-Manager, die in Zukunft an den Inhalten arbeiten, bequem und intuitiv sein. Daher reicht es nicht aus, nur ein Textfeld zu erstellen, in dem die ID-Nummer des gewünschten Produkts angegeben wird. Möglicherweise gibt es in einem Online-Shop nur ein paar Dutzend Produkte, und dann ist die Auswahl eines Produkts für die Kommunikation nicht sehr schwierig. Bei Tausenden von Produkten ist die Funktionalität zum Suchen und Filtern von Produkten nach Parametern wichtig. Wenn Sie die Produktliste nach Kategorie oder Hersteller filtern oder unter Hunderten anderen nach Namen suchen können, wird Ihre Arbeit viel schneller und einfacher.

Sehen Sie sich das Video an

Dieses Feld ähnelt sehr der Arbeit der Editor-Button-Plugins (Gruppe editors-xtd), bei denen die Daten zur Auswahl im modalen Fenster angezeigt werden: ein Link zum Artikel, ein Kurzcode für das Modul usw.

Eine kleine Theorie

Im Joomla-Administratorbereich gibt es verschiedene Felder, die mit Daten aus anderen Komponenten gefüllt werden müssen: Geben Sie den Artikel, den Menüpunkt, den Kontakt, das Produkt usw. an. Normalerweise sind solche Felder als Dropdown-Liste mit Auswahloptionen konzipiert , können sie als Eingabetyp="Text" mit einer Datenliste gestaltet werden, es gibt aber auch praktische Felder, die eine Liste der gewünschten Entitäten anzeigen, mit Filterung, Suche und Paginierung. Als Datenquelle können nicht nur Quellen innerhalb der Site (verschiedene Komponenten, Plugins) fungieren, sondern auch über die REST-API verfügbare Dienste von Drittanbietern: CRM, Lieferdienste, externe Datenbanken, andere Joomla-Sites usw.

Wir alle haben diese Felder in Aktion gesehen, als wir einen Artikel in einem Menüpunkt wie „Artikel – Einzelner Artikel“, „Kontakte – Einzelner Kontakt“ oder beim Erstellen eines Alias ​​​​des Menüpunkts – „Systemlinks – Menü“ – ausgewählt haben Artikelalias". Erinnern wir uns jedoch daran, wie sie aussehen.

Ein modales Artikelauswahlfenster.

Ein modales Einzelkontaktauswahlfenster.

Die Möglichkeiten des modalen Auswahlfelds in Joomla

Schauen wir uns diese Felder genauer an – was genau sie Ihnen ermöglichen. Irgendwo tief im Inneren verstehen wir, dass die Hauptaufgabe dieses Feldes darin besteht, die ID der ausgewählten Entität abzurufen und diese ID in ein Textfeld einzufügen. Aber auf dem Bildschirm sehen wir etwas anderes – statt einer ID-Nummer sehen wir den Titel des Artikels oder Kontakts. Es ist schön und praktisch. Sie müssen sich den Namen des Artikels mit der ID 1452704 nicht merken. Außerdem zeigt das Video deutlich, dass die Schaltfläche „Löschen“ angezeigt wird, wenn das Feld bereits einen Wert enthält. Dadurch wird der Wert des Felds zurückgesetzt und Sie können erneut auf die Schaltfläche „Auswählen“ klicken.

In manchen Fällen haben wir die Möglichkeit einen ausgewählten Entitätstyp zu erstellen – Artikel, Kontakt usw.direkt beim Erstellen eines Menüpunkts. Diese Schaltfläche funktioniert unter Berücksichtigung der ACL – Trennung der Zugriffsrechte in Joomla.

Stellen Sie sich vor, Sie erstellen eine Website und erstellen eine „Kontakte“-Seite. Wenn Sie nicht viele Unternehmenszweige mit einer komplexen Struktur haben, dann ist dies nur der übliche Joomla-Artikel in der Kategorie „Nicht kategorisiert“. Und es verfügt bereits über alle Kontakte in Form von Text oder Variablen. In der Antike musste man zuerst den Artikel erstellen und dann zu den Menüpunkten gehen und einen Menüpunkt dafür erstellen. Das müssen Sie jetzt nicht tun.

Und wenn das Feld bereits einen Wert hat, ist es in manchen Fällen möglich, die ausgewählte Entität (Artikel, Menüpunkt usw.) direkt beim Erstellen eines Menüpunkts zu bearbeiten.

Mithilfe des Auswahlfelds im modalen Fenster können wir also:

• auswählen
• erstellen
• Bearbeiten
• klar

Das ist es, was ich vor Augen habe. Aber in den Tiefen von Joomla gibt es auch einen merkwürdigen urlCheckin-Parameter, der es Ihnen ermöglicht, den ausgewählten Wert an die im Feld angegebene URL zu senden. Es ist erwähnenswert, dass sich diese Funktionalität in Joomla seit geraumer Zeit schrittweise weiterentwickelt. Ein separater universeller Feldtyp, der für Ihre Bedürfnisse verwendet werden kann, erschien jedoch nur in Joomla 5. Dies ist nicht einmal in Joomla 4 der Fall.

Wie sind die Felder des Formularkonstruktors der Joomla-Admin-Panel-Oberfläche angeordnet?

Zuvor hieß dieser Konstruktor JForm. Ich gehe davon aus, dass nicht alle meine Leser über ein solches Entwicklungstool wie eine IDE – Entwicklungsumgebung – a la PHP Storm oder VS Code verfügen, daher werde ich versuchen, zusätzliche Richtlinien für die Navigation in der Codebasis zu geben.

In Joomla ist die Logik von der Ansicht (der eigentlichen HTML-Ausgabe) getrennt, daher werden wir sie an mehreren Stellen gleichzeitig untersuchen.

Logic ist die Form-Klasse

Logic ist die Form-Klasse. In Joomla 5 befinden sich die Form-Klassendateien in libraries/src/Form. Wir untersuchen diese Dateien, um die Logik selbst zu verstehen, was mit den Daten passiert und wie man damit arbeitet.

Kurz gesagt, der Formularkonstruktor empfängt XML mit einer Beschreibung der Felder. liest Daten (Feldtyp, benutzerdefinierte Feldklasse aus dem Attribut addfieldprefix, falls vorhanden usw.), lädt die erforderliche Feldklasse mit FormHelper. Wenn das Feld einige Regeln zum Filtern der Ausgabedaten enthält – die FormRule-Klasse wird verwendet – denken Sie an die Joomla-Felder vom Typ Dateiliste, in denen Sie Filterparameter angeben und beispielsweise nur PHP- oder nur CSS-Dateien auswählen können.

Joomla Form-Feldklassendateien befinden sich in libraries/src/Form/Field. Es gibt, gelinde gesagt, viele davon. Dies ist das Baumaterial des Admin-Panels und manchmal auch des Frontends.

Klassendateien beschreiben Klasseneigenschaften wie $type, $layout und andere, die für den Betrieb notwendig sind. Die meisten Felder verfügen über Methoden getInput() – gibt tatsächlich die HTML-Ausgabe des Felds zurück, getLayoutData() – verarbeitet Daten für das Feld vor, bevor es an den Renderer gesendet wird, getLabel() – arbeitet mit der Feldbezeichnung usw.

Wir erinnern uns, dass die Feldklassen die übergeordnete FormField-Klasse erben. In der Klassendatei libraries/src/Form/FormField.php werden die möglichen Attribute des Feldes beschrieben, die in der Beschreibung in XML verwendet werden können. Sie haben eine kurze Beschreibung, was es ist und warum.

Untergeordnete Klassen (Erben) haben die Möglichkeit, mit den Methoden der übergeordneten Klasse zu arbeiten und diese bei Bedarf zu überschreiben.

Ansicht (HTML-Ausgabe, Layout) eines Feldes in Joomla 5

Jede Feldklasse verfügt über eine HTML-Ausgabe. Im klassischen MVC funktioniert die Ansicht sofort mit der Datenausgabe, aber in Joomla gibt es eine zusätzliche Ebene – Layout, mit der Sie Layouts überschreiben können – eine der wichtigsten Funktionen dieses CMS. Die Kernlayouts sind wird voraussichtlich im Layouts-Ordner im Stammverzeichnis der Site liegen. Sie übergeben ein Array von $displayData mit allen von der Methode getLayoutData() empfangenen Daten. Wir geben in der Klasseneigenschaft $layout an, welches Ausgabelayout verwendet werden soll.

<?php
/**
 * Name of the layout being used to render the field
 *
 * @var    string
 * @since  3.7
 */
protected $layout = 'joomla.form.field.email';

Diese Art der Aufnahme kommt recht häufig vor. In Joomla ist Layout ein durch Punkte getrennter Pfad zur Layout-Datei aus dem Layout-Ordner im Stammverzeichnis der Site. Das heißt, der Eintrag $layout = 'joomla.form.field.email' bedeutet das Beim Rendern des Feldes werden Layouts verwendet layouts/joomla/form/field/email.php.

<?php 
use Joomla\CMS\Layout\LayoutHelper;

$displayData = [
                'src' => $this->item->image,
                'alt' => $this->item->name,
               ];

echo LayoutHelper::render(
                        'joomla.html.image',
                         $displayData
                    );

In ähnlicher Weise wird in diesem Beispiel das Layout layouts/joomla/html/image.php verwendet. Einige Layouts können im Ordner html der Site-Vorlagen und im Admin-Bereich überschrieben werden.

Wenn wir dementsprechend genau sehen möchten, welche Daten am Ende in das Layout gelangen und wie diese angezeigt werden, gehen Sie in die Layoutdatei und schauen Sie nach.

Erstellen eines Datenauswahlfelds im Modal Select-Fenster in Joomla 5

Jetzt kehren wir zur Hauptaufgabe des Artikels zurück.

Beispiele sind für uns wichtig, um sie zu studieren (Joomla 5.0.1 zum Zeitpunkt des Schreibens dieses Artikels):

• Die Hauptklasse des Feldes ist libraries/src/Form/Field/ModalSelectField.php
• das modale Auswahlfeld für Joomla-Artikel – administrator/components/com_content/src/Field/Modal/ArticleField.php
• modales Auswahlfeld für den Menütyp – administrator/components/com_menus/src/Field/MenutypeField.php
• modales Auswahlfeld für Menüelemente – administrator/components/com_menus/src/Field/MenutypeField.php
• Ausgabelayout – layouts/joomla/form/field/modal-select.php

Das modale Einzelkontakt-Auswahlfeld von com_contacts zum Zeitpunkt des Schreibens dieses Artikels wurde noch nicht in einen universellen Feldtyp eins konvertiert und liegt nur (in Joomla 5.0.2, als dieser Artikel geschrieben wurde) Administrator /components/com_contact/src/Field/Modal/ContactField.php. Es erbt FormField direkt, nicht ModalSelectField.

Der Aktionsalgorithmus zum Hinzufügen eines eigenen Felds ist wie folgt:

• Erstellen Sie ein XML-Formular mit unserem Feld in einer XML-Datei oder programmgesteuert mit SimpleXMLElement.
• Wenn wir spontan arbeiten, fügen wir mithilfe des Plugins für das onContentPrepareForm-Ereignis XML-Formulare zum gewünschten Formular hinzu (überprüfen Sie vorher $form->getName())
• Erstellen einer Feldklasse.
• Bei Bedarf erstellen wir eine eigene HTML-Ausgabe (Layout) des Feldes. Wir werden dies aus dem Rahmen dieses Artikels herauslassen. Und es funktioniert. ## Feld-XML Das Wichtigste in diesem Code ist das Attribut addfieldprefix, das den Namensraum Ihrer Feldklasse bedeutet. Der Klassenname wird aus addfieldprefix "" type "Field" gebildet. In diesem Fall ist die Feldklasse JoomlaPluginWtproductbuilderProviderjoomshoppingFieldProductlistField.

<?php
/**
 * Name of the layout being used to render the field
 *
 * @var    string
 * @since  3.7
 */
protected $layout = 'joomla.form.field.email';

HTML-Ausgabe (Layout) des Feldes

Damit alles, was in PHP passiert, klar ist, müssen Sie sich zunächst das Layout der Feldausgabe ansehen. Es befindet sich in der Datei layouts/joomla/form/field/modal-select.php. Tatsächlich werden 2 Eingabefelder ausgegeben – eines sichtbar, das andere unsichtbar. Der Titel des ausgewählten Artikels, Kontakts oder Produkts wird in Form eines Platzhalters – dem Parameter $valueTitle – in das sichtbare Feld eingetragen. Und der zweite ist seine ID – $value. Wenn wir noch nichts ausgewählt haben, sollte im Feld ein Satz wie „Artikel auswählen“ oder „Produkt auswählen“ stehen. Dies ist eine Sprachkonstante, die wir in das Hint-Attribut im XML-Feld oder in die setup()-Methode der Feldklasse einfügen.

Alle für das Ausgabelayout verfügbaren Parameter (d. h. diejenigen, die programmgesteuert oder in einer XML-Datei verwendet werden können):

<?php
/**
 * Name of the layout being used to render the field
 *
 * @var    string
 * @since  3.7
 */
protected $layout = 'joomla.form.field.email';

PHP-Feldklasse

Die Feldklasse befindet sich, wie Sie vielleicht erraten haben, in meinem Plugin. Der Weg dorthin plugins/wtproductbuilder/providerjoomshopping/src/Field/ProductlistField.php. Ich habe das einzelne modale Artikelauswahlfeld als Grundlage genommen und es an meine Bedürfnisse angepasst – Auswahl eines Produkts aus dem JoomShopping-Onlineshop. Wir erweitern die übergeordnete ModalSelectField-Klasse um unsere eigene Klasse.

Zu meinen Aufgaben gehört nur die Produktauswahl, Bearbeitung und Erstellung nicht, daher geht es im Text des Artikels nur um die Produktauswahl. Die PHP-Klasse ist klein, ich werde sie vollständig wiedergeben und kommentieren.

<?php 
use Joomla\CMS\Layout\LayoutHelper;

$displayData = [
                'src' => $this->item->image,
                'alt' => $this->item->name,
               ];

echo LayoutHelper::render(
                        'joomla.html.image',
                         $displayData
                    );

Separat wurde die Methode getValueTitle() eingeführt, die den Namen der ausgewählten Entität (Produktname, Artikeltitel usw.) anzeigt, wenn diese bereits ausgewählt und gespeichert wurde. Das heißt, wir haben den Menüpunkt bearbeitet, wir berühren das Feld nicht, aber wir möchten, dass der Titel des Artikels/Produktnamens für die Menschen verständlich ist und nicht nur eine ID. Diese Methode zeigt den gewünschten Titel an.

<field
      type="productlist"
      name="product_id"
      addfieldprefix="Joomla\Plugin\Wtproductbuilder\Providerjoomshopping\Field"
      label="Field label"
      hint="Field placeholder"
      />

In einigen Feldern, in denen komplexere Funktionen erforderlich sind – mehrsprachige Assoziationen usw. – gibt es andere Methoden in der Feldklasse, die die grundlegenden Methoden der FormField-Klasse überschreiben:

• setLayoutData() ist eine Methode zur Vorverarbeitung von Daten vor dem tatsächlichen Rendern des Felds
• getRenderer() – zusätzliche Parameter für das Rendern usw.

In unserem Fall besteht kein solcher Bedarf, daher verwenden wir sie nicht.

HTML-Ausgabe des Inhalts des modalen Fensters

Wenn Sie auf die Schaltfläche „Auswählen“ klicken, öffnet sich ein modales Bootstrap-Fenster, in dem sich eine Liste der Produkte im