Parameter

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 Typ radio hat in Joomla einen typischen Look. Es wird Switcher genannt und den Look erzeugst du über das Layout joomla.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

1. Installiere deine Komponente in Joomla Version 4, um sie zu testen: Kopiere die Dateien im administrator Ordner in den administrator Ordner deiner Joomla 4 Installation. Kopiere die Dateien im components Ordner in den components Ordner deiner Joomla 4 Installation.

2. Die Datenbank ist geändert worden, so dass es erforderlich ist, sie zu aktualisieren. Öffne den Bereich System | Information | Database, wie im Teil Veröffentlichen und Verstecken beschrieben. Wähle deine Komponente aus und klicke auf Update Structure.

3. Öffne die Ansicht deiner Komponente im Administrationsbereich. Beim Bearbeiten eines Items gibt es jetzt den Tabulator Display und den Parameter Show Name.

4. Öffne die Optionen deiner Komponente im Administrationsbereich. Hier gibt es jetzt ebenfalls den Parameter Show Name.

5. Öffne den Menümanager, um einen Menüpunkt anzulegen. Klicke dazu in der linken Seitenleite auf Menü und dann auf All Menu Items. Klicke danach auf die Schaltfläche New und fülle alle notwendigen Felder aus. Den passenden Menu Item Typ findest du über die Select Schaltfläche. Hier gibt es jetzt den Tabulator Display und den Parameter Show Name.

6. Setzte den Parameter Show Name in unterschiedlichen Kombinationen und vergewissere dich, dass die Anzeige im Frontend korrekt ist.