/ 
Quiq-1.222
River stage zero No dependents
/ Quiq::Template

NAME

Quiq::Template - Klasse für HTML/XML/Text-Generierung

BASE CLASS

Quiq::Hash

EXAMPLE

Template-Datei test.html oder Template-String $str:

<html>
<head>
  <title>__TITLE__</title>
</head>
<body>
  __BODY__
</body>

Code:

$tpl = Quiq::Template->new('html','test.html');
-oder-
$tpl = Quiq::Template->new('html',\$str);

$tpl->replace(
    __TITLE__ => 'Testseite',
    __BODY__ => 'Hello World!',
);
$str = $tpl->asString;

Resultat $str:

<html>
<head>
  <title>Testseite</title>
</head>
<body>
  Hello World!
</body>

METHODS

Konstruktor

new() - Instantiiere Template-Objekt

Synopsis

$tpl = Quiq::Template->new($type,$file,@opt);
$tpl = Quiq::Template->new($type,\$str,@opt);

Options

-lineContinuation => $type (Default: undef)

Art der Zeilenfortsetzung. Mögliche Werte:

undef

Keine Zeilenfortsetzung.

'backslash'

Endet eine Zeile mit einem Backslash, entferne Whitespace am Anfang der Folgezeile und füge den Rest zur Zeile hinzu.

Dies kann für eine Zeile unterdrückt werden, indem der Backslash am Ende der Zeile durch einen davorgestellten Backslash maskiert wird. In dem Fall wird statt einer Fortsetzung der Zeile der maskierende Backslash entfernt.

Diese Option ist nützlich, wenn ein Template-Text im Editor auf eine bestimmte Breite (z.B. 80 Zeichen/Zeile) begrenzt sein soll, aber der generierte Text breiter sein darf.

-singleReplace => $bool (Default: 0)

Ersetze bei replace() immer nur den ersten von mehreren identischen Platzhaltern. Dies ist z.B. in HTML bei Ersetzung von mehreren Checkboxen mit gleichem Namen nützlich.

Description

Instantiiere ein Template vom Typ $type aus Datei $file oder String $str und liefere eine Referenz auf dieses Objekt zurück.

Template-Typen:

'xml'

XML-Template. Metazeichen &, < und > in Werten werden durch Entities ersetzt.

'html'

HTML-Template. Metazeichen &, < und > in Werten werden durch Entities ersetzt.

'text'

Text-Template. Werte werden unverändert eingesetzt.

Klassenmethoden

combine() - Ersetze Platzhalter in Text

Synopsis

$str = $class->combine(@argVal);

Arguments

placeholders => \@keyVal (Default: [])

Liste von Platzhalter/Wert-Paaren.

template => $text (Default: '')

Text mit Platzhaltern.

Description

Ersetze in Template $text die Platzhalter durch die Werte aus @keyVal und liefere den resultierenden Text zurück. Die Methode ist eine Vereinfachung, sie instantiiert intern ein Template-Objekt, wendet darauf die Methode replace() an und liefert den resultierenden Text zurück.

Eine Tilde (~) kann als Zeilenfortsetzungszeichen im Template verwendet werden.

Example

$js = Quiq::Template->combine(
    placeholders => [
        __NAME__ => $name,
        __CONFIG__ => $config,
    ],
    template => q~
        Chart.defaults.global.defaultFontSize = 12;
        Chart.defaults.global.animation.duration = 1000;
        var __NAME__ = new Chart('__NAME__',__CONFIG__);
~);

Objektmethoden

placeholders() - Liefere Liste der Platzhalter

Synopsis

@arr | $arr = $tpl->placeholders;

replace() - Ersetze Platzhalter

Synopsis

$tpl = $tpl->replace(@keyVal);

Returns

Referenz auf das Template-Objekt (für Method-Chaining)

Description

Ersetze alle Platzhalter durch ihre Werte. Platzhalter und Werte werden als Paare @keyVal übergeben.

Der Wert kann ein String, eine Arrayrefernz, eine Codereferenz oder ein Template-Objekt sein. Siehe Methode value().

Es wird für jeden Platzhalter mit einem Wert ungleich undef geprüft, ob dieser im Template vorkommt. Wenn nicht, wird eine Exception geworfen.

Example

Subroutine liefert Platzhalter-Wert:

my $tpl = Quiq::Template->new('xml',\$Order);
$tpl->replace(
    __CUSTNR__ => $kundenNr,
    __LIEFERNAME__ => $vor->{'liefername'},
    __LIEFERSTRASSE__ => $lieferstrasse,
    __LIEFERHAUSNR__ => $lieferhausnr,
    __LIEFERPLZ__ => $vor->{'lieferplz'},
    __LIEFERORT__ => $vor->{'lieferort'},
    __LIEFERLAND_ISO__ => $vor->{'lieferland_iso'},
    __BESTELLDATUM__ => POSIX::strftime('%Y-%m',localtime),
    __BESTELLNUMMER__ => $vor->{'vorgang_bestellnummer'},
    __WAEHRUNG__ => $waehrung,
    __ENVIRONMENT__ => $test? 'T': 'L',
    __ORDERLINES__ => sub {
        my @arr;
        my $i = 0;
        for my $pos (@$posA) {
            my $tpl = Quiq::Template->new('xml',\$OrderLine);
            $tpl->replace(
                __I__ => $i++,
                __LIEFERNR__ => $pos->{'posten_liefernr'},
                __ARTBE__ => $pos->{'posten_artbe'},
                __ANZAHL__ => $pos->{'posten_anzahl'},
                __EPREIS__ => $pos->{'posten_epreis'},
            );
            push @arr,$tpl;
        }
        return \@arr;
    },
);

Die Subroutine, die den Wert des Platzhalters __ORDERLINES__ berechnet, liefert keinen String, sondern eine Referenz auf ein Array von Template-Objekten. Wie jeder Platzhalterwert wird dieser von der Methode $tpl->value() in einen String (oder undef) umgesetzt.

key() - Liefere Schlüssel und Ersetzungsattribut(e)

Synopsis

$key = $tpl->key($arg);
($key,@attr) = $tpl->key($arg);

Description

Als Schlüssel $arg kann

  1. ein String,

  2. eine Stringreferenz

  3. eine Arrayreferenz

angegeben sein.

MEMO: Die Methode ist so gestaltet, dass (weitere) Einsetzungsattribute definiert werden können, wenn als Platzhalter eine Arrayreferenz übergeben wird, z.B.

['__ITEMS__',call=>sub {...}]

Die Ersetzungsattribute werden im Arraykontext neben dem Schlüssel zurückgegeben und können in replace() den Ersetzungsvorgang in spezieller Weise steuern. Dies wird aber noch nicht genutzt.

value() - Liefere Platzhalter-Wert als Zeichenkette

Synopsis

$str = $tpl->value($arg);

Description

Die Methode liefert die Zeichenkette $str zum (bei replace() angegebenen) Platzhalter-Wert $arg.

String:

Liefere String.

Arrayreferenz:

Ermittele die Zeichenketten-Werte aller Array-Elemente, konkateniere diese mit "\n" und liefere das Resultat zurück.

Corereferenz:

Rufe Subroutine auf und liefere den Zeichenketten-Wert des Returnwerts.

Template-Objekt:

Rufe Methode asString() des Objekts auf und liefere das Resultat zurück.

removeOptional() - Entferne Optional-Metatags

Synopsis

$tpl->removeOptional;

Description

Entferne die <optional>-Metatags aus dem Template-Text. Ein <optional>-Metatag hat die Struktur

<!--optional-->...<!--/optional-->

oder

<!--optional-->
...
<!--/optional-->

<optional>-Konstrukte können geschachtelt sein. Sie werden von innen nach außen aufgelöst.

Attribute

default="VALUE"

Enthält der Inhalt einen unersetzten Platzhalter, ersetze den Inhalt durch VALUE.

placeholder="NAME"

Entferne den Inhalt nur dann, wenn der Platzhalter __NAME__ unersetzt ist. Andere unersetzte Platzhalter werden nicht beachtet.

asString() - Liefere Inhalt

Synopsis

$str = $tpl->asString;

asStringNL() - Liefere Inhalt mit Newline am Ende

Synopsis

$str = $tpl->asStringNL;

VERSION

1.222

AUTHOR

Frank Seitz, http://fseitz.de/

COPYRIGHT

Copyright (C) 2024 Frank Seitz

LICENSE

This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself.