modChrome-Nerverl. Modulstile sind ab Joomla 4 JLayouts (JLayoutHelper-Funktionalitäten)

Bisher hat man eigene Modulstile ("Modul-Chromes") in der unhandlichen und ggf. konfliktbeladenen Templatedatei html/modules.php definiert. Seit Joomla 4 wird für jeden Stil ein eigenes Layout im Ordner html/layouts/chromes/ angelegt. Die verwenden die altbekannten JLayoutHelper-Funktionalitäten. Klingt vielleicht komplizierter als es final ist. Sein Joomla-3-Template kann man auch schon vorbereiten.

Bild in größter Auflösung öffnen (Popup)

Muss oder nicht müssen? Wie immer die Frage.

Kurz: Ein klares Jain auf die Frage.

Nein, man muss sein Joomla-3-Template diesbezüglich nicht unbedingt anpassen, wenn man es nach Version 4 mitnehmen will. Ich persönlich mache das allerdings, da es einen Mittelweg gibt, die eklige modules.php jetzt schon auszudünnen, um sie dann unter Joomla 4 einfach löschen zu können und alles wird gut.

Zwei Wochen später präzisiere ich obige Antwort lieber: Ja, spätestens unter Joomla 4 sollte man den unten beschriebenen Umbau der Modulstile auf JLayouts früh-früh-zeitig in Angriff nehmen, bevor man anfängt, im Backend Module zu bearbeiten, um keine dummen Erlebnisse zu haben. Dann, wenn sich noch eine html/modules.php im Templateordner befindet und sich die darin enthaltenen Stile nicht im Ordner html/layouts/chromes finden; dort als Einzeldateien.

Ein Blick in die Antike

Öffnet man in J!3 ein Modul und inspiziert das Feld "Modulstil", sieht man ein paar Stile unter der Überschrift "System"; bspw. "html5".

Im Ordner des system-Templates, nicht zu verwechseln mit dem Protostar-Template, das aber eigene Stile im analogen Ordner haben könnte, findet man in zugehöriger, oben genannter Datei die function modChrome_html5(...). Hier wird also der Stil "html5" definiert, den ich auch in meinem und jedem anderen Template als Wunschstil (Parameter style) für eine Modulposition angeben kann.

<jdoc:include type="modules" name="position-8" style="html5" />

Crux dabei: Lege ich in meinem, eigenen Template oder Protostar nun ebenfalls eine solche Stil-Definition mit function modChrome_html5(...) in der  html/modules.php an, in der Erwartung, ich könnte so den Stil überschreiben, hängt sich Joomla auf:

Fatal error: Cannot redeclare modChrome_html5() (previously declared in /templates/system/html/modules.php:23) in /templates/protostar/html/modules.php on line 12

Ich muss einen einzigartigen Funktionsnamen erfinden und die Modulposition in meiner Template-index.php entsprechend umschreiben (Parameter style) oder alle Module öffnen und den Modulstil darin umschalten. Ein Joomla-üblicher Template-Override des System-Stils "html5" und anderer ist nicht möglich, nur ein Ersetzen.

Zweite Crux: Oft sind diese html/modules.php komplett überladen mit Code, je nachdem wie kreativ so ein Template-Ersteller ist und der ganze Code wird geladen, egal, ob man ihn später benötigt oder nicht.

Und jetzt Modul-Stile als JLayouts. Überschreibbar!

In J!4 hat sich in der Modulstil-Auswahl in einem Modul nicht viel geändert. Auch da findet sich ein System > html5 zur Auswahl.

Eine Datei /templates/system/html/modules.php gibt es aber nicht mehr, ebenso die ehemaligen, blöd benannten, modChrome_-Funktionen.

Die System-Stile finden sich jetzt, und jeder in einer eigenen Datei, im Joomla-Ordner /layouts/chromes/, darunter auch html5.php. Ein paar System-Stile wie "xhtml" sind übrigens verschwunden, lassen sich aber durch das neue Verfahren im eigenen Template nachbasteln, ohne, dass man groß in Modulen oder Template rumwerkeln muss, falls man den Modulstil exzessiv verwendet hat.

 Damit die Stileauswahl im Folgenden funktioniert, darf, mindestens bis Joomla 4.2.4, der Ordner /DEINTEMPLATE/ keine Bindestriche enthalten. Sonst findet Joomla die richtige Datei nicht. Keine Ahnung, was diese unnötige Einschränkung bzgl. Templatenamen soll.

Will ich nun den Stil "html5" templateweit variieren, überschreiben, kopiere ich obige Datei als /templates/DEINTEMPLATE/html/layouts/chromes/html5.php und ändere sie nach Belieben. Falls der Ordner noch nicht existiert, lege ich ihn zuvor an.

Selbstverständlich funktionieren auch komponentenweise Overrides wie es für JLayouts in Joomla schon lange üblich ist. Will ich also nur auf den Kontaktseiten den Stil ein bisschen oder ganz anders "stylen", erstelle ich eine Kopie im Ordner /templates/DEINTEMPLATE/html/layouts/com_contact/chromes/html5.php.

Wenn ich sogar eine eigene Komponente namens Firlefanz (com_firlefanz) programmiert habe, lege ich den Stil-Override in /components/com_firlefanz/layouts/chromes/html5.php.

Zur Erinnerung

JLayouts überschreiben sich in folgender Reihenfolge. Das letzte Existierende gewinnt. Die beiden mit com_firlefanz im Pfad aber nur, wenn man sich auf einer Seite befindet, die was von Komponente Firlefanz anzeigt.

• /layouts/chromes/stilname.php
• /templates/DEINTEMPLATE/html/layouts/chromes/stilname.php
• /components/com_firlefanz/layouts/chromes/stilname.php
• /templates/DEINTEMPLATE/html/layouts/com_firlefanz/chromes/stilname.php

Es gibt auch Tricksereien andere Pfade zu forcieren. Nicht Thema hier.

Beispiel: System-Stil "xhtml" nach Joomla 4 retten

Den gibt es, wie gesagt, in J!4 nicht mehr. Ebenso wurden die Stile horz und rounded entfernt.

• Lege Datei /templates/DEINTEMPLATE/html/layouts/chromes/xhtml.php an.
• Kopiere aus J!3-Datei den Inhalt der function modChrome_xhtml(...) in die Datei.
• Ergänze die ersten sechs Zeilen aus folgendem Code!

<?php
defined('_JEXEC') or die;

$module = $displayData['module'];
$params = $displayData['params'];
$attribs = $displayData['attribs'];

$moduleTag      = htmlspecialchars($params->get('module_tag', 'div'),
	ENT_QUOTES, 'UTF-8');
$headerTag      = htmlspecialchars($params->get('header_tag', 'h3'),
	ENT_QUOTES, 'UTF-8');
$bootstrapSize  = (int) $params->get('bootstrap_size', 0);
$moduleClass    = $bootstrapSize !== 0 ? ' span' . $bootstrapSize : '';

// Temporarily store header class in variable
$headerClass    = $params->get('header_class');
$headerClass    = $headerClass ? ' class="'
	. htmlspecialchars($headerClass, ENT_COMPAT, 'UTF-8') . '"' : '';

if (!empty ($module->content)) : ?>
	<<?php echo $moduleTag; ?>
	class="moduletable<?php echo htmlspecialchars($params->get('moduleclass_sfx'),
		ENT_COMPAT, 'UTF-8') . $moduleClass; ?>">
		<?php if ((bool) $module->showtitle) : ?>
			<<?php echo $headerTag . $headerClass . '>' . $module->title; ?>
			</<?php echo $headerTag; ?>>
		<?php endif; ?>
		<?php echo $module->content; ?>
	</<?php echo $moduleTag; ?>>
<?php endif;

Eine Modulpositions-Zeile im Template mit Wunschstil "xhtml" funktioniert wieder. So was meine ich:

<jdoc:include type="modules" name="position-8" style="xhtml" />

Und in den Modulen muss ich den Stil auch nicht umstellen, wo er explizit eingestellt war. Erst mal zumindest. Aaaaaber, dann doch Enttäuschung: Spätestens vor dem nächsten Speichern des Moduls unter J!4 dann wohl leider doch neu auswählen.

Und wie war das gemeint mit "die eklige modules.php schon unter J!3 auszudünnen"?

Ich habe in der html/modules.php meines Templates einen eigenen Stil/modChrome "firlefanz" definiert.

function modChrome_firlefanz($module, &$params, &$attribs)
{
 [---Hier ein Haufen PHP-HTML-Code zum Stil-Generieren---]
}

• Ich lege eine Datei /templates/DEINTEMPLATE/html/layouts/chromes/firlefanz.php an,
• schneide aus dem obigen Code den Teil [---Hier ein Haufen PHP-HTML-Code zum Stil-Generieren---] raus und lege ihn erst mal in der neuen Datei blind ab. Geht gleich weiter damit.
• Dann füge ich in die jetzt leere function in der modules.php den folgenden JLayoutHelper-Code ein:

function modChrome_firlefanz($module, &$params, &$attribs)
{
	echo JLayoutHelper::render('chromes.firlefanz',
		array(
			'module' => $module,
			'params' => $params,
			'attribs' => $attribs
		)
	);
}

• Zuletzt die firlefanz.php noch ergänzen:

<?php
defined('_JEXEC') or die;

$module = $displayData['module'];
$params = $displayData['params'];
$attribs = $displayData['attribs'];

[---Hier der kopierte Haufen PHP-HTML-Code zum Stil-Generieren---]

Und schon kann Joomla 4 kommen und ich kann später noch die nun wirkungslose html/modules.php löschen.

Ich kann sie aber auch parallel noch drinnen lassen, falls sich darin Stile befinden, die ich noch nicht nach html/layouts/chromes/ portiert habe. Die sollten laut Versprechen (nicht meines!) nämlich auch noch funktionieren.

So zumindest meine Erwartungen. Dass man ggf. doofe Überraschungen mit Joomla-3-nach-4-Migrationen erlebt, weiß ich ja mittlerweile schon...

Und die Erwartung wurde enttäuscht! Man darf sich keinesfalls darauf verlassen, dass die modules.php noch irgendwie irgendwo irgendwann unter Joomla 4 funktioniert. Ich bin jetzt aber leider auch angenervt genug, um NICHT auszuprobieren, wo wie wann dann eventuell doch oder nur manchmal vielleicht dann doch nicht. ERGO: Bauen Sie Ihre Modulstile zu JLayouts um, wie oben beschrieben, je früher desto besser!