PHPTAL Handbuch

Dieses Attribut definiert eine oder mehrere Variablen, die im weiteren Verlauf in der Vorlage verwendet werden können.

Es können eine oder mehrere durch Semikolon getrennte Variablen angegeben werden.

Definition eines Kürzels für einen langen Pfad:

<span tal:define="global destname pfad/zu/einer/Variable">…</div>

Mehrere Variablen zugleich definieren:

<span tal:define="global vname string:Hans; nname string:Meier">…</span>

Beginnt eine Definition mit global Schlüsselwort ist die Variable dannach überall in der Vorlage und in allen Makros sichtbar. Eine globale Variablen darf später in der Vorlage auch neu definiert werden.

<span tal:define="global hello string:Hallo Welt"/>
            <p tal:content="hello"/>
            

Im Gegensatz dazu ist eine lokale Variable nur innerhalb der Auszeichnung sichtbar, in der Sie definiert ist.

<span tal:define="hello string:Hallo Welt"/>
            <p tal:content="hello"/>
            

Dieser Code liefert einen 'undefined variable'-Fehler.

Definition einer Zeichenkette innerhalb einer Vorlage:

<span tal:define="global destname string:irgendetwas">…</span>

Defining a string containing another variable:

<span tal:define="fname string:Paul; hello string:Hello $fname! Welcome to this page" />
            

Definition einer Zeichenkette, die eine weitere Variable enthält:

<span tal:define="global hello string:Hallo $fname, willkommen auf dieser Seite" />

Ein kleiner Trick, der den Inhalt einer Auszeichnung verwendet (für sehr komplexe Werte hilfreich):

<span tal:define="global hello">Hallo ${fname}, willkommen auf dieser Seite</span>

In obigen Beispielen wird die <span>-Auszeichnung in der Ausgabe nicht auftauchen, da sie weder druckbaren Inhalt noch Attribute enthält. Selbst die Meldung im letzten Beispiel wird nicht erscheinen. Sie wird von der Variablen hello geschluckt.

Andererseits wird durch

<span tal:define="hello string:Hallo ${fname}, willkommen auf dieser Seite" tal:content="hello" />

sowohl die Variable hello gesetzt, als auch der Text ausgegeben.

Der folgende Code aber ist nicht erlaubt, da tal:define der Variablen »hello« den Inhalt des Knotens zuweist. Der Inhalt des Knotens ist allerdings zu diesem Zeitpunkt noch unklar, da tal:content ihn erst später festlegt. Der tatsächliche Inhalt wird dabei wie Beispielinhalt ignoriert. hello wird nicht definiert, und Sie erhalten eine Fehlermeldung.

<span tal:define="hello" tal:content="hello">
              Hallo ${fname}, willkommen auf dieser Seite
            </span>
            

Das Element und sein Inhalt werden nur angezeigt, wenn das Ergebnis der Bedingung wahr ist.

<p tal:condition="identified"> Welcome member …  </p>

<p tal:condition="not: identified">
  Please login before accessing this page
</p>

Wenn ihr PHP Unterbau ihrer Vorlage nicht genügend Methoden zu Verfügung stellt, werden Sie des öfteren auf PHP zurückgreifen müssen, um spezielle Bedingungen zu prüfen:

<span tal:comment="show only if more than five items in the cart"
      tal:condition="php: cart.countItems() GT 5">…</span>

Dadurch kann unerwünscht viel Logik in der Vorlage landen. Manchmal ist es daher besser, der Vorlage boolsche Ausdrücke oder Methoden anzubieten.

<span tal:condition="cart/hasEnoughItems">…</span>

Dieses Attribut arbeitet auf abzählbaren Objekten wie Feldern, assoziativen Feldern oder Objekten, die die PHP5 Iterator Klasse implementiert.

Das tal:repeat Attribut wiederholt seine Auszeichnung und seinen Inhalt solange, bis es am Ende der angegebenen Quelle (Feld, Objekt) angekommen ist.

<tr tal:repeat="item some/result">
  <td tal:content="item">text replaced by item</td>
</tr>

Innerhalb einer solchen Schleife können Sie mit speziellen repeat/* Pfaden auf aktuelle Schleifenzustände (und die ihrer Eltern für verschachtelte Schleifen) zugreifen.

In obigen Beispiel liefert

item ist die Variable, die im tal:repeat Ausdruck definiert wird.

tal:repeat wird in den meisten Fällen auf das Ergebnis einer SQL Datenbankabfrage angewendet werden. Der folgende Code funktioniert wenn playersRanking ein Objekt enthält, das das PHP Iterator Interface implementiert:

<table>
  <thead>
    <tr>
      <th>Position</th>
      <th>Player</th>
      <th>Score</th>
    </tr>
  </thead>
  <tbody>
    <tr tal:repeat="ranking playersRanking">
      <td tal:content="ranking/position"/>
      <td tal:content="ranking/player"/>
      <td tal:content="ranking/score"/>
    </tr>
  </tbody>
</table>

Dieses Attribut gibt dem PHPTAL Parser auf, die Anfangs- und Endauszeichnung des umgebenden Elementes zu ignorieren und nur den Inhalt auszugeben.

<span tal:omit-tag="condition">
  if the condition is true, then only this text will appear and span open and close will be removed
</span>

Ergibt:

only this text will appear, span open and close will be removed

Dieses Attribut ist nützlich, wenn Sie ein Auszeichnung wahlweise darstellen möchten oder nicht. Z.B. kann ein Text in Abhängigkeit von einer Bedingung einmal als Text und einmal als Verweis ausgezeichnet werden.

Wenn Sie ein Element benötigen, das niemals ausgegeben wird, können Sie dazu tal:block verwenden

<tal:block tal:repeat="x php:range(1,10)">only this text will appear, ten times.</tal:block>

Dieses Attribut ersetzt die gesamte Auszeichnung durch den angegebenen Wert, oder durch nichts, wenn kein Wert agegeben wird.

<span tal:replace="string:this beautiful string">
  this ugly string and span
</span>

Ergibt:

this beautiful string

tal:replace kann auch verwendet werden und Beispiele in Vorlagen zu schreiben die in der endgültigen Ausgabe nicht enhalten sein sollen.

<table>
  <tr tal:repeat="item myresult">
    <td tal:content="item">item value</td>
  </tr>
  <tr tal:replace="">
    <td>sample 1</td>
  </tr>
  <tr tal:replace="">
    <td>sample 2</td>
  </tr>
</table>

Dieses Attribut ersetzt den Auszeichnungsinhalt durch das Ergebnis des enthaltenen Ausdrucks.

<span tal:define="myvar string:my string"/>
<span tal:content="myvar">will be replaced</span>

Ergibt:

<span>my string</span>

Mit tal:attributes können HTML Attribute gesetzt oder verändert werden.

<a href="http://www.foo.com" title="some foo link"
   tal:attributes="href somelink/href; title somelink/title"
  tal:content="somelink/text"
>sample link</a>

Wobei 'somelink' aus folgendem besteht:

$somelink->href = "http://www.google.com";
$somelink->title = "google search engine";
$somelink->text = "the google search engine";

Ergibt:

<a href="http://www.google.com"
title="google search engine">the google search engine</a>

Das Semikolon (;) trennt einzelne Attribute. Möchten Sie ein Semikolon ausgeben, so müssen Sie es verdoppeln (;;).

Ein etwas komplexeres Beispiel zu tal:repeat:

<tr tal:repeat="ranking playerRankings"
    tal:attributes="class php: repeat.ranking.odd ? 'odd' : NULL">
    …
</tr>

Der php: Operator wird später genauer erklärt werden. Hier wird, wenn die Zeilennummer ungerade ist, tr ein class Attribut mit 'odd' als Wert zugewiesen sonst wird kein class Attribut gesetzt.

"condition ? then : else" ist ein normales PHP Konstrukt, daß vorsichtig verwendet werden muß, sich aber in mehr als einer Situation als nützlich erweist.

Ein besserer Weg um dasselbe Ergebnis zu erhalten ist es, den PHP Programmierer um einen maßgeschneiderten Operator zu bitten (siehe PHP Integration / maßgeschneiderte Operatoren), der dann wie folgt genutzt wird:

<tr tal:repeat="ranking playerRankings"
    tal:attributes="class css-odd:repeat/ranking/odd">
  …
</tr>

Der Operator sollte "odd" zurückgeben, wenn repeat/ranking/odd wahr ist, sonst NULL.

… tal:attributes="title object/tooltip | nothing"> 

<input type="checkbox" tal:attributes="checked object/isChecked"/>

Wenn ein Pfadfehler oder irgendeine PHP-Ausnahme in der Auszeichnung auftritt, ersetzt dieses Attribut die Auszeichnung durch das Ergebnis des tal:on-error-Ausdrucks.

<span tal:on-error="string:No username defined here"
      tal:content="user/name">the user name here</span>

Tritt beim Zugriff auf name oder user ein Fehler auf, wird die Fehlermeldung anstelle der Auszeichnung ausgegeben.

Dies funktioniert auch bei mehreren Vorlagenebenen:

<span tal:on-error="string:error occurred somewhere">
  <span tal:content="user/firstname"/>
  <span tal:content="user/lastname"/>
  <span metal:use-macro="userMenu" />
</span>

Dieses Attribut deklariert ein Makro. Mit Makros lassen sich Bibliotheken aus kleinen Vorlagen erstellen, die in anderen Vorlagen wiederverwendet werden können.

<div metal:define-macro="main_menu">
  <ul>
    <li><a href="/">home</a></li>
    <li><a href="/products">products</a></li>
    <li><a href="/contact">contact</a></li>
  </ul>

  <div>
    Last modified:
    <span tal:content="mdate">page modification date</span>
  </div>
</div>
        

Makros erben den Variablenkontext des Aufrufers. In obigem Beispiel hängt die Variable „mdate“ von der aufrufenden Vorlage ab.

Dieses Attribut ruft ein Makro auf und setzt das Ergebnis an seiner statt in die aktuelle Vorlage ein.

<span
  tal:comment="main_menu template requires 'mdate' variable"
  tal:define="mdate page/last_modified"
  metal:use-macro="main_menu"
/>
        

Makros lassen sich über die Angabe des Dateinamens auch aus anderen Vorlagen ansprechen.

<span metal:use-macro="site_macros.xhtml/main_menu"/>

Der PHPTAL-Ersetzungsmechanismus läßt sich auch innerhalb von metal:use-macro Werten nutzen:

<span metal:use-macro="${design}/site_macros.xhtml/main_menu"/>

Ein Makro darf sich selbst aufrufen. Auf diese Weise können Sie Felder rekursiv ausgeben:

        <ul metal:define-macro="show-list">
            <li tal:repeat="item list">
                <tal:block tal:condition="php:is_array(item)" tal:define="list item" metal:use-macro="show-list" />
                <tal:block tal:condition="php:!is_array(item)" tal:content="item" />
            </li>
        </ul>
        

Dieses Attribut darf nur innerhalb einer Auszeichnung mit metal:define-macro auftreten.

Slots können von der aufrufenden Vorlage mit, auch dynamisch generiertem, eigenem XML/XHTML-Inhalt gefüllt werden.

Slots können als eine Art rückwirkende Einfügungen gesehen werden; ein Makro kann eine ganze Seite erzeugen, die durch Slots in Abhängigkeit vom URL individualisiert wird.

<span metal:define-slot="news_place">
  <table>
    <tr tal:repeat="item php:latestNews()">
      <td tal:content="item/value">news description</td>
    </tr>
  </table>
</span>

Obiges Beispiel definiert eine Stelle 'news_place', die durch die aufrufende Vorlage überschrieben werden kann. Im nächsten Abschnitt wird dieses Beispiel fortgeführt.

Dieses Attribut darf nur innerhalb eines metal:use-macro-Blocks verwendet werden.

Hiermit wird PHPTAL angewiesen, einen bestimmten Slot mit dem Inhalt innerhalb der metal:fill-slot-Auszeichnung zu ersetzen.

<span tal:condition="logged" metal:fill-slot="news_place">
  <h2>user menu</h2>
  <ul>
    <li><a href="/user/action/inbox">inbox</a></li>
    <li><a href="/user/action/new">new mail</a></li>
    <li><a href="/user/action/disconnect">disconnect</a></li>
  </ul>
</span>

Slots ermöglichen durch ein einfaches Einsetzverfahren tatsächlich wiederverwendbare und individualisierbare Vorlagen.

Dieses Attribut definiert Text, der durch das PHPTAL-Übersetzungssystem übersetzt werden soll.

<div i18n:translate="string:welcome_message">Welcome here</div>

Im obigen Beispiel wird PHPTAL nach einem Übersetzungsschlüssel 'welcome_message' suchen und den Auszeichnungsinhalt durch die Übersetzung in der gerade aktuellen Sprache ersetzen.

<div i18n:translate="">Welcome here</div>

Hier ist die Verwendung ein wenig anders, da kein Übersetzungsschlüssel angegeben worden ist. PHPTAL wird den Auszeichnungsinhalt 'Welcome here' als Schlüssel benutzen. Kennt das Übersetzungssystem den Schlüssel 'Welcome here', ergibt das eine regelgerechte Übesetzung.

Wird keine Übersetzung gefunden, wird der Schlüssel als Ergebnis benutzt. Darum ist es sinnvoll, lesbare Texte statt Kürzel als Schlüssel zu verwenden.

Beachten Sie bitte, daß der Schlüssel, um eine dynamische Schlüsselwahl zu ermöglichen, auch in einer Variablen enthalten sein kann.

<div tal:define="welcome random_welcome_message">
  <div i18n:translate="welcome">…</div>
</div>

Dieses Attribut legt fest, welche HTML-Attribute übersetzt werden sollen. Ähnlich zu i18n:translate verlangt i18n:attributes eine durch Semikola getrennte Liste aus Attribut-/Schlüssel-Paaren.

<img i18n:attributes="alt 'picture alternative text';title thetitle" alt="Picture" title="${thetitle}" />

Dieses Attribut weist einer Übersetzungsvariablen einen Wert zu.

Übersetzungen können ${xxx} Zeichenketten enthalten, in denen "xxx" den Namen einer Variablen bezeichnet, die dynamisch eingefügt werden soll.

Diese Variable enthält die Auszeichnung und ihren Inhalt. Wird die Auszeichnung um den Inhalt herum nicht benötigt, benutzen Sie tal:replace anstatt tal:content. Falls der Wert eine Verknüpfung von Zeichenketten ist kann tal:omit-tag hilfreich sein.

<span i18n:name="myVar" tal:content="some/path"/>
<!-- <span>${some/path}</span> -->

<span i18n:name="myVar" tal:replace="some/path"/>
<!-- ${some/path} -->

<span i18n:name="myVar">foo</span>
<!-- <span>foo</span> -->

<span i18n:name="myVar" tal:omit-tag="">foo</span>
<!-- foo -->

Ein Beispiel zur Benutzung von i18n:

<div i18n:translate="">
  Welcome <span i18n:name="user" tal:replace="user/name"/>,
  you have <span i18n:name="mails" tal:replace="user/nbrMails"/>
  unread mails.
</div>

Der Übersetzungsschlüssel lautet hier:

"Welcome ${user}, you have ${mails} unread mails."

PHPTAL wird in ihrer Übersetzung ${user} durch ${user/name} und ${mails} durch ${user/nbrMails} ersetzen.

Weitere Informationen zu I18N und PHPTAL finden sich im PHP-Kapitel dieses Buches.

In der Grundeinstellung wird angenommen, daß Übersetzungen nur Text enthalten; daher maskiert PHPTAL sämtliche "<" Zeichen.

In i18n:translate können Sie das structure-Schlüsselwort verwenden, um die Maskierung zu unterbinden und den übersetzten Text unverändert zu übernehmen.

<div i18n:translate="structure '<b>bold text</b>'" />

Ergibt:

<div><b>bold text</b></div>

Dieses Attribut schaltet für den Inhalt der Auszeichnung innerhalb derer es definiert ist das PHPTAL Debugging ein.

Der Debugmodus speichert Informationen wie den Dateinamen und die Quellcodezeilennummer in der Vorlage, so daß Ausnahmemeldungen über fehlerhafte Pfadzugriffen mehr Information über das 'Wo' enthalten.

<html>
  <head>
    …
  </head>
  <body>
    <div id="menu">
      …
    </div>
    <div id="leftPane" phptal:debug=""
      tal:comment="this div seems buggy, keep
      trace of where errors are thrown">
          …
    </div>
  </body>
</html>

Durch dieses Attribut wird ein komplettes Element, also Auszeichnung samt Attributen und Inhalt, auf der Festplatte gepuffert und erst dann wieder neu interpretiert, wenn die Pufferzeit abgelaufen ist.

Der Inhalt dieses Attributs ist eine Zeitspanne (wie lange soll das Element gepuffert werden), die als Zahl mit 'd', 'h', 'm' oder 's' als Einheit geschrieben wird.

<div class="footer" phptal:cache="3h">…</div>

<div> wird maximal alle 3 Stunden einmal ausgeführt.

Der Zeitspanne kann wahlweise ein "per"-Parameter folgen, der festlegt, ob der Puffer geteilt wird. In der Grundeinstellung wird ein Elementpuffer von allen Seiten genutzt, die die entsprechende Vorlage nutzen. Sie können ein "per url" hinzufügen, so daß jede URL einen eigenen Puffer für das betreffende Element erhält.

<ol id="breadcrumbs" phptal:cache="1d per url">…</ol>

<ol> wird für jede Seite separat einen Tag lang gepuffert.

Um für jeden einzelnen Wert eines Ausdrucks (der im Ergebnis eine Zeichenkette liefern muß) einen eigenen Puffer zu erhalten, können Sie "per expression" verwenden.

<ul id="user-info" phptal:cache="25m per object/id">…</ul>

<ul> wird für jede Object-ID einzeln 25 Minuten lang gepuffert.

<div phptal:cache="100d per php:news.id . news.last_modified_date">…</div>

Mit diesem Attribut läßt sich das Verhalten von PHPTALES verändern. In der Grundeinstellung werden PHPTAL-Attribute eng an ZPT angelehnt interpretiert. In manchen Fällen bräuchte man aber nur PHP und findet sich bei der ständigen Verwendung des php:- Operators wieder.

Ein weiterer Punkt ist die Art und Weise, in der PHPTAL Pfade auswerten muß. Zum Beispiel dauert die Auswertung von myobject/mymethod/property/10/othermethod/hashkey relativ lange (denken Sie darüber aber nicht zuviel nach - optimieren Sie erst, wenn Sie wirklich ein Problem mit dem Durchsatz haben!).

Zur Laufzeit nimmt sich PHPTAL myobject und findet heraus, daß es ein Objekt ist; stellt dann fest, daß mymethod eine Methode dieses Objektes (und keine Variable) ist und ruft sie auf; untersucht das Ergebnis, um festzustellen, daß dies ein Objekt mit einer Eigenschaft ist; sieht, daß sein Wert ein Feld ist; greift sich das 10-Element dieses Feldes und bestimmt, daß das ein Objekt ist; entscheidet, daß othermethod eine Methode dieses Objektes (und keine Variable) ist und erhält das Ergebnis ihrer Ausführung; um dieses wiederum als Objekt zu erkennen und sich den Wert für den Schlüssel hashkey zu holen.

Natürlich ist das ein extremes Beispiel, und da das Ganze schnell genug ist, interessiert es zumeist nicht. Was geschieht aber, wenn ein solcher Pfad innerhalb eines großen tal:repeat aufgerufen wird? Hmm… Hier kann phptal:tales hilfreich sein:

<html>
  <body>
    <table phptal:tales="php">
      <tr tal:repeat="myobject document.getChildren()">
        <td
          tal:content="myobject.mymethod().property[10].otherMethod().hashkey"></td>
      </tr>
    </table>
  </body>
</html>

Beachten Sie, daß obiges Beispiel dasselbe tut wie:

<html>
  <body>
    <table>
      <tr tal:repeat="myobject php:document.getChildren()">
        <td
          tal:content="php:myobject.mymethod().property[10].otherMethod().hashkey"></td>
      </tr>
    </table>
  </body>
</html>

Das ist der Standardoperator, der innerhalb eines TAL-Ausdrucks verwendet wird, wenn kein anderer Operator angegeben wird.

Folgende Zeilen liefern dasselbe Ergebnis:

<span tal:content="data/user/name"/>
<span tal:content="path:data/user/name"/>
<span>${data/user/name}</span>

In der Vorlage oder in einem Ausdruck können Sie auf eine bekannte Variable zugreifen, indem Sie ihren Pfad in der Form ${path/to/my/variable} angeben.

<h1>${document/title}</h1>
<span tal:replace="string:welcome ${user/name},
this page has been readed ${page/countRead} times"/>

Da '<', '>' und '&' in XML nur umständlich zu verwenden sind, bietet PHPTAL eine alternative PHP-Operator Syntax für diese und, aus Konsistenzgründen, ein paar weitere Zeichen.

Diese Syntax kann nur in php:-Ausdrücken verwendet werden.

Da Ausdrücke mit ';' getrennt werden, und weil '$' Zeichen den Anfang eines Pfades markieren, müssen Sie

<span tal:replace="string:this is a $$100 page"/>
string:foo $bar baz       <!-- $bar wird ersetzt -->
string:foo $$bar baz      <!-- keine Ersetzung -->
string:foo ; php:doFoo()  <!-- zwei einzelne Ausdrücke -->
string:foo ;; php:doFoo() <!-- eine einzige Zeichenkette -->

Dieser Operator erwartet als Argument einen regulären PHP-Ausdruck, wobei er '->' durch einen Punkt '.' ersetzt, und Variablennamen mit einem vorangestellen Dollarzeichen '$' versieht.

Ein vom Rest des Ausdrucks durch Leerzeichen getrennter Punkt '.' wird als Verkettungszeichen behandelt.

php:htmlentities(foo)
php:'string ${varReplaced}'
php:'string ${some.path().to[0].var}'
php:NOT foo OR (bar GT baz)
php:a + b
php:array('a', 'b', 'c')
php:range(0, 90)
php:foo . a.b.c(e) . htmlentities(SomeClass::staticMethod())
php:SomeClass::ConstOfClass
php:SomeClass::$staticVar

Verwenden Sie php: sparsam. In 80% ihrer Vorlagen werden Sie diesen Operator nicht benötigen, aber manchmal werden Sie eine spezielle PHP-Methode aufrufen müssen, z.B. um sich zu vergewissern, daß ein Benutzer angemeldet ist, oder um spezielle, komplexe Daten, in Abhängigkeit von einigen Bedingungen, innerhalb der Vorlage dynamisch zu laden.

Dieser Operator bewirkt eine boolsche Negation. Er wird in tal:condition Ausdrücken verwendet.

<span tal:condition="not: logged">not logged</span>

Dieser boolsche Operator gibt wahr (true) zurück, wenn der getestete Pfad existiert und falsch (false) sonst. Er funktioniert analog zur PHP-Funktion isset().

Normalerweise liefert die Verwendung eines nicht existierenden Pfades eine Fehlermeldung wie "Cannot find variable 'foo' in current scope". Darum sollten unsichere Pfade vor der Verwendung immer geprüft werden:

<span tal:condition="exists: user/preferences"
      tal:content="user/preferences">
  user preferences here if defined
</span>

Dies ist kein Operator, sondern ein Schlüsselwort, das es Vorlagenentwicklern erlaubt, im Falle eines Fehlers, oder wenn etwas nicht definiert ist, den Inhalt einer Auszeichnung als Ersatzwert zu verwenden.

<span tal:define="myVar path/to/possible/var | default">
  default my var value
</span>

<span tal:content="some/var | other/path | default">
  no some/var and no other/path found here
</span>

<a href="unknown.xhtml" title="Unknown page"
   tal:attributes="href item/href | default; title item/title | default"
   tal:content="item/title | default">Unknown page</a>

Das obige Beispiel führt das '|'-Zeichen ein, das für Definitionen oder Ausgaben die Festlegung von Alternativen ermöglicht.

Dies ist kein Operator, sondern ein Schlüsselwort.

Bei der Ausgabe von Variablen innerhalb von PHPTAL-Vorlagen kodiert PHPTAL alle HTML/XML-eigenen Zeichen, um sicherzustellen, daß das Ausgabedokument gültig ist.

Es kommt vor, daß Sie HTML/XML-Variablen verwenden, die unverändert ausgegeben werden sollen:

<h1 tal:content="structure document/title"/>
<span tal:replace="structure document/content"/>

Im obigen Beispiel wird angenommen, daß $document->title und $document->content Variablen sind, die vorformatiertes HTML enthalten, das unverändert ausgegeben werden soll.

Ein Ausdruckskette ist eine durch das '|'-Zeichen getrennte Liste von Ausdrücken.

PHPTAL wertet die Ausdrücke in einer solchen Kette von vorne nach hinten aus, bis der erste Ausdruck ein Nicht-Null-Ergebnis zurückliefert, das keine Fehlermeldung ist. Danach bricht die Auswertung ab.

Da ein string:-Ausdruck immer wahr ist, wird die Auswertung durch einen string:-Ausdruck immer beendet.

Innerhalb von Ausdrucksketten können Sie, wie jeden anderen Ausdruck, auch Ausdrücke mit dem php:-Operator verwenden:

<h1 tal:content="page/title | page/alternativeTitle | default>
  untitled page
</h1>

Changes what syntax is used when generating elements. Valid modes are:

Gibt die in Ihren Vorlagen verwendete Kodierung an. Die Grundeinstellung ist UTF-8.

PHPTAL geht davon aus, das die Kodierung aller Vorlagen und erzeugten Dokumente die gleiche ist. Der BOM (Byte Order Marker) wird aus UTF-8 Dokumenten entfernt.

Diese Methode kann durch die Vorlage aufgerufen werden, um die aktuelle Ausgabesprache zu ändern (z.B. de_CH).

Die Argumente sind eine Liste möglicher Sprachen (verwenden Sie func_get_args(), um die Argumentliste zu erhalten). Ihr Dienst sollte dann die erste bekannte Sprache wählen.

<?php
require_once 'PHPTAL/TranslationService.php';

class MyTranslator implements PHPTAL_TranslationService {
…
    public function setLanguage(){
        $langs = func_get_args();
        foreach($langs as $lang){
            // if $lang known use it and stop the loop
            $this->_currentLang = $lang;
            break;
        }
        return $this->_currentLang;
    }
    …
    private $_currentLang;
}
?>

If you decided to store your translations into separate files, one for each application, for example, this method allows you to select the translation domain from your templates (i18n:domain).

<?php
require_once 'PHPTAL/TranslationService.php';

class MyTranslator implements PHPTAL_TranslationService {
    …
    public function useDomain($domain){
        if (!array_key_exists($domain, $this->_domains)){
            $file = "domains/$this->_currentLang/$domain.php";
            $this->_domains[$domain] = include($file);
        }
        $this->_currentDomain = $this->_domains[$domain];
    }
    …
    private $_currentDomain;
    private $_domains = array();
}
?>

Das obige Beispiel ist eine möglich Übersetzungslösung, bei der die Schlüssel in PHP-Dateien gespeichert werden, die ein assoziatives key=>translation-Feld zurückgeben.

This method matches i18n:name calls. It builds an interpolation context for later translate calls.

<?php
require_once 'PHPTAL/TranslationService.php';

class MyTranslator implements PHPTAL_TranslationService {
    …
    public function setVar($key, $value){
        $this->_context[$key] = $value;
    }
    …
    private $_context = array();
}
?>

The last and most important method to implement, it asks your service to translate the specified key for the currently selected language.

<?php
require_once 'PHPTAL/TranslationService.php';

class MyTranslator implements PHPTAL_TranslationService {
    …
    public function translate($key){
        $value = $this->_currentDomain[$key];

        // interpolate ${myvar} using context associative array
        while (preg_match('/\${(.*?)\}/sm', $value, $m)){
            list($src,$var) = $m;
            if (!array_key_exists($var, $this->_context)){
                $err = sprintf('Interpolation error, var "%s" not set',
                               $var);
                throw new Exception($err);
            }
            $value = str_replace($src, $this->_context[$var], $value);
        }

        return $value;
    }
    …
}
?>

Die PHP-gettext™-Erweiterung verlangt nach einer bestimmten Verzeichnisstruktur, die die Übersetzungsdateien enthält.

/path/to/your/translation_root/en_US/LC_MESSAGES/
/path/to/your/translation_root/en_GB/LC_MESSAGES/
/path/to/your/translation_root/fr_FR/LC_MESSAGES/
/path/to/your/translation_root/es_ES/LC_MESSAGES/
… and so on …

Die Sprachkode besteht aus zwei Zeichen, die die eigentliche Sprache (fr, de, it, …) und zwei Zeichen, die das Land (FR, CH, DE, IT, …) festlegen.

Das Verzeichnismuster sieht so aus:

<path_to_where_you_want>/<ll_CC>/LC_MESSAGES/

PO-Dateien sind Klartextdateien, die die Übersetzungen enthalten. Sie können sie problemlos händisch editieren.

minimalistisches po-Beispiel (en_US/LC_MESSAGES/mydomain.po):

msgid ""
msgstr ""
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"

msgid "Simple test"
msgstr "A small sentence in english"

Einmal bearbeitet, muß jede PO-Datei indiziert werden:

msgfmt mydomain.po -o mydomain.mo

Dieser Aufruf funktioniert nur, wenn Sie die gettext™-Werkzeuge auf ihrem System installiert haben.

Hierdurch wird eine MO-Datei (machine object) erzeugt, in der Ihre Übersetzungen für einen schnellen Zugriff indiziert vorliegen.

Nun müssen Sie diese Datei in die anderen gewünschten Sprachen übersetzen.

Minimalistisches PO-Beispiel (fr_FR/LC_MESSAGES/mydomain.po):

msgid ""
msgstr ""
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"

msgid "Simple test"
msgstr "Une petite phrase en français"

Auch diese Übersetzungsdatei muß indiziert werden:

msgfmt mydomain.po -o mydomain.mo

The domain is matched against your translation file names. In above examples we used 'mydomain' as domain name.

You can have more than one domain for the same application, it can enhance gettext™'s performance to split your application translations in more than one file.

<?php
require_once 'PHPTAL.php';
require_once 'PHPTAL/GetTextTranslator.php';

try {
    $tr = new PHPTAL_GetTextTranslator();

    // set language to use for this session (first valid language will
    // be used)
    $tr->setLanguage('en_GB.utf8', 'en_GB');

    // register gettext domain to use
    $tr->addDomain('mydomain', '/path/to/your/translation_root');

    // specify current domain
    $tr->useDomain('mydomain');

    $tpl = new PHPTAL('mytemplate.xhtml');

    // tell PHPTAL to use our translator
    $tpl->setTranslator($tr);

    // output translated template
    echo $tpl->execute();
}
catch (Exception $e){
    echo $e;
}

If you need to translate some other text, that is not in the template (e.g. plaintext e-mail message), you can reuse PHPTAL's translator:

$tr = $tpl->getTranslator();

$subject = $tr->translate("Registration information");

$tr->setVar("user",$username);
$message = $tr->translate("Dear ${user}, thanks for registering!");

mail($email, $subject, $message);

If you're using PHPTAL's standard gettext™ translator, you can use gettext() too.

The I18N Namensraum allows some variable interpolation in your translations.

# english
msgid "welcome"
msgstr "Welcome ${name} you have ${n} mails!"

# french
msgid "welcome"
msgstr "Bienvenue ${name} vous avez recu ${n} messages!"
        

A template can use this interpolation as follows:

<span i18n:translate="welcome">
  Welcome
  <span i18n:name="name" tal:replace="user/name"/>
  you currently have
  <span i18n:name="n" tal:replace="user/unreadeMails"/>
  unread messages!
</span>
        

Because i18n:translate contains a value 'welcome', the template data will be ignored and the message given by gettext™ will be used instead.