Prty::Html::Tag - Generierung von HTML-Tags
Prty::Hash
Die Klasse generiert HTML-Code. Sie implementiert zwei Methoden - tag() und cat() - mit denen HTML-Code beliebiger Komplexität erzeugt werden kann.
Ein Objekt der Klasse wird instantiiert durch
my $h = Prty::Html::Tag->new;
Die Methoden dieses Objekts generieren (X)HTML.
Die Methode tag() generiert einen Tag. Sie kennt alle Element-Typen des W3C HTML/XHTML Standard und liefert bei Aufruf eine formatierte Tag-Repräsentation des betreffenden Element-Typs und seiner Attribute. Beispiel:
$str = $h->tag('img',src=>'URL');
ergibt
<img src="URL" alt="" />
Das Beispiel verdeutlicht, dass der Methode tag() die Element-Typen "kennt". In diesem Fall "weiß" die Methode, dass Elemente des Typs 'img' leer sind und diese ein Pflicht-Attribut 'alt' besitzen (wird es nicht gesetzt, erhält es den Wert "").
Die Methode tag() hat die Signatur:
$str = $h->tag($elem,@keyVal,$content);
Hierbei ist $elem der Element-Typ, @keyVal die Liste der Attribut/Wert-Paare und Optionen (siehe unten) und $content ist der Inhalt des Tag.
Da die Argumente der Methode die gleiche Abfolge haben wie die Bestandteile eines Tag in HTML, können die Methodenaufrufe in Perl analog geschachtelt werden wie die Tags in HTML. Beispiel:
$h->tag('a',href=>'URL1', $h->tag('img',src=>'URL2'), );
<a href="URL1"><img src="URL2" alt="" /></a>
Die Elemente eines HTML-Dokuments können syntaktisch ntürlich nicht nur geschachtelt auftreten, sie können auch aufeinanderfolgen. Die Methode cat() fügt aufeinanderfolgende HTML-Elemente zusammen.
Die Methode cat() hat folgende Signatur:
$str = $h->cat(@args);
Hierbei ist @args die Liste der HTML-Elemente, die zusammengefügt werden sollen.
Beispiel:
$h->cat( $h->tag('li','Orange'), $h->tag('li','Zitrone'), $h->tag('li','Ananas'), );
<li>Orange</li> <li>Zitrone</li> <li>Ananas</li>
Die Methode cat() wird von der Methode tag() intern gerufen, um den Content des Tag zu konstruieren. Erstreckt sich der Content über mehrere Argumente, statt nur einem Argument (dem letzten), muss der Methode tag() das Ende der @keyVal Argumente angezeigt werden. Dies geschieht durch Setzen des Arguments '-' vor die Content-Argumente.
$h->tag('ul','-', $h->tag('li','Orange'), $h->tag('li','Zitrone'), $h->tag('li','Ananas'), );
<ul> <li>Orange</li> <li>Zitrone</li> <li>Ananas</li> </ul>
Der Inhalt eines Tag kann nicht nur aus HTML-Elementen bestehen, sondern auch einfachen Text enthalten oder aus einer Mischung aus Text und Elementen bestehen. Beispiel:
$h->tag('p','-', 'Auf ',$h->tag('a',href=>'http://cpan.org','CPAN'), ' sind ',$h->tag('b','viele'),' Module!', );
<p> Auf <a href="http://cpan.org">CPAN</a> sind <b>viele</b> Module! </p>
Mit der Methode tag() lassen sich beliebig komplexe HTML-Strukturen generieren. Der folgende Code produziert ein einfaches, bis auf die fehlende Dokumenttyp-Deklaration vollständiges HTML-Dokument.
$h->tag('html','-', $h->tag('head', $h->tag('title','Test'), ), $h->tag('body', $h->tag('p',q| Hallo Welt! |), ), );
liefert
<html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>Test</title> </head> <body> <p> Hallo Welt! </p> </body> </html>
Wer die obigen Beispiele genau betrachtet, bemerkt, dass die Tags nicht alle mit der gleichen Formatierung generiert werden. Der a-Tag umschließt seinen Inhalt unmittelbar
<a ...>INHALT</a>
wohingegen der p-Tag seinen Inhalt um zwei Leerzeichen einrückt und der Begin- und End-Tag auf einer eignenen Zeile stehen
<p> INHALT </p>
Dies sind zwei der Formatierungsvarianten, die die Methode tag() kennt.
Für jeden HTML Element-Typ ist eine Default-Formatierung definiert, welche bestimmt, wie die Tags des Element-Typs formatiert werden. Jedes Format wird mit einem Buchstaben bezeichnet: e, E, i, m, M, p, v.
e=empty mit Zeilenumbruch
Der Tag hat keinen Inhalt und steht auf einer eigenen Zeile (d.h. er wird mit \n abgeschlossen):
<br />\n
E=empty ohne Zeilenumbruch
Wie e, nur dass der Tag nicht auf einer eigenen Zeile steht (also nicht mit \n abgeschlossen wird):
<img ... />
i=inline
Der Tag umschließt seinen Inhalt unmittelbar, es wird kein \n angehängt:
<a ...>IRGENDEIN\n INHALT</a>
m=multiline mit Einrückung
Der Inhalt wird um zwei Leerzeichen eingerückt, der Tag umschließt diesen auf getrennten Zeilen. Das Konstrukt endet mit einem \n:
<p ...>\n IRGENDEIN\n INHALT\n </p>\n
M=multiline ohne Einrückung
Wie m, nur dass der Inhalt nicht eingerückt wird:
<html ...>\n HEAD\n BODY\n </html>\n
p=protected
Der Inhalt wird einzeilig gemacht, indem LF- und CR-Zeichen durch die Entities und ersetzt werden und vom Tag unmittelbar umschlossen werden.
<pre ...>IRGENDEIN INHALT</pre>\n
Diese Formatierung schützt den Tag-Inhalt davor, dass er durch eine Einrückung äußerer Tags verändert wird. Sie wird bei Tags angewendet, bei deren Inhalt Whitespace signifikant ist.
v=variable
Enthält der Inhalt keine Zeilenumbrüche, wird er einzeilig ausgelegt:
<title>INHALT</title>\n
Enthält der Inhalt Zeilenumbrüche, wird er mehrzeilig ausgelegt:
<title> EIN TITEL </title>
Die Methode tag() unterstützt data-* Attribute auf zwei Weisen:
Einzelne Attribute:
$h->tag('form', 'data-x'=>'a', 'data-y'=>'b', 'data-z'=>'c', ... );
Liste von Attributen:
$h->tag('form', data=>[ x=>'a', y=>'b', z=>'c', ], ... );
Das Resultat in beiden Fällen:
<form data-z="c" data-y="b" data-x="a" ...></form>
Die Methode tag() kennt alle Element-Typen des W3C-Standards. Die folgende Liste gibt den Element-Typ, die Default-Formatierung und die Default-Attribute an:
Element Format Default-Attribute a i abbr i acronym i address v area e b i base e bdo i big i blockquote m body M br e button v caption v cite i code i col e colgroup m dd v del i dfn i div m dl m dt v em i fieldset m form M frame e frameset m h1 v h2 v h3 v h4 v h5 v h6 v head m hr e html M xmlns=>'http://www.w3.org/1999/xhtml' (nur XHTML) i i iframe v img E alt=>'' input e ins i kbd i label v legend v li v link e map m meta e noframes m noscript m object m ol m optgroup m option v p m param e pre p q i samp i script m type=>'text/javascript' select v small i span i strong i style m type=>'text/css' sub i sup i table M tbody m td v textarea p tfoot m th v thead m title v tr m tt i ul m var i
Das Default-Format kann mit der Option -fmt=>$val bei Aufruf der Methode tag() überschrieben werden.
Bei allen Formaten außer i (inline) endet der generierte Tag Code per Default mit einem Zeilenumbruch. Die Zahl der angehängten Zeilenumbrüche kann unabhängig davon mit der Option -nl=>$n gesetzt werden. Bei -nl=>0 wird kein Zeilenumbruch angehängt.
Per Default wird XHTML-Code generiert. Um klassischen HTML-Code zu generieren, wird die HTML-Version gesetzt:
Prty::Html::Tag->setDefault(htmlVersion=>'html-4.01');
Ab diesem Aufruf instantiieren die nachfolgenden Konstruktor-Aufrufe (sofern sie die htmlVersion nicht selbst setzen) Objekte zur Generierung von klassischem HTML.
Der generierte Code sieht bei klassischem HTML folgendermaßen aus:
<a href="URL1"><img src="URL2" alt=""></a>
Man beachte, dass der img-Tag nun mit '>', nicht mit ' />' abgeschlossen ist.
HTML-Code mit großgeschriebenen Element- und Attributnamen wird nach folgender Setzung erzeugt:
Prty::Html::Tag->setDefault(htmlVersion=>'html-4.01',uppercase=>1);
Der generierte Code sieht dann so aus:
<A HREF="URL1"><IMG SRC="URL2" ALT=""></A>
Ist XHTML ('xhtml-1.0') eingestellt, hat die Option uppercase=>1 keinen Einfluss.
Umfang der Element/Attribut-Prüfung.
keine Prüfung
prüfe Element-Typ
prüfe Element-Typ und Attributnamen
Wird ein Fehler festgestellt, wird eine Exception geworfen.
Generiere den HTML-Code einzeilig mit so wenig Whitespace wie möglich.
Füge Bilddaten direkt in HTML ein.
HTML-Version. Beginnt die Versionsangabe mit 'xhtml' wird das HTML gemäß den Regeln für XHTML generiert, andernfalls für klassisches HTML. Die Versionsnummer wird bei der Generierung des DOCTYPE herangezogen.
Forciere eine Content-Einrückung um $n Leerzeichen. Bei indentation=>0 wird nicht eingerückt. Ist indentation nicht gesetzt, gilt die Einrückung, die als Argument bei der Tag-Methode angegeben ist bzw. die in der Methode tag() als Default vorgegeben ist.
Erzeuge Tag- und Attribut-Namen in Großschreibung. Diese Setzung wird nur bei klassischem HTML - nicht bei XHTML - beachtet.
$h = $class->new(@keyVal); $h = $class->new($htmlVersion,@keyVal);
Instantiiere ein Objekt zur Generierung von HTML-Code und liefere eine Referenz auf dieses Objekt zurück.
$html = $h->tag($elem,@keyVal); # [1] $html = $h->tag($elem,@keyVal,$content); # [2] $html = $h->tag($elem,@keyVal,'-',@content); # [3]
Generiere HTML-Tag $tag gemäß den Optionen und Attributen @keyVal und dem Inhalt $content und liefere das Resultat zurück [2]. Der Inhalt kann auch fehlen [1] oder sich über mehrere Argumente erstrecken [3].
Boolsche Attribute werden in HTML ohne Wert und in XHTML mit sich selbst als Wert generiert.
HTML
<TAG ... ATTRIBUTE ...>
XHTML
<TAG ... ATTRIBUTE="ATTRIBUTE" ...>
Boolsche Attribute sind:
checked declare defer disabled ismap multiple nohref noresize readonly selected
Für einige Elemente sind Default-Attribute vereinbart, die nicht explizit gesetzt werden müssen.
Element Attribute form method=>'post', enctype=>'multipart/form-data' script type=>'text/javascript' style type=>'text/css'
Ende der Attribut/Wert-Liste. Die restlichen Argumente werden zum Inhalt konkateniert.
$h->tag('p',class=>'p1','-', 'Ein ',$h->tag('b','kurzer'),' Text.' );
Man beachte die Kommata zwischen den Argumenten.
Ohne '-' wird allein das letzte Argument als Inhalt aufgefasst. Besteht der Inhalt aus mehreren Teilen, müssen die Teile dann konkateniert werden:
$h->tag('p',class=>'p1', 'Ein '.$h->tag('b','kurzer').' Text.' );
Umfang der Element-Typ und Attribut-Prüfung.
Generiere den HTML-Code einzeilig mit so wenig Whitespace wie möglich. Soll sämtlicher HTML-Code einzeilig erzeugt werden, genügt es, beim Konstruktor das Attribut compact zu setzen:
$h = Prty::Html::Tag->new(...,compact=>1);
Reduziere die Content-Einrückung auf $n, wenn möglich. Im Falle von undef wird an der Content-Einrückung nichts geändert. Diese Option ist nützlich, wenn der Content eingerückter Code ist (Tags <style> und <script>) und dieser auf bei der Seitengenerierung auf eine geringere Einrücktiefe gebracht werden soll (z.B. von 4 auf 2).
Bette im Falle eines <img>-Tag das Bild in den HTML-Code ein.
Erzeuge nur den Content und den End-Tag. Diese Option ist nützlich, wenn der HTML-Code inkrementell geschrieben wird und z.B. im Fehlerfall nur der Rest mit schließenden Tags generiert werden soll.
my $html = $h->tag('html', -endTagOnly=>1, $h->tag('body', -endTagOnly=>1, '-', $h->tag('h1','Fatal Error'), $h->tag('pre',$msg), ) ); $http->append($html);
Art der Content-Formatierung.
Element hat keinen Content (br, hr, ...)
<TAG ... />\n
Wie 'e', nur ohne NEWLINE am Ende (img, input, ...)
<TAG ... />
Content wird auf eigene Zeile(n) zwischen Begin- und End-Tag gesetzt und um -ind=>$n Leerzeichen eingerückt. Ist der Content leer, wird der End-Tag direkt hinter den Begin-Tag gesetzt. (html, head, body, form, p, div, script, style, ...)
<TAG ...> CONTENT </TAG>\n
Ist der Content leer:
<TAG ...></TAG>
Wie 'm', nur ohne Einrückung (html, ...)
Wie 'm', nur dass der Content in CDATA eingefasst wird:
<TAG ...> // <![CDATA[ CONTENT // ]]> </TAG>
Der W3 HTML Validator bemängelt die Zeichen & und > dann nicht im Content. (script)
Der Content wird geschützt, indem dieser einzeilig gemacht (LF und CR werden durch und ersetzt) und unmittelbar zwischen Begin- und End-Tag gesetzt wird (pre, textarea, ...).
<TAG ...>CONTENT</TAG>\n
Wie 'p', nur dass die Einrückung des Content entfernt wird.
Ist der Content einzeilig, wird er unmittelbar zwischen Begin- und End-Tag gesetzt:
Ist der Content mehrzeilig, wird er eingerückt:
(title, h1-h6, ...)
Der Content wird belassen wie er ist. Dies ist der Default für Tags, die in Fließtext eingesetzt werden. Ein NEWLINE wird nicht angehängt.
Text Text <TAG ...>Text Text Text</TAG> Text Text
(a, b, span, ...)
Bei Wert 0 generiere keinen End-Tag bei leerem Content, sondern
<TAG .../>
Liefere Leerstring, wenn Bedingung $bool erfüllt ist.
Liefere Leerstring, wenn $content null (Leerstring oder undef) ist.
Liefere $content (ohne Tag), wenn $bool erfüllt ist.
Rücke $content um $n Leerzeichen ein.
Rücke bis auf die erste Zeile den Tag um $n Leerzeichen ein und entferne Zeilenumbrüche am Ende. Diese Option ist nützlich, wenn der Tag für einen Platzhalter mit der Einrücktiefe $n in bestehenden HTML-Code eingesetzt wird.
Rücke den Tag um $n Leerzeichen ein.
Anzahl NEWLINEs am Ende.
-nl=>0 (kein NEWLINE):
<TAG>CONTENT</TAG>
-nl=>1 (ein NEWLINE):
<TAG>CONTENT</TAG>\n
-nl=>2 (zwei NEWLINEs):
<TAG>CONTENT</TAG>\n\n usw.
Ersetze im generierten HTML-Code die angegebenen Platzhalter durch ihre Werte.
Entferne Kommentare aus dem Content. Die Option berücksichtigt, ob es sich um HTML-, CSS- oder JavaScript-Content handelt.
Entferne Leerzeilen aus dem Content.
Mit dieser Option kann der Tag verändert werden. Anwendungsfall: statt eigentlich beim Aufruf angegebenen td soll ein th-Tag gesetzt werden. Beispiel:
$h->tag('td', -tag=>'th', ... );
Siehe: Prty::Html::Table::Simple
Brich eine Tag-Zeile um, wenn sie $n Zeichen überschreitet. Wenn 0, findet kein Umbruch statt. Diese Option ist nützlich, wenn ein Tag lange Attribute haben kann und dies stört (siehe <embed> in R1::YouTube::Player).
Behandele den Content als Text, d.h. schütze &, < und >.
$str = $this->wrapTag($maxWidth,$str);
$html = $h->cat(@opt,@args);
Füge die HTML-Fragmente @args zusammen und liefere den resultierenden HTML-Code zurück.
@args ist eine Abfolge von Array-Referenzen und/oder Zeichenketten.
Der Aufruf
$h->cat( ['doctype'], ['comment',-nl=>2,'Copyright Lieschen Müller'], ['HTML', ['HEAD', ['TITLE','Meine Homepage'], ['STYLE',q| .text { color: red; } |], ], ['BODY', ['H1','Hallo Welt!'], ['P',class=>'text',q| Ich heiße Lieschen Müller und dies ist meine Homepage. |], ], ] );
ist äquivalent zu
$h->cat( $h->doctype, $h->comment(-nl=>2,'Copyright Lieschen Müller'), $h->tag('html','-', $h->tag('head','-', $h->tag('title','Meine Homepage'), $h->tag('style',q| .text { color: red; } |), ), $h->tag('body','-', $h->tag('h1','Hallo Welt!'), $h->tag('p',class=>'text',q| Ich heiße Lieschen Müller und dies ist meine Homepage. |), ), ), );
Beide liefern
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <!-- Copyright Lieschen Müller --> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>Meine Homepage</title> <style type="text/css"> .text { color: red; } </style> </head> <body> <h1>Hallo Welt!</h1> <p class="text"> Ich heiße Lieschen Müller und dies ist meine Homepage. </p> </body> </html>
Verwende $str als Trenner zwischen den Fragmenten. Diese Option ist praktisch, wenn die Fragmente optional sind und die auftretenden Elemente durch eine Zeichenkette voneinander getrennt werden sollen. Beispiel: Eine Icon-Leiste, deren Zusammensetzung nicht festgelegt ist und die nicht direkt aneinander stoßen sollen, sondern durch Leerzeichen getrennt werden.
$str = $h->doctype(@opt);
Liefere <!DOCTYPE>-Tag:
<!DOCTYPE ...>
Der Tag ergibt sich aus der eingestellten HTML-Variante.
Liefere Frameset-Doctype.
Ergänze Doctype um $n Zeilenumbrüche.
$html = $h->comment(@keyVal,$content);
Liefere HTML Kommentar-Tag:
<!-- TEXT -->
bzw.
wenn TEXT mehrzeilig ist.
Wie Methode tag()
$html = $h->optional(@keyVal,$content);
Liefere optional-Klammer:
<!--optional-->...<!--/optional-->
<!--optional--> ... <!--/optional-->
wenn $content mehrzeilig ist.
$h->checkValue($dom,$val);
Prüfe, ob der Attributwert $val für Domäne $dom korrekt ist. Fällt die Prüfung negativ aus, löse eine Exception aus. Die Methode liefert keinen Wert zurück.
$val = $this->imgSrcValue($val,$embedImage);
$class->import(@keyVal);
Setze die Konstruktor-Defaults @keyVal der Klasse. Die Setzung gilt für alle folgenden Konstruktor-Aufrufe, bei denen die betreffenden Werte beim Konstruktor-Aufruf nicht gesetzt werden. Die Methode liefert keinen Wert zurück.
use Prty::Html::Tag;
use Prty::Html::Tag(htmlVersion=>'html-4.01',uppercase=>1);
1.105
Frank Seitz, http://fseitz.de/
Copyright (C) 2017 Frank Seitz
This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
2 POD Errors
The following errors were encountered while parsing the POD:
Expected text after =item, not a number
To install Prty, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Prty
CPAN shell
perl -MCPAN -e shell install Prty
For more information on module installation, please visit the detailed CPAN module installation guide.