Venobox in Joomla: Integration via JHtml-Helper (System-Plugin VenoboxGhsvs)

Die Stärke der Venobox, einer JavaScript-Lightbox für Bild-Pop-Ups, ist, dass sie die Bildgröße nur an die Breite des Viewports anpasst. Wenn das Bild höher als der Darstellungsbereich ist, kann man es vertikal scrollen. Die Simple Image Gallery Extended von Kubik Rubik verwendet sie zum Beispiel. Mein Plugin hat einen anderen Ansatz. Es hilft, die Venobox in eigenem Joomla-Code zu nutzen/konfigurieren.

Die JHtml-Klasse ist obsolet und sollte in zukonftsorientiertem Umfeld wannimmer möglich nicht mehr verwendet werden. Irgendwann wird sie nicht mehr funktionieren. Schon in Joomla 5 muss Joomlas Plugin "Verhalten - Abwärtskompatibilität" aktiviert sein, damit man keine fatalen Fehler bekommt (Seite hängt sich auf).
Da die Klassen JHtml und HTMLHelper derzeit vom Ergebnis der Ausgabe her identisch sind und zweitere Variante etwas mehr Erklärung benötigt, verwende ich oft faul auch Erstere in Codebeispielen. Gesagt sei nur, dass man seit Joomla 3.9 beide Varianten verwenden kann. Ebenso in Joomla 4, wo jedoch im Core-Code die HTMLHelper-Klasse das JHtml gänzlich abgelöst hat. Vielleicht von Interesse: Joomla: JHtml- vs. HTMLHelper-Methoden. Unterschiede?!?

Einfaches Test-Szenario. Was auf Sie zukommt.

Das Joomla-Plugin PLG_SYSTEM_VENOBOXGHSVS ist keine "Lightbox", die von alleine Bilder in PopUps ("Modals") zaubert. Man muss dafür nach der Installation und Aktivierung eine oder mehrere Zeilen Code im PHP der Seite platzieren. Das kann auch im Template sein (index.php), wenn man das PopUp-Feature global verfügbar haben will.

Schritt 1: Die Ladezeile im PHP-Code

Die simpelste Variante einer solchen Zeile; ohne weitere Konfiguration:

JHtml::_('plgvenoboxghsvs.venobox');

oder mit Namespaces; ab Joomla 3.9 möglich:

Joomla\CMS\HTML\HTMLHelper::_('plgvenoboxghsvs.venobox');

oder, falls die HTMLHelper-Klasse, der aktuellere Ersatz für die veraltete JHtml-Klasse, sowieso per use Zeile am Anfang der Datei bekannt gemacht wurde:

use Joomla\CMS\HTML\HTMLHelper;

HTMLHelper::_('plgvenoboxghsvs.venobox');

Dadurch wird der nötige Venobox-Grund-Code (JavaScript und CSS) in die Seite geladen. Zeile 4 verwendet die im Plugin eingestellte Konfiguration oder, falls keine gemacht, die Grundkonfiguration wie im folgenden Codeblock zu sehen:

<link href="/media/plg_system_venoboxghsvs/css/venobox/venobox.min.css?2.0.4" rel="stylesheet" />
<script src="/media/plg_system_venoboxghsvs/js/venobox/venobox.min.js?2.0.4"></script>

<script>document.addEventListener("DOMContentLoaded", (event) => {new VenoBox({"selector":".venobox"})});</script>

Exkurs: Assets-Overrides - CSS und JS

Für die Assets der Zeilen 1 und 2 kann man bei Lust (echt jetzt?) altherkömmlich Overrides im Template-Assets-Ordner ablegen; in Joomla 4 auch mit Hilfe der joomla.asset.json des Templates oder eigener Erweiterung, wenn man die Override-Pfade individueller über die uri-Attribute "umbiegen" will, statt den ansonsten üblichen Override-Pfadwürmern wie beispielsweise .../css/plg_system_venoboxghsvs/venobox/venobox.css.

Eine zusätzliche, eigene, zu ladende venobox.css kann man unter Joomla 3 im Ordner /templates/DEINTEMPLATE/css/ ablegen, in Joomla 4 ist man flexibler und kann sie ebenso in ein anderes CSS-Assets-Verzeichnis reintun, das ja neumodern vielleicht /media/templates/site/DEINTEMPLATE/css ist. Der Joomla-Web-Asset-Manager findet das dann schon; egal wo.

Die joomla.asset.json dieses Plugins.

Schritt 2: HTML-Code für poppendes Bild

Weiters muss man seinen HTML-Code entsprechend auszeichnen, was ja auch bei anderen "Lightboxes" notwendig ist. Im einfachsten Fall sieht das so aus:

<a href=images/meinBild-das-aufpoppen-soll.jpg class="venobox">
 ... Hier ein Bild oder ein Text oder sonstwas, was man klickt ...
</a>

Beachte das class="venobox" im <A>-Tag! Das ist die Standard-CSS-Klasse, auf die Venobox horcht. Man kann eine abweichende konfigurieren; in den Plugin-Einstellungen oder in der HTMLHelper-PHP-Zeile (Beispiele im Folgenden).

Das href-Attribut des <A>-Tag ist der Pfad zum Bild, das aufpoppen soll.

Mit einem geeigneten Joomla-Editor ja kein Problem einen Link entsprechend per Klickie-Tippie auszuzeichnen.

Ergebnis

... Hier ein Bild oder ein Text oder sonstwas, was man klickt ...

Herunterladen, Installation und Vorarbeiten

  • Am Ende dieses Beitrags finden Sie den Link zum Download des Plugins, das Sie im Backend Ihres Joomlas Installieren. Beachten Sie auf der Downloadseite, dass es Versionen für unterschiedliche Joomla-Versionen gibt (siehe dort jeweils Hinweis "Joomla-Target-Platform(s)").
  • Sie finden es anschließend im Joomla-Backend unter Erweiterungen > Plugins unter dem Namen System - Venoboxintegration-v2plus by GHSVS.de. Öffnen, aktivieren und speichern Sie es.
  • Scheuen Sie sich nicht, mir Fragen zu stellen (deutsch oder englisch), wenn Sie Hilfe benötigen!

Nice to know (oder nicht). "Nerds-Talk".

JHtml-, HTMLHelper-Klassen - Was ist das?

Beides sind in Joomla existierende "Mutterklassen", die es Programmierern mittels "Kinderklassen" und darin befindlicher Methoden (Funktionen) erlauben, mehr oder weniger komplexen HTML-Code via PHP-Einzeiler in eine Seite einzusetzen. Das können z.B. <LINK>s auf CSS-Dateien im <HEAD> der Seite sein, aber auch speziell aufbereitete Codeblöcke an anderen Stellen. Vieles ist möglich.

Die Mutterklassen dienen als Loader für die Kinderklassen (sie laden die Kinder bei Bedarf), deren Speicherort man mittels einer Methode addIncludePath(...) bekannt machen kann. Auch mein Plugin hat so Kinder-Klassen dabei.

Natürlich übernimmt das Plugin im Normalbetrieb diesen Job. Wer es deaktiviert lassen will und trotzdem die Venobox-JHtml-Klasse nutzen, kann so eine Zeile im PHP-Code abfeuern:

\Joomla\CMS\HTML\HTMLHelper::addIncludePath(JPATH_SITE . '/plugins/system/venoboxghsvs/src/Html');

In Joomla 4, falls jemand nach Codestellen mit  addIncludePath(...) sucht, wo diese Methode zum Einsatz kommt: Der Core verwendet nun vornehmlich weitaus komplexere (im Volksmund: kompliziertere) Techniken für das Bekanntmachen der Speicherorte. Trotzdem funktioniert der "alte Kram" immer noch. Wie lange noch? Keine Ahnung.

Joomla bringt viele praktische HTMLHelper-Kinder-Klassen und -Methoden mit, die man verwenden kann.

Core-Beispiel: Link einsetzen

echo \Joomla\CMS\HTML\HTMLHelper::_('link',
 'https://www.ghsvs.de',
 'Dumme Seite',
 array('target' => '_blank', 'class' => 'text-fett')
);

erzeugt

<a href="https://www.ghsvs.de" target="_blank" class="text-fett">Dumme Seite</a>
Core-Beispiel: Bootstrap-JavaScript und (nur in Joomla 3) zugleich JQuery-Link in <HEAD> (seit Joomla 4 eventuell auch anderswo) einsetzen
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.framework');

erzeugt (in Joomla 3):

<script src="/media/jui/js/jquery.min.js"></script>
<script src="/media/jui/js/jquery-noconflict.js"></script>
<script src="/media/jui/js/jquery-migrate.min.js"></script>
<script src="/media/jui/js/bootstrap.min.js"></script>

Da Joomla 4 neuere Bootstrap-Versionen beigepackt hat, die JQuery nicht mehr zwingend benötigen, sieht das Ergebnis dort anders aus.

Core-Beispiel: Text verkürzen
echo \Joomla\CMS\HTML\HTMLHelper::_('string.truncate',
 '1234567891011121314151617',
 13,
 false
);

Ausgegeben wird der auf 13 Zeichen verkürzte Text; leider immer mit drei Punkten dahinter:

1234567891011...

Das Joomla-Plugin PLG_SYSTEM_VENOBOXGHSVS

Das Plugin bringt einen eigenen JHtml-Helper mit, also eine JHtml-Kinderklasse, und macht Joomla das Verzeichnis, wo sie liegt, (nur) im Frontend bekannt, ohne sie schon komplett zu laden. Sie kann dann genutzt werden oder auch nicht. Eine Beispielzeile haben wir oben schon gesehen.

Bild(er) via Link mit CSS-Klasse venobox öffnen

Siehe oben Überschrift "Test-Szenario".

Standard-Konfiguration

Im Plugin finden Sie den Tabulator Standards-Configuration Dort einige Konfigurationsparameter, die ich manchmal verwende.

Wenn Sie alle im Einstellfeld "Activate" deaktivieren oder sie löschen, werden die Standards des Venobox-JavaScripts verwendet.

Alle diese Einstell-Möglichkeiten finden Sie auf der Herstellerseite https://veno.es/venobox/ unter der Überschrift "Options". Im Plugin können Sie sie hinzufügen, überschreiben usw. Vergessen Sie das Aktivieren der einzelnen Parameter und abschließendes Speichern des Plugins nicht.

Unsere blanke Zeile unter "Test-Szenario" wird sie dann automatisch in den Code einsetzen.

Immer eigene CSS-Klasse zum PopUp-Öffnen

Im Reiter Standards-Configuration des Plugins finden Sie ein Eingabefeld "Standard selector". Wenn Sie hier z.B. .pillePalle eintragen (Punkt vorne nicht vergessen!), lauscht das Plugin nicht mehr auf Links mit class="venobox" sondern auf class="pillePalle".

Eigene CSS-Klasse zum Öffnen verwenden und erstes code-seitiges Konfigurationsbeispiel

Beispiel-Szenario: Zwei oder mehr PopUp-Klassen verwenden
  1. Ich hatte mal ein PopUp-Plugin installiert, das auf die CSS-Klasse class="thickbox" in Links lauschte. Das war kaputt und ich habe es deinstalliert. Anstatt nun überall in den alten Beiträgen die Link-Klasse gegen class="venobox" auszutauschen, verwende ich die Venobox mit einer zusätzlichen, abgewandelten Konfiguration, die ich per Code "übermittele".
  2. Das alte Plugin verwendete das title-Attribut des Links als Beschriftung für das Bild im PopUp. Ich habe die Venobox über Plugin-Konfiguration aber so eingestellt, dass das Attribut data-title verwendet wird. Auch das wollte ich jetzt natürlich nicht überall umschreiben müssen.
  3. Andererseits hatte ich in neueren Beiträgen schon überall die class="venobox" verwendet und dafür den Einzeiler oben unter Überschrift "Test-Szenario" in meinem Template drinnen, die die Optionen aus dem Plugin verwendet. Eine globale Umstellung des "Standard selector" auf .thickbox im Plugin war also nicht zielführend, weil ich ja beide Klassen nebeneinander verwenden wollte.

Aaaalso ?:

  • Also übergibt man in einer zusätzlichen HTMLHelper-Zeile seinen Wunsch-Selektor (beachte im folgenden Code den Punkt in Zeile 3 vorne dran).
  • Zeile 4: Weiters möchte ich, dass in diesen PopUps nicht das data-title-Attribut des Links als Beschriftung verwendet wird, was ich im Plugin eingestellt habe, sondern das Attribut title. Man kann jedes Attribut verwenden, das in einem Link angegeben ist. Könnte also auch sein eigenes erfinden oder sogar das href-Attribut des Links.
  • Zeile 5 fügt kleine Buttons unter dem Bild ein; zum Download oder Kopieren des Links des Bildes.

Das PHP:

\Joomla\CMS\HTML\HTMLHelper::_('plgvenoboxghsvs.venobox',
 array(
  'selector' => '.thickbox',
  'titleattr' => 'title',
  'share' => true,
 )
);

Das HTML für die Links:

<p>
 <a href="/images/erweiterungen/plg_venoboxghsvs/Demobild_700x2000px.jpg" class="thickbox"
 data-title="Ich tue gar nichts, weil ich wegkonfiguriert wurde."
 title="Hallo, ich bin der title des Bild-Links und werden im PopUp angezeigt.">
  Öffne ein PopUp via eigener CSS-Klasse 'thickbox' mit Beschriftung aus 'title' und nicht 'data-title'. Mit 2 Buttons unter dem Bild.
 </a>
</p>
<p>
 <a href="/images/erweiterungen/plg_venoboxghsvs/Demobild_700x2000px.jpg" class="venobox"
 data-title="Hallo, ich bin der data-title des Bild-Links."
 title="Ich bin der title des Bild-Links und hab nix zu tun.">
  Und ich bin ein PopUp, das weiterhin die Klasse 'venobox' verwendet und die Grundkonfiguration des Plugins.
 </a>
</p>
Ergebnis

Öffne ein PopUp via eigener CSS-Klasse 'thickbox' mit Beschriftung aus 'title' und nicht 'data-title' und 2 Teilen-Knöpfen

Und ich bin ein PopUp, das weiterhin die Klasse 'venobox' verwendet und die Grundkonfiguration des Plugins.

Crux

Man muss ein bisschen aufpassen, dass man pro Seite jeden CSS-Selektor, z.B.  class="meinePopUpKlasse", nur 1x konfiguriert. Es passiert zwar nix, aber die zweite Konfiguration, wird dann ignoriert. Ein früheres

\Joomla\CMS\HTML\HTMLHelper::_('plgvenoboxghsvs.venobox', array('selector' => '.meinePopUpKlasse'));

im Joomla-Ablauf wird ein später im Joomla-Ablauf auftauchendes

\Joomla\CMS\HTML\HTMLHelper::_('plgvenoboxghsvs.venobox',
 array(
  'selector' => '.meinePopUpKlasse',
  'titleBackground' => '#f00',
  'titleColor' => '#000'
 )
);

unwirksam machen.

Was die Sache kompliziert(er) machen kann, ist, dass es oft nicht einfach nachvollziehbar ist, wann Joomla, welche Konfiguration abarbeitet. Eine in einem Modul kommt bspw. früher dran als eine im Template und ähnlich.