/
templates.gtw
364 lines (231 loc) · 13.2 KB
/
templates.gtw
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
~~LANG:FR@frman:templates~~
Jelix includes its own template engine: jTpl. Templates are files with the ".tpl" extension and located in the @@F@templates@@ directory of modules.
===== The jTpl object =====
The @@C@jTpl@@ object is meant to generate the content specified in a template file, with data input by you, following the instructions in the template.
Some of @@C@jResponse*@@ objects or @@C@jZone@@ instanciate for you a jTpl object. For example the @@P@body@@ property of the @@C@jResponseHtml@@ object is a @@C@jTpl@@ object, as for the @@M@_tpl@@ property of @@C@jZone@@.
In other case, you have to instanciate a @@C@jTpl@@:
<code php>
$tpl = new jTpl();
</code>
Here are the most important methods to know.
=== assign ===
<code php>
$tpl->assign($name, $value);
</code>
This method allows you to create a template variable. A template variable is only accessible in the template level. You will then use this method to pass data (static values, objects, iterators, etc) to the template to be able to use it for content generation.
You can also create or modify a variable directly in the template, using:
<code html>
{assign $name = $value}
</code>
**Important** : the name of a template variable should follow syntaxic rules for a name of a PHP variable. the name should contain only letters, numbers or "_".
=== assignByRef ===
Same purpose of the @@M@assign@@ method, but the value is passed by reference, so you can assigne huge array without duplicating them in memory.
=== assignIfNone ===
Same purpose of the @@M@assign@@ method, but the value is assigned only if the variable doesn't exist.
=== assignZone ===
<code php>
$tpl->assignZone($name, $zoneSelector, $params);
</code>
The @@V@$params@@ parameters is optional. This method is a shortcut for:
<code php>
$tpl->assign($name, jZone::get($zoneSelector, $params));
</code>
=== assignZoneIfNone ===
Same as @@M@assignZone@@, but the content of the zone is assigned only if the variable doesn't exist.
=== get ===
If you want to get the value of a template variable that is already initialized, you can use this method :
<code php>
$value = $tpl->get('foo');
</code>
=== Generating the content ===
After variables are created and initialized, you can call the @@M@fetch@@ method to generate the content of the template, and to retrieve it. You give the selector of the file template as the first parameter.
<code php>
$content = $tpl->fetch('mymodule~mytemplate');
</code>
You call this method only if you have instanciate the jTpl object. In other case, you needn't to call it.
There is an other method you won't never call, since jResponse objects use it : @@M@display@@.
<code php>
$tpl->display('mymodule~mytemplate');
</code>
It generates the content and ouput it directly.
===== Template files =====
A template file is made of HTML, XUL or whatever you want if it corresponds to the type of the response. It contains also some instructions to incorporate values that you will define, instructions to repeat the generation of parts of HTML, XUL, etc.
The syntax used in jTpl is in the middle of the one used in smarty and the one of PHP. The goal is to have templates readable enough, easy to modify and not forcing a syntax that is too different from PHP. All this proposing features that PHP doesn't have and adapted to Jelix.
Do not forget that most of the templates that you will make shouldn't be entire files. Especially for the HTML responses, your templates must contain only what is between the @@E@<body>@@ and @@E@</body>@@ tags, the rest is automatically generated thanks to @@C@jResponseHtml@@.
==== Instruction syntax ====
Instructions in jTpl are specified between curly braces : @@{instruction ...}@@
If you want to include curly braces in your template, outside of a jTpl instruction, you can use @@{ldelim}@@ for "{", or @@{rdelim}@@ for "}".
If you have a block with several curly braces, like in a piece of code of javascript, you can use @@{literal}@@ instead of @@{ldelim}@@ or @@{rdelim}@@.
<code html>
<script type="text/javascript">
{literal}
for(i=0;i<max;i++) {
if(foo){ ...}
}
{/literal}
</script>
</code>
If you want to put comments which won't be include in the resulting content, use @@{*...*}@@
<code html>
<p>bla bla</p>
{* this is a comment *}
</code>
You can write an instruction on several lines:
<code html>
<div>
{zone
'foo~bar',
array(
'foo1'=>$foo1,
'foo2'=>$foo2)}
</div>
</code>
==== Expressions ====
A jtpl expression is identical to a PHP expression, and return a value, like in PHP. You can use classical PHP operators, objects, array etc. You can use also template variables, like any PHP variables. You use jtpl expressions as arguments of jtpl instructions. Here is a simple expression:
<code php>
$template_variable
</code>
An expression can also contain some selector of locales, by using a specific syntax. This selectors should be introduced between two "@".
<code html>
@my_module~key.localized.string@."fooo bar"
</code>
It is equal to this PHP code :
<code php>
jLocale("my_module~key.localized.string")."fooo bar"
</code>
Inside a locale key, you can use some template variables. It allows to construct dynamically a locale key:
<code php>
@my_module~key.$variable.string@."fooo bar"
</code>
It is equal to this PHP code :
<code php>
jLocale("my_module~key.".$variable.".string")."fooo bar"
</code>
==== Displaying an expression, a variable ====
To display the result of an expression, you should put it between curly braces. The first element of the expression should be a variable or a locale selector.
<code>
{$myvariable}
{$myvariable * 3}
{$myvariable." - ".@mod~message.ok@}
{@modul~a.key.of.locale@."-".$anOtherVariable}
{@modul~a.key.$dynamique@."-".$anOtherVariable}
</code>
This is equal to
<code php>
<?php echo $myvariable; ?>
<?php echo $myvariable * 3; ?>
<?php echo $myvariable." - ".jLocale::get("mod~message.ok"); ?>
<?php echo jLocale::get("modul~a.key.of.locale")."-".$anOtherVariable; ?>
<?php echo jLocale::get("modul~a.key.".$dynamique)."-".$anOtherVariable; ?>
</code>
Since Jelix 1.1, for more complex expressions , you can use the syntax with @@=@@:
<code>
{=$myvariable}
{=intval($myvariable)*3}
</code>
==== Predefined constant ====
Some variables are predefined so you have not to assign them:
* @@V@$j_basepath@@ : it contains the url path of the directory of the application (this is the value of the parameter "basePath" in the configuration)
* @@V@$j_jelixwww@@ : it contains the url path of the directory @@F@jelix-www/@@ (this is the value of the parameter "jelixWWWPath" in the configuration)
* @@V@$j_themepath@@ : it contains the url path of the directory of the current theme in www
* @@V@$j_datenow@@ : current date (aaaa-mm-jj)
* @@V@$j_timenow@@ : current hour (hh:mm:ss)
==== Modifiers ====
A modifier is a function which modify the output of an expression. You can use many modifiers at the same time. It works in fact like modifiers of Smarty:
<code>
{$avariable|upper}
{$avariable|upper|escxml}
{$aUrl|escurl}
</code>
It is equal to:
<code>
<?php echo strtoupper($avariable);?>
<?php echo htmlspecialchars(strtoupper($avariable));?>
<?php echo rawurlencode($aUrl);?>
</code>
Some modifiers, like those in the previous example, are simple aliases to some native PHP functions:
* upper (strtoupper)
* lower (strtolower)
* escxml (htmlspecialchars)
* strip_tags (strip_tags)
* escurl (rawurlencode)
* capitalize (ucwords)
Many others are function defined in plugins for jTpl. See the list in the [[refapi:/|API reference]]
=== Modifiers with parameters ===
Some modifiers need some parameters. You should put this parameters after a ":" after the modifier name, and you should separate parameters with ",". Parameters are expressions.
Example with the jdatetime modifier:
<code smarty>
<p>The date is {$myDate|jdatetime:'db_date','timestamp'}.</p>
</code>
==== Control statements ====
They are similar to statements of PHP, except that parenthesis are not required around conditions or expressions.
=== if, else, elseif ===
{if condition_1}
// code here
{elseif condition_2}
// code here
{else}
// code here
{/if}
Note that some plugins are provided and are specific conditional statements, like @@ifacl2 'a.right'@@. You can use the @@else@@ statement for all of them begining by "if".
=== while ===
{while condition}
// code here
{/while}
=== foreach ===
{foreach $iterator_or_array as $key=>$value}
// code here
{/foreach}
=== for ===
{for expression}
// code here
{/for}
The expression should be identical as the expression of the @@for@@ in PHP.
==== functions ====
Functions in a template are plugins you can use in a template. This plugins are simple PHP functions and you can create some kind of plugins.
The syntaxe of the call in a template is:
{function_name expression, expression,...}
You mustn't use parentheses around all parameters. Expressions are jtpl expressions, so similar to PHP expressions.
Note that some functions and other template plugins are callable in general only in a template used by a specific type of response. Some plugins are for HTML responses, some other plugins are for text responses.
==== personnalized functions and modifiers ====
If you want to have some new jtpl functions or modifiers, you can realized some plugins. [[plugins/tpl|See the documentation about it]]. This is simple.
An other solution is to declare the modifiers or the functions dynamically, by calling the jtpl methods @@M@registerModifier()@@ or @@M@registerFunction()@@. To this methods, you should indicate a name which will used in the template, and a name of a php function which implements the modifier or the function. The arguments of the php function are the same of the php function of a jtpl plugin.
==== meta informations ====
There is a special tag: @@{meta}@@. It doesn't change how the template is generated, it doesn't generate some content, and more important, it cannot be influenced by any other template instructions. Putting it inside an "if" statement for example, does nothing. The meta tag will be interpreted, even if the if statement is false. The meta tag exists only to provide informations for the code which uses the jtpl object.
The syntax is
<code html>
{meta name expression}
</code>
Example:
{meta author 'laurent'}
You can create all meta you want. Then this informations are available in the @@C@jTpl@@ object, by using the @@M@meta@@ method.
<code php>
$tpl = new jTpl();
$metas = $tpl->meta('mymodule~thetemplate');
$metas['author']; // contains 'laurent'
</code>
Note: if you use a variable in the expression of a meta tag, this variable should be assigned from the jtpl object, not from other instruction in the template itself (like @@{assign ...}@@).
==== Advanced meta informations ====
Another type of meta tag allows you to automatically process meta data. Those are implemented through template plugins.
Their syntax is:
<code html>
{meta_//plugin_name// name expression}
</code>
Example which uses the meta_html plugin. This plugin allows to modify the current html response: it can add a css stylesheet, a javascript link etc.
<code html>
{meta_html css '/styles/my.css'}
{meta_html js 'fooscript.js'}
{meta_html bodyattr array('onload'=>'alert("charge")')}
</code>
===== templates dedicated to a locale =====
In a template, we saw that we can use {@foo.bar@} to include localized string. However, you can have many localized string, and so the template is less readable, and performance are lower.
There is a solution: create templates for each language. Of course, it means that you duplicate the code of the template, and so it is less easy to maintain them. So you should think if you prefer performance or easy modifications...
To create a template for each language, create sub-directories into the template directory. Their name should be the code of a lang. Example: @@F@templates/fr_FR@@, @@F@templates/en_EN@@ etc. And save in each of this sub-directories a copy of your translated template.
===== Redefining a template =====
Each module defines some template. If the module comes from an other project, or is shared by other application, you shouldn't modify the template, because each time you want to update this module, you should take car to not erase your modifications.
Fortunately, Jelix provide a system of theme, so you can redefine template without modify the original files.
The default theme is in the directory @@F@var/themes/default/@@. So the @@F@var/themes/default/my_module/my_template.tpl@@ redefines the template @@F@my_module/templates/my_template.tpl@@
For more details, see the [[themes|chapter on themes]]
===== Inside the template engine =====
Jtpl templates are "compiled". Jtpl convert template to PHP files, and this php file are stored in the cache to increase performances. You can see them in @@F@temp/your_appname/compiled/templates/modules/your_module~your_template.php@@, or for templates included in themes, look in @@F@temp/your_appname/compiled/templates/themes/theme_name/your_module~your_template.php@@
You can create your own plugin template, if you have particular needs or want to use your own tag(s) in a template. See [[plugins/tpl]]