(:redirect 'http://docs.studip.de/develop/Entwickler/FlexiTemplates':)

Template-Objekte

Bisher wurde nur die Möglichkeit vorgestellt, den Namen (bzw. Pfad) eines Templates beim Öffnen und Rendern anzugeben. Es ist aber auch immer möglich, statt eines Namens das Template-Objekt zu verwenden. Für gewöhnlich ist das nicht nötig, wenn man aber mit mehreren TemplateFactories arbeiten muss, bietet sich das gelegentlich an. Ein typischer Fall wird im folgenden Beispiel dargestellt:

$factoryA = new Flexi_TemplateFactory('/ein/pfad');
$factoryB = new Flexi_TemplateFactory('/anderer/pfad');

$layout = $factoryA->open('layout');

$hello = $factoryB->open('hello_world');
$hello->set_layout($layout);

// oder auch
echo $hello->render(array('name' => 'Axel'), $layout);

// oder einfach 
echo $factoryB->render('hello_world', array('name' => 'Axel'), $layout);

An allen Stellen, bei denen mit einem String ein Template benannt wird, kann jederzeit auch ein beliebiges Template-Objekt stehen. Dieses kennt seine Ursprungs-Factory, so dass es zu keinerlei Verwirrung kommen kann.

Bis die Doku vervollständigt worden ist (Freiwillige vor..), hier die Folien vom letzten Vortrag: Attach:flexi.pdf

S5 Folien: http://mainland.virtuos.uos.de/projects/studip/browser/personal/mlunzena/entwicklerweiterbildung/flexi_templates/flexi_templates.xml?rev=5265&format=raw

Beispiel 1: "Hello World"

Wie es sich gehört, kommt als erstes Beispiel das bekannte "Hello world". Dafür brauchen wir zwei Sachen:

• eine Template-Datei, die wie ein Lückentext funktioniert,
• ein PHP-Skript, das diesen Lückentext füllt und ausgibt.

Die Template-Datei liegt aus Hygienegründen in einem eigenen Verzeichnis templates. Damit sieht dann das Beispiel so aus:

  index.php
  templates/hello_world.php

Der Lückentext ist in der Datei templates/hello_world.php gespeichert. Die Flexi_Template-Engine benutzt die Endung einer Template-Datei, um die Art dieser zu erkennen. Eine Endung ".php" weißt dabei auf ein Flexi_PhpTemplate hin. Diese Art von Template ist einfach ein plain vanilla PHP-Skript. Wie sieht also unser Template aus?

<h1>Hello, <?= $name ?>!</h1>

Offenbar wird der Platzhalter $name verwendet, um den Namen des Gegrüßten anzuzeigen.

Wie füllt man also dann diesen Lückentext? Schauen wir uns doch die Datei index.php an:

<?php

1. load flexi lib

require_once dirname(__FILE__) . '/../../vendor/flexi/flexi.php';

1. where are the templates

$path_to_the_templates = dirname(__FILE__) . '/templates';

1. we need a template factory

$factory = new Flexi_TemplateFactory($path_to_the_templates);

1. open template

$template = $factory->open('hello_world');

1. set name of the greetee

$template->set_attribute('name', 'Axel');

1. render template

echo $template->render();

Zunächst wird offenbar die Flexi-Bibliothek geladen, daraufhin eine Variable mit dem Pfad zum Verzeichnis, wo unser Template liegt, gefüllt und dann mit dieser eine Flexi_TemplateFactory erzeugt.

Wie der Name schon andeutet, wird diese factory dazu benutzt, Templates herzustellen. Und genau das passiert als nächstes. Indem man der factory die Nachricht #open schickt, erhält man ein Template-Objekt. Dazu muss man als Argument nur den Namen der Template-Datei mitgeben. Da die factory ein wenig schlau ist, reicht ihr dabei der Name der Datei ohne Endung (die man aber natürlich auch mitangeben dürfte; man muss es eben nur nicht..). Für unser Template hello_world.php genügt also ein "hello_world".

Die Verwendung des Namens ohne Endung erlaubt ein Feature, auf das wir später noch einmal eingehen werden.

Zurück zum Thema: In einem weiteren Schritt setzen wir für das Template das Attribut "name" auf den Wert "Axel". Und zum Schluss lassen wir das Template auswerten und geben das Ergebnis (einen String) aus.

Wenig überraschend erhält man nach Ausführung im Browser:

––

Beispiel 2: "Darf's ein bisschen mehr sein?"

Eben haben wir gerade eine "Lücke" mit einem String gefüllt. Als nächstes probieren wir das mal mit anderen Sachen als Strings.

Schauen wir uns als erstes einmal das PHP-Skript an, das unser Template füllen wird.

<?php

1. load flexi lib

require_once dirname(__FILE__) . '/../../vendor/flexi/flexi.php';

1. where are the templates

$path_to_the_templates = dirname(__FILE__) . '/templates';

1. we need a template factory

$factory = new Flexi_TemplateFactory($path_to_the_templates);

1. open template

$template = $factory->open('quotes');

1. set quotes

$quotes = array(

  array('author' => 'August Strindberg',
        'quote'  => 'Der Mensch ist ein wunderliches Tier.'),
  array('author' => 'Pierre Reverdy',
        'quote'  => 'Der Mensch ist ein Tier, das sich selbst gezähmt hat.'),
  array('author' => 'Thomas Niederreuther',
        'quote'  => 'Der Mensch ist das einzige Tier, das sich für einen Menschen hält.'),
  array('author' => 'Durs Grünbein',
        'quote'  => 'Der Mensch ist das Tier, das Kaugummi kaut.'),
  array('author' => 'Mark Twain',
        'quote'  => 'Der Mensch ist das einzige Tier, das erröten kann - oder sollte.'));

1. select one randomly

shuffle($quotes); $quote_of_the_day = array_shift($quotes);

$template->set_attributes(array('quotes' => $quotes,

                                'quote_of_the_day' => $quote_of_the_day));

1. set current time

$time = time(); $template->set_attribute('time', $time);

1. render template

echo $template->render();

Hier erwartet uns nichts besonderes. Die Zeilen 1-13 sind dieselben, die wir schon im ersten Beispiel hatten. Die Flexi-Bibliothek wird geladen, der Pfad zu den Templates wird gesetzt und mit ihm eine Template-Factory erzeugt, die wir dann verwenden, um das Template namens "quotes" zu öffnen.

Danach (Zeilen 16-27) wird ein Vektor von Zitaten angelegt, um dann in den Zeilen 29-31 diesen Vektor zu mischen und den ersten zum Zitat des Tages zu kören.

Interessanter wird es dann in Zeile 33. Dort senden wir an unser Template eine neue Nachricht #set_attributes. Anstatt also zweimal hintereinander #set_attribute aufzurufen, was so aussehen würde:

template->set_attribute('quotes', $quotes); template->set_attribute('quote_of_the_day', $quote_of_the_day);

setzen wir stattdessen direkt ein Array von Schlüssel-Wert-Paaren.

Die Zeilen 37-39 demonstrieren, dass man hinterher gerne weitere Attribute wie gewohnt setzen kann. Auch andersherum wäre das kein Problem gewesen (also zunächst #set_attribute und dann #set_attributes). Die Nachricht #set_attributes überschreibt nämlich nur, löscht also nicht alle vorher eingetragenen Attribute.

Die Zeilen 42-43 sollten einem dann wieder bekannt vorkommen. Wir evaluieren die Attribute im Kontext der Template-Datei und geben diese aus.

Die Template-Datei ist wieder ein Flexi_PhpTemplate also ein gewöhnliches PHP-Skript. Diesmal haben wir aber eine kleine Überraschung eingebaut. Es soll nämlich ein bisschen Ausgabelogik demonstriert werden:

<h1>Zitat des Tages (<?= date('d.m.Y', $time) ?>)</h1> <p>

  <em>
    „<?= $quote_of_the_day['quote'] ?>“
  </em>
  (<?= $quote_of_the_day['author'] ?>)

</p>

<? if (sizeof($quotes)) : ?>

  <h1>Mehr Zitate</h1>
  <? foreach ($quotes as $quote) : ?>
    <p>
      <em>
        „<?= $quote['quote'] ?>“
      </em>
      (<?= $quote['author'] ?>)
    </p>
  <? endforeach ?>

<? endif ?>

Interessant sind hier wohl die Aufrufe von Ausgabefunktionen wie #date in Zeile 1, die Verwendung eines if-Konstrukts in Zeile 10 (und natürlich dessen Ende in Zeile 20) und die Verwendung von foreach in Zeile 12 (und 19).

Wenn man also von der Verwendung der alternativen Syntax für if und foreach (http://de.php.net/manual/en/control-structures.alternative-syntax.php) absieht, sollte der Inhalt des Templates für einen wahren PHP-Connoisseur absolut Standardcode sein.

Eine Beispielausgabe sieht dann also ungefähr so aus:

––

Beispiel 3: "Und nun in hübsch"

Wenn man viele verschiedene Templates fertig gestellt hat, fällt einem irgendwann auf, dass sich darin zu Beginn und zum Ende eines Templates Text wiederholt. Nicht selten liegt dann ungefähr folgender Aufbau in den Templates vor:

<!– hier steht ein "header" –>

<!– dann folgt der inhalt –> Hello World

<!– und zum schluss noch ein footer –>

Da Header und Footer in allen Dateien gleich ist, liegt es nahe, sich nicht immer zu wiederholen (DRY - Don't Repeat Yourself). Für die Flexi-Templates gibt es speziell zu diesem Zweck einen Mechanismus: "Layouts".

Im folgenden wird nun die Zitatensammlung aus Beispiel 2 in ein Layout eingebettet.

Zunächst aber die theoretische Seite: Layouts sind ein Beispiel für Martin Fowlers "Decorator Pattern". Templates werden dazu in andere Layout-Templates eingebettet. Diese Layout-Templates bilden eine gemeinsame Struktur für die eingebetteten Inhalts-Templates. Das Layout-Template entscheidet, wohin der Inhalt der eingebetteten Templates eingefügt wird.

Layout-Templates sind dabei ganz normale Templates, allerdings mit zwei zusätzlichen Eigenschaften:

• Die Ausgabe des Inhalttemplates wird im Attribut "content_for_layout" zur Verfügung gestellt.
• Alle Attribute, die das Inhalts-Template erhält, ebenso wie alle Variablen, die das Inhalts-Template während seiner Evaluierung setzt, werden an das Layout-Template vererbt.

Ein Layout-Template sieht dann also im Prinzip so aus:

(:source linenum:)[@ header <?= $content_for_layout ?> footer

Wenn dann das Inhalt-Template folgende Ausgabe erzeugt:

(:source linenum:)[@ Hello, world!

wäre das Endergebnis dann:

(:source linenum:)[@ header Hello, world! footer

Um also nun einem Template ein Layout zuzuordnen, ruft man einfach die Methode #set_layout auf:

$template->set_layout('my_chunky_layout');

Zurück zur Zitatensammlung aus Beispiel 2. Um unsere Zitate in ein Layout einzubetten, müssen wir lediglich:

• dem Template-Objekt die Nachricht #set_layout senden
• ein Layout-Template erstellen

Der erste Punk ist schnell erledigt. In dem PHP-Skript, das in Beispiel 2 unser Template-Objekt erzeugt hat, fügen wir folgende Zeile hinzu:

[..]

1. open template

$template = $factory->open('quotes');

1. set layout

$template->set_layout('layout');

1. set quotes

[..]

Damit bleibt nur noch Punkt 2: ein Layout-Template namens 'layout' erstellen:

<html> <head>

  <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
  <title><?= $title ?></title>
  <link rel="stylesheet" type="text/css" href="style.css" media="screen"/>

</head> <body>

  <?= $content_for_layout ?>

</body> </html>

Das Stylesheet wird an dieser Stelle nicht wiedergegeben. Wichtig ist ja auch nur Zeile 8, in der die Ausgabe des Inhalts-Templates eingefügt wird.

Zusätzlich wird nun noch der Einsatz von in Inhalt-Templates gesetzten Variablen demonstriert. Gegenüber dem in Beispiel 2 verwendeten Template 'quotes', enthält dieses nun ausserdem folgende Zeile:

[..] <? $title = "Zitate"; ?> [..]

Da nun im Inhalts-Template die Variable 'title' gesetzt wurde, kann diese im Layout-Template verwendet werden. (siehe dazu Zeile 4 im Layout-Template oben)

Damit sind nun alle wichtigen Mechanismen der Flexi-Templates vorgestellt worden. Es folgen nun noch ein paar Gimmicks…

––

Meanwhile, in another place …

Bevor wir zu den Gadgets kommen, noch ein kurzer Überblick über die API, die die Flexi-Templates bietet.

Zunächst kurz die Methoden, die ein Flexi_Template-Objekt bietet. Anzumerken ist, dass diese Objekte dieser Klasse nicht direkt instanziiert werden können, da man dafür eine Template-Factory benötigt.

class Flexi_Template {

  function get_attribute($name);
  function get_attributes();

  function set_attribute($name, $value);
  function set_attributes($attributes);

  function clear_attributes();
  function clear_attribute($name);

  function render($attributes = null, $layout = null);

  function set_layout($layout);

Die ersten sechs Methoden:

• #get_attribute
• #get_attributes
• #set_attribute
• #set_attributes
• #clear_attributes
• #clear_attribute

dienen zum Setzen, Abfragen und Entfernen von Attributen. Für gewöhnlich werden wohl nur die beiden Setter

• #set_attribute
• #set_attributes

benötigt. Während #set_attribute einem Schlüssel einen Wert zuordnet:

$template->set_attribute('key', new Value());

Mit der Methode #set_attributes kann man gleich ein ganzes (assoziatives) Array von Schlüssel-Wert-Paaren setzen:

$attributes = array(); $attributes['title'] = "a title"; $attributes['content'] = "some content";

$template->set_attributes($attributes);

Anzumerken ist, dass diese Methode #set_attributes die bereits gesetzten Attribute nicht entfernt, sondern nur bereits vorhandene Schlüssel aktualisiert:

$template->set_attribute('key', 'value'); $template->set_attribute('title', 'former title');

$attributes = array(); $attributes['title'] = "a title"; $attributes['content'] = "some content";

$template->set_attributes($attributes);

Während also das #set_attributes den alten Wert des Attributs 'title' gegen den neuen Wert ersetzt, bleibt das Attribut 'key' erhalten.

Nun bleiben also noch die Methoden #set_layout und #render.

Die erste Methode #set_layout wurde schon in Beispiel 3 vorgestellt und hat als einzigen Parameter das Template, welches als Layout-Template verwendet werden soll.

Die letzte Methode #render wurde auch schon verwendet, hat allerdings zwei zusätzliche Parameter, die bisher nicht gezeigt wurden. Diese dienen aber lediglich dem Komfort. Während wir bisher folgende Verwendung gesehen haben:

$template = $factory->open('hello_world');

$template->set_attribute('name', 'Axel');

$template->set_layout('layout');

echo $template->render();

kann mit dieser Code mit den zwei zusätzlichen Methodenparametern so geschrieben werden:

$template = $factory->open('hello_world'); echo $template->render(array('name' => 'Axel'), 'layout');

(:source lang=php:)[@

                     $a, $b, $c,
                     56.44, $d, 500);

                     'secondKey' => 'secondValue');

tag must always be omitted.

                    $a, $b, $c,
                    56.44, $d, 500);

                    'secondKey' => 'secondValue');

Coding Style

PHP Code Demarcation

PHP code must always be delimited by the full-form, standard PHP tags:

<?php

?>

Short tags are never allowed. For files containing only PHP code, the closing tag must always be omitted (See Section B.2.1, “General”).

Strings

String Literals

When a string is literal (contains no variable substitutions), the apostrophe or "single quote" should always be used to demarcate the string:

$a = 'Example String';

String Literals Containing Apostrophes

When a literal string itself contains apostrophes, it is permitted to demarcate the string with quotation marks or "double quotes". This is especially useful for SQL statements:

$sql = "SELECT `id`, `name` from `people` "

     . "WHERE `name`='Fred' OR `name`='Susan'";

This syntax is preferred over escaping apostrophes as it is much easier to read.

Variable Substitution

Variable substitution is permitted using either of these forms:

$greeting = "Hello $name, welcome back!";

$greeting = "Hello , welcome back!";

For consistency, this form is not permitted:

$greeting = "Hello ${name}, welcome back!";

String Concatenation

Strings must be concatenated using the "." operator. A space must always be added before and after the "." operator to improve readability:

$company = 'Zend' . ' ' . 'Technologies';

When concatenating strings with the "." operator, it is encouraged to break the statement into multiple lines to improve readability. In these cases, each successive line should be padded with white space such that the "."; operator is aligned under the "=" operator:

(:source lang=php linenum:)[@ $sql = "SELECT `id`, `name` FROM `people` "

     . "WHERE `name` = 'Susan' "
     . "ORDER BY `name` ASC ";

Arrays

Numerically Indexed Arrays

Negative numbers are not permitted as indices.

An indexed array may start with any non-negative number, however all base indices besides 0 are discouraged.

When declaring indexed arrays with the array function, a trailing space must be added after each comma delimiter to improve readability:

(:source lang=php linenum:)[@ $sampleArray = array(1, 2, 3, 'Zend', 'Studio');

It is permitted to declare multi-line indexed arrays using the "array" construct. In this case, each successive line must be padded with spaces such that beginning of each line is aligned:

$sampleArray = array(1, 2, 3, 'Zend', 'Studio',

                     $a, $b, $c,
                     56.44, $d, 500);

Associative Arrays

When declaring associative arrays with the array construct, breaking the statement into multiple lines is encouraged. In this case, each successive line must be padded with white space such that both the keys and the values are aligned:

$sampleArray = array('firstKey' => 'firstValue',

                     'secondKey' => 'secondValue');

Classes

Class Declaration

Classes must be named according to Zend Framework's naming conventions.

The brace should always be written on the line underneath the class name.

Every class must have a documentation block that conforms to the PHPDocumentor standard.

All code in a class must be indented with four spaces.

Only one class is permitted in each PHP file.

Placing additional code in class files is permitted but discouraged. In such files, two blank lines must separate the class from any additional PHP code in the class file.

The following is an example of an acceptable class declaration:

/**

 * Documentation Block Here
 */

class SampleClass {

    // all contents of class
    // must be indented four spaces

}

Class Member Variables

Member variables must be named according to Zend Framework's variable naming conventions.

Any variables declared in a class must be listed at the top of the class, above the declaration of any methods.

The var construct is not permitted. Member variables always declare their visibility by using one of the private, protected, or public modifiers. Giving access to member variables directly by declaring them as public is permitted but discouraged in favor of accessor methods (set/get).

Functions and Methods

Function and Method Declaration

Functions must be named according to the Zend Framework function naming conventions.

Methods inside classes must always declare their visibility by using one of the private, protected, or public modifiers.

As with classes, the brace should always be written on the line underneath the function name. Space between the function name and the opening parenthesis for the arguments is not permitted.

Functions in the global scope are strongly discouraged.

The following is an example of an acceptable function declaration in a class:

/**

 * Documentation Block Here
 */

class Foo {

    /**
     * Documentation Block Here
     */
    public function bar()
    {
        // all contents of function
        // must be indented four spaces
    }

}

NOTE: Pass-by-reference is the only parameter passing mechanism permitted in a method declaration.

/**

 * Documentation Block Here
 */

class Foo {

    /**
     * Documentation Block Here
     */
    public function bar(&$baz)
    {}

Call-time pass-by-reference is strictly prohibited.

The return value must not be enclosed in parentheses. This can hinder readability, in additional to breaking code if a method is later changed to return by reference.

/**

 * Documentation Block Here
 */

class Foo {

    /**
     * WRONG
     */
    public function bar()
    {
        return($this->bar);
    }

    /**
     * RIGHT
     */
    public function bar()
    {
        return $this->bar;
    }

}

Function and Method Usage

Function arguments should be separated by a single trailing space after the comma delimiter. The following is an example of an acceptable invocation of a function that takes three arguments:

threeArguments(1, 2, 3);

Call-time pass-by-reference is strictly prohibited. See the function declarations section for the proper way to pass function arguments by-reference.

In passing arrays as arguments to a function, the function call may include the "array" hint and may be split into multiple lines to improve readability. In such cases, the normal guidelines for writing arrays still apply:

threeArguments(array(1, 2, 3), 2, 3);

threeArguments(array(1, 2, 3, 'Zend', 'Studio',

                     $a, $b, $c,
                     56.44, $d, 500), 2, 3);

Control Statements

If/Else/Elseif

Control statements based on the if and elseif constructs must have a single space before the opening parenthesis of the conditional and a single space after the closing parenthesis.

Within the conditional statements between the parentheses, operators must be separated by spaces for readability. Inner parentheses are encouraged to improve logical grouping for larger conditional expressions.

The opening brace is written on the same line as the conditional statement. The closing brace is always written on its own line. Any content within the braces must be indented using four spaces.

if ($a != 2) {

    $a = 2;

}

For "if" statements that include "elseif" or "else", the formatting conventions are similar to the "if" construct. The following examples demonstrate proper formatting for "if" statements with "else" and/or "elseif" constructs:

if ($a != 2) {

    $a = 2;

} else {

   $a = 7;

}

if ($a != 2) {

    $a = 2;

} elseif ($a == 3) {

   $a = 4;

} else {

   $a = 7;

}

PHP allows statements to be written without braces in some circumstances. This coding standard makes no differentiation- all "if", "elseif" or "else" statements must use braces.

Use of the "elseif" construct is permitted but strongly discouraged in favor of the "else if" combination.

Switch

Control statements written with the "switch" statement must have a single space before the opening parenthesis of the conditional statement and after the closing parenthesis.

All content within the "switch" statement must be indented using four spaces. Content under each "case" statement must be indented using an additional four spaces.

switch ($numPeople) {
    case 1:
        break;

    case 2:
        break;

    default:
        break;
}

The construct default should never be omitted from a switch statement.

NOTE: It is sometimes useful to write a case statement which falls through to the next case by not including a break or return within that case. To distinguish these cases from bugs, any case statement where break or return are omitted should contain a comment indicating that the break was intentionally omitted.

Inline Documentation

Documentation Format

All documentation blocks ("docblocks") must be compatible with the phpDocumentor format. Describing the phpDocumentor format is beyond the scope of this document. For more information, visit: http://phpdoc.org/

All class files must contain a "file-level" docblock at the top of each file and a "class-level" docblock immediately above each class. Examples of such docblocks can be found below.

Files

Every file that contains PHP code must have a docblock at the top of the file that contains these phpDocumentor tags at a minimum:

/**
 * Short description for file
 *
 * Long description for file (if any)...
 *
 * LICENSE: Some license information
 *
 * @copyright  2008 Zend Technologies
 * @license    http://framework.zend.com/license   BSD License
 * @version    $Id:$
 * @link       http://framework.zend.com/package/PackageName
 * @since      File available since Release 1.5.0
*/

Classes

Every class must have a docblock that contains these phpDocumentor tags at a minimum:

/**
 * Short description for class
 *
 * Long description for class (if any)...
 *
 * @copyright  2008 Zend Technologies
 * @license    http://framework.zend.com/license   BSD License
 * @version    Release: @package_version@
 * @link       http://framework.zend.com/package/PackageName
 * @since      Class available since Release 1.5.0
 * @deprecated Class deprecated in Release 2.0.0
 */

Functions

Every function, including object methods, must have a docblock that contains at a minimum:

A description of the function

All of the arguments

All of the possible return values

It is not necessary to use the "@access" tag because the access level is already known from the "public", "private", or "protected" modifier used to declare the function.

If a function/method may throw an exception, use @throws for all known exception classes:

@throws exceptionclass [description]

Zunächst kurz die Methoden, die ein Flexi_Template-Objekt bietet. Anzumerken ist, dass diese Objekte dieser Klasse nicht direkt instanziiert werden können, da man dafür eine Template-Factory benötigt.

Das Stylesheet wird an dieser Stelle nicht wiedergegeben. Wichtig ist ja auch nur Zeile 8, in der die Ausgabe des Inhalts-Templates eingefügt wird.

Bevor wir zu den Gadgets kommen, noch ein kurzer Überblick über die API, die die Flexi-Templates bietet.

require_once dirname(__FILE__) . '/../../vendor/flexi/flexi.php';

require_once dirname(__FILE__) . '/../../vendor/flexi/flexi.php';

Bis die Doku vervollständigt worden ist (Freiwillige vor..), hier die Folien vom letzten Vortrag: Attach:flexi.pdf

S5 Folien: http://mainland.virtuos.uos.de/projects/studip/browser/personal/mlunzena/entwicklerweiterbildung/flexi_templates/flexi_templates.xml?rev=5265&format=raw

S5 Folien: http://mainland.virtuos.uos.de/projects/studip/browser/personal/mlunzena/entwicklerweiterbildung/flexi_templates/flexi_templates.xml?rev=5265&format=raw

Bis die Doku vervollständigt worden ist (Freiwillige vor..), hier die Folien vom letzten Vortrag: Attach:flexi.pdf

Während also das #set_attributes den alten Wert des Attributs 'title' gegen den neuen Wert ersetzt, bleibt das Attribut 'key' erhalten.

Nun bleiben also noch die Methoden #set_layout und #render.

Die erste Methode #set_layout wurde schon in Beispiel 3 vorgestellt und hat als einzigen Parameter das Template, welches als Layout-Template verwendet werden soll.

Die letzte Methode #render wurde auch schon verwendet, hat allerdings zwei zusätzliche Parameter, die bisher nicht gezeigt wurden. Diese dienen aber lediglich dem Komfort. Während wir bisher folgende Verwendung gesehen haben:

$template = $factory->open('hello_world');

$template->set_attribute('name', 'Axel');

$template->set_layout('layout');

echo $template->render();

kann mit dieser Code mit den zwei zusätzlichen Methodenparametern so geschrieben werden:

$template = $factory->open('hello_world');
echo $template->render(array('name' => 'Axel'), 'layout');

Zusätzlich wird nun noch der Einsatz von in Inhalt-Templates gesetzten Variablen demonstriert. Gegenüber dem in Beispiel 2 verwendeten Template 'quotes', enthält dieses nun ausserdem folgende Zeile:

[..]
<? $title = "Zitate"; ?>
[..]

Da nun im Inhalts-Template die Variable 'title' gesetzt wurde, kann diese im Layout-Template verwendet werden. (siehe dazu Zeile 4 im Layout-Template oben)

Um also nun einem Template ein Layout zuzuordnen, ruft man einfach die Methode #set_layout auf:

$template->set_layout('my_chunky_layout');

Zurück zur Zitatensammlung aus Beispiel 2. Um unsere Zitate in ein Layout einzubetten, müssen wir lediglich:

• dem Template-Objekt die Nachricht #set_layout senden
• ein Layout-Template erstellen

Der erste Punk ist schnell erledigt. In dem PHP-Skript, das in Beispiel 2 unser Template-Objekt erzeugt hat, fügen wir folgende Zeile hinzu:

[..]
# open template
$template = $factory->open('quotes');


# set layout
$template->set_layout('layout');


# set quotes
[..]

Damit bleibt nur noch Punkt 2: ein Layout-Template namens 'layout' erstellen:

<html>
<head>
  <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
  <title><?= $title ?></title>
  <link rel="stylesheet" type="text/css" href="style.css" media="screen"/>
</head>
<body>
  <div id="header">Zitate <span class="amp">&amp;</span> mehr</div>
  <?= $content_for_layout ?>
</body>
</html>

Das Stylesheet wird an dieser Stelle nicht wiedergegeben. Wichtig ist ja auch nur Zeile 9, in der die Ausgabe des Inhalts-Templates eingefügt wird.

Damit sind nun alle wichtigen Mechanismen der Flexi-Templates vorgestellt worden. Es folgen nun noch ein paar Gimmicks…

––

Meanwhile, in another place …

Bevor es zu den Gadgets kommen, noch ein kurzer Überblick über die API, die die Flexi-Templates bietet.

Zunächst kurz die Methoden, die ein Flexi_Template-Objekt bietet. Anzumerken ist, dass diese Objekte dieser Klasse nicht direkt instanziiert werden können, da man dafür eine Template-Gactory benötigt.

class Flexi_Template {

  function get_attribute($name);
  function get_attributes();

  function set_attribute($name, $value);
  function set_attributes($attributes);

  function clear_attributes();
  function clear_attribute($name);

  function render($attributes = null, $layout = null);

  function set_layout($layout);
}

Die ersten sechs Methoden:

• #get_attribute
• #get_attributes
• #set_attribute
• #set_attributes
• #clear_attributes
• #clear_attribute

dienen zum Setzen, Abfragen und Entfernen von Attributen. Für gewöhnlich werden wohl nur die beiden Setter

• #set_attribute
• #set_attributes

benötigt. Während #set_attribute einem Schlüssel einen Wert zuordnet:

$template->set_attribute('key', new Value());

Mit der Methode #set_attributes kann man gleich ein ganzes (assoziatives) Array von Schlüssel-Wert-Paaren setzen:

$attributes = array();
$attributes['title'] = "a title";
$attributes['content'] = "some content";

$template->set_attributes($attributes);

Anzumerken ist, dass diese Methode #set_attributes die bereits gesetzten Attribute nicht entfernt, sondern nur bereits vorhandene Schlüssel aktualisiert:

$template->set_attribute('key', 'value');
$template->set_attribute('title', 'former title');


$attributes = array();
$attributes['title'] = "a title";
$attributes['content'] = "some content";

$template->set_attributes($attributes);

Während also das #set_attributes den alten Wert des Attributs 'title' gegen den neuen Wert ersetzt, bleibt das Attribut 'key' erhalten.

(:source linenum:)[@

(:source linenum:)[@

(:source linenum:)[@

Da Header und Footer in allen Dateien gleich ist, liegt es nahe, sich nicht immer zu wiederholen (DRY - Don't Repeat Yourself). Für die Flexi-Templates gibt es speziell zu diesem Zweck einen Mechanismus: "Layouts".

Layout-Templates sind dabei ganz normale Templates, allerdings mit zwei zusätzlichen Eigenschaften:

• Die Ausgabe des Inhalttemplates wird im Attribut "content_for_layout" zur Verfügung gestellt.
• Alle Attribute, die das Inhalts-Template erhält, ebenso wie alle Variablen, die das Inhalts-Template während seiner Evaluierung setzt, werden an das Layout-Template vererbt.

Ein Layout-Template sieht dann also im Prinzip so aus:

header
<?= $content_for_layout ?>
footer

Wenn dann das Inhalt-Template folgende Ausgabe erzeugt:

Hello, world!

wäre das Endergebnis dann:

header
Hello, world!
footer

––

Beispiel 3: "Und nun in hübsch"

Wenn man viele verschiedene Templates fertig gestellt hat, fällt einem irgendwann auf, dass sich darin zu Beginn und zum Ende eines Templates Text wiederholt. Nicht selten liegt dann ungefähr folgender Aufbau in den Templates vor:

<!-- hier steht ein "header" -->

<!-- dann folgt der inhalt -->
Hello World

<!-- und zum schluss noch ein footer -->

Da Header und Footer in allen Dateien gleich ist, liegt es nahe, sich nicht immer zu wiederholen (DRY - Don't Repear Yourself). Für die Flexi-Templates gibt es speziell zu diesem Zweck einen Mechanismus: "Layouts".

Im folgenden wird nun die Zitatensammlung aus Beispiel 2 in ein Layout eingebettet.

Zunächst aber die theoretische Seite: Layouts sind ein Beispiel für Martin Fowlers "Decorator Pattern". Templates werden dazu in andere Layout-Templates eingebettet. Diese Layout-Templates bilden eine gemeinsame Struktur für die eingebetteten Inhalts-Templates. Das Layout-Template entscheidet, wohin der Inhalt der eingebetteten Templates eingefügt wird.

<h1>Zitat des Tages (<?= date('d.m.Y', $time) ?>)</h1>

<h1>Zitat des Tages (<?= date('d.m.Y', $time) ?>)</h1>

Offenbar wird der Platzhalter $name verwendet, um den Namen des Gegrüßten anzuzeigen.

Wenn man also von der Verwendung der alternativen Syntax für if und foreach (http://de.php.net/manual/en/control-structures.alternative-syntax.php) absieht, sollte der Inhalt des Templates für einen wahren PHP-Connoisseur absolut Standardcode sein.

Eine Beispielausgabe sieht dann also ungefähr so aus:

Hier erwartet uns nichts besonderes. Die Zeilen 1-13 sind dieselben, die wir schon im ersten Beispiel hatten. Die Flexi-Bibliothek wird geladen, der Pfad zu den Templates wird gesetzt und mit ihm eine Template-Factory erzeugt, die wir dann verwenden, um das Template namens "quotes" zu öffnen.

Danach (Zeilen 16-27) wird ein Vektor von Zitaten angelegt, um dann in den Zeilen 29-31 diesen Vektor zu mischen und den ersten zum Zitat des Tages zu kören.

Interessanter wird es dann in Zeile 33. Dort senden wir an unser Template eine neue Nachricht #set_attributes. Anstatt also zweimal hintereinander #set_attribute aufzurufen, was so aussehen würde:

template->set_attribute('quotes', $quotes); template->set_attribute('quote_of_the_day', $quote_of_the_day); @]

setzen wir stattdessen direkt ein Array von Schlüssel-Wert-Paaren.

Die Zeilen 37-39 demonstrieren, dass man hinterher gerne weitere Attribute wie gewohnt setzen kann. Auch andersherum wäre das kein Problem gewesen (also zunächst #set_attribute und dann #set_attributes). Die Nachricht #set_attributes überschreibt nämlich nur, löscht also nicht alle vorher eingetragenen Attribute.

Die Zeilen 42-43 sollten einem dann wieder bekannt vorkommen. Wir evaluieren die Attribute im Kontext der Template-Datei und geben diese aus.

Die Template-Datei ist wieder ein Flexi_PhpTemplate also ein gewöhnliches PHP-Skript. Diesmal haben wir aber eine kleine Überraschung eingebaut. Es soll nämlich ein bisschen Ausgabelogik demonstriert werden:

(:source lang=php linenum:)[@

@]

Interessant sind hier wohl die Aufrufe von Ausgabefunktionen wie #date in Zeile 1, die Verwendung eines if-Konstrukts in Zeile 10 (und natürlich dessen Ende in Zeile 20) und die Verwendung von foreach in Zeile 12 (und 19).

Wenn man also von der Verwendung der alternativen Syntax für if und foreach (http://de.php.net/manual/en/control-structures.alternative-syntax.php) absieht, sollte der Inhalt des Templates für einen wahren PHP-Connoisseur absolut Standardcode sein.

––

Eben haben wir gerade eine "Lücke" mit einem String gefüllt. Als nächstes probieren wir das mal mit anderen Sachen als Strings.

Schauen wir uns als erstes einmal das PHP-Skript an, das unser Template füllen wird.

<?php

# load flexi lib
require_once dirname(__FILE__) . '/../../lib/flexi.php';

# where are the templates
$path_to_the_templates = dirname(__FILE__) . '/templates';

# we need a template factory
$factory = new Flexi_TemplateFactory($path_to_the_templates);

# open template
$template = $factory->open('quotes');


# set quotes
$quotes = array(
  array('author' => 'August Strindberg',
        'quote'  => 'Der Mensch ist ein wunderliches Tier.'),
  array('author' => 'Pierre Reverdy',
        'quote'  => 'Der Mensch ist ein Tier, das sich selbst gezähmt hat.'),
  array('author' => 'Thomas Niederreuther',
        'quote'  => 'Der Mensch ist das einzige Tier, das sich für einen Menschen hält.'),
  array('author' => 'Durs Grünbein',
        'quote'  => 'Der Mensch ist das Tier, das Kaugummi kaut.'),
  array('author' => 'Mark Twain',
        'quote'  => 'Der Mensch ist das einzige Tier, das erröten kann - oder sollte.'));

# select one randomly
shuffle($quotes);
$quote_of_the_day = array_shift($quotes);

$template->set_attributes(array('quotes'           => $quotes,
                                'quote_of_the_day' => $quote_of_the_day));


# set current time
$time = time();
$template->set_attribute('time', $time);


# render template
echo $template->render();

Dort erwartet uns nichts

<h1>Zitat des Tages (<?= date('m.d.Y', $time) ?>)</h1>
<p>
  <em>
    &#8222;<?= $quote_of_the_day['quote'] ?>&#8220;
  </em>
  (<?= $quote_of_the_day['author'] ?>)
</p>


<? if (sizeof($quotes)) : ?>
  <h1>Mehr Zitate</h1>
  <? foreach ($quotes as $quote) : ?>
    <p>
      <em>
        &#8222;<?= $quote['quote'] ?>&#8220;
      </em>
      (<?= $quote['author'] ?>)
    </p>
  <? endforeach ?>
<? endif ?>

(:source lang=php linenum:)[@

(:source lang=php linenum:)[@

Beispiel 1: "Hello World"

Wenig überraschend erhält man nach Ausführung im Browser:

Beispiel 2: "Darf's ein bisschen mehr sein?"

im Browser.

<h1>Hello, <?= $name ?>!</h1>

<<<<<<<

im Browser. ======= Wenig überraschend erhält man nach Ausführung ein:

im Browser. >>>>>>>

Wenig überraschend erhält man nach Ausführung ein:

"Hello, Axel!"

im Browser.

Beispiel 1: Hello World

Wie es sich gehört, kommt als erstes Beispiel das bekannte "Hello world". Dafür brauchen wir zwei Sachen:

• eine Template-Datei, die wie ein Lückentext funktioniert,
• ein PHP-Skript, das diesen Lückentext füllt und ausgibt.

Die Template-Datei liegt aus Hygienegründen in einem eigenen Verzeichnis templates. Damit sieht dann das Beispiel so aus:

  index.php
  templates/hello_world.php

Der Lückentext ist in der Datei templates/hello_world.php gespeichert. Die Flexi_Template-Engine benutzt die Endung einer Template-Datei, um die Art dieser zu erkennen. Eine Endung ".php" weißt dabei auf ein Flexi_PhpTemplate hin. Diese Art von Template ist einfach ein plain vanilla PHP-Skript. Wie sieht also unser Template aus?

<h1>Hello, <?= $name ?></h1>

Offenbar wird der Platzhalter @$name@ verwendet, um den Namen des Gegrüßten anzuzeigen.

Wie füllt man also dann diesen Lückentext? Schauen wir uns doch die Datei index.php an:

<?php

# load flexi lib
require_once dirname(__FILE__) . '/../../lib/flexi.php';

# where are the templates
$path_to_the_templates = dirname(__FILE__) . '/templates';

# we need a template factory
$factory = new Flexi_TemplateFactory($path_to_the_templates);

# open template
$template = $factory->open('hello_world');

# set name of the greetee
$template->set_attribute('name', 'Axel');

# render template
echo $template->render();

Zunächst wird offenbar die Flexi-Bibliothek geladen, daraufhin eine Variable mit dem Pfad zum Verzeichnis, wo unser Template liegt, gefüllt und dann mit dieser eine Flexi_TemplateFactory erzeugt.

Wie der Name schon andeutet, wird diese factory dazu benutzt, Templates herzustellen. Und genau das passiert als nächstes. Indem man der factory die Nachricht #open schickt, erhält man ein Template-Objekt. Dazu muss man als Argument nur den Namen der Template-Datei mitgeben. Da die factory ein wenig schlau ist, reicht ihr dabei der Name der Datei ohne Endung (die man aber natürlich auch mitangeben dürfte; man muss es eben nur nicht..). Für unser Template hello_world.php genügt also ein "hello_world".

Die Verwendung des Namens ohne Endung erlaubt ein Feature, auf das wir später noch einmal eingehen werden.

Zurück zum Thema: In einem weiteren Schritt setzen wir für das Template das Attribut "name" auf den Wert "Axel". Und zum Schluss lassen wir das Template auswerten und geben das Ergebnis (einen String) aus.

"Hello, Axel!"