doc/parsen.htm

   1 <?xml version="1.0" encoding="iso-8859-1" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   4
   5 <html xmlns="http://www.w3.org/1999/xhtml">
   6 <head>
   7 <title>Templates parsen</title>
   8 <meta name="author" content="Patrick Canterino" />
   9 <link rel="stylesheet" href="style.css" type="text/css" />
  10 <base target="_self" />
  11 </head>
  12 <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#0000FF" alink="#0000FF">
  13
  14 <h1><a name="top" id="top">Templates parsen</a></h1>
  15
  16 <ul id="content">
  17 <li><a href="#laden-einlesen">Klasse laden und Template einlesen</a></li>
  18 <li><a href="#variablen-setzen">Variablen setzen</a></li>
  19 <li><a href="#schleifen-setzen">Daten f&uuml;r Schleifen setzen</a></li>
  20 <li><a href="#parsen">Templates parsen</a></li>
  21 </ul>
  22
  23 <h2><a name="laden-einlesen" id="laden-einlesen">Klasse laden und Template einlesen</a></h2>
  24
  25 <p>Erstmal ist es wichtig, die Klasse in Ihre Scripts einzubinden:</p>
  26
  27 <pre class="code">
  28 # PHP:
  29
  30 include(&quot;class.Template.php&quot;);
  31
  32 # Perl:
  33
  34 use Template;
  35
  36 # Python:
  37
  38 import template
  39 </pre>
  40
  41 <p>Ggf. m&uuml;ssen Sie andere Pfade angeben, oder in Perl zun&auml;chst mit <code>use lib</code> einen weiteren Pfad f&uuml;r Perl-Module hinzuf&uuml;gen. Andererseits k&ouml;nnen Sie die Klassen auch direkt in Ihre Scripts einbetten.</p>
  42
  43 <p>Nun m&uuml;ssen Sie ein neues Objekt der Klasse anlegen:</p>
  44
  45 <pre class="code">
  46 # PHP / Perl:
  47
  48 $tpl = new Template;
  49
  50 # Python:
  51
  52 tpl = template.Template()
  53 </pre>
  54
  55 <p>Dadurch stellt die Variable <code>$tpl</code> bzw. <code>tpl</code> ein neues Objekt der Template-Klasse dar (wird in den nachfolgenden Beispielen auch verwendet). &Uuml;ber das Objekt k&ouml;nnen Sie auf die verschiedenen Methoden der Klasse zugreifen.</p>
  56
  57 <p>Das Wichtigste ist, erstmal eine Datei einzulesen. Das geschieht &uuml;ber die Methode <code>read_file()</code>:</p>
  58
  59 <pre class="code">
  60 # PHP / Perl:
  61
  62 $tpl-&gt;read_file(Datei);
  63
  64 # Python:
  65
  66 tpl.read_file(Datei)
  67 </pre>
  68
  69 <p>Dadurch wird die angegebene Datei eingelesen und die <a href="aufbau.htm#includes"><code>{INCLUDE}</code>-Anweisungen</a> verarbeitet. Der Inhalt der Datei wird anschlie&szlig;end in den Objekteigenschaften gespeichert.<br />
  70 Es ist auch m&ouml;glich, den Vorlagentext direkt einzugeben. Das k&ouml;nnen Sie mit Hilfe der Methoden <code>set_template()</code> und <code>add_text()</code> erreichen. Das einzige Argument dieser Funktionen, ist der Text, der in den Objeteigenschaften gespeichert werden soll. <code>set_template()</code> legt den kompletten Vorlagentext fest, <code>add_text()</code> h&auml;ngt den Text nur an (<code>read_file()</code> verwendet diese Methode intern auch). <code>{INCLUDE}</code>-Anweisungen werden hierbei allerdings nicht verarbeitet, Sie k&ouml;nnen dies jedoch manuell durch Aufruf der Methode <code>parse_includes()</code> durchf&uuml;hren.</p>
  71
  72 <p class="upanddown"><a href="#top">Nach oben</a></p>
  73
  74 <h2><a name="variablen-setzen" id="variablen-setzen">Variablen setzen</a></h2>
  75
  76 <p>Eines der wichtigsten Merkmale von Templates ist die Tatsache, dass bestimmte Abschnitte variabel sind, d.h. hier werden Daten vom Script eingef&uuml;llt. F&uuml;r diese Klasse werden die variablen Abschnitte von geschweiften Klammern umschlossen. Eine Variable kann zum Beispiel so aussehen:<br />
  77 <code>{VARIABLE}</code><br />
  78 Um f&uuml;r eine Variable einen Wert festzulegen, k&ouml;nnen Sie ganz einfach die Methode <code>set_var()</code> verwenden:</p>
  79
  80 <pre class="code">
  81 # PHP / Perl:
  82
  83 $tpl-&gt;set_var(Variablenname,Wert);
  84
  85 # Python:
  86
  87 tpl.set_var(Variablenname,Wert)
  88 </pre>
  89
  90 <p>Bei den Variablen wird zwischen Gro&szlig;- und Kleinschreibung unterschieden. Die Variable <code>variable</code> ist also eine andere als <code>VARIABLE</code>.</p>
  91
  92 <p>Sie k&ouml;nnen als Variable auch ein Array angeben, dieses wird dann ganz einfach zusammengef&uuml;gt.</p>
  93
  94 <p>Auf den Inhalt einer Variable k&ouml;nnen Sie jederzeit mit der Methode <code>get_var()</code> zugreifen. Wenn die Variable nicht existiert, wird <code>false</code> zur&uuml;ckgegeben. Wenn Sie beim Aufruf von <code>get_var()</code> &uuml;berhaupt keinen Variablennamen angeben, wird ein Array mit den Namen s&auml;mtlicher definierten Variablen zur&uuml;ckgegeben.</p>
  95
  96 <p class="upanddown"><a href="#top">Nach oben</a></p>
  97
  98 <h2><a name="schleifen-setzen" id="schleifen-setzen">Daten f&uuml;r Schleifen setzen</a></h2>
  99
 100 <p>Bei Schleifen haben Sie die M&ouml;glichkeit, entweder f&uuml;r jeden Abschnitt die Daten einzeln oder alle Daten auf einmal hinzuzuf&uuml;gen.<br />
 101 Dazu stehen Ihnen die Methoden <code>add_loop_data()</code> und <code>set_loop_data()</code> zur Verf&uuml;gung (erstere f&uuml;gt neue Daten hinzu, letztere setzt die Daten komplett). Beide Methoden verwenden dasselbe Schema. Als erster Parameter kommt der Name der Schleife, dann der Datensatz bzw. alle Daten. Der Datensatz besteht aus einem assoziativen Array bzw. Hash-Referenz bzw. Dictionary, bei dem die Schl&uuml;ssel den Namen der Variablen und der Wert eben den Wert der Variablen darstellen. Bei <code>set_loop_data()</code> m&uuml;ssen Sie die Datens&auml;tze als ein Array bzw. Array-Referenz bzw. Liste von Datens&auml;tzen &uuml;bergeben.</p>
 102
 103 <p>Beispiel f&uuml;r <code>add_loop_data()</code>:</p>
 104
 105 <pre class="code">
 106 # PHP:
 107
 108 $tpl-&gt;add_loop_data('Test-Schleife',array('name' =&gt; 'Bart Simpson', 'email' =&gt; 'el-barto@example.org'));
 109 $tpl-&gt;add_loop_data('Test-Schleife',array('name' =&gt; 'Homer Simpson', 'email' =&gt; 'homer.simpson@example.org'));
 110
 111 # Perl:
 112
 113 $tpl-&gt;add_loop_data('Test-Schleife',{'name' =&gt; 'Bart Simpson', 'email' =&gt; 'el-barto@example.org'});
 114 $tpl-&gt;add_loop_data('Test-Schleife',{'name' =&gt; 'Homer Simpson', 'email' =&gt; 'homer.simpson@example.org'});
 115
 116 # Python:
 117
 118 tpl.add_loop_data('Test-Schleife',{'name': 'Bart Simpson', 'email': 'el-barto@example.org'})
 119 tpl.add_loop_data('Test-Schleife',{'name': 'Homer Simpson', 'email': 'homer.simpson@example.org'})
 120 </pre>
 121
 122 <p>Beispiel f&uuml;r <code>set_loop_data()</code>:</p>
 123
 124 <pre class="code">
 125 # PHP:
 126
 127 $tpl-&gt;set_loop_data('Test-Schleife',array(array('name' =&gt; 'Bart Simpson', 'email' =&gt; 'el-barto@example.org'),
 128                                           array('name' =&gt; 'Homer Simpson', 'email' =&gt; 'homer.simpson@example.org')));
 129
 130 # Perl:
 131
 132 $tpl-&gt;set_loop_data('Test-Schleife',[{'name' =&gt; 'Bart Simpson', 'email' =&gt; 'el-barto@example.org'},
 133                                      {'name' =&gt; 'Homer Simpson', 'email' =&gt; 'homer.simpson@example.org'}]);
 134
 135 # Python:
 136
 137 tpl.set_loop_data('Test-Schleife',[{'name': 'Bart Simpson', 'email': 'el-barto@example.org'},
 138                                    {'name': 'Homer Simpson', 'email': 'homer.simpson@example.org'}])
 139 </pre>
 140
 141 <p class="upanddown"><a href="#top">Nach oben</a></p>
 142
 143 <h2><a name="parsen" id="parsen">Templates parsen</a></h2>
 144
 145 <p>Wenn Sie alle Variablen und Schleifen-Daten gesetzt haben, ist es an der Zeit, diese Daten auch auf die Template-Datei anzuwenden. Dies geschieht mit Hilfe der Methode <code>parse()</code>:</p>
 146
 147 <pre class="code">
 148 # PHP / Perl:
 149
 150 $tpl-&gt;parse();
 151
 152 # Python:
 153
 154 tpl.parse()
 155 </pre>
 156
 157 <p>Dadurch werden alle <a href="aufbau.htm#variablen">Variablen</a> durch Text ersetzt, <a href="aufbau.htm#bedingt">bedingte Bl&ouml;cke</a> und <a href="aufbau.htm#schleifen">Schleifen</a> verarbeitet und in der Template-Datei <a href="aufbau.htm#definitionen">definierte Variablen</a> ausgelesen und auf die Template-Datei angewendet.</p>
 158
 159 <p>Zu guter letzt k&ouml;nnen Sie noch die verarbeiteten Daten zur&uuml;ckgeben lassen:</p>
 160
 161 <pre class="code">
 162 # PHP / Perl:
 163
 164 $template = $tpl-&gt;get_template();
 165
 166 # Python:
 167
 168 template = tpl.get_template()
 169 </pre>
 170
 171 <p>Dadurch enth&auml;lt die Variable <code>$template</code> bzw. <code>template</code> die nun verarbeitete Template-Datei (sie k&ouml;nnen <code>get_template()</code> &uuml;brigens jederzeit verwenden, um an den Vorlagentext heranzukommen).</p>
 172
 173 <p>Weiterhin k&ouml;nnen Sie den kompletten Vorlagentext auch in eine Datei schreiben. Diese muss allerdings bereits ge&ouml;ffnet sein. Verwenden Sie dazu die Methode <code>to_file()</code> und geben Sie als Parameter das Handle der ge&ouml;ffneten Datei an.</p>
 174
 175 <pre class="code">
 176 # PHP:
 177
 178 $handle = fopen(&quot;datei.htm&quot;,&quot;w&quot;);
 179 $tpl-&gt;to_file($handle);
 180 fclose($handle);
 181
 182 # Perl:
 183
 184 open(HANDLE,&quot;&gt;datei.htm&quot;);
 185 $tpl-&gt;to_file(\*HANDLE);
 186 close(HANDLE);
 187
 188 # Python:
 189
 190 handle = open(&quot;datei.htm&quot;,&quot;w&quot;)
 191 tpl.to_file(handle)
 192 handle.close()
 193 </pre>
 194
 195 <p><b>Achtung:</b><br />
 196 Mit Version&nbsp;2.5 der Template-Klasse hat sich der komplette Vorgang des Parsens ver&auml;ndert. Falls Sie merken, dass sich dadurch das Ergebnis des endg&uuml;tigen Textes von dem, was Sie gewohnt sind, unterscheidet, k&ouml;nnen Sie wieder auf den alten Parsing-Vorgang umschalten. F&uuml;gen Sie dazu irgendwo <b>vor</b> dem Aufruf von <code>parse()</code> folgende Zeile ein:</p>
 197
 198 <pre class="code">
 199 # PHP:
 200
 201 $tpl-&gt;old_parsing = 1;
 202
 203 # Perl:
 204
 205 $tpl-&gt;{'old_parsing'} = 1;
 206
 207 # Python:
 208
 209 tpl.old_parsing = 1
 210 </pre>
 211
 212 <p>Durch diese Anweisung aktivieren Sie den alten Parsing-Mechanismus. Wenn Sie zu dieser Ma&szlig;nahme greifen m&uuml;ssen (was ich nat&uuml;rlich nicht hoffe), w&uuml;rde ich mich freuen, wenn Sie mir eine kurze Mail schicken, damit wir uns dieses Problem evtl. gemeinsam mal ansehen k&ouml;nnen.</p>
 213
 214 <p class="upanddown"><a href="#top">Nach oben</a></p>
 215
 216 <h2><a name="parsen" id="parsen">Zustand sichern und wiederherstellen</a></h2>
 217
 218 <p>Falls Sie den Template-Text wieder in den Zustand zur&uuml;ckversetzen m&ouml;chten, den er direkt nach dem Einlesen der Template-Datei hatte, m&uuml;ssen Sie diese nicht wieder neu einlesen. Sie k&ouml;nnen ganz einfach die Methode <code>reset()</code> verwenden:</p>
 219
 220 <pre class="code">
 221 # PHP / Perl:
 222
 223 $tpl-&gt;reset()
 224
 225 # Python:
 226
 227 tpl.reset()
 228 </pre>
 229
 230 <p>Umgekehrt k&ouml;nnen Sie den aktuellen Status des Template-Textes auch sichern, um sp&auml;ter diesen Status wiederherstellen zu k&ouml;nnen. Dies geschieht mit der Methode <code>save_state()</code>:</p>
 231
 232 <pre class="code">
 233 # PHP / Perl:
 234
 235 $tpl-&gt;save_state()
 236
 237 # Python:
 238
 239 tpl.save_state()
 240 </pre>
 241
 242 <p>Dadurch k&ouml;nnen Sie diesen Status mit <code>reset()</code> wiederherstellen. Es ist dadurch allerdings nicht mehr m&ouml;glich den Zustand, den der Template-Text direkt nach dem Einlesen hatte, wiederherzustellen.</p>
 243
 244 <hr width="80%" noshade="noshade" />
 245
 246 <p><a href="index.htm">Zur &Uuml;bersicht</a></p>
 247
 248 <hr width="80%" noshade="noshade" />
 249
 250 <p style="font-size:8pt">&copy;&nbsp;2002-2011 Patrick Canterino</p>
 251
 252 <table border="0" cellspacing="0" style="font-size:8pt">
 253 <tr>
 254 <td>Homepage:</td>
 255 <td><a href="http://www.patshaping.de/">http://www.patshaping.de/</a></td>
 256 </tr>
 257 <tr>
 258 <td><a name="bottom" id="bottom">E-Mail:</a></td>
 259 <td><a href="mailto:patrick@patshaping.de">patrick@patshaping.de</a></td>
 260 </tr>
 261 </table>
 262 </body>
 263 </html>