smarty/docs/de/getting-started.sgml

<!-- Smarty German Documentation Port -->
<!-- $Id$ -->
<!-- $Author$ -->
<!-- $Revision$ -->
<part id="getting.started">
 <title>Erste Schritte</title>
 <chapter id="what.is.smarty">
   <title>Was ist Smarty?</title>
   <para>
	Smarty ist eine Template-Engine f&uuml;r PHP. Genauer gesagt erlaubt es
	die einfache Trennung von Applikations-Logik und Design/Ausgabe. Dies
	ist vor allem w&uuml;nschenswert, wenn der Applikationsentwickler nicht
	die selbe Person ist wie der Designer. Nehmen wir zum Beispiel eine
	Webseite die Zeitungsartikel ausgibt. Der Titel, die Einf&uuml;hrung,
	der Author und der Inhalt selbst enthalten keine Informationen dar&uuml;ber
	wie sie dargestellt werden sollen. Also werden sie von der Applikation
	an Smarty &uuml;bergeben, damit der Designer in den Templates mit einer Kombination von
	HTML- und Template-Tags die Ausgabe (Tabellen, Hintergrundfarben,
	Schriftgr&ouml;ssen, Stylesheets, etc.) gestalten kann. Falls nun die
	Applikation eines Tages angepasst werden muss, ist dies f&uuml;r den
	Designer nicht von Belang, da die Inhalte immer noch genau gleich
	&uuml;bergeben werden. Genauso kann der Designer die Ausgabe der
	Daten beliebig ver&auml;ndern, ohne dass eine &Auml;nderung der
	Applikation vorgenommen werden muss. Somit k<>nnen der Programmierer
	die Applikations-Logik und der Designer die Ausgabe frei anpassen,
	ohne sich dabei in die Quere zu kommen.
	</para>
	<para>
	Was Smarty nicht kann: Smarty versucht nicht die gesamte Logik aus dem
	Template zu verbannen. Solange die verwendete Logik ausschlie<69>lich f&uuml;r die
	Ausgabe verwendet wird, kann sie auch im Template eingebettet werden. Ein Tip:
	versuchen Sie Applikations-Logik aus dem Template und Pr&auml;sentations-Logik 
    aus der Applikation herauszuhalten. Nur so bleibt die Applikation auf absehbere Zeit
    gut skalier- und wartbar.
	</para>
	<para>
	Einer der einzigartigen Aspekte von Smarty ist die Kompilierung der
	Templates. Smarty liest die Template-Dateien und generiert daraus neue
	PHP-Skripte; von da an werden nur noch diese Skripte verwendet. Deshalb
	m&uuml;ssen Templates nicht f&uuml;r jeden Seitenaufruf performance-intensiv 
    neu geparst werden und jedes Template kann voll von PHP Compiler-Cache 
    L&ouml;sungen profitieren. 
    (Zend, http://www.zend.com; PHP Accelerator, http://www.php-accelerator.co.uk)
   </para>
   <para>
    Ein paar Smarty Charakteristiken
   </para>
   <itemizedlist>
    <listitem><para>Sehr schnell.</para></listitem>
    <listitem><para>Sehr effizient, da der PHP-Parser die 'schmutzige' Arbeit &uuml;bernimmt.</para></listitem>
    <listitem><para>Kein Overhead durch Template-Parsing, nur einmaliges kompilieren.</para></listitem>
    <listitem><para>Re-kompiliert nur g&auml;nderte Templates.</para></listitem>
    <listitem><para>Sie k&ouml;nnen die Engine um <link linkend="language.custom.functions">individuelle Funktionen</link> und <link linkend="language.modifiers">Variablen-Modifikatoren</link> erweitern.</para></listitem>
    <listitem><para>Konfigurierbare Syntax f<>r Template-Tags: Sie k&ouml;nnen {}, {{}}, &lt;!--{}--&gt;, etc. verwenden.</para></listitem>
    <listitem><para>'if/elseif/else/endif'-Konstrukte werden direkt dem PHP-Parser &uuml;bergeben. Somit k&ouml;nnen {if ...} Ausdr<64>cke sowohl sehr einfach als auch sehr komplex sein.</para></listitem>
    <listitem><para>Unbegrenzte Verschachtelung von 'section', 'if' und anderen Bl&ouml;cken.</para></listitem>
    <listitem><para>Erm&ouml;glicht die direkte Einbettung von PHP-Code. (Obwohl es weder ben&ouml;tigt noch empfohlen wird, da die Engine einfach erweiterbar ist.)</para></listitem>
    <listitem><para>Eingebauter Caching-Support</para></listitem>
    <listitem><para>Beliebige Template-Quellen</para></listitem>
    <listitem><para>Eigene Cache-Handling Funktionen</para></listitem>
    <listitem><para>Plugin Architektur</para></listitem>
   </itemizedlist>
 </chapter>
 <chapter id="installation">
  <title>Installation</title>
  <sect1 id="installation.requirements">
   <title>Anforderungen</title>
   <para>
   Smarty ben&ouml;tigt einen Webserver mit PHP >=4.0.6.
   </para>
  </sect1>

  <sect1 id="installing.smarty.basic">
    <title>Basis Installation</title>
	<para>
	Installieren Sie die Smarty Library Dateien aus dem /libs/ Verzeichnis
	der Distribution. Diese PHP Dateien sollten NICHT angepasst werden. Sie
	werden zwischen den verschieden Applikationen die Smarty verwenden geteilt.
	Diese Dateien werden bei einem upgrade ersetzt.
	</para>
	<example>
     <title>Smarty-Library Dateiliste</title>
     <screen>
Smarty.class.php
Smarty_Compiler.class.php
Config_File.class.php
debug.tpl
/plugins/*.php (alle Dateien!)</screen>
	</example>

	<para>
	Smarty verwendet eine PHP Konstante namens <link linkend="constant.smarty.dir">SMARTY_DIR</link>
	die den Systempfad zu den Library Dateien enth&auml;lt. Wenn Ihre Applikation keine
	Probleme hat die Library Dateien zu finden, m&uuml;ssen Sie diese Konstante nicht zuweisen,
	und Smarty wird alle ben&ouml;tigten Dateien finden. Falls <emphasis>Smarty.class.php</emphasis>
	nicht in Ihrem 'include_path' ist und Sie nicht den absoluten Pfad angeben, m&uuml;ssen Sie
	SMARTY_DIR manuell zuweisen. SMARTY_DIR <emphasis>must</emphasis> muss mit einem '/'-Zeichen (slash) enden.
	</para>
	<para>
	So erzeugt man eine Instanz der Smarty-Klasse im PHP-Skript:
	</para>

	<example>
     <title>Smarty Instanz aus 'include_path' erstellen:</title>
     <screen>
require('Smarty.class.php');
$smarty = new Smarty;</screen>
	</example>

	<para>
	Versuchen Sie das oben gezeigte Script auszuf&uuml;hren. Wenn Sie einen Fehler erhalten ('<emphasis>Smarty.class.php</emphasis> file could not be found'),
	m&uuml;ssen Sie wie folgt vorgehen:
	</para>

	<example>
       <title>&Uuml;bergeben Sie den vollen Pfad</title>
      <screen>
 require('/usr/local/lib/php/Smarty/Smarty.class.php');
 $smarty = new Smarty;</screen>
       </example>

       <example>
      <title>F&uuml;gen Sie den Library Pfad Ihrem PHP-'include_path' hinzu</title>
      <screen>
 // Editieren Sie die php.ini Datei und f&uuml;gen Sie den Library Pfad Ihrem PHP-'include_path' hinzu
 // Danach sollte folgendes funktionieren.
 require('Smarty.class.php');
 $smarty = new Smarty;</screen>
       </example>

       <example>
      <title>Setzen Sie SMARTY_DIR manuell</title>
       <screen>
define('SMARTY_DIR','/usr/local/lib/php/Smarty/');
require(SMARTY_DIR.'Smarty.class.php');
$smarty = new Smarty;</screen>
	</example>

	<para>
	Jetzt, wo die Library Dateien an ihrem Platz sind, wird es
	Zeit, die Smarty Verzeichnisse zu erstellen. Smarty ben&ouml;tigt 4 Verzeichnisse
	welche (normerweise) <emphasis>templates</emphasis>, <emphasis>templates_c</emphasis>, <emphasis>configs</emphasis>
	und <emphasis>cache</emphasis> heissen. Jedes kann jedoch &uuml;ber die
	Smarty Attribute <emphasis>$template_dir</emphasis>, <emphasis>$compile_dir</emphasis>, <emphasis>$config_dir</emphasis>,
	und <emphasis>$cache_dir</emphasis> definiert werden. Es wird empfohlen f&uuml;r jede Applikation die Smarty verwenden
	soll eigene Verzeichnisse einzurichten.
	</para>
	<para>
	Stellen Sie sicher dass Sie die DocumentRoot Ihres Webservers kennen.
	In unserem Beispiel verwenden wir "/web/www.mydomain.com/docs/". Alle
	Smarty-Verzeichnisse werden immer nur von Smarty aufgerufen, nie vom Browser
	direkt. Deshalb wird empfohlen diese Verzeichnisse <emphasis>ausserhalb</emphasis>
	der DocumentRoot einzurichten.
	</para>

	<para>
	F&uuml;r unser installations-Beispiel werden wir die Umgebung f&uuml;r eine
	G&auml;stebuchapplikation einrichten. Wir verwenden dies nur als Beispiel,
	falls Sie ihre eigene Applikationsumgebung einrichten, ersetzen sie '/guestbook/'
	einfach durch den Namen Ihrer eigener Applikation. Unsere Dateien werden unter
	"/web/www.mydomain.com/smarty/guestbook/" abgelegt.

	</para>
	<para>
	In Ihrer DocumentRoot muss mindestens eine Datei liegen, die f&uuml;r Browser
	zug&auml;nglich ist. Wir nennen dieses Skript 'index.php', und legen
	es in das Verzeichnis '/guestbook/' in unserer DocumentRoot.
	Bequem ist es, den Webserver so zu konfigurieren, dass 'index.php' als
	Standard-Verzeichnis-Index verwendet wird. Somit kann man das Skript
	direkt mit 'http://www.domain.com/guestbook/' aufrufen. Falls Sie Apache
	verwenden, l&auml;sst sich dies konfigurieren indem Sie 'index.php'
	als letzten Eintrag f&uuml;r DirectoryIndex verwenden. (Jeder Eintrag muss
	mit einem Leerzeichen abgetrennt werden). 
	</para>
	
	<para>
	Die Dateistruktur bis jetzt:
	</para>

	<example>
     <title>Beispiel der Dateistruktur</title>
     <screen>
/usr/local/lib/php/Smarty/Smarty.class.php
/usr/local/lib/php/Smarty/Smarty_Compiler.class.php
/usr/local/lib/php/Smarty/Config_File.class.php
/usr/local/lib/php/Smarty/debug.tpl
/usr/local/lib/php/Smarty/plugins/*.php

/web/www.mydomain.com/smarty/guestbook/templates/
/web/www.mydomain.com/smarty/guestbook/templates_c/
/web/www.mydomain.com/smarty/guestbook/configs/
/web/www.mydomain.com/smarty/guestbook/cache/

/web/www.mydomain.com/docs/guestbook/index.php</screen>
	</example>

	<para>
	Smarty ben&ouml;tigt Schreibzugriff auf die Verzeichnisse '$compile_dir' und '$cache_dir'.
	Stellen Sie also sicher, dass der Webserver-Benutzer (normalerweise Benutzer 'nobody' und Gruppe 'nogroup')
	in diese Verzeichnisse schreiben kann. (In OS X lautet der Benutzer normalerweise 'web' und
	ist in der Gruppe 'web'). Wenn Sie Apache verwenden, k&ouml;nnen Sie in der httpd.conf (gew<65>hnlich in '/usr/local/apache/conf/')
	nachsehen, unter welchem Benutzer Ihr Server l&auml;uft.
	</para>

	<example>
     <title>Dateirechte einrichten</title>
     <screen>

chown nobody:nobody /web/www.mydomain.com/smarty/templates_c/
chmod 770 /web/www.mydomain.com/smarty/templates_c/

chown nobody:nobody /web/www.mydomain.com/smarty/cache/
chmod 770 /web/www.mydomain.com/smarty/cache/</screen>
	</example>

	<note>
	 <title>Technische Bemerkung</title>
	 <para>
	 'chmod 770' setzt ziemlich strenge Rechte und erlaubt nur dem Benutzer 'nobody'
	 und der Gruppe 'nobody' Lese-/Schreibzugriff auf diese Verzeichnisse. Falls Sie
	 die Rechte so setzen m&ouml;chten, dass auch andere Benutzer die Dateien lesen
	 k&ouml;nnen (vor allem f&uuml;r Ihren eigenen Komfort), so erreichen Sie dies mit 775.
     </para>
	</note>

	<para>
	Nun m&uuml;ssen wir die 'index.tpl' Datei erstellen, welche Smarty laden soll.
	Die Datei wird in Ihrem '$template_dir' abgelegt.
	</para>

	<example>
     <title>Editieren von /web/www.mydomain.com/smarty/templates/index.tpl</title>
     <screen>

{* Smarty *}

Hallo, {$name}!</screen>
	</example>


	<note>
	<title>Technische Bemerkung</title>
	<para>
		{* Smarty *} ist ein Template-Kommentar. Der wird zwar nicht ben&ouml;tigt,
		es ist jedoch eine gute Idee jedes Template mit einem Kommentar zu versehen.
		Dies erleichtert die Erkennbarkeit des Templates, unabh&auml;ngig von der
		verwendeten Dateierweiterung. (Zum Beispiel f&uuml;r Editoren die Syntax-Highlighting
		unterst&uuml;tzen.)
	</para>
	</note>

	<para>
	Als n&auml;chstes editieren wir die Datei 'index.php'. Wir erzeugen eine
	Smarty-Instanz, weisen dem Template eine Variable zu und geben 'index.tpl' aus.
	In unserem Beispiel ist '/usr/local/lib/php/Smarty' in unserem PHP-'include_path',
	stellen Sie sicher dass dies bei Ihrer Installation auch der Fall ist, oder
	verwenden Sie ansonsten aboslute Pfade.
	</para>

	<example>
     <title>Editieren von /web/www.mydomain.com/docs/guestbook/index.php</title>
     <screen>

// Smarty laden
require('Smarty.class.php');

$smarty = new Smarty;

$smarty->template_dir = '/web/www.mydomain.com/smarty/guestbook/templates/';
$smarty->compile_dir = '/web/www.mydomain.com/smarty/guestbook/templates_c/';
$smarty->config_dir = '/web/www.mydomain.com/smarty/guestbook/configs/';
$smarty->cache_dir = '/web/www.mydomain.com/smarty/guestbook/cache/';

$smarty->assign('name','Ned');

$smarty->display('index.tpl');</screen>
	</example>

	<note>
	 <title>Technische Bemerkung</title>
	 <para>
	 In unserem Beispiel verwenden wir durchwegs absolute Pfadnamen zu den
	 Smarty-Verzeichnissen. Falls '/web/www.mydomain.com/smarty/guestbook/' in
	 Ihrem PHP-'include_path' liegt, w&auml;re dies nicht n&ouml;tig. Es ist jedoch
	 effizienter und weniger fehleranf&auml;llig die Pfade absolut zu setzen.
	 Und es garantiert, dass Smarty die Templates aus dem geplanten Verzeichnis l&auml;dt.
	 </para>
	</note>

	<para>
	Wenn Sie 'index.php' nun in Ihrem Webbrowser &ouml;ffnen, sollte 'Hallo, Ned!' ausgegeben werden.
	</para>
	<para>
	Die Basis-Installation von Smarty w&auml;re somit beendet.
	</para>
   </sect1>
   <sect1 id="installing.smarty.extended">
   <title>Erweiterte Konfiguration</title>

   <para>
   
   Dies ist eine Weiterf&uuml;hrung der <link linkend="installing.smarty.basic">Basis Installation</link>, bitte lesen Sie diese zuerst!
   </para>
   <para>
   Ein flexiblerer Weg um Smarty aufzusetzen ist, die Klasse zu erweitern und
   eine eigene Smarty-Umgebung zu initialisieren. Anstatt immer wieder
   die Verzeichnisse zu definieren, kann diese Aufgabe auch in einer einzigen
   Datei erledigt werden. Beginnen wir, indem wir ein neues Verzeichnis namens '/php/includes/guestbook/'
   erstellen und eine Datei namens 'setup.php' darin anlegen. In unserem Beispiel ist '/php/includes'
   im PHP-'include_path'. Stellen Sie sicher dass das auch bei Ihnen der Fall ist, oder benutzen Sie absolute Pfadnamen.
   </para>

   <example>
    <title>Editieren von /php/includes/guestbook/setup.php</title>
    <screen>

// Smarty Library Dateien laden
require(SMARTY_DIR.'Smarty.class.php');

// steup.php ist auch ein guter Platz um Applikations spezifische Libraries zu laden
// require('guestbook/guestbook.lib.php');

class Smarty_GuestBook extends Smarty {

   function Smarty_GuestBook() {
   

		// Konstruktor. Diese Werte werden f&uuml;r jede Instanz automatisch gesetzt

		$this->Smarty();

		$this->template_dir = '/web/www.mydomain.com/smarty/guestbook/templates/';
		$this->compile_dir = '/web/www.mydomain.com/smarty/guestbook/templates_c/';
		$this->config_dir = '/web/www.mydomain.com/smarty/guestbook/configs/';
		$this->cache_dir = '/web/www.mydomain.com/smarty/guestbook/cache/'; 
		
		$this->caching = true;
		$this->assign('app_name','Guest Book');
   }

}</screen>
   </example>

  <para>
  Nun passen wir 'index.php' an, um 'setup.php' zu verwenden:
  </para>
   
   <example>
    <title>Editieren von /web/www.mydomain.com/docs/guestbook/index.php</title>
    <screen>

require('guestbook/setup.php');

$smarty = new Smarty_GuestBook;

$smarty->assign('name','Ned');

$smarty->display('index.tpl');</screen>
   </example>

  <para>
  Wie Sie sehen k&ouml;nnen, ist es sehr einfach eine Instanz von Smarty zu erstellen.
  Mit Hilfe von Smarty_GuestBook werden alle Variablen automatisch initialisiert.
  </para>
   
  </sect1>

 </chapter>
</part>