Gibt es Einstellungen, die für alle Items deiner Komponente gelten und die ein Anwender an seine Erfordernisse anpasst? Zeigst du beispielsweise digitale Karten an und willst es dem Benutzer ermöglichen, das Einblenden der Lizenz selbst zu bestimmen? In Joomla gibt für diesen Zweck Parameter.
Parameter werden für
- ein Item speziell,
- für ganze Komponente (alle Items der Komponente) und
- für einen Menüpunkt. gesetzt.
Wenn ein Parameter bei den drei Möglichkeiten gesetzt ist, gilt in Joomla standarmäßig folgende Hierarchie:
- Die Einstellung am Menüpunkt hat immer Vorrang.
- Danach zieht der Parameter, der für das Item speziell gilt.
- Die niedrigst Priorität hat der Parameter, der für die Komponente gesetzt ist.
Beim Menüpunkt hatten wir schon einen Parameter gesetzt. Für die Komponente gibt es diesen in den Optionen der Konfiguration. Das Item im Speziellen nehmen wir uns in diesem Abschnitt vor.
Für Ungeduldige: Sieh dir den geänderten Programmcode in der Diff-Ansicht[^codeberg.org/astrid/j4examplecode/compare/t19...t18] an und übernimm diese Änderungen in deine Entwicklungsversion.
Schritt für Schritt
Der Code mit dem die Belegung eines Parameters berechnet wird, war lange Zeit unterschiedlich in den Joomla Kern Komponenten integriert. Kurz vor der Veröffentlichung von Joomla 4 gab es Bestrebungen, diesen zu vereinfachen und zu vereinheitlichen. Beispiel Pull Requests sind PR 34894[^github.com/joomla/joomla-cms/pull/34894] und PR 32538[^github.com/joomla/joomla-cms/pull/32538], von denen man sich für eigene Implementierungen inspirieren lassen kann.
Neue Dateien
administrator/components/com_foos/sql/updates/mysql/18.0.0.sql
Damit bei einer Aktualisierung der Komponente die Spalte params
in der Datenbank erstellt wird, in welcher die Parameter gespeichert werden, benötigen wir die SQL-Datei administrator/components/com_foos/sql/updates/mysql/18.0.0.sql
.
administrator/components/com_foos/sql/updates/mysql/18.0.0.sql
/* https://codeberg.org/astrid/j4examplecode/raw/branch/39598941015020537d51ccb6ca4098f019d76b04/src/administrator/components/com_foos/sql/updates/mysql/18.0.0.sql */
ALTER TABLE `#__foos_details` ADD COLUMN `params` text NOT NULL AFTER `alias`;
Geänderte Dateien
administrator/components/com_foos/config.xml
In der Konfiguration wird der Parameter gespeichert, um einen Standardwert zu setzen. Wir fügen ein Feld show_name
zur Konfiguration hinzu. Anschließend schaffen wir die Möglichkeit, diesen für ein einzelnes Element administrator/components/com_foos/forms/foo.xml
oder einen Menüpunkt components/com_foos/tmpl/foo/default.xml
zu überschreiben.
administrator/components/com_foos/config.xml
<option value="0">JNO</option>
<option value="1">JYES</option>
</field>
<field
name="show_name"
type="radio"
label="COM_FOOS_FIELD_PARAMS_NAME_LABEL"
default="1"
layout="joomla.form.field.radio.switcher"
>
<option value="0">JHIDE</option>
<option value="1">JSHOW</option>
</field>
</fieldset>
<fieldset
name="permissions"
administrator/components/com_foos/ forms/foo.xml
In dem Formular, mit dem wir ein Element bearbeiten, fügen wir das Feld params
hinzu. So ist show_name
ebenfalls für ein einzelnes Element konfigurierbar.
administrator/components/com_foos/forms/foo.xml
content_type="com_foos.foo"
/>
</fieldset>
<fields name="params" label="JGLOBAL_FIELDSET_DISPLAY_OPTIONS">
<fieldset name="display" label="JGLOBAL_FIELDSET_DISPLAY_OPTIONS">
<field
name="show_name"
type="list"
label="COM_FOOS_FIELD_PARAMS_NAME_LABEL"
useglobal="true"
>
<option value="0">JHIDE</option>
<option value="1">JSHOW</option>
</field>
</fieldset>
</fields>
</form>
In Joomla gibt es die Möglichkeit, den Parmeter auf den Wert global zu setzen. Der Vorteil ist, dass beim Konfigurien angezeigt wird, was global eingestellt ist. Verwende dazu
useglobal="true"
wie /administrator/components/com_contact/forms/contact.xml.
administrator/components/com_foos/sql/install.mysql.utf8.sql
Damit bei einer neuen Installation die Spalte erstellt wird, in der die Parameter gespeichert werden, ergänzen wir die SQL-Datei administrator/components/com_foos/sql/install.mysql.utf8.sql
.
administrator/components/com_foos/sql/install.mysql.utf8.sql
ALTER TABLE `#__foos_details` ADD KEY `idx_language` (`language`);
ALTER TABLE `#__foos_details` ADD COLUMN `ordering` int(11) NOT NULL DEFAULT 0 AFTER `alias`;
ALTER TABLE `#__foos_details` ADD COLUMN `params` text NOT NULL AFTER `alias`;
administrator/components/com_foos/ src/Table/FooTable.php
In der Klasse, die die Tabelle verwaltet, stellen wir sicher, dass die Parameter in der korrekten Form gespeichert werden. Wir verwenden das Registry-Entwurfsmuster[^de.wikipedia.org/wiki/registry_(entwurfsmuster)]. Dieses nutzt die Möglichkeit, Eigenschaften in PHP zu überschreiben[^php.net/manual/de/language.oop5.overloading.php#language.oop5.overloading.members]. Eigenschaften fügen wir mittels
$registry = neue Registry;
$registry->foo = 'foo';
zur Registry hinzu. Um einen Wert abzurufen, nutzen wir
$foo = $registry->foo;
administrator/components/com_foos/src/Table/FooTable.php
use Joomla\CMS\Application\ApplicationHelper;
use Joomla\CMS\Table\Table;
use Joomla\Database\DatabaseDriver;
use Joomla\CMS\Language\Text;
use Joomla\Registry\Registry;
/**
* Foos Table class.
public function check()
*/
public function store($updateNulls = true)
{
// Transform the params field
if (is_array($this->params)) {
$registry = new Registry($this->params);
$this->params = (string) $registry;
}
return parent::store($updateNulls);
}
}
components/com_foos/src/View/Foo/HtmlView.php
Die View kombiniert die Daten zu den Parametern so, dass die Anzeige passt.
In Joomla ist es üblich, dass die Einstellung beim Menüpunkt alles überschreibt. Falls es hier keinen Parameter gibt, zieht der Wert, der beim Element gespeichert wurde. Last but not least wird der Wert der Konfiguration herangezogen. Den aktiven Menüpunkt fragst du über
$active = $app->getMenu()->getActive();
ab.
Manchmal ist es intuitiver, die Anzeige beim Element als Prioriät zu verwenden. Dies habe ich hier so umgesetzt. $state->get('params')
gibt den Wert an, der beim Menüpunkt gespeichert wurde. $item->params
ist der Parameter, der beim Element gespeichert wurde. Der nachfolgende Code zeigt dir, wie du die beiden so mischst, dass der Wert beim Item Vorrang hat.
components/com_foos/src/View/Foo/HtmlView.php
use Joomla\CMS\MVC\View\HtmlView as BaseHtmlView;
use Joomla\CMS\Factory;
use Joomla\Registry\Registry;
/**
* HTML Foos View class for the Foo component
*/
class HtmlView extends BaseHtmlView
{
protected $params = null;
protected $state;
/**
* The item object details
*
public function display($tpl = null)
{
$item = $this->item = $this->get('Item');
$state = $this->state = $this->get('State');
$params = $this->params = $state->get('params');
$itemparams = new Registry(json_decode($item->params));
$temp = clone $params;
/**
* $item->params are the foo params, $temp are the menu item params
* Merge so that the menu item params take priority
*
* $itemparams->merge($temp);
*/
// Merge so that foo params take priority
$temp->merge($itemparams);
$item->params = $temp;
Factory::getApplication()->triggerEvent('onContentPrepare', ['com_foos.foo', &$item]);
// Store the events for later
components/com_foos/ tmpl/foo/default.php
Am Ende nutzen wir den Parameter beim Handling der Anzeige im Template components/com_foos/tmpl/foo/default.php
. Wenn es den Parameter gibt und er so gesetzt ist, dass der Name angezeigt werden soll if ($this->item->params->get('show_name'))
, dann wird der Name angezeigt. Das Label $this->params->get('show_foo_name_label')
wird ebenfalls nur dann angezeigt:
components/com_foos/tmpl/foo/default.php
use Joomla\CMS\Language\Text;
if ($this->get('State')->get('params')->get('show_foo_name_label')) {
echo Text::_('COM_FOOS_NAME');
}
if ($this->item->params->get('show_name')) {
if ($this->params->get('show_foo_name_label')) {
echo Text::_('COM_FOOS_NAME');
}
echo $this->item->name;
echo $this->item->name;
}
echo $this->item->event->afterDisplayTitle;
echo $this->item->event->beforeDisplayContent;
components/com_foos/ tmpl/foo/default.xml
components/com_foos/tmpl/foo/default.xml
Damit es möglich ist, den Parameter beim Menüpunkt zu speichern, fügen wir ein Feld in der XML-Datei hinzu. Wichtig ist, dass es unter fields
angeordnet wird und params
heißt - zumindest zum Verwenden der Joomla Standardfunktionen!
/>
</fieldset>
</fields>
<!-- Add fields to the parameters object for the layout. -->
<fields name="params">
<fieldset name="basic" label="JGLOBAL_FIELDSET_DISPLAY_OPTIONS">
<field
name="show_name"
type="radio"
label="COM_FOOS_FIELD_PARAMS_NAME_LABEL"
layout="joomla.form.field.radio.switcher"
default="1"
class=""
>
<option value="0">JHIDE</option>
<option value="1">JSHOW</option>
</field>
</fieldset>
</fields>
</metadata>
Das HTML Formularelement
input
mit dem Typradio
hat in Joomla einen typischen Look. Es wird Switcher genannt und den Look erzeugst du über das Layoutjoomla.form.field.radio.switcher
.![]()
<field
name="show_name"
type="radio"
label="COM_FOOS_FIELD_PARAMS_NAME_LABEL"
layout="joomla.form.field.radio.switcher"
default="1"
class=""
>
<option value="0">JHIDE</option>
<option value="1">JSHOW</option>
</field>
Teste deine Joomla-Komponente
-
Installiere deine Komponente in Joomla Version 4, um sie zu testen: Kopiere die Dateien im
administrator
Ordner in denadministrator
Ordner deiner Joomla 4 Installation. Kopiere die Dateien imcomponents
Ordner in dencomponents
Ordner deiner Joomla 4 Installation. -
Die Datenbank ist geändert worden, so dass es erforderlich ist, sie zu aktualisieren. Öffne den Bereich
System | Information | Database
, wie im TeilVeröffentlichen und Verstecken
beschrieben. Wähle deine Komponente aus und klicke aufUpdate Structure
. -
Öffne die Ansicht deiner Komponente im Administrationsbereich. Beim Bearbeiten eines Items gibt es jetzt den Tabulator
Display
und den ParameterShow Name
.
- Öffne die Optionen deiner Komponente im Administrationsbereich. Hier gibt es jetzt ebenfalls den Parameter
Show Name
.
- Öffne den Menümanager, um einen Menüpunkt anzulegen. Klicke dazu in der linken Seitenleite auf
Menü
und dann aufAll Menu Items
. Klicke danach auf die SchaltflächeNew
und fülle alle notwendigen Felder aus. Den passendenMenu Item Typ
findest du über dieSelect
Schaltfläche. Hier gibt es jetzt den TabulatorDisplay
und den ParameterShow Name
.
- Setzte den Parameter
Show Name
in unterschiedlichen Kombinationen und vergewissere dich, dass die Anzeige im Frontend korrekt ist.
Webmentions