HTMLHeader-Erweiterung

1. Einleitung

Die HTMLHeader-Erweiterung (nachfolgend HTMLHeader) dient dazu, beliebige HTML-Elemente nachträglich in den head- Bereich einer Seite zu kopieren, JavaScript und CSS-Objekte an beliebiger Stelle innerhalb eines APF-Ordners auszuliefern sowie JS- und CSS-Dateien zu einer Datei zusammenzufassen, zu minimieren, zu komprimieren und zu cachen. Dies ermöglicht schnellere Ladezeiten komplexer JS- und CSS-Konstrukte. Zusätzlich können sämtliche JS-Knoten an das Ende des Html-Body injiziert werden, was die gefühlte Ladezeit einer Seite nochmals erhöht.

2. Head-Knoten nachträglich hinzufügen

In dynamischen Anwendungen ist es oftmals notwendig von einem beliebigen Punkt aus nachträglich Daten im Html-Head der Seite anzufügen, obwohl dieser eigentlich nicht im aktuellen Einflussbereich liegt. Der HTMLHeader wurde zu genau diesem Zweck geschaffen. Mit ihm kann an jeder beliebigen Stelle der head-Bereich ergänzt werden, egal ob aus einem Template heraus, von einem Manager oder durch einen Documentcontroller. Es können so ziemlich alle möglichen HTML-Head-Elemente hinzugefügt werden, angefangen vom title-Tag bis hin zum Einbinden von JavaScript- und CSS-Dateien. Sollte ein benötigter Tag fehlen ist es problemlos möglich diesen nachträglich hinzuzufügen.

Die JS- und CSS-Dateien können dabei statisch definiert werden, oder mithilfe einer Action oder als Paket ausgeliefert werden, deren URLs automatisch generiert werden.

Im head-Bereich der Webseite muss der htmlheader:gethead Tag platziert werden, welcher sich mithilfe eines Output-Filters um die Ausgabe der nachträglich hinzugefügten Informationen kümmert:

APF-Template
<head> <core:addtaglib class="APF\extensions\htmlheader\pres\taglib\HtmlHeaderGetHeadTag" prefix="htmlheader" name="gethead" /> <htmlheader:gethead /> </head>

Sofern JavaScript Dateien an das Ende des Html-Body angefügt werden sollen später, so muss vor dem schließenden body-Tag die getbodyjs-Taglib eingefügt werden:

APF-Template
<body> ... <core:addtaglib class="APF\extensions\htmlheader\pres\taglib\HtmlHeaderGetBodyJsTag" prefix="htmlheader" name="getbodyjs" /> <htmlheader:getbodyjs /> </body>

2.1. In Templates

Es stehen einige Taglibs zur Verfügung, mit welchen Informationen in Templates hinzugefügt werden können. Sollte ein Anwendungsfall nicht abgedeckt sein, können problemlos eigene Taglibs geschrieben werden, welche intern die API des HTMLHeader ansprechen. Die Taglibs befinden sich alle unter extensions/htmlheader/pres/taglib, besitzen das Prefix "HtmlHeader" und müssen vor der Verwendung mittels core:addtaglib hinzugefügt werden. In einem Core-Template würde das Bekanntmachen für htmlheader:addcss so aussehen:

APF-Template
<core:addtaglib class="APF\extensions\htmlheader\pres\taglib\HtmlHeaderAddCssTag" prefix="htmlheader" name="addcss" /> [...]
2.1.1. Title-Tag

Der Titel der Webseite (title) kann mithilfe der addtitle-Taglib definiert werden. Wenn das optionale Attribut append auf true gesetzt wird, wird der Inhalt des Tags an einen eventuell bereits existierenden Titel angehängt, andernfalls wird der vorhandene Titel ersetzt.

APF-Template
<htmlheader:addtitle append="true"> Mein Titel der Webseite </htmlheader:addtitle>
2.1.2. Statischer JS- & CSS-Code

Statischer JS- und CSS-Code (inline, nicht in externer Datei ausgelagert) kann wie folgt hinzugefügt werden:

APF-Template
<htmlheader:addjscontent> $('#foo').appendClass('bar'); </htmlheader:addjscontent>
APF-Template
<htmlheader:addcsscontent> .exampleClass { border: 1px solid red; } </htmlheader:addcsscontent>
2.1.3. Statische JS- & CSS-Dateien

Statische JS- und CSS-Dateien können wie folgt hinzugefügt werden:

APF-Template
<htmlheader:addstaticjs file="http://maps.google.com/maps/api/js?sensor=false" />
APF-Template
<htmlheader:addstaticcss file="http://media.adventure-php-framework.org/css/apf.css" />
2.1.4. Dynamische JS- & CSS-Dateien

Es besteht die Möglichkeit die URL der JS- und CSS-Dateien automatisch generieren zu lassen, und die Dateien über eine FC-Action einbinden zu lassen, wenn diese sich z.B. außerhalb des von außen zugänglichen Bereichs befinden.

Hierfür stehen die beiden Taglibs htmlheader:addcss und htmlheader:addjs zur Verfügung. Die Funktionsweise wird nur anhand der addjs-Taglib gezeigt, da addcss nach dem gleichen Schema funktioniert.

Zur Verfügung stehen die Attribute:

  • url: Kann benutzt werden um Dateien von einem fremden Server einzubinden.
  • folder: Wenn eine Datei von einem fremden Server eingebunden wird, wird hiermit der Namespace zur Datei auf dem Server definiert, mit \ als / Trennung.
  • namespace: Der Namespace der Datei, wenn diese auf dem selben Server liegt.
  • filename: Der Dateiname ohne Dateiendung.
  • rewriting: Optional. Anzugeben, wenn explizit eine URL generiert werden soll, die rewriting an-/abgeschaltet hat. Standardmäßig wird die aktuelle Einstellung der Webseite verwendet.
  • fcaction: Optional. Wenn keine FC-Action zum Ausliefern verwendet werden soll, diesen wert auf false setzen. (Standard: true)

Beispiel: Einbinden einer JS-Datei des aktuellen Servers mithilfe einer FC-Action:

APF-Template
<htmlheader:addjs namespace="APF\sites\example\pres\frontend\static\js" filename="jquery.min" />

Beispiel: Einbinden einer externen Datei mit deaktiviertem URL-Rewriting und ohne FC-Action an das Ende des body-Bereichs:

APF-Template
<htmlheader:addjs url="http://static/" folder="js\anything" filename="jquery.min" rewriting="false" fcaction="false" appendtobody="true" />
2.1.5. JS- & CSS-Pakete

Mithilfe des im HTMLHeader integrierten JsCssPackagers können viele JS- oder CSS-Dateien zu je einer Datei zusammengefasst werden. Für die Konfiguration dieses Verhaltens scrollen Sie bitte zum Kapitel 3. JS- & CSS-Pakete definieren. Hier wird die Einbindung eines Pakets innerhalb eines Templates beschrieben.

Das name-Attribut entspricht dem Paketnamen, welcher in der Konfiguration als Sektionsname verwendet wird. Mögliche type Angaben sind js und css.

APF-Template
<htmlheader:addpackage name="form_clientvalidators_all" type="js" />
APF-Template
<htmlheader:addpackage name="mystylesheetpackage" type="css"
2.1.6. CSS-Images (Favicons etc.)

Um ein Favicon hinzuzufügen gibt es die Taglib htmlheader:addcssimage:

APF-Template
<htmlheader:addcssimage rel="icon" href="favicon.png" type="image/png" />
2.1.7. Reihenfolge beeinflussen

Die Reihenfolge der JS- und CSS-Dateien und Pakete kann mit dem optionalen Attribut priority beeinflusst werden. Je größer die angegebene Zahl (Integer) desto weiter oben wird die Datei eingefügt:

APF-Template
<htmlheader:addpackage name="admin" type="js" appendtobody="true" priority="100" />
Wird das Attribut nicht angegeben, wird 0 als Standardwert gesetzt.

2.2. In Controllern und anderen PHP-Dateien

Die Erweiterung besteht aus einer Vielzahl von Html-Knoten ("Nodes") im Namespace APF\extensions\htmlheader\biz. Die jeweils gewünschten Knoten müssen zuerst eingebunden werden, z.B. über:

PHP-Code
use APF\extensions\htmlheader\biz\DynamicJsNode;

Es stehen folgende Nodes zur Verfügung:

  • BaseUrlNode: Um base href="" zu definieren
  • CanonicalNode: Um link rel="canonical" href="" zu definieren
  • ConditionalDynamicCssNode
  • ConditionalStaticCssNode
  • CssContentNode
  • CssImageNode
  • CssPackageNode
  • DynamicCssNode
  • DynamicJsNode
  • HttpMetaNode
  • JsContentNode
  • JsPackageNode
  • LanguageMetaNode
  • RefreshNode
  • SimpleMetaNode
  • SimpleTitleNode
  • StaticCssNode
  • StaticJsNode
  • Anschließend wird eine Instanz des HtmlHeaderManager bezogen, welcher für die Speicherung der Knoten zuständig ist:

    PHP-Code
    // Get an instance of HtmlHeaderManager: $HHM = $this->getServiceObject('APF\extensions\htmlheader\biz\HtmlHeaderManager');

    Nun kann eine Instanz jedes gewünschten Knoten erzeugt werden, und dem HtmlHeaderManager übergeben werden:

    PHP-Code
    use APF\extensions\htmlheader\biz\RefreshNode; // Add a refresh on index.php?test=abc, with a delay of 5 seconds: $HHM->addNode(new RefreshNode('index.php', 5, array("test" => "abc")));
    PHP-Code
    use APF\extensions\htmlheader\biz\SimpleTitleNode; // Add a title $HHM->addNode(new SimpleTitleNode("Example title"));
    PHP-Code
    use APF\extensions\htmlheader\biz\DynamicCssNode; //Get instance, configure in constructor and add to HtmlHeaderManager: $CssNode = new DynamicCssNode($url, $namespace, $filename, $rewriting, $fcaction); $HHM->addNode($CssNode);
    PHP-Code
    use APF\extensions\htmlheader\biz\SimpleMetaNode; // Add a simple description meta tag $HHM->addNode(new SimpleMetaNode('description', $description));
    PHP-Code
    use APF\extensions\htmlheader\biz\HttpMetaNode; // Add a http meta tag definition $HHM->addNode(new HttpMetaNode('content-type', 'text/html; charset=utf-8'));
    PHP-Code
    use APF\extensions\htmlheader\biz\JsPackageNode; // Define and add a JsCSSPackager-Package (JavaScript) to HHM $PackageNode = new JsPackageNode($url, $name, $type, $rewriting); $HHM->addPackage($PackageNode);
    Die Reihenfolge der Nodes lässt sich ebenfalls über die Methode setPriority() beeinflussen:
    PHP-Code
    use APF\extensions\htmlheader\biz\SimpleMetaNode; $node = new SimpleMetaNode('description', $description); $node->setPriority(20); $HHM->addNode($node);
    Die JavaScript-Nodes oder -Pakete können auch zum Ende des Body hinzugefügt werden. Nutzen Sie hierzu die Methode setAppendToBody():
    PHP-Code
    use APF\extensions\htmlheader\biz\JsPackageNode; $PackageNode = new JsPackageNode($url, $name, $type, $rewriting); $PackageNode->setAppendToBody(true); $HHM->addPackage($PackageNode);

    3. JS- & CSS-Pakete definieren

    Sollen Pakete ausgeliefert werden, müssen diese vorher konfiguriert werden. Hierzu muss die Konfigurations-Datei config/extensions/htmlheader/biz/{CONTEXT}/{ENVIRONMENT}_JsCssPackager.ini angelegt werden.
    Für jedes Paket muss dort eine Sektion angelegt werden, mit einem frei wählbaren Paketname als Sektionsname:

    APF-Konfiguration
    [administration] ClientCacheDays = "7" ; How long should it be cached on client? ServerCacheMinutes = "10080" ; How long should it be cached on server? EnableShrinking = "false" ; Shrink the code in the package? PackageType = "js" ; Possible types: 'js' and 'css' ; The files the package contains. Filename without extension! Files.1.Namespace = "VENDOR\pres\js\jquery" Files.1.Filename = "jquery-3.3.1.min" Files.2.Namespace = "VENDOR\pres\js\popper" Files.2.Filename = "popper.min" Files.3.Namespace = "VENDOR\pres\js\bootstrap" Files.3.Filename = "bootstrap.min"

    Jedes Paket kann individuell mit Cachingzeiten konfiguriert werden, sowie Shrinking (de-)aktiviert werden. Beim Shrinking werden unnötige Zeichen aus den Dateien entfernt, daraus resultiert meistens ein einzeiliger Code der für Menschen schwer lesbar ist, jedoch vom Browser problemlos interpretiert werden kann.

    In der Subsection Files wird für jede Datei eine Nummer angegeben (Mehrfachdefinition einer Zahl ist nicht erlaubt und führt zu unerwünschten Resultaten), und jeweils Namespace und Dateiname ohne Dateiendung angegeben.

    Selbiges gilt für CSS-Dateien, hier muss lediglich der PackageType auf "css" geändert werden.
    Wenn serverseitiges Caching aktiviert wird, wird das fertige Paket einmal komprimiert (gzip) und einmal unkomprimiert (für Clienten die kein gzip beherrschen) zwischengespeichert, damit dies beim nächsten Aufruf nicht erneut generiert werden muss und direkt ausgeliefert werden kann. Hierfür wird der CacheManager des APF verwendet.
    Für das Caching wird daher eine Konfiguration des CacheManagers benötigt. Der Packager verwendet den Cache mit Name jscsspackager_cache, dieser muss in der CacheManager-Config definiert werden. Es wird hierfür der TextCacheProvider empfohlen.
    Für weitere Informationen beachten Sie bitte die Dokumentation zum CacheManager: CacheManager.

    4. JS- & CSS-Dateien/Pakete ausliefern

    Um JS- & CSS-Dateien per FC-Action ausliefern zu können, beziehungsweise um entsprechende Pakete ausliefern zu können, muss eine FrontController-Action konfiguriert werden. Unter config/extensions/htmlheader/{CONTEXT}/{ENVIRONMENT}_actionconfig.ini muss daher folgende Konfiguration abgelegt werden:

    APF-Konfiguration
    [JsCss] ActionClass = "APF\extensions\htmlheader\biz\actions\JsCssInclusionAction"

    Desweiteren können einfache JS- & CSS-Dateien ebenfalls geshrinkt (verkleinert) werden vor dem ausliefern, um Bandbreite zu sparen. Dies kann in der Konfigurations-Datei config/extensions/htmlheader/biz/{CONTEXT}/{ENVIRONMENT}_JsCssInclusion.ini festgelegt werden:

    APF-Konfiguration
    [General] EnableShrinking = "true"
    Diese Einstellung gilt nur für Dateien. Pakete können einzeln konfiguriert werden, beachten Sie dafür das Kapitel 3. JS- & CSS-Pakete definieren.
    Um JavaScript-Dateien in JS-Paketen zu verkleinern ist die externe Bibliothek JShrink erforderlich. Diese ist unter https://github.com/tedivm/JShrink verfügbar. Zur Aktivierung des Shrinking binden Sie bitte die Datei Minifier.php z. B. in Ihre Bootstrap-Datei ein um die Klasse JShrink im globalen Namespace verfügbar zu machen.

    5. Aussehen der Action-URLs

    Im APF-Standardschema sehen die URLs für Dateien und Pakete, die mithilfe der Action eingebunden werden, wie folgt aus:

    Sofern ausschliesslich die HtmlHeader-Nodes verwendet werden, ist es nicht notwendig dieses Schema zu kennen. Dies ist nur nötig wenn die URLs manuell eingefügt werden müssen, da die Nodes die URL automatisch generieren.

    Ohne URL-Rewriting:

    Code
    // Einzelne Css-Datei (themes/default/css/menu.css) /index.php?extensions_htmlheader-action:JsCss=path:themes_default_css|type:css|file:menu // Einzelnes Paket (CSS) /index.php?extensions_htmlheader-action:JsCss=package:DefaultTheme.css

    Mit URL-Rewriting:

    Code
    // Einzelne Css-Datei (themes/default/css/menu.css) /~/extensions_htmlheader-action/JsCss/path/themes_default_css/type/css/file/menu // Einzelnes Paket (CSS) /~/extensions_htmlheader-action/JsCss/package/DefaultTheme.css

    Kommentare

    Möchten Sie den Artikel eine Anmerkung hinzufügen, oder haben Sie ergänzende Hinweise? Dann können Sie diese hier einfügen. Die bereits verfassten Anmerkungen und Kommentare finden Sie in der untenstehenden Liste.
    Für diesen Artikel liegen aktuell keine Kommentare vor.

    Um unsere Webseite für Sie optimal zu gestalten und fortlaufend verbessern zu können, verwenden wir Cookies. Durch die Nutzung der Webseite stimmen Sie der Verwendung von Cookies zu. Weitere Informationen finden Sie in den Datenschutzrichtlinien.