aboutsummaryrefslogtreecommitdiffstats
path: root/library/Smarty/README
blob: 6367f030e2cb6534d012c80ce1793e4a9616e036 (plain) (blame)
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
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
Smarty 3.1.21

Author: Monte Ohrt <monte at ohrt dot com >
Author: Uwe Tews

AN INTRODUCTION TO SMARTY 3

NOTICE FOR 3.1 release:

Please see the SMARTY_3.1_NOTES.txt file that comes with the distribution.

NOTICE for 3.0.5 release:

Smarty now follows the PHP error_reporting level by default. If PHP does not mask E_NOTICE and you try to access an unset template variable, you will now get an E_NOTICE warning. To revert to the old behavior:

$smarty->error_reporting = E_ALL & ~E_NOTICE;

NOTICE for 3.0 release:

IMPORTANT: Some API adjustments have been made between the RC4 and 3.0 release.
We felt it is better to make these now instead of after a 3.0 release, then have to
immediately deprecate APIs in 3.1. Online documentation has been updated
to reflect these changes. Specifically:

---- API CHANGES RC4 -> 3.0 ----

$smarty->register->*
$smarty->unregister->*
$smarty->utility->*
$samrty->cache->*

Have all been changed to local method calls such as:

$smarty->clearAllCache()
$smarty->registerFoo()
$smarty->unregisterFoo()
$smarty->testInstall()
etc.

Registration of function, block, compiler, and modifier plugins have been
consolidated under two API calls:

$smarty->registerPlugin(...)
$smarty->unregisterPlugin(...)

Registration of pre, post, output and variable filters have been
consolidated under two API calls:

$smarty->registerFilter(...)
$smarty->unregisterFilter(...)

Please refer to the online documentation for all specific changes:

http://www.smarty.net/documentation

----

The Smarty 3 API has been refactored to a syntax geared
for consistency and modularity. The Smarty 2 API syntax is still supported, but
will throw a deprecation notice. You can disable the notices, but it is highly
recommended to adjust your syntax to Smarty 3, as the Smarty 2 syntax must run
through an extra rerouting wrapper.

Basically, all Smarty methods now follow the "fooBarBaz" camel case syntax. Also,
all Smarty properties now have getters and setters. So for example, the property
$smarty->cache_dir can be set with $smarty->setCacheDir('foo/') and can be
retrieved with $smarty->getCacheDir().

Some of the Smarty 3 APIs have been revoked such as the "is*" methods that were
just duplicate functions of the now available "get*" methods.

Here is a rundown of the Smarty 3 API:

$smarty->fetch($template, $cache_id = null, $compile_id = null, $parent = null)
$smarty->display($template, $cache_id = null, $compile_id = null, $parent = null)
$smarty->isCached($template, $cache_id = null, $compile_id = null)
$smarty->createData($parent = null)
$smarty->createTemplate($template, $cache_id = null, $compile_id = null, $parent = null)
$smarty->enableSecurity()
$smarty->disableSecurity()
$smarty->setTemplateDir($template_dir)
$smarty->addTemplateDir($template_dir)
$smarty->templateExists($resource_name)
$smarty->loadPlugin($plugin_name, $check = true)
$smarty->loadFilter($type, $name)
$smarty->setExceptionHandler($handler)
$smarty->addPluginsDir($plugins_dir)
$smarty->getGlobal($varname = null)
$smarty->getRegisteredObject($name)
$smarty->getDebugTemplate()
$smarty->setDebugTemplate($tpl_name)
$smarty->assign($tpl_var, $value = null, $nocache = false)
$smarty->assignGlobal($varname, $value = null, $nocache = false)
$smarty->assignByRef($tpl_var, &$value, $nocache = false)
$smarty->append($tpl_var, $value = null, $merge = false, $nocache = false)
$smarty->appendByRef($tpl_var, &$value, $merge = false)
$smarty->clearAssign($tpl_var)
$smarty->clearAllAssign()
$smarty->configLoad($config_file, $sections = null)
$smarty->getVariable($variable, $_ptr = null, $search_parents = true, $error_enable = true)
$smarty->getConfigVariable($variable)
$smarty->getStreamVariable($variable)
$smarty->getConfigVars($varname = null)
$smarty->clearConfig($varname = null)
$smarty->getTemplateVars($varname = null, $_ptr = null, $search_parents = true)
$smarty->clearAllCache($exp_time = null, $type = null)
$smarty->clearCache($template_name, $cache_id = null, $compile_id = null, $exp_time = null, $type = null)

$smarty->registerPlugin($type, $tag, $callback, $cacheable = true, $cache_attr = array())

$smarty->registerObject($object_name, $object_impl, $allowed = array(), $smarty_args = true, $block_methods = array())

$smarty->registerFilter($type, $function_name)
$smarty->registerResource($resource_type, $function_names)
$smarty->registerDefaultPluginHandler($function_name)
$smarty->registerDefaultTemplateHandler($function_name)

$smarty->unregisterPlugin($type, $tag)
$smarty->unregisterObject($object_name)
$smarty->unregisterFilter($type, $function_name)
$smarty->unregisterResource($resource_type)

$smarty->compileAllTemplates($extension = '.tpl', $force_compile = false, $time_limit = 0, $max_errors = null)
$smarty->clearCompiledTemplate($resource_name = null, $compile_id = null, $exp_time = null)
$smarty->testInstall()

// then all the getters/setters, available for all properties. Here are a few:

$caching = $smarty->getCaching();      // get $smarty->caching
$smarty->setCaching(true);             // set $smarty->caching
$smarty->setDeprecationNotices(false); // set $smarty->deprecation_notices
$smarty->setCacheId($id);              // set $smarty->cache_id
$debugging = $smarty->getDebugging();  // get $smarty->debugging


FILE STRUCTURE

The Smarty 3 file structure is similar to Smarty 2:

/libs/
  Smarty.class.php
/libs/sysplugins/
  internal.*
/libs/plugins/
  function.mailto.php
  modifier.escape.php
  ...

A lot of Smarty 3 core functionality lies in the sysplugins directory; you do
not need to change any files here. The /libs/plugins/ folder is where Smarty
plugins are located. You can add your own here, or create a separate plugin
directory, just the same as Smarty 2. You will still need to create your own
/cache/, /templates/, /templates_c/, /configs/ folders. Be sure /cache/ and
/templates_c/ are writable.

The typical way to use Smarty 3 should also look familiar:

require('Smarty.class.php');
$smarty = new Smarty;
$smarty->assign('foo','bar');
$smarty->display('index.tpl');


However, Smarty 3 works completely different on the inside. Smarty 3 is mostly
backward compatible with Smarty 2, except for the following items:

*) Smarty 3 is PHP 5 only. It will not work with PHP 4.
*) The {php} tag is disabled by default. Enable with $smarty->allow_php_tag=true.
*) Delimiters surrounded by whitespace are no longer treated as Smarty tags.
   Therefore, { foo } will not compile as a tag, you must use {foo}. This change
   Makes Javascript/CSS easier to work with, eliminating the need for {literal}.
   This can be disabled by setting $smarty->auto_literal = false;
*) The Smarty 3 API is a bit different. Many Smarty 2 API calls are deprecated
   but still work. You will want to update your calls to Smarty 3 for maximum
   efficiency.


There are many things that are new to Smarty 3. Here are the notable items:
   
LEXER/PARSER
============

Smarty 3 now uses a lexing tokenizer for its parser/compiler. Basically, this
means Smarty has some syntax additions that make life easier such as in-template
math, shorter/intuitive function parameter options, infinite function recursion,
more accurate error handling, etc.


WHAT IS NEW IN SMARTY TEMPLATE SYNTAX
=====================================

Smarty 3 allows expressions almost anywhere. Expressions can include PHP
functions as long as they are not disabled by the security policy, object
methods and properties, etc. The {math} plugin is no longer necessary but
is still supported for BC.

Examples:
{$x+$y}                           will output the sum of x and y.
{$foo = strlen($bar)}             function in assignment
{assign var=foo value= $x+$y}     in attributes 
{$foo = myfunct( ($x+$y)*3 )}     as function parameter 
{$foo[$x+3]}                      as array index

Smarty tags can be used as values within other tags.
Example:  {$foo={counter}+3}

Smarty tags can also be used inside double quoted strings.
Example:  {$foo="this is message {counter}"}

You can define arrays within templates.
Examples:
{assign var=foo value=[1,2,3]}
{assign var=foo value=['y'=>'yellow','b'=>'blue']}
Arrays can be nested.
{assign var=foo value=[1,[9,8],3]}

There is a new short syntax supported for assigning variables.
Example: {$foo=$bar+2}

You can assign a value to a specific array element. If the variable exists but
is not an array, it is converted to an array before the new values are assigned.
Examples:
{$foo['bar']=1}
{$foo['bar']['blar']=1}

You can append values to an array. If the variable exists but is not an array,
it is converted to an array before the new values are assigned.
Example: {$foo[]=1}

You can use a PHP-like syntax for accessing array elements, as well as the
original "dot" notation.
Examples:
{$foo[1]}             normal access
{$foo['bar']}
{$foo['bar'][1]}
{$foo[$x+$x]}         index may contain any expression
{$foo[$bar[1]]}       nested index
{$foo[section_name]}  smarty section access, not array access!

The original "dot" notation stays, and with improvements.
Examples:
{$foo.a.b.c}        =>  $foo['a']['b']['c'] 
{$foo.a.$b.c}       =>  $foo['a'][$b]['c']        with variable index
{$foo.a.{$b+4}.c}   =>  $foo['a'][$b+4]['c']       with expression as index
{$foo.a.{$b.c}}     =>  $foo['a'][$b['c']]         with nested index

note that { and } are used to address ambiguties when nesting the dot syntax. 

Variable names themselves can be variable and contain expressions.
Examples:
$foo         normal variable
$foo_{$bar}  variable name containing other variable 
$foo_{$x+$y} variable name containing expressions 
$foo_{$bar}_buh_{$blar}  variable name with multiple segments
{$foo_{$x}}  will output the variable $foo_1 if $x has a value of 1.

Object method chaining is implemented.
Example: {$object->method1($x)->method2($y)}

{for} tag added for looping (replacement for {section} tag):
{for $x=0, $y=count($foo); $x<$y; $x++}  ....  {/for}
Any number of statements can be used separated by comma as the first
inital expression at {for}.

{for $x = $start to $end step $step} ... {/for}is in the SVN now .
You can use also
{for $x = $start to $end} ... {/for}
In this case the step value will be automaticall 1 or -1 depending on the start and end values.
Instead of $start and $end you can use any valid expression.
Inside the loop the following special vars can be accessed:
$x@iteration = number of iteration
$x@total = total number of iterations
$x@first = true on first iteration
$x@last = true on last iteration


The Smarty 2 {section} syntax is still supported.

New shorter {foreach} syntax to loop over an array.
Example: {foreach $myarray as $var}...{/foreach}

Within the foreach loop, properties are access via:

$var@key            foreach $var array key
$var@iteration      foreach current iteration count (1,2,3...)
$var@index          foreach current index count (0,1,2...)
$var@total          foreach $var array total
$var@first          true on first iteration
$var@last           true on last iteration

The Smarty 2 {foreach} tag syntax is still supported.

NOTE: {$bar[foo]} still indicates a variable inside of a {section} named foo. 
If you want to access an array element with index foo, you must use quotes
such as {$bar['foo']}, or use the dot syntax {$bar.foo}.

while block tag is now implemented:
{while $foo}...{/while}
{while $x lt 10}...{/while}

Direct access to PHP functions:
Just as you can use PHP functions as modifiers directly, you can now access
PHP functions directly, provided they are permitted by security settings:
{time()}

There is a new {function}...{/function} block tag to implement a template function.
This enables reuse of code sequences like a plugin function. It can call itself recursively.
Template function must be called with the new {call name=foo...} tag.

Example:

Template file:
{function name=menu level=0}
  <ul class="level{$level}">
  {foreach $data as $entry}
    {if is_array($entry)}
      <li>{$entry@key}</li>
       {call name=menu data=$entry level=$level+1}
    {else}
      <li>{$entry}</li>
    {/if}
  {/foreach}
  </ul>
{/function}

{$menu = ['item1','item2','item3' => ['item3-1','item3-2','item3-3' =>
  ['item3-3-1','item3-3-2']],'item4']}

{call name=menu data=$menu}


Generated output:
    * item1
    * item2
    * item3
          o item3-1
          o item3-2
          o item3-3
                + item3-3-1
                + item3-3-2
    * item4

The function tag itself must have the "name" attribute. This name is the tag
name when calling the function. The function tag may have any number of
additional attributes. These will be default settings for local variables.

New {nocache} block function:
{nocache}...{/nocache} will declare a section of the template to be non-cached
when template caching is enabled.

New nocache attribute:
You can declare variable/function output as non-cached with the nocache attribute.
Examples:

{$foo nocache=true}
{$foo nocache} /* same */

{foo bar="baz" nocache=true}
{foo bar="baz" nocache} /* same */

{time() nocache=true}
{time() nocache} /* same */

Or you can also assign the variable in your script as nocache:
$smarty->assign('foo',$something,true); // third param is nocache setting
{$foo} /* non-cached */

$smarty.current_dir returns the directory name of the current template.

You can use strings directly as templates with the "string" resource type.
Examples:
$smarty->display('string:This is my template, {$foo}!'); // php
{include file="string:This is my template, {$foo}!"} // template



VARIABLE SCOPE / VARIABLE STORAGE
=================================

In Smarty 2, all assigned variables were stored within the Smarty object. 
Therefore, all variables assigned in PHP were accessible by all subsequent 
fetch and display template calls.

In Smarty 3, we have the choice to assign variables to the main Smarty object, 
to user-created data objects, and to user-created template objects. 
These objects can be chained. The object at the end of a chain can access all
variables belonging to that template and all variables within the parent objects.
The Smarty object can only be the root of a chain, but a chain can be isolated
from the Smarty object.

All known Smarty assignment interfaces will work on the data and template objects.

Besides the above mentioned objects, there is also a special storage area for
global variables.

A Smarty data object can be created as follows:
$data = $smarty->createData();    // create root data object
$data->assign('foo','bar');       // assign variables as usual
$data->config_load('my.conf');									 // load config file    

$data= $smarty->createData($smarty);  // create data object having a parent link to
the Smarty object

$data2= $smarty->createData($data);   // create data object having a parent link to
the $data data object

A template object can be created by using the createTemplate method. It has the
same parameter assignments as the fetch() or display() method.
Function definition:
function createTemplate($template, $cache_id = null, $compile_id = null, $parent = null)

The first parameter can be a template name, a smarty object or a data object.

Examples:
$tpl = $smarty->createTemplate('mytpl.tpl'); // create template object not linked to any parent
$tpl->assign('foo','bar');                   // directly assign variables
$tpl->config_load('my.conf');									 // load config file    

$tpl = $smarty->createTemplate('mytpl.tpl',$smarty);  // create template having a parent link to the Smarty object
$tpl = $smarty->createTemplate('mytpl.tpl',$data);    // create template having a parent link to the $data object

The standard fetch() and display() methods will implicitly create a template object.
If the $parent parameter is not specified in these method calls, the template object
is will link back to the Smarty object as it's parent.

If a template is called by an {include...} tag from another template, the
subtemplate links back to the calling template as it's parent. 

All variables assigned locally or from a parent template are accessible. If the
template creates or modifies a variable by using the {assign var=foo...} or
{$foo=...} tags, these new values are only known locally (local scope). When the
template exits, none of the new variables or modifications can be seen in the
parent template(s). This is same behavior as in Smarty 2. 

With Smarty 3, we can assign variables with a scope attribute which allows the
availablility of these new variables or modifications globally (ie in the parent
templates.)

Possible scopes are local, parent, root and global. 
Examples:
{assign var=foo value='bar'}       // no scope is specified, the default 'local'
{$foo='bar'}                       // same, local scope
{assign var=foo value='bar' scope='local'} // same, local scope

{assign var=foo value='bar' scope='parent'} // Values will be available to the parent object 
{$foo='bar' scope='parent'}                 // (normally the calling template)

{assign var=foo value='bar' scope='root'}   // Values will be exported up to the root object, so they can 
{$foo='bar' scope='root'}                   // be seen from all templates using the same root.

{assign var=foo value='bar' scope='global'} // Values will be exported to global variable storage, 
{$foo='bar' scope='global'}                 // they are available to any and all templates.


The scope attribute can also be attached to the {include...} tag. In this case,
the specified scope will be the default scope for all assignments within the
included template.


PLUGINS
=======

Smarty3 are following the same coding rules as in Smarty2. 
The only difference is that the template object is passed as additional third parameter.

smarty_plugintype_name (array $params, object $smarty, object $template)

The Smarty 2 plugins are still compatible as long as they do not make use of specific Smarty2 internals.


TEMPLATE INHERITANCE:
=====================

With template inheritance you can define blocks, which are areas that can be
overriden by child templates, so your templates could look like this: 

parent.tpl:
<html>
  <head>
    <title>{block name='title'}My site name{/block}</title>
  </head>
  <body>
    <h1>{block name='page-title'}Default page title{/block}</h1>
    <div id="content">
      {block name='content'}
        Default content
      {/block}
    </div>
  </body>
</html>

child.tpl:
{extends file='parent.tpl'} 
{block name='title'}
Child title
{/block}

grandchild.tpl:
{extends file='child.tpl'} 
{block name='title'}Home - {$smarty.block.parent}{/block} 
{block name='page-title'}My home{/block}
{block name='content'}
  {foreach $images as $img}
    <img src="{$img.url}" alt="{$img.description}" />
  {/foreach}
{/block}

We redefined all the blocks here, however in the title block we used {$smarty.block.parent},
which tells Smarty to insert the default content from the parent template in its place.
The content block was overriden to display the image files, and page-title has also be 
overriden to display a completely different title. 

If we render grandchild.tpl we will get this: 
<html>
  <head>
    <title>Home - Child title</title>
  </head>
  <body>
    <h1>My home</h1>
    <div id="content">
      <img src="/example.jpg" alt="image" />
      <img src="/example2.jpg" alt="image" />
      <img src="/example3.jpg" alt="image" />
    </div>
  </body>
</html>

NOTE: In the child templates everything outside the {extends} or {block} tag sections
is ignored.

The inheritance tree can be as big as you want (meaning you can extend a file that 
extends another one that extends another one and so on..), but be aware that all files 
have to be checked for modifications at runtime so the more inheritance the more overhead you add.

Instead of defining the parent/child relationships with the {extends} tag in the child template you
can use the resource as follow:

$smarty->display('extends:parent.tpl|child.tpl|grandchild.tpl');

Child {block} tags may optionally have a append or prepend attribute. In this case the parent block content 
is appended or prepended to the child block content.

{block name='title' append} My title {/block}


PHP STREAMS:
============

(see online documentation)

VARIBLE FILTERS:
================

(see online documentation)


STATIC CLASS ACCESS AND NAMESPACE SUPPORT
=========================================

You can register a class with optional namespace for the use in the template like:

$smarty->register->templateClass('foo','name\name2\myclass');

In the template you can use it like this:
{foo::method()}  etc.


=======================

Please look through it and send any questions/suggestions/etc to the forums.

http://www.phpinsider.com/smarty-forum/viewtopic.php?t=14168

Monte and Uwe