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ß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ü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>
	<note>
	<title>Technische Bemerkung</title>
	<para>
	Dieser Leitfaden geht davon aus, dass Sie Ihr Webserver- und PHP-Setup kennen
	und mit den Namenskonventionen f&uuml;r Dateien und Verzeichnisse Ihres Betriebssystems
	vertraut sind. Im Folgenden wird ein Unix-Dateisystem verwendet, stellen Sie also
	sicher, dass sie die f&uuml;r Ihr Betriebssystem n&ouml;tigen &Auml;nderungen vornehmen.
	</para>
	<para>
	Das Beispiel geht davon aus, dass '/php/includes' in Ihrem PHP-'include_path'
	liegt. Konsultieren Sie das PHP-Manual f&uuml;r weiterf&uuml;hrende Informationen hierzu.
	</para>
	</note>
	<para>
	Installieren Sie als erstes die Smarty-Library Dateien. Diese Dateien
	sollten von Ihnen NICHT editiert und von allen Applikationen
	verwendet werden. Sie werden nur erneuert, wenn Sie eine neue Version von Smarty installieren.
	</para>
	<note>
	 <title>Technische Bemerkung</title>
	 <para>
	 Wir empfehlen keine &Auml;nderungen an den Smarty-Library Dateien vorzunehmen.
	 Dies macht ein m&ouml;gliches Upgrade wesentlich einfacher. Sie m&uuml;ssen
	 diese Dateien auch nicht anpassen, um Smarty zu konfigurieren! Benutzen Sie für
     diesen Zwecke eine Instanz der Smarty-Klasse.
	</para>
	</note>

	<para>
	Folgende Library Dateien werden mit Smarty geliefert und werden ben&ouml;tigt:
	</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>
	Sie k&ouml;nnen diese Dateien entweder in Ihrem PHP-'include_path' oder
	auch in irgend einem anderen Verzeichnis ablegen, solange die Konstante
	<link linkend="constant.smarty.dir">SMARTY_DIR</link> auf den korrekten
	Pfad zeigt. Im Folgenden werden Beispiele f&uuml;r beide F&auml;lle aufgezeigt.
	</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>
	Wenn sich die Dateien ausserhalb des PHP-'include_path' befinden,
	muss die Konstante <link linkend="constant.smarty.dir">SMARTY_DIR</link>
	auf den absoluten Pfad zeigen und mit einem '/' enden. Nehmen wir an,
	die Library-Dateien befinden sich in '/usr/local/lib/php/Smarty/':
	</para>

	<example>
     <title>Instanz von Smarty aus SMARTY_DIR erstellen:</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.
	</para>
	<para>
	F&uuml;r unser Beispiel werden wir die Smarty Umgebung f&uuml;r eine
	G&auml;stebuch-Applikation konfigurieren. Wir verwenden den Applikationsnamen
	nur, um die Verzeichnis-Struktur zu verdeutlichen. Sie k&ouml;nnen die selbe
	Umgebung f&uuml;r alle Ihre Applikationen verwenden indem Sie 'guestbook'
	durch dem Namen Ihrer Applikation ersetzen.
	</para>
	<para>
	Stellen Sie sicher, dass Sie die DocumentRoot Ihres Webservers kennen.
	In unserem Beispiel lautet sie '/web/www.domain.com/docs/'.
	</para>
	<para>
	Die Smarty Verzeichnisse werden in den Klassen-Variablen $template_dir,
	$compile_dir, $config_dir und $cache_dir definiert. Die Standardwerte sind:
	"templates", "templates_c", "configs" und "cache". F&uuml;r unser Beispiel
	legen wir alle diese Verzeichnisse unter '/web/www.domain.com/smarty/guestbook/' an.
	</para>

	<note>
	<title>Technische Bemerkung</title>
	<para>
	Wir empfehlen, diese Verzeichnisse ausserhalb der DocumentRoot anzulegen,
	um m&ouml;gliche Direktzugriffe zu verhindern.
	</para>
	</note>

	<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.
	</para>
	
	<note>
	<title>Technische Bemerkung</title>
	<para>
	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>
	</note>
	
	<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>

	<note>
	 <title>Technische Bemerkung</title>
	 <para>
	 Falls Sie kein Caching und keine Konfigurationsdateien verwenden, ist es nicht
	 erforderlich die Verzeichnisse '$config_dir' und '$cache_dir' zu erstellen.
	 Es wird jedoch trotzdem empfohlen, da diese Funktionalit&auml;ten eventuell sp&auml;ter
	 genutzt werden sollen.
     </para>
	</note>

	<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ö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.
	</para>

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

define('SMARTY_DIR','/usr/local/lib/php/Smarty/');
require(SMARTY_DIR.'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.
   </para>

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

// Smarty Library Dateien laden
define('SMARTY_DIR','/usr/local/lib/php/Smarty/');
require(SMARTY_DIR.'Smarty.class.php');

// 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>

   <note>
	<title>Technische Bemerkung</title>
	<para>
	In unserem Beispiel werden die Library Dateien ausserhalb der DocumentRoot
	abgelegt. Diese Dateien k&ouml;nnten sensitive Informationen enthalten,
	die wir nicht zug&auml;nglich machen m&ouml;chten.
	Deshalb legen wir alle Library Dateien in '/php/includes/guestbook/' ab
	und laden sie in unserem 'setup.php' Skript, wie Sie im oben gezeigten
	Beispiel sehen k&ouml;nnen.
	</para>
   </note>

  <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>