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
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Strict//EN">
<html>
<head>
<title>Template::Manual::Config</title>
<link rel="stylesheet" type="text/css" href="../css/blue.css" title="Clear Blue">
<link rel="alternate stylesheet" type="text/css" href="../css/orange.css" title="Clear Orange">
<link rel="alternate stylesheet" type="text/css" href="../css/green.css" title="Clear Green">
<link rel="alternate stylesheet" type="text/css" href="../css/purple.css" title="Clear Purple">
<link rel="alternate stylesheet" type="text/css" href="../css/grey.css" title="Clear Grey">
<!--[if IE 6]>
<link rel="stylesheet" type="text/css" href="../css/ie6.css" />
<![endif]-->
<link rel="stylesheet" type="text/css" href="/css/print.css" media="print">
<script type="text/javascript" src="../js/tt2.js"></script>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<meta name="author" content="Andy Wardley">
</head>
<body id="body">
<div id="layout">
<div id="header">
<a href="../index.html" id="logo" alt="" title="Click for the Home Page"><span class="alt">TT2 Home Page</span></a>
<ul id="trail">
<li><a href="../manual/index.html">Manual</a></li>
<li class="last"><a href="../manual/Config.html">Config</a></li>
</ul>
<div class="controls">
<a href="#" class="menu show" onclick="widescreen_off(); return false" title="Show Menu">
<span class="about">Click to view the menu. It's very nice.</span>
</a>
<a href="#" class="menu hide" onclick="widescreen_on(); return false" title="Hide Menu">
<span class="about">Click to hide the menu and go all widescreen!</span>
</a>
<div class="pager">
<a href="../manual/VMethods.html" title="Template::Manual::VMethods" class="go back">Back<span class="about"><h4>Template::Manual::VMethods</h4>Virtual Methods</span></a>
<a href="../manual/index.html" title="Template::Manual" class="go up">Up<span class="about"><h4>Template::Manual</h4>Template Toolkit User Manual</span></a>
<a href="../manual/Filters.html" title="Template::Manual::Filters" class="go next">Next<span class="about"><h4>Template::Manual::Filters</h4>Standard filters</span></a>
</div>
</div>
<h1 class="headline">Template::Manual::Config</h1>
<h2 class="subhead">Configuration options</h1>
</div>
<div id="page">
<div id="sidebar">
<a href="../index.html" id="logo"></a>
<div id="menu">
<ul class="menu">
<li class="l0 first"><a href="../manual/index.html" class="warm">Manual</a></li>
<li class="l1"><a href="../manual/Intro.html">Intro</a></li>
<li class="l1"><a href="../manual/Syntax.html">Syntax</a></li>
<li class="l1"><a href="../manual/Directives.html">Directives</a></li>
<li class="l1"><a href="../manual/Variables.html">Variables</a></li>
<li class="l1"><a href="../manual/VMethods.html">VMethods</a></li>
<li class="l1"><a href="../manual/Config.html" class="warm">Config</a></li>
<li class="l1"><a href="../manual/Filters.html">Filters</a></li>
<li class="l1"><a href="../manual/Plugins.html">Plugins</a></li>
<li class="l1"><a href="../manual/Internals.html">Internals</a></li>
<li class="l1"><a href="../manual/Views.html">Views</a></li>
<li class="l1"><a href="../manual/Credits.html">Credits</a></li>
<li class="l0"><a href="../modules/index.html">Modules</a></li>
<li class="l0"><a href="../tools/index.html">Tools</a></li>
<li class="l0 last"><a href="../tutorial/index.html">Tutorial</a></li>
</ul>
<div class="foot"></div>
</div>
</div>
<div id="content">
<div class="section">
<div class="head">
<h1 id="contents" onclick="switch_section(this)" title="Click title to show/hide section content.">Contents</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<ul class="toc">
<li class=""><a href="#Template_Style_and_Parsing_Options">Template Style and Parsing Options</a></li>
<li class="sub"><a href="#section_START_TAG_END_TAG">START_TAG, END_TAG</a></li>
<li class="sub"><a href="#section_TAG_STYLE">TAG_STYLE</a></li>
<li class="sub"><a href="#section_PRE_CHOMP_POST_CHOMP">PRE_CHOMP, POST_CHOMP</a></li>
<li class="sub"><a href="#section_TRIM">TRIM</a></li>
<li class="sub"><a href="#section_INTERPOLATE">INTERPOLATE</a></li>
<li class="sub"><a href="#section_ANYCASE">ANYCASE</a></li>
<li class=""><a href="#Template_Files_and_Blocks">Template Files and Blocks</a></li>
<li class="sub"><a href="#section_INCLUDE_PATH">INCLUDE_PATH</a></li>
<li class="sub"><a href="#section_DELIMITER">DELIMITER</a></li>
<li class="sub"><a href="#section_ABSOLUTE">ABSOLUTE</a></li>
<li class="sub"><a href="#section_RELATIVE">RELATIVE</a></li>
<li class="sub"><a href="#section_DEFAULT">DEFAULT</a></li>
<li class="sub"><a href="#section_BLOCKS">BLOCKS</a></li>
<li class="sub"><a href="#section_AUTO_RESET">AUTO_RESET</a></li>
<li class="sub"><a href="#section_RECURSION">RECURSION</a></li>
<li class=""><a href="#Template_Variables">Template Variables</a></li>
<li class="sub"><a href="#section_VARIABLES">VARIABLES</a></li>
<li class="sub"><a href="#section_CONSTANTS">CONSTANTS</a></li>
<li class="sub"><a href="#section_CONSTANT_NAMESPACE">CONSTANT_NAMESPACE</a></li>
<li class="sub"><a href="#section_NAMESPACE">NAMESPACE</a></li>
<li class=""><a href="#Template_Processing_Options">Template Processing Options</a></li>
<li class="sub"><a href="#section_PRE_PROCESS_POST_PROCESS">PRE_PROCESS, POST_PROCESS</a></li>
<li class="sub"><a href="#section_PROCESS">PROCESS</a></li>
<li class="sub"><a href="#section_WRAPPER">WRAPPER</a></li>
<li class="sub"><a href="#section_ERROR">ERROR</a></li>
<li class=""><a href="#Template_Runtime_Options">Template Runtime Options</a></li>
<li class="sub"><a href="#section_EVAL_PERL">EVAL_PERL</a></li>
<li class="sub"><a href="#section_OUTPUT">OUTPUT</a></li>
<li class="sub"><a href="#section_OUTPUT_PATH">OUTPUT_PATH</a></li>
<li class="sub"><a href="#section_DEBUG">DEBUG</a></li>
<li class="sub"><a href="#section_DEBUG_FORMAT">DEBUG_FORMAT</a></li>
<li class=""><a href="#Caching_and_Compiling_Options">Caching and Compiling Options</a></li>
<li class="sub"><a href="#section_CACHE_SIZE">CACHE_SIZE</a></li>
<li class="sub"><a href="#section_STAT_TTL">STAT_TTL</a></li>
<li class="sub"><a href="#section_COMPILE_EXT">COMPILE_EXT</a></li>
<li class="sub"><a href="#section_COMPILE_DIR">COMPILE_DIR</a></li>
<li class=""><a href="#Plugins_and_Filters">Plugins and Filters</a></li>
<li class="sub"><a href="#section_PLUGINS">PLUGINS</a></li>
<li class="sub"><a href="#section_PLUGIN_BASE">PLUGIN_BASE</a></li>
<li class="sub"><a href="#section_LOAD_PERL">LOAD_PERL</a></li>
<li class="sub"><a href="#section_FILTERS">FILTERS</a></li>
<li class=""><a href="#Customisation_and_Extension">Customisation and Extension</a></li>
<li class="sub"><a href="#section_LOAD_TEMPLATES">LOAD_TEMPLATES</a></li>
<li class="sub"><a href="#section_LOAD_PLUGINS">LOAD_PLUGINS</a></li>
<li class="sub"><a href="#section_LOAD_FILTERS">LOAD_FILTERS</a></li>
<li class="sub"><a href="#section_TOLERANT">TOLERANT</a></li>
<li class="sub"><a href="#section_SERVICE">SERVICE</a></li>
<li class="sub"><a href="#section_CONTEXT">CONTEXT</a></li>
<li class="sub"><a href="#section_STASH">STASH</a></li>
<li class="sub"><a href="#section_PARSER">PARSER</a></li>
<li class="sub"><a href="#section_GRAMMAR">GRAMMAR</a></li>
</ul>
</div>
</div>
<div class="pod">
<div class="section">
<div class="head">
<h1 id="Template_Style_and_Parsing_Options" onclick="switch_section(this)" title="Click title to show/hide section content.">Template Style and Parsing Options</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<div class="subsection">
<div class="head">
<h2 id="section_START_TAG_END_TAG" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">START_TAG, END_TAG</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>START_TAG</code> and <code>END_TAG</code> options are used to
specify character sequences or regular expressions that mark the start
and end of a template directive. The default values for
<code>START_TAG</code> and <code>END_TAG</code> are '<code>[%</code>' and
'<code>%]</code>' respectively, giving us the familiar directive style:
</p>
<pre>[% example %]</pre>
<p>
Any Perl regex characters can be used and therefore should be escaped (or
use the Perl <code>quotemeta</code> function) if they are intended to
represent literal characters.
</p>
<pre>my $template = Template->new({
START_TAG => quotemeta('<+'),
END_TAG => quotemeta('+>'),
});</pre>
<p>
Example:
</p>
<pre><+ INCLUDE foobar +></pre>
<p>
The <code>TAGS</code> directive can also be used to set the
<code>START_TAG</code> and <code>END_TAG</code> values on a per-template
file basis.
</p>
<pre>[% TAGS <+ +> %]</pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_TAG_STYLE" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">TAG_STYLE</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>TAG_STYLE</code> option can be used to set both
<code>START_TAG</code> and <code>END_TAG</code> according to pre-defined
tag styles.
</p>
<pre>my $template = Template->new({
TAG_STYLE => 'star',
});</pre>
<p>
Available styles are:
</p>
<pre>template [% ... %] (default)
template1 [% ... %] or %% ... %% (TT version 1)
metatext %% ... %% (Text::MetaText)
star [* ... *] (TT alternate)
php <? ... ?> (PHP)
asp <% ... %> (ASP)
mason <% ... > (HTML::Mason)
html <!-- ... --> (HTML comments)</pre>
<p>
Any values specified for <code>START_TAG</code> and/or
<code>END_TAG</code> will override those defined by a
<code>TAG_STYLE</code>.
</p>
<p>
The <code>TAGS</code> directive may also be used to set a
<code>TAG_STYLE</code>
</p>
<pre>[% TAGS html %]
<!-- INCLUDE header --></pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_PRE_CHOMP_POST_CHOMP" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">PRE_CHOMP, POST_CHOMP</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Anything outside a directive tag is considered plain text and is
generally passed through unaltered (but see the <a
href="#section_INTERPOLATE">INTERPOLATE</a> option). This includes all
whitespace and newlines characters surrounding directive tags. Directives
that don't generate any output will leave gaps in the output document.
</p>
<p>
Example:
</p>
<pre>Foo
[% a = 10 %]
Bar</pre>
<p>
Output:
</p>
<pre>Foo
Bar</pre>
<p>
The <code>PRE_CHOMP</code> and <code>POST_CHOMP</code> options can help
to clean up some of this extraneous whitespace. Both are disabled by
default.
</p>
<pre>my $template = Template-E<gt>new({
PRE_CHOMP =E<gt> 1,
POST_CHOMP =E<gt> 1,
});</pre>
<p>
With <code>PRE_CHOMP</code> set to <code>1</code>, the newline and
whitespace preceding a directive at the start of a line will be deleted.
This has the effect of concatenating a line that starts with a directive
onto the end of the previous line.
</p>
<pre> Foo <----------.
|
,---(PRE_CHOMP)----'
|
`-- [% a = 10 %] --.
|
,---(POST_CHOMP)---'
|
`-> Bar</pre>
<p>
With <code>POST_CHOMP</code> set to <code>1</code>, any whitespace after
a directive up to and including the newline will be deleted. This has the
effect of joining a line that ends with a directive onto the start of the
next line.
</p>
<p>
If <code>PRE_CHOMP</code> or <code>POST_CHOMP</code> is set to
<code>2</code>, all whitespace including any number of newline will be
removed and replaced with a single space. This is useful for HTML, where
(usually) a contiguous block of whitespace is rendered the same as a
single space.
</p>
<p>
With <code>PRE_CHOMP</code> or <code>POST_CHOMP</code> set to
<code>3</code>, all adjacent whitespace (including newlines) will be
removed entirely.
</p>
<p>
These values are defined as <code>CHOMP_NONE</code>,
<code>CHOMP_ONE</code>, <code>CHOMP_COLLAPSE</code> and
<code>CHOMP_GREEDY</code> constants in the <a href="../modules/Template/Constants.html">Template::Constants</a> module.
<code>CHOMP_ALL</code> is also defined as an alias for
<code>CHOMP_ONE</code> to provide backwards compatability with earlier
version of the Template Toolkit.
</p>
<p>
Additionally the chomp tag modifiers listed below may also be used for
the <code>PRE_CHOMP</code> and <code>POST_CHOMP</code> configuration.
</p>
<pre>my $template = Template->new({
PRE_CHOMP => '~',
POST_CHOMP => '-',
});</pre>
<p>
<code>PRE_CHOMP</code> and <code>POST_CHOMP</code> can be activated for
individual directives by placing a '<code>-</code>' immediately at the
start and/or end of the directive.
</p>
<pre>[% FOREACH user IN userlist %]
[%- user -%]
[% END %]</pre>
<p>
This has the same effect as <code>CHOMP_ONE</code> in removing all
whitespace before or after the directive up to and including the newline.
The template will be processed as if written:
</p>
<pre>[% FOREACH user IN userlist %][% user %][% END %]</pre>
<p>
To remove all whitespace including any number of newlines, use the
'<code>~</code>' character instead.
</p>
<pre>[% FOREACH user IN userlist %]
[%~ user ~%]
[% END %]</pre>
<p>
To collapse all whitespace to a single space, use the '<code>=</code>'
character.
</p>
<pre>[% FOREACH user IN userlist %]
[%= user =%]
[% END %]</pre>
<p>
Here the template is processed as if written:
</p>
<pre>[% FOREACH user IN userlist %] [% user %] [% END %]</pre>
<p>
If you have <code>PRE_CHOMP</code> or <code>POST_CHOMP</code> set as
configuration options then you can use '<code>+</code>' to disable any
chomping options (i.e. leave the whitespace intact) on a per-directive
basis.
</p>
<pre>[% FOREACH user = userlist %]
User: [% user +%]
[% END %]</pre>
<p>
With <code>POST_CHOMP</code> set to <code>CHOMP_ONE</code>, the above
example would be parsed as if written:
</p>
<pre>[% FOREACH user = userlist %]User: [% user %]
[% END %]</pre>
<p>
For reference, the <code>PRE_CHOMP</code> and <code>POST_CHOMP</code>
configuration options may be set to any of the following:
</p>
<pre>Constant Value Tag Modifier
----------------------------------
CHOMP_NONE 0 +
CHOMP_ONE 1 -
CHOMP_COLLAPSE 2 =
CHOMP_GREEDY 3 ~</pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_TRIM" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">TRIM</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>TRIM</code> option can be set to have any leading and trailing
whitespace automatically removed from the output of all template files
and <code>BLOCK</code>s.
</p>
<p>
By example, the following <code>BLOCK</code> definition
</p>
<pre>[% BLOCK foo %]
Line 1 of foo
[% END %]</pre>
<p>
will be processed is as "<code>\nLine 1 of foo\n</code>". When
<code>INCLUDE</code>d, the surrounding newlines will also be introduced.
</p>
<pre>before
[% INCLUDE foo %]
after</pre>
<p>
Generated output:
</p>
<pre>before
Line 1 of foo
after</pre>
<p>
With the <code>TRIM</code> option set to any true value, the leading and
trailing newlines (which count as whitespace) will be removed from the
output of the <code>BLOCK</code>.
</p>
<pre>before
Line 1 of foo
after</pre>
<p>
The <code>TRIM</code> option is disabled (<code>0</code>) by default.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_INTERPOLATE" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">INTERPOLATE</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>INTERPOLATE</code> flag, when set to any true value will cause
variable references in plain text (i.e. not surrounded by
<code>START_TAG</code> and <code>END_TAG</code>) to be recognised and
interpolated accordingly.
</p>
<pre>my $template = Template->new({
INTERPOLATE => 1,
});</pre>
<p>
Variables should be prefixed by a '<code>$</code>' to identify them.
Curly braces can be used in the familiar Perl/shell style to explicitly
scope the variable name where required.
</p>
<pre># INTERPOLATE => 0
<a href="http://[% server %]/[% help %]">
<img src="[% images %]/help.gif"></a>
[% myorg.name %]</pre>
<pre># INTERPOLATE => 1
<a href="http://$server/$help">
<img src="$images/help.gif"></a>
$myorg.name
# explicit scoping with { }
<img src="$images/${icon.next}.gif"></pre>
<p>
Note that a limitation in Perl's regex engine restricts the maximum
length of an interpolated template to around 32 kilobytes or possibly
less. Files that exceed this limit in size will typically cause Perl to
dump core with a segmentation fault. If you routinely process templates
of this size then you should disable <code>INTERPOLATE</code> or split
the templates in several smaller files or blocks which can then be joined
backed together via <code>PROCESS</code> or <code>INCLUDE</code>.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_ANYCASE" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">ANYCASE</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
By default, directive keywords should be expressed in UPPER CASE. The
<code>ANYCASE</code> option can be set to allow directive keywords to be
specified in any case.
</p>
<pre># ANYCASE => 0 (default)
[% INCLUDE foobar %] # OK
[% include foobar %] # ERROR
[% include = 10 %] # OK, 'include' is a variable</pre>
<pre># ANYCASE => 1
[% INCLUDE foobar %] # OK
[% include foobar %] # OK
[% include = 10 %] # ERROR, 'include' is reserved word</pre>
<p>
One side-effect of enabling <code>ANYCASE</code> is that you cannot use a
variable of the same name as a reserved word, regardless of case. The
reserved words are currently:
</p>
<pre>GET CALL SET DEFAULT INSERT INCLUDE PROCESS WRAPPER
IF UNLESS ELSE ELSIF FOR FOREACH WHILE SWITCH CASE
USE PLUGIN FILTER MACRO PERL RAWPERL BLOCK META
TRY THROW CATCH FINAL NEXT LAST BREAK RETURN STOP
CLEAR TO STEP AND OR NOT MOD DIV END</pre>
<p>
The only lower case reserved words that cannot be used for variables,
regardless of the <code>ANYCASE</code> option, are the operators:
</p>
<pre>and or not mod div</pre>
</div>
</div>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Template_Files_and_Blocks" onclick="switch_section(this)" title="Click title to show/hide section content.">Template Files and Blocks</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<div class="subsection">
<div class="head">
<h2 id="section_INCLUDE_PATH" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">INCLUDE_PATH</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>INCLUDE_PATH</code> is used to specify one or more directories
in which template files are located. When a template is requested that
isn't defined locally as a <code>BLOCK</code>, each of the
<code>INCLUDE_PATH</code> directories is searched in turn to locate the
template file. Multiple directories can be specified as a reference to a
list or as a single string where each directory is delimited by
'<code>:</code>'.
</p>
<pre>my $template = Template->new({
INCLUDE_PATH => '/usr/local/templates',
});
my $template = Template->new({
INCLUDE_PATH => '/usr/local/templates:/tmp/my/templates',
});
my $template = Template->new({
INCLUDE_PATH => [ '/usr/local/templates',
'/tmp/my/templates' ],
});</pre>
<p>
On Win32 systems, a little extra magic is invoked, ignoring delimiters
that have '<code>:</code>' followed by a '<code>/</code>' or
'<code>\</code>'. This avoids confusion when using directory names like
'<code>C:\Blah Blah</code>'.
</p>
<p>
When specified as a list, the <code>INCLUDE_PATH</code> path can contain
elements which dynamically generate a list of <code>INCLUDE_PATH</code>
directories. These generator elements can be specified as a reference to
a subroutine or an object which implements a <code>paths()</code> method.
</p>
<pre>my $template = Template->new({
INCLUDE_PATH => [ '/usr/local/templates',
\&incpath_generator,
My::IncPath::Generator->new( ... ) ],
});</pre>
<p>
Each time a template is requested and the <code>INCLUDE_PATH</code>
examined, the subroutine or object method will be called. A reference to
a list of directories should be returned. Generator subroutines should
report errors using <code>die()</code>. Generator objects should return
undef and make an error available via its <code>error()</code> method.
</p>
<p>
For example:
</p>
<pre>sub incpath_generator {
# ...some code...
if ($all_is_well) {
return \@list_of_directories;
}
else {
die "cannot generate INCLUDE_PATH...\n";
}
}</pre>
<p>
or:
</p>
<pre>package My::IncPath::Generator;
# Template::Base (or Class::Base) provides error() method
use Template::Base;
use base qw( Template::Base );
sub paths {
my $self = shift;
# ...some code...
if ($all_is_well) {
return \@list_of_directories;
}
else {
return $self->error("cannot generate INCLUDE_PATH...\n");
}
}
1;</pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_DELIMITER" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">DELIMITER</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Used to provide an alternative delimiter character sequence for
separating paths specified in the <code>INCLUDE_PATH</code>. The default
value for <code>DELIMITER</code> is '<code>:</code>'.
</p>
<pre>my $template = Template->new({
DELIMITER => '; ',
INCLUDE_PATH => 'C:/HERE/NOW; D:/THERE/THEN',
});</pre>
<p>
On Win32 systems, the default delimiter is a little more intelligent,
splitting paths only on '<code>:</code>' characters that aren't followed
by a '<code>/</code>'. This means that the following should work as
planned, splitting the <code>INCLUDE_PATH</code> into 2 separate
directories, <code>C:/foo</code> and <code>C:/bar</code>.
</p>
<pre># on Win32 only
my $template = Template->new({
INCLUDE_PATH => 'C:/Foo:C:/Bar'
});</pre>
<p>
However, if you're using Win32 then it's recommended that you explicitly
set the <code>DELIMITER</code> character to something else (e.g.
'<code>;</code>') rather than rely on this subtle magic.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_ABSOLUTE" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">ABSOLUTE</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>ABSOLUTE</code> flag is used to indicate if templates specified
with absolute filenames (e.g. '<code>/foo/bar</code>') should be
processed. It is disabled by default and any attempt to load a template
by such a name will cause a '<code>file</code>' exception to be raised.
</p>
<pre>my $template = Template->new({
ABSOLUTE => 1,
});
# this is why it's disabled by default
[% INSERT /etc/passwd %]</pre>
<p>
On Win32 systems, the regular expression for matching absolute pathnames
is tweaked slightly to also detect filenames that start with a driver
letter and colon, such as:
</p>
<pre>C:/Foo/Bar</pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_RELATIVE" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">RELATIVE</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>RELATIVE</code> flag is used to indicate if templates specified
with filenames relative to the current directory (e.g.
'<code>./foo/bar</code>' or '<code>../../some/where/else</code>') should
be loaded. It is also disabled by default, and will raise a
'<code>file</code>' error if such template names are encountered.
</p>
<pre>my $template = Template->new({
RELATIVE => 1,
});
[% INCLUDE ../logs/error.log %]</pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_DEFAULT" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">DEFAULT</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>DEFAULT</code> option can be used to specify a default template
which should be used whenever a specified template can't be found in the
<code>INCLUDE_PATH</code>.
</p>
<pre>my $template = Template->new({
DEFAULT => 'notfound.html',
});</pre>
<p>
If a non-existant template is requested through the Template <a
href="#method_process">Template#process()</a> method, or by an
<code>INCLUDE</code>, <code>PROCESS</code> or <code>WRAPPER</code>
directive, then the <code>DEFAULT</code> template will instead be
processed, if defined. Note that the <code>DEFAULT</code> template is not
used when templates are specified with absolute or relative filenames, or
as a reference to a input file handle or text string.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_BLOCKS" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">BLOCKS</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>BLOCKS</code> option can be used to pre-define a default set of
template blocks. These should be specified as a reference to a hash array
mapping template names to template text, subroutines or <a href="../modules/Template/Document.html">Template::Document</a> objects.
</p>
<pre>my $template = Template->new({
BLOCKS => {
header => 'The Header. [% title %]',
footer => sub { return $some_output_text },
another => Template::Document->new({ ... }),
},
}); </pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_AUTO_RESET" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">AUTO_RESET</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>AUTO_RESET</code> option is set by default and causes the local
<code>BLOCKS</code> cache for the <a href="../modules/Template/Context.html">Template::Context</a> object to be
reset on each call to the Template <a
href="#method_process">Template#process()</a> method. This ensures that
any <code>BLOCK</code>s defined within a template will only persist until
that template is finished processing. This prevents <code>BLOCK</code>s
defined in one processing request from interfering with other independent
requests subsequently processed by the same context object.
</p>
<p>
The <code>BLOCKS</code> item may be used to specify a default set of
block definitions for the <a href="../modules/Template/Context.html">Template::Context</a> object. Subsequent <code>BLOCK</code>
definitions in templates will over-ride these but they will be reinstated
on each reset if <code>AUTO_RESET</code> is enabled (default), or if the
<a href="../modules/Template/Context.html">Template::Context</a> <a
href="#method_reset">Template::Context#reset()</a> method is called.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_RECURSION" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">RECURSION</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The template processor will raise a file exception if it detects direct
or indirect recursion into a template. Setting this option to any true
value will allow templates to include each other recursively.
</p>
</div>
</div>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Template_Variables" onclick="switch_section(this)" title="Click title to show/hide section content.">Template Variables</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<div class="subsection">
<div class="head">
<h2 id="section_VARIABLES" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">VARIABLES</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>VARIABLES</code> option (or <code>PRE_DEFINE</code> - they're
equivalent) can be used to specify a hash array of template variables
that should be used to pre-initialise the stash when it is created. These
items are ignored if the <code>STASH</code> item is defined.
</p>
<pre>my $template = Template->new({
VARIABLES => {
title => 'A Demo Page',
author => 'Joe Random Hacker',
version => 3.14,
},
};</pre>
<p>
or
</p>
<pre>my $template = Template->new({
PRE_DEFINE => {
title => 'A Demo Page',
author => 'Joe Random Hacker',
version => 3.14,
},
};</pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_CONSTANTS" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">CONSTANTS</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>CONSTANTS</code> option can be used to specify a hash array of
template variables that are compile-time constants. These variables are
resolved once when the template is compiled, and thus don't require
further resolution at runtime. This results in significantly faster
processing of the compiled templates and can be used for variables that
don't change from one request to the next.
</p>
<pre>my $template = Template->new({
CONSTANTS => {
title => 'A Demo Page',
author => 'Joe Random Hacker',
version => 3.14,
},
};</pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_CONSTANT_NAMESPACE" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">CONSTANT_NAMESPACE</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Constant variables are accessed via the <code>constants</code> namespace
by default.
</p>
<pre>[% constants.title %]</pre>
<p>
The <code>CONSTANTS_NAMESPACE</code> option can be set to specify an
alternate namespace.
</p>
<pre>my $template = Template->new({
CONSTANTS => {
title => 'A Demo Page',
# ...etc...
},
CONSTANTS_NAMESPACE => 'const',
};</pre>
<p>
In this case the constants would then be accessed as:
</p>
<pre>[% const.title %]</pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_NAMESPACE" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">NAMESPACE</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The constant folding mechanism described above is an example of a
namespace handler. Namespace handlers can be defined to provide alternate
parsing mechanisms for variables in different namespaces.
</p>
<p>
Under the hood, the <a href="../modules/Template.html">Template</a>
module converts a constructor configuration such as:
</p>
<pre>my $template = Template->new({
CONSTANTS => {
title => 'A Demo Page',
# ...etc...
},
CONSTANTS_NAMESPACE => 'const',
};</pre>
<p>
into one like:
</p>
<pre>my $template = Template->new({
NAMESPACE => {
const => Template:::Namespace::Constants->new({
title => 'A Demo Page',
# ...etc...
}),
},
};</pre>
<p>
You can use this mechanism to define multiple constant namespaces, or to
install custom handlers of your own.
</p>
<pre>my $template = Template->new({
NAMESPACE => {
site => Template:::Namespace::Constants->new({
title => "Wardley's Widgets",
version => 2.718,
}),
author => Template:::Namespace::Constants->new({
name => 'Andy Wardley',
email => 'abw@andywardley.com',
}),
voodoo => My::Namespace::Handler->new( ... ),
},
};</pre>
<p>
Now you have two constant namespaces, for example:
</p>
<pre>[% site.title %]
[% author.name %]</pre>
<p>
as well as your own custom namespace handler installed for the 'voodoo'
namespace.
</p>
<pre>[% voodoo.magic %]</pre>
<p>
See <a href="../modules/Template/Namespace/Constants.html">Template::Namespace::Constants</a> for an example of what a
namespace handler looks like on the inside.
</p>
</div>
</div>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Template_Processing_Options" onclick="switch_section(this)" title="Click title to show/hide section content.">Template Processing Options</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The following options are used to specify any additional templates that
should be processed before, after, around or instead of the template
passed as the first argument to the <a href="../modules/Template.html">Template</a> <a href="#method_process">Template#process()</a>
method. These options can be perform various useful tasks such as adding
standard headers or footers to all pages, wrapping page output in other
templates, pre-defining variables or performing initialisation or cleanup
tasks, automatically generating page summary information, navigation
elements, and so on.
</p>
<p>
The task of processing the template is delegated internally to the <a
href="../modules/Template/Service.html">Template::Service</a>
module which, unsurprisingly, also has a <a
href="#method_process">Template::Service#process()</a> method. Any
templates defined by the <code>PRE_PROCESS</code> option are processed
first and any output generated is added to the output buffer. Then the
main template is processed, or if one or more <code>PROCESS</code>
templates are defined then they are instead processed in turn. In this
case, one of the <code>PROCESS</code> templates is responsible for
processing the main template, by a directive such as:
</p>
<pre>[% PROCESS $template %]</pre>
<p>
The output of processing the main template or the <code>PROCESS</code>
template(s) is then wrapped in any <code>WRAPPER</code> templates, if
defined. <code>WRAPPER</code> templates don't need to worry about
explicitly processing the template because it will have been done for
them already. Instead <code>WRAPPER</code> templates access the content
they are wrapping via the <code>content</code> variable.
</p>
<pre>wrapper before
[% content %]
wrapper after</pre>
<p>
This output generated from processing the main template, and/or any
<code>PROCESS</code> or <code>WRAPPER</code> templates is added to the
output buffer. Finally, any <code>POST_PROCESS</code> templates are
processed and their output is also added to the output buffer which is
then returned.
</p>
<p>
If the main template throws an exception during processing then any
relevant template(s) defined via the <code>ERROR</code> option will be
processed instead. If defined and successfully processed, the output from
the error template will be added to the output buffer in place of the
template that generated the error and processing will continue, applying
any <code>WRAPPER</code> and <code>POST_PROCESS</code> templates. If no
relevant <code>ERROR</code> option is defined, or if the error occurs in
one of the <code>PRE_PROCESS</code>, <code>WRAPPER</code> or
<code>POST_PROCESS</code> templates, then the process will terminate
immediately and the error will be returned.
</p>
<div class="subsection">
<div class="head">
<h2 id="section_PRE_PROCESS_POST_PROCESS" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">PRE_PROCESS, POST_PROCESS</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
These values may be set to contain the name(s) of template files
(relative to <code>INCLUDE_PATH</code>) which should be processed
immediately before and/or after each template. These do not get added to
templates processed into a document via directives such as
<code>INCLUDE</code>, <code>PROCESS</code>, <code>WRAPPER</code> etc.
</p>
<pre>my $template = Template->new({
PRE_PROCESS => 'header',
POST_PROCESS => 'footer',
};</pre>
<p>
Multiple templates may be specified as a reference to a list. Each is
processed in the order defined.
</p>
<pre>my $template = Template->new({
PRE_PROCESS => [ 'config', 'header' ],
POST_PROCESS => 'footer',
};</pre>
<p>
Alternately, multiple template may be specified as a single string,
delimited by '<code>:</code>'. This delimiter string can be changed via
the <code>DELIMITER</code> option.
</p>
<pre>my $template = Template->new({
PRE_PROCESS => 'config:header',
POST_PROCESS => 'footer',
};</pre>
<p>
The <code>PRE_PROCESS</code> and <code>POST_PROCESS</code> templates are
evaluated in the same variable context as the main document and may
define or update variables for subsequent use.
</p>
<p>
config:
</p>
<pre>[% # set some site-wide variables
bgcolor = '#ffffff'
version = 2.718
%]</pre>
<p>
header:
</p>
<pre>[% DEFAULT title = 'My Funky Web Site' %]
<html>
<head>
<title>[% title %]</title>
</head>
<body bgcolor="[% bgcolor %]"></pre>
<p>
footer:
</p>
<pre> <hr>
Version [% version %]
</body>
</html></pre>
<p>
The <a href="../modules/Template/Document.html">Template::Document</a> object representing the main template being
processed is available within <code>PRE_PROCESS</code> and
<code>POST_PROCESS</code> templates as the <code>template</code>
variable. Metadata items defined via the <code>META</code> directive may
be accessed accordingly.
</p>
<pre>$template->process('mydoc.html', $vars);</pre>
<p>
mydoc.html:
</p>
<pre>[% META title = 'My Document Title' %]
blah blah blah
...</pre>
<p>
header:
</p>
<pre><html>
<head>
<title>[% template.title %]</title>
</head>
<body bgcolor="[% bgcolor %]"></pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_PROCESS" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">PROCESS</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>PROCESS</code> option may be set to contain the name(s) of
template files (relative to <code>INCLUDE_PATH</code>) which should be
processed instead of the main template passed to the <a href="../modules/Template.html">Template</a> <a
href="#method_process">Template#process()</a> method. This can be used to
apply consistent wrappers around all templates, similar to the use of
<code>PRE_PROCESS</code> and <code>POST_PROCESS</code> templates.
</p>
<pre>my $template = Template->new({
PROCESS => 'content',
};
# processes 'content' instead of 'foo.html'
$template->process('foo.html');</pre>
<p>
A reference to the original template is available in the
<code>template</code> variable. Metadata items can be inspected and the
template can be processed by specifying it as a variable reference (i.e.
prefixed by <code>$</code>) to an <code>INCLUDE</code>,
<code>PROCESS</code> or <code>WRAPPER</code> directive.
</p>
<p>
content:
</p>
<pre><html>
<head>
<title>[% template.title %]</title>
</head>
<body>
<!-- begin content -->
[% PROCESS $template %]
<!-- end content -->
<hr>
&copy; Copyright [% template.copyright %]
</body>
</html></pre>
<p>
foo.html:
</p>
<pre>[% META
title = 'The Foo Page'
author = 'Fred Foo'
copyright = '2000 Fred Foo'
%]
<h1>[% template.title %]</h1>
Welcome to the Foo Page, blah blah blah</pre>
<p>
output:
</p>
<pre><html>
<head>
<title>The Foo Page</title>
</head>
<body>
<!-- begin content -->
<h1>The Foo Page</h1>
Welcome to the Foo Page, blah blah blah
<!-- end content -->
<hr>
&copy; Copyright 2000 Fred Foo
</body>
</html></pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_WRAPPER" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">WRAPPER</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>WRAPPER</code> option can be used to specify one or more
templates which should be used to wrap around the output of the main page
template. The main template is processed first (or any
<code>PROCESS</code> template(s)) and the output generated is then passed
as the <code>content</code> variable to the <code>WRAPPER</code>
template(s) as they are processed.
</p>
<pre>my $template = Template->new({
WRAPPER => 'wrapper',
};
# process 'foo' then wrap in 'wrapper'
$template->process('foo', { message => 'Hello World!' });</pre>
<p>
wrapper:
</p>
<pre><wrapper>
[% content %]
</wrapper></pre>
<p>
foo:
</p>
<pre>This is the foo file!
Message: [% message %]</pre>
<p>
The output generated from this example is:
</p>
<pre><wrapper>
This is the foo file!
Message: Hello World!
</wrapper></pre>
<p>
You can specify more than one <code>WRAPPER</code> template by setting
the value to be a reference to a list of templates. The
<code>WRAPPER</code> templates will be processed in reverse order with
the output of each being passed to the next (or previous, depending on
how you look at it) as the 'content' variable. It sounds complicated, but
the end result is that it just "Does The Right Thing" to make wrapper
templates nest in the order you specify.
</p>
<pre>my $template = Template->new({
WRAPPER => [ 'outer', 'inner' ],
};
# process 'foo' then wrap in 'inner', then in 'outer'
$template->process('foo', { message => 'Hello World!' });</pre>
<p>
outer:
</p>
<pre><outer>
[% content %]
</outer></pre>
<p>
inner:
</p>
<pre><inner>
[% content %]
</inner></pre>
<p>
The output generated is then:
</p>
<pre><outer>
<inner>
This is the foo file!
Message: Hello World!
</inner>
</outer></pre>
<p>
One side-effect of the "inside-out" processing of the
<code>WRAPPER</code> configuration item (and also the
<code>WRAPPER</code> directive) is that any variables set in the template
being wrapped will be visible to the template doing the wrapping, but not
the other way around.
</p>
<p>
You can use this to good effect in allowing page templates to set
pre-defined values which are then used in the wrapper templates. For
example, our main page template 'foo' might look like this:
</p>
<p>
foo:
</p>
<pre>[% page = {
title = 'Foo Page'
subtitle = 'Everything There is to Know About Foo'
author = 'Frank Oliver Octagon'
}
%]
<p>
Welcome to the page that tells you everything about foo
blah blah blah...
</p></pre>
<p>
The <code>foo</code> template is processed before the wrapper template
meaning that the <code>page</code> data structure will be defined for use
in the wrapper template.
</p>
<p>
wrapper:
</p>
<pre><html>
<head>
<title>[% page.title %]</title>
</head>
<body>
<h1>[% page.title %]</h1>
<h2>[% page.subtitle %]</h1>
<h3>by [% page.author %]</h3>
[% content %]
</body>
</html></pre>
<p>
It achieves the same effect as defining <code>META</code> items which are
then accessed via the <code>template</code> variable (which you are still
free to use within <code>WRAPPER</code> templates), but gives you more
flexibility in the type and complexity of data that you can define.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_ERROR" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">ERROR</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>ERROR</code> (or <code>ERRORS</code> if you prefer)
configuration item can be used to name a single template or specify a
hash array mapping exception types to templates which should be used for
error handling. If an uncaught exception is raised from within a template
then the appropriate error template will instead be processed.
</p>
<p>
If specified as a single value then that template will be processed for
all uncaught exceptions.
</p>
<pre>my $template = Template->new({
ERROR => 'error.html'
});</pre>
<p>
If the <code>ERROR</code> item is a hash reference the keys are assumed
to be exception types and the relevant template for a given exception
will be selected. A <code>default</code> template may be provided for the
general case. Note that <code>ERROR</code> can be pluralised to
<code>ERRORS</code> if you find it more appropriate in this case.
</p>
<pre>my $template = Template->new({
ERRORS => {
user => 'user/index.html',
dbi => 'error/database',
default => 'error/default',
},
});</pre>
<p>
In this example, any <code>user</code> exceptions thrown will cause the
<i>user/index.html</i> template to be processed, <code>dbi</code> errors
are handled by <i>error/database</i> and all others by the
<i>error/default</i> template. Any <code>PRE_PROCESS</code> and/or
<code>POST_PROCESS</code> templates will also be applied to these error
templates.
</p>
<p>
Note that exception types are hierarchical and a <code>foo</code> handler
will catch all <code>foo.*</code> errors (e.g. <code>foo.bar</code>,
<code>foo.bar.baz</code>) if a more specific handler isn't defined. Be
sure to quote any exception types that contain periods to prevent Perl
concatenating them into a single string (i.e. <code>user.passwd</code> is
parsed as <code>'user'.'passwd'</code>).
</p>
<pre>my $template = Template->new({
ERROR => {
'user.login' => 'user/login.html',
'user.passwd' => 'user/badpasswd.html',
'user' => 'user/index.html',
'default' => 'error/default',
},
});</pre>
<p>
In this example, any template processed by the <a
href="#section_$template">$template</a> object, or other templates or
code called from within, can raise a <code>user.login</code> exception
and have the service redirect to the <i>user/login.html</i> template.
Similarly, a <code>user.passwd</code> exception has a specific handling
template, <i>user/badpasswd.html</i>, while all other <code>user</code>
or <code>user.*</code> exceptions cause a redirection to the
<i>user/index.html</i> page. All other exception types are handled by
<i>error/default</i>.
</p>
<p>
Exceptions can be raised in a template using the <code>THROW</code>
directive,
</p>
<pre>[% THROW user.login 'no user id: please login' %]</pre>
<p>
or by calling the <a href="#method_throw">Template::Context#throw()</a>
method on the current <a href="../modules/Template/Context.html">Template::Context</a> object,
</p>
<pre>$context->throw('user.passwd', 'Incorrect Password');
$context->throw('Incorrect Password'); # type 'undef'</pre>
<p>
or from Perl code by calling <code>die()</code> with a <a href="../modules/Template/Exception.html">Template::Exception</a> object,
</p>
<pre>die (Template::Exception->new('user.denied', 'Invalid User ID'));</pre>
<p>
or by simply calling <a href="#method_die">die()</a> with an error
string. This is automagically caught and converted to an exception of
'<code>undef</code>' type which can then be handled in the usual way.
</p>
<pre>die "I'm sorry Dave, I can't do that";</pre>
<p>
Note that the '<code>undef</code>' we're talking about here is a literal
string rather than Perl's <code>undef</code> used to represent undefined
values.
</p>
</div>
</div>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Template_Runtime_Options" onclick="switch_section(this)" title="Click title to show/hide section content.">Template Runtime Options</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<div class="subsection">
<div class="head">
<h2 id="section_EVAL_PERL" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">EVAL_PERL</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
This flag is used to indicate if <code>PERL</code> and/or
<code>RAWPERL</code> blocks should be evaluated. It is disabled by
default and any <code>PERL</code> or <code>RAWPERL</code> blocks
encountered will raise exceptions of type '<code>perl</code>' with the
message '<code>EVAL_PERL not set</code>'. Note however that any
<code>RAWPERL</code> blocks should always contain valid Perl code,
regardless of the <code>EVAL_PERL</code> flag. The parser will fail to
compile templates that contain invalid Perl code in <code>RAWPERL</code>
blocks and will throw a '<code>file</code>' exception.
</p>
<p>
When using compiled templates (see <a
href="#section_Caching_and_Compiling_Options">Caching_and_Compiling_Options</a>),
the <code>EVAL_PERL</code> has an affect when the template is compiled,
and again when the templates is subsequently processed, possibly in a
different context to the one that compiled it.
</p>
<p>
If the <code>EVAL_PERL</code> is set when a template is compiled, then
all <code>PERL</code> and <code>RAWPERL</code> blocks will be included in
the compiled template. If the <code>EVAL_PERL</code> option isn't set,
then Perl code will be generated which <b>always</b> throws a
'<code>perl</code>' exception with the message '<code>EVAL_PERL not
set</code>' <b>whenever</b> the compiled template code is run.
</p>
<p>
Thus, you must have <code>EVAL_PERL</code> set if you want your compiled
templates to include <code>PERL</code> and <code>RAWPERL</code> blocks.
</p>
<p>
At some point in the future, using a different invocation of the Template
Toolkit, you may come to process such a pre-compiled template. Assuming
the <code>EVAL_PERL</code> option was set at the time the template was
compiled, then the output of any <code>RAWPERL</code> blocks will be
included in the compiled template and will get executed when the template
is processed. This will happen regardless of the runtime
<code>EVAL_PERL</code> status.
</p>
<p>
Regular <code>PERL</code> blocks are a little more cautious, however. If
the <code>EVAL_PERL</code> flag isn't set for the <i>current</i> context,
that is, the one which is trying to process it, then it will throw the
familiar '<code>perl</code>' exception with the message, '<code>EVAL_PERL
not set</code>'.
</p>
<p>
Thus you can compile templates to include <code>PERL</code> blocks, but
optionally disable them when you process them later. Note however that it
is possible for a <code>PERL</code> block to contain a Perl "<code>BEGIN
{ # some code }</code>" block which will always get run regardless of the
runtime <code>EVAL_PERL</code> status. Thus, if you set
<code>EVAL_PERL</code> when compiling templates, it is assumed that you
trust the templates to Do The Right Thing. Otherwise you must accept the
fact that there's no bulletproof way to prevent any included code from
trampling around in the living room of the runtime environment, making a
real nuisance of itself if it really wants to. If you don't like the idea
of such uninvited guests causing a bother, then you can accept the
default and keep <code>EVAL_PERL</code> disabled.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_OUTPUT" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">OUTPUT</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Default output location or handler. This may be specified as one of: a
file name (relative to <code>OUTPUT_PATH</code>, if defined, or the
current working directory if not specified absolutely); a file handle
(e.g. <code>GLOB</code> or <a href="http://search.cpan.org/search?query=IO::Handle&mode=all">IO::Handle</a>) opened for writing; a reference to a text string to
which the output is appended (the string isn't cleared); a reference to a
subroutine which is called, passing the output text as an argument; as a
reference to an array, onto which the content will be
<code>push()</code>ed; or as a reference to any object that supports the
<code>print()</code> method. This latter option includes the
<code>Apache::Request</code> object which is passed as the argument to
Apache/mod_perl handlers.
</p>
<p>
example 1 (file name):
</p>
<pre>my $template = Template->new({
OUTPUT => "/tmp/foo",
});</pre>
<p>
example 2 (text string):
</p>
<pre>my $output = '';
my $template = Template->new({
OUTPUT => \$output,
});</pre>
<p>
example 3 (file handle):
</p>
<pre>open (TOUT, "> $file") || die "$file: $!\n";
my $template = Template->new({
OUTPUT => \*TOUT,
});</pre>
<p>
example 4 (subroutine):
</p>
<pre>sub output { my $out = shift; print "OUTPUT: $out" }
my $template = Template->new({
OUTPUT => \&output,
});</pre>
<p>
example 5 (array reference):
</p>
<pre>my $template = Template->new({
OUTPUT => \@output,
})</pre>
<p>
example 6 (Apache/mod_perl handler):
</p>
<pre>sub handler {
my $r = shift;
my $t = Template->new({
OUTPUT => $r,
});
...
}</pre>
<p>
The default <code>OUTPUT</code> location be overridden by passing a third
parameter to the <a href="../modules/Template.html">Template</a> <a
href="#method_process">Template#process()</a> method. This can be
specified as any of the above argument types.
</p>
<pre>$t->process($file, $vars, "/tmp/foo");
$t->process($file, $vars, \$output);
$t->process($file, $vars, \*MYGLOB);
$t->process($file, $vars, \@output);
$t->process($file, $vars, $r); # Apache::Request
...</pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_OUTPUT_PATH" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">OUTPUT_PATH</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>OUTPUT_PATH</code> allows a directory to be specified into
which output files should be written. An output file can be specified by
the <code>OUTPUT</code> option, or passed by name as the third parameter
to the <a href="../modules/Template.html">Template</a> <a
href="#method_process">Template#process()</a> method.
</p>
<pre>my $template = Template->new({
INCLUDE_PATH => "/tmp/src",
OUTPUT_PATH => "/tmp/dest",
});
my $vars = {
...
};
foreach my $file ('foo.html', 'bar.html') {
$template->process($file, $vars, $file)
|| die $template->error();
}</pre>
<p>
This example will read the input files <i>/tmp/src/foo.html</i> and
<i>/tmp/src/bar.html</i> and write the processed output to
<i>/tmp/dest/foo.html</i> and <i>/tmp/dest/bar.html</i>, respectively.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_DEBUG" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">DEBUG</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>DEBUG</code> option can be used to enable debugging within the
various different modules that comprise the Template Toolkit. The <a
href="../modules/Template/Constants.html">Template::Constants</a>
module defines a set of <code>DEBUG_XXXX</code> constants which can be
combined using the logical OR operator, '<code>|</code>'.
</p>
<pre>use Template::Constants qw( :debug );
my $template = Template->new({
DEBUG => DEBUG_PARSER | DEBUG_PROVIDER,
});</pre>
<p>
For convenience, you can also provide a string containing a list of lower
case debug options, separated by any non-word characters.
</p>
<pre>my $template = Template->new({
DEBUG => 'parser, provider',
});</pre>
<p>
The following <code>DEBUG_XXXX</code> flags can be used:
</p>
<ul>
<li><b id="item_DEBUG_SERVICE">DEBUG_SERVICE</b>
<p>
Enables general debugging messages for the <a href="../modules/Template/Service.html">Template::Service</a> module.
</p>
</li>
<li><b id="item_DEBUG_CONTEXT">DEBUG_CONTEXT</b>
<p>
Enables general debugging messages for the <a href="../modules/Template/Context.html">Template::Context</a> module.
</p>
</li>
<li><b id="item_DEBUG_PROVIDER">DEBUG_PROVIDER</b>
<p>
Enables general debugging messages for the <a href="../modules/Template/Provider.html">Template::Provider</a> module.
</p>
</li>
<li><b id="item_DEBUG_PLUGINS">DEBUG_PLUGINS</b>
<p>
Enables general debugging messages for the <a href="../modules/Template/Plugins.html">Template::Plugins</a> module.
</p>
</li>
<li><b id="item_DEBUG_FILTERS">DEBUG_FILTERS</b>
<p>
Enables general debugging messages for the <a href="../modules/Template/Filters.html">Template::Filters</a> module.
</p>
</li>
<li><b id="item_DEBUG_PARSER">DEBUG_PARSER</b>
<p>
This flag causes the <a href="../modules/Template/Parser.html">Template::Parser</a> to generate debugging messages that show the
Perl code generated by parsing and compiling each template.
</p>
</li>
<li><b id="item_DEBUG_UNDEF">DEBUG_UNDEF</b>
<p>
This option causes the Template Toolkit to throw an '<code>undef</code>'
error whenever it encounters an undefined variable value.
</p>
</li>
<li><b id="item_DEBUG_DIRS">DEBUG_DIRS</b>
<p>
This option causes the Template Toolkit to generate comments indicating
the source file, line and original text of each directive in the
template. These comments are embedded in the template output using the
format defined in the <code>DEBUG_FORMAT</code> configuration item, or a
simple default format if unspecified.
</p>
<p>
For example, the following template fragment: Hello World
</p>
<p>
would generate this output:
</p>
<pre>## input text line 1 : ##
Hello
## input text line 2 : World ##
World</pre>
</li>
<li><b id="item_DEBUG_ALL">DEBUG_ALL</b>
<p>
Enables all debugging messages.
</p>
</li>
<li><b id="item_DEBUG_CALLER">DEBUG_CALLER</b>
<p>
This option causes all debug messages that aren't newline terminated to
have the file name and line number of the caller appended to them.
</p>
</li>
</ul>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_DEBUG_FORMAT" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">DEBUG_FORMAT</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>DEBUG_FORMAT</code> option can be used to specify a format
string for the debugging messages generated via the
<code>DEBUG_DIRS</code> option described above. Any occurances of
<code>$file</code>, <code>$line</code> or <code>$text</code> will be
replaced with the current file name, line or directive text,
respectively. Notice how the format is single quoted to prevent Perl from
interpolating those tokens as variables.
</p>
<pre>my $template = Template->new({
DEBUG => 'dirs',
DEBUG_FORMAT => '<!-- $file line $line : [% $text %] -->',
});</pre>
<p>
The following template fragment:
</p>
<pre>[% foo = 'World' %]
Hello [% foo %]</pre>
<p>
would then generate this output:
</p>
<pre><!-- input text line 2 : [% foo = 'World' %] -->
Hello <!-- input text line 3 : [% foo %] -->World</pre>
<p>
The DEBUG directive can also be used to set a debug format within a
template.
</p>
<pre>[% DEBUG format '<!-- $file line $line : [% $text %] -->' %]</pre>
</div>
</div>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Caching_and_Compiling_Options" onclick="switch_section(this)" title="Click title to show/hide section content.">Caching and Compiling Options</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<div class="subsection">
<div class="head">
<h2 id="section_CACHE_SIZE" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">CACHE_SIZE</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <a href="../modules/Template/Provider.html">Template::Provider</a> module caches compiled templates to avoid the
need to re-parse template files or blocks each time they are used. The
<code>CACHE_SIZE</code> option is used to limit the number of compiled
templates that the module should cache.
</p>
<p>
By default, the <code>CACHE_SIZE</code> is undefined and all compiled
templates are cached. When set to any positive value, the cache will be
limited to storing no more than that number of compiled templates. When a
new template is loaded and compiled and the cache is full (i.e. the
number of entries == <code>CACHE_SIZE</code>), the least recently used
compiled template is discarded to make room for the new one.
</p>
<p>
The <code>CACHE_SIZE</code> can be set to <code>0</code> to disable
caching altogether.
</p>
<pre>my $template = Template->new({
CACHE_SIZE => 64, # only cache 64 compiled templates
});</pre>
<pre>my $template = Template->new({
CACHE_SIZE => 0, # don't cache any compiled templates
});</pre>
<p>
As well as caching templates as they are found, the <a href="../modules/Template/Provider.html">Template::Provider</a> also
implements negative caching to keep track of templates that are
<i>not</i> found. This allows the provider to quickly decline a request
for a template that it has previously failed to locate, saving the effort
of going to look for it again. This is useful when an
<code>INCLUDE_PATH</code> includes multiple providers, ensuring that the
request is passed down through the providers as quickly as possible.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_STAT_TTL" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">STAT_TTL</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
This value can be set to control how long the <a href="../modules/Template/Provider.html">Template::Provider</a> will keep a
template cached in memory before checking to see if the source template
has changed.
</p>
<pre>my $provider = Template::Provider->new({
STAT_TTL => 60, # one minute
});</pre>
<p>
The default value is 1 (second). You'll probably want to set this to a
higher value if you're running the Template Toolkit inside a persistent
web server application (e.g. mod_perl). For example, set it to 60 and the
provider will only look for changes to templates once a minute at most.
However, during development (or any time you're making frequent changes
to templates) you'll probably want to keep it set to a low value so that
you don't have to wait for the provider to notice that your templates
have changed.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_COMPILE_EXT" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">COMPILE_EXT</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
From version 2 onwards, the Template Toolkit has the ability to compile
templates to Perl code and save them to disk for subsequent use (i.e.
cache persistence). The <code>COMPILE_EXT</code> option may be provided
to specify a filename extension for compiled template files. It is
undefined by default and no attempt will be made to read or write any
compiled template files.
</p>
<pre>my $template = Template->new({
COMPILE_EXT => '.ttc',
});</pre>
<p>
If <code>COMPILE_EXT</code> is defined (and <code>COMPILE_DIR</code>
isn't, see below) then compiled template files with the
<code>COMPILE_EXT</code> extension will be written to the same directory
from which the source template files were loaded.
</p>
<p>
Compiling and subsequent reuse of templates happens automatically
whenever the <code>COMPILE_EXT</code> or <code>COMPILE_DIR</code> options
are set. The Template Toolkit will automatically reload and reuse
compiled files when it finds them on disk. If the corresponding source
file has been modified since the compiled version as written, then it
will load and re-compile the source and write a new compiled version to
disk.
</p>
<p>
This form of cache persistence offers significant benefits in terms of
time and resources required to reload templates. Compiled templates can
be reloaded by a simple call to Perl's <code>require()</code>, leaving
Perl to handle all the parsing and compilation. This is a Good Thing.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_COMPILE_DIR" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">COMPILE_DIR</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>COMPILE_DIR</code> option is used to specify an alternate
directory root under which compiled template files should be saved.
</p>
<pre>my $template = Template->new({
COMPILE_DIR => '/tmp/ttc',
});</pre>
<p>
The <code>COMPILE_EXT</code> option may also be specified to have a
consistent file extension added to these files.
</p>
<pre>my $template1 = Template->new({
COMPILE_DIR => '/tmp/ttc',
COMPILE_EXT => '.ttc1',
});</pre>
<pre>my $template2 = Template->new({
COMPILE_DIR => '/tmp/ttc',
COMPILE_EXT => '.ttc2',
});</pre>
<p>
When <code>COMPILE_EXT</code> is undefined, the compiled template files
have the same name as the original template files, but reside in a
different directory tree.
</p>
<p>
Each directory in the <code>INCLUDE_PATH</code> is replicated in full
beneath the <code>COMPILE_DIR</code> directory. This example:
</p>
<pre>my $template = Template->new({
COMPILE_DIR => '/tmp/ttc',
INCLUDE_PATH => '/home/abw/templates:/usr/share/templates',
});</pre>
<p>
would create the following directory structure:
</p>
<pre>/tmp/ttc/home/abw/templates/
/tmp/ttc/usr/share/templates/</pre>
<p>
Files loaded from different <code>INCLUDE_PATH</code> directories will
have their compiled forms save in the relevant <code>COMPILE_DIR</code>
directory.
</p>
<p>
On Win32 platforms a filename may by prefixed by a drive letter and
colon. e.g.
</p>
<pre>C:/My Templates/header</pre>
<p>
The colon will be silently stripped from the filename when it is added to
the <code>COMPILE_DIR</code> value(s) to prevent illegal filename being
generated. Any colon in <code>COMPILE_DIR</code> elements will be left
intact. For example:
</p>
<pre># Win32 only
my $template = Template->new({
DELIMITER => ';',
COMPILE_DIR => 'C:/TT2/Cache',
INCLUDE_PATH => 'C:/TT2/Templates;D:/My Templates',
});</pre>
<p>
This would create the following cache directories:
</p>
<pre>C:/TT2/Cache/C/TT2/Templates
C:/TT2/Cache/D/My Templates</pre>
</div>
</div>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Plugins_and_Filters" onclick="switch_section(this)" title="Click title to show/hide section content.">Plugins and Filters</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<div class="subsection">
<div class="head">
<h2 id="section_PLUGINS" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">PLUGINS</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>PLUGINS</code> options can be used to provide a reference to a
hash array that maps plugin names to Perl module names. A number of
standard plugins are defined (e.g. <code>table</code>,
<code>format</code>, <code>cgi</code>, etc.) which map to their
corresponding <code>Template::Plugin::*</code> counterparts. These can be
redefined by values in the <code>PLUGINS</code> hash.
</p>
<pre>my $template = Template->new({
PLUGINS => {
cgi => 'MyOrg::Template::Plugin::CGI',
foo => 'MyOrg::Template::Plugin::Foo',
bar => 'MyOrg::Template::Plugin::Bar',
},
}); </pre>
<p>
The recommended convention is to specify these plugin names in lower
case. The Template Toolkit first looks for an exact case-sensitive match
and then tries the lower case conversion of the name specified.
</p>
<pre>[% USE Foo %] # look for 'Foo' then 'foo'</pre>
<p>
If you define all your <code>PLUGINS</code> with lower case names then
they will be located regardless of how the user specifies the name in the
USE directive. If, on the other hand, you define your
<code>PLUGINS</code> with upper or mixed case names then the name
specified in the <code>USE</code> directive must match the case exactly.
</p>
<p>
The <code>USE</code> directive is used to create plugin objects and does
so by calling the <a href="#method_plugin">Template::Context#plugin()</a>
method on the current <a href="../modules/Template/Context.html">Template::Context</a> object. If the plugin name is defined in the
<code>PLUGINS</code> hash then the corresponding Perl module is loaded
via <code>require()</code>. The context then calls the <a
href="#method_load">Template::Plugin#load()</a> class method which should
return the class name (default and general case) or a prototype object
against which the <a href="#method_new">Template::Plugin#new()</a> method
can be called to instantiate individual plugin objects.
</p>
<p>
If the plugin name is not defined in the <code>PLUGINS</code> hash then
the <code>PLUGIN_BASE</code> and/or <code>LOAD_PERL</code> options come
into effect.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_PLUGIN_BASE" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">PLUGIN_BASE</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
If a plugin is not defined in the <code>PLUGINS</code> hash then the
<code>PLUGIN_BASE</code> is used to attempt to construct a correct Perl
module name which can be successfully loaded.
</p>
<p>
The <code>PLUGIN_BASE</code> can be specified as a reference to an array
of module namespaces, or as a single value which is automatically
converted to a list. The default <code>PLUGIN_BASE</code> value
(<code>Template::Plugin</code>) is then added to the end of this list.
</p>
<p>
example 1:
</p>
<pre>my $template = Template->new({
PLUGIN_BASE => 'MyOrg::Template::Plugin',
});
[% USE Foo %] # => MyOrg::Template::Plugin::Foo
or Template::Plugin::Foo </pre>
<p>
example 2:
</p>
<pre>my $template = Template->new({
PLUGIN_BASE => [ 'MyOrg::Template::Plugin',
'YourOrg::Template::Plugin' ],
});</pre>
<p>
template:
</p>
<pre>[% USE Foo %] # => MyOrg::Template::Plugin::Foo
or YourOrg::Template::Plugin::Foo
or Template::Plugin::Foo </pre>
<p>
If you don't want the default <code>Template::Plugin</code> namespace
added to the end of the <code>PLUGIN_BASE</code>, then set the
<code>$Template::Plugins::PLUGIN_BASE</code> variable to a false value
before calling the <a href="../modules/Template.html">Template</a>
<a href="#method_new">Template#new()</a> constructor method. This is
shown in the example below where the <code>Foo</code> plugin is located
as <code>My::Plugin::Foo</code> or <code>Your::Plugin::Foo</code> but not
as <code>Template::Plugin::Foo</code>.
</p>
<p>
example 3:
</p>
<pre>use Template::Plugins;
$Template::Plugins::PLUGIN_BASE = '';
my $template = Template->new({
PLUGIN_BASE => [ 'My::Plugin',
'Your::Plugin' ],
});</pre>
<p>
template:
</p>
<pre>[% USE Foo %] # => My::Plugin::Foo
or Your::Plugin::Foo </pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_LOAD_PERL" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">LOAD_PERL</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
If a plugin cannot be loaded using the <code>PLUGINS</code> or
<code>PLUGIN_BASE</code> approaches then the provider can make a final
attempt to load the module without prepending any prefix to the module
path. This allows regular Perl modules (i.e. those that don't reside in
the <a href="../modules/Template/Plugin.html">Template::Plugin</a>
or some other such namespace) to be loaded and used as plugins.
</p>
<p>
By default, the <code>LOAD_PERL</code> option is set to <code>0</code>
and no attempt will be made to load any Perl modules that aren't named
explicitly in the <code>PLUGINS</code> hash or reside in a package as
named by one of the <code>PLUGIN_BASE</code> components.
</p>
<p>
Plugins loaded using the <code>PLUGINS</code> or <code>PLUGIN_BASE</code>
receive a reference to the current context object as the first argument
to the <a href="#method_new">Template::Plugin#new()</a> constructor.
Modules loaded using <code>LOAD_PERL</code> are assumed to not conform to
the plugin interface. They must provide a <code>new()</code> class method
for instantiating objects but it will not receive a reference to the
context as the first argument.
</p>
<p>
Plugin modules should provide a <a
href="#method_load">Template::Plugin#load()</a> class method (or inherit
the default one from the <a href="../modules/Template/Plugin.html">Template::Plugin</a> base class) which is called the first time the
plugin is loaded. Regular Perl modules need not. In all other respects,
regular Perl objects and Template Toolkit plugins are identical.
</p>
<p>
If a particular Perl module does not conform to the common, but not
unilateral, <code>new()</code> constructor convention then a simple
plugin wrapper can be written to interface to it.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_FILTERS" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">FILTERS</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>FILTERS</code> option can be used to specify custom filters
which can then be used with the <code>FILTER</code> directive like any
other. These are added to the standard filters which are available by
default. Filters specified via this option will mask any standard filters
of the same name.
</p>
<p>
The <code>FILTERS</code> option should be specified as a reference to a
hash array in which each key represents the name of a filter. The
corresponding value should contain a reference to an array containing a
subroutine reference and a flag which indicates if the filter is static
(<code>0</code>) or dynamic (<code>1</code>). A filter may also be
specified as a solitary subroutine reference and is assumed to be static.
</p>
<pre>$template = Template->new({
FILTERS => {
'sfilt1' => \&static_filter, # static
'sfilt2' => [ \&static_filter, 0 ], # same as above
'dfilt1' => [ \&dyanamic_filter_factory, 1 ],
},
});</pre>
<p>
Additional filters can be specified at any time by calling the <a
href="#method_define_filter">Template::Context#define_filter()</a> method
on the current <a href="../modules/Template/Context.html">Template::Context</a> object. The method accepts a filter name, a
reference to a filter subroutine and an optional flag to indicate if the
filter is dynamic.
</p>
<pre>my $context = $template->context();
$context->define_filter('new_html', \&new_html);
$context->define_filter('new_repeat', \&new_repeat, 1);</pre>
<p>
Static filters are those where a single subroutine reference is used for
all invocations of a particular filter. Filters that don't accept any
configuration parameters (e.g. <code>html</code>) can be implemented
statically. The subroutine reference is simply returned when that
particular filter is requested. The subroutine is called to filter the
output of a template block which is passed as the only argument. The
subroutine should return the modified text.
</p>
<pre>sub static_filter {
my $text = shift;
# do something to modify $text...
return $text;
}</pre>
<p>
The following template fragment:
</p>
<pre>[% FILTER sfilt1 %]
Blah blah blah.
[% END %]</pre>
<p>
is approximately equivalent to:
</p>
<pre>&static_filter("\nBlah blah blah.\n");</pre>
<p>
Filters that can accept parameters (e.g. <code>truncate</code>) should be
implemented dynamically. In this case, the subroutine is taken to be a
filter 'factory' that is called to create a unique filter subroutine each
time one is requested. A reference to the current <a href="../modules/Template/Context.html">Template::Context</a> object is
passed as the first parameter, followed by any additional parameters
specified. The subroutine should return another subroutine reference
(usually a closure) which implements the filter.
</p>
<pre>sub dynamic_filter_factory {
my ($context, @args) = @_;
return sub {
my $text = shift;
# do something to modify $text...
return $text;
}
}</pre>
<p>
The following template fragment:
</p>
<pre>[% FILTER dfilt1(123, 456) %]
Blah blah blah
[% END %] </pre>
<p>
is approximately equivalent to:
</p>
<pre>my $filter = &dynamic_filter_factory($context, 123, 456);
&$filter("\nBlah blah blah.\n");</pre>
<p>
See the <code>FILTER</code> directive for further examples.
</p>
</div>
</div>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Customisation_and_Extension" onclick="switch_section(this)" title="Click title to show/hide section content.">Customisation and Extension</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<div class="subsection">
<div class="head">
<h2 id="section_LOAD_TEMPLATES" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">LOAD_TEMPLATES</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>LOAD_TEMPLATES</code> option can be used to provide a reference
to a list of <a href="../modules/Template/Provider.html">Template::Provider</a> objects or sub-classes thereof which will
take responsibility for loading and compiling templates.
</p>
<pre>my $template = Template->new({
LOAD_TEMPLATES => [
MyOrg::Template::Provider->new({ ... }),
Template::Provider->new({ ... }),
],
});</pre>
<p>
When a <code>PROCESS</code>, <code>INCLUDE</code> or <code>WRAPPER</code>
directive is encountered, the named template may refer to a locally
defined <code>BLOCK</code> or a file relative to the
<code>INCLUDE_PATH</code> (or an absolute or relative path if the
appropriate <code>ABSOLUTE</code> or <code>RELATIVE</code> options are
set). If a <code>BLOCK</code> definition can't be found (see the <a
href="../modules/Template/Context.html">Template::Context</a> <a
href="#method_template">Template::Context#template()</a> method for a
discussion of <code>BLOCK</code> locality) then each of the
<code>LOAD_TEMPLATES</code> provider objects is queried in turn via the
<a href="#method_fetch">Template::Provider#fetch()</a> method to see if
it can supply the required template.
</p>
<p>
Each provider can return a compiled template, an error, or decline to
service the request in which case the responsibility is passed to the
next provider. If none of the providers can service the request then a
'not found' error is returned. The same basic provider mechanism is also
used for the <code>INSERT</code> directive but it bypasses any
<code>BLOCK</code> definitions and doesn't attempt is to parse or process
the contents of the template file.
</p>
<p>
If <code>LOAD_TEMPLATES</code> is undefined, a single default provider
will be instantiated using the current configuration parameters. For
example, the <a href="../modules/Template/Provider.html">Template::Provider</a> <code>INCLUDE_PATH</code> option can be
specified in the <a href="../modules/Template.html">Template</a>
configuration and will be correctly passed to the provider's constructor
method.
</p>
<pre>my $template = Template->new({
INCLUDE_PATH => '/here:/there',
});</pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_LOAD_PLUGINS" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">LOAD_PLUGINS</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>LOAD_PLUGINS</code> options can be used to specify a list of
provider objects (i.e. they implement the <a
href="#method_fetch">Template::Plugins#fetch()</a> method) which are
responsible for loading and instantiating template plugin objects. The <a
href="../modules/Template/Context.html">Template::Context</a> <a
href="#method_plugin">Template::Context#plugin()</a> method queries each
provider in turn in a "Chain of Responsibility" as per the <a
href="#method_template">Template::Context#template()</a> and <a
href="#method_filter">Template::Context#filter()</a> methods.
</p>
<pre>my $template = Template->new({
LOAD_PLUGINS => [
MyOrg::Template::Plugins->new({ ... }),
Template::Plugins->new({ ... }),
],
});</pre>
<p>
By default, a single <a href="../modules/Template/Plugins.html">Template::Plugins</a> object is created using the current
configuration hash. Configuration items destined for the <a href="../modules/Template/Plugins.html">Template::Plugins</a> constructor may
be added to the Template constructor.
</p>
<pre>my $template = Template->new({
PLUGIN_BASE => 'MyOrg::Template::Plugins',
LOAD_PERL => 1,
});</pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_LOAD_FILTERS" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">LOAD_FILTERS</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>LOAD_FILTERS</code> option can be used to specify a list of
provider objects (i.e. they implement the <a
href="#method_fetch">Template::Filters#fetch()</a> method) which are
responsible for returning and/or creating filter subroutines. The <a
href="../modules/Template/Context.html">Template::Context</a> <a
href="#method_filter">Template::Context#filter()</a> method queries each
provider in turn in a "Chain of Responsibility" as per the <a
href="#method_template">Template::Context#template()</a> and <a
href="#method_plugin">Template::Context#plugin()</a> methods.
</p>
<pre>my $template = Template->new({
LOAD_FILTERS => [
MyTemplate::Filters->new(),
Template::Filters->new(),
],
});</pre>
<p>
By default, a single <a href="../modules/Template/Filters.html">Template::Filters</a> object is created for the
<code>LOAD_FILTERS</code> list.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_TOLERANT" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">TOLERANT</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>TOLERANT</code> flag is used by the various Template Toolkit
provider modules (<a href="../modules/Template/Provider.html">Template::Provider</a>, <a href="../modules/Template/Plugins.html">Template::Plugins</a>, <a href="../modules/Template/Filters.html">Template::Filters</a>) to control their behaviour when errors are
encountered. By default, any errors are reported as such, with the
request for the particular resource (<code>template</code>,
<code>plugin</code>, <code>filter</code>) being denied and an exception
raised.
</p>
<p>
When the <code>TOLERANT</code> flag is set to any true values, errors
will be silently ignored and the provider will instead return
<code>STATUS_DECLINED</code>. This allows a subsequent provider to take
responsibility for providing the resource, rather than failing the
request outright. If all providers decline to service the request, either
through tolerated failure or a genuine disinclination to comply, then a
'<code><resource> not found</code>' exception is raised.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_SERVICE" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">SERVICE</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
A reference to a <a href="../modules/Template/Service.html">Template::Service</a> object, or sub-class thereof, to which the <a
href="../modules/Template.html">Template</a> module should delegate.
If unspecified, a <a href="../modules/Template/Service.html">Template::Service</a> object is automatically created using the
current configuration hash.
</p>
<pre>my $template = Template->new({
SERVICE => MyOrg::Template::Service->new({ ... }),
});</pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_CONTEXT" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">CONTEXT</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
A reference to a <a href="../modules/Template/Context.html">Template::Context</a> object which is used to define a specific
environment in which template are processed. A <a href="../modules/Template/Context.html">Template::Context</a> object is
passed as the only parameter to the Perl subroutines that represent
"compiled" template documents. Template subroutines make callbacks into
the context object to access Template Toolkit functionality, for example,
to to <code>INCLUDE</code> or <code>PROCESS</code> another template (<a
href="#method_include">Template::Context#include()</a> and <a
href="#method_process">Template::Context#process()</a> methods,
respectively), to <code>USE</code> a plugin (<a
href="#method_plugin">Template::Context#plugin()</a>) or instantiate a
filter (<a href="#method_filter">Template::Context#filter()</a>) or to
access the stash (<a href="#method_stash">Template::Context#stash()</a>)
which manages variable definitions via the <a
href="#method_get">Template::Stash#get()</a> and <a
href="#method_set">Template::Stash#set()</a> methods.
</p>
<pre>my $template = Template->new({
CONTEXT => MyOrg::Template::Context->new({ ... }),
});</pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_STASH" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">STASH</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
A reference to a <a href="../modules/Template/Stash.html">Template::Stash</a> object or sub-class which will take
responsibility for managing template variables.
</p>
<pre>my $stash = MyOrg::Template::Stash->new({ ... });
my $template = Template->new({
STASH => $stash,
});</pre>
<p>
If unspecified, a default stash object is created using the
<code>VARIABLES</code> configuration item to initialise the stash
variables.
</p>
<pre>my $template = Template->new({
VARIABLES => {
id => 'abw',
name => 'Andy Wardley',
},
};</pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_PARSER" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">PARSER</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <a href="../modules/Template/Parser.html">Template::Parser</a>
module implements a parser object for compiling templates into Perl code
which can then be executed. A default object of this class is created
automatically and then used by the <a href="../modules/Template/Provider.html">Template::Provider</a> whenever a
template is loaded and requires compilation. The <code>PARSER</code>
option can be used to provide a reference to an alternate parser object.
</p>
<pre>my $template = Template->new({
PARSER => MyOrg::Template::Parser->new({ ... }),
});</pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_GRAMMAR" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">GRAMMAR</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>GRAMMAR</code> configuration item can be used to specify an
alternate grammar for the parser. This allows a modified or entirely new
template language to be constructed and used by the Template Toolkit.
</p>
<p>
Source templates are compiled to Perl code by the <a href="../modules/Template/Parser.html">Template::Parser</a> using the <a
href="../modules/Template/Grammar.html">Template::Grammar</a> (by
default) to define the language structure and semantics. Compiled
templates are thus inherently "compatible" with each other and there is
nothing to prevent any number of different template languages being
compiled and used within the same Template Toolkit processing environment
(other than the usual time and memory constraints).
</p>
<p>
The <a href="../modules/Template/Grammar.html">Template::Grammar</a> file is constructed from a YACC like grammar
(using <code>Parse::YAPP</code>) and a skeleton module template. These
files are provided, along with a small script to rebuild the grammar, in
the <i>parser</i> sub-directory of the distribution.
</p>
<p>
You don't have to know or worry about these unless you want to hack on
the template language or define your own variant. There is a
<i>README</i> file in the same directory which provides some small
guidance but it is assumed that you know what you're doing if you venture
herein. If you grok LALR parsers, then you should find it comfortably
familiar.
</p>
<p>
By default, an instance of the default <a href="../modules/Template/Grammar.html">Template::Grammar</a> will be created
and used automatically if a <code>GRAMMAR</code> item isn't specified.
</p>
<pre>use MyOrg::Template::Grammar;
my $template = Template->new({
GRAMMAR = MyOrg::Template::Grammar->new();
});</pre>
</div>
</div>
</div>
</div>
</div></div>
<br class="clear" />
<div class="pageinfo">
/manual/Config.html last modified 10:57:38 31-May-2007
</div>
</div>
<div id="footer">
<a href="http://opensource.org/" class="osi"></a>
<div class="controls">
<div class="pager">
<a href="../manual/VMethods.html" title="Template::Manual::VMethods" class="go back">Back<span class="about"><h4>Template::Manual::VMethods</h4></span></a>
<a href="../manual/index.html" title="Template::Manual" class="go up">Up<span class="about"><h4>Template::Manual</h4></span></a>
<a href="../manual/Filters.html" title="Template::Manual::Filters" class="go next">Next<span class="about"><h4>Template::Manual::Filters</h4></span></a>
</div>
</div>
<div class="copyright">
Copyright © 1996-2007 <a href="http://wardley.org/">Andy Wardley</a>. All Rights Reserved.
</div>
<div class="licence">
The <a href="http://template-toolkit.org/">Template Toolkit</a> is <a href="http://opensource.org/">Open Source</a> software.
You can redistribute and/or modify it under the terms of the <a href="http://www.opensource.org/licenses/gpl-license.php">GNU Public Licence</a>
or the <a href="http://www.opensource.org/licenses/artistic-license.php">Perl Artistic Licence</a>.
</div>
</div>
<div id="palette">
<ul>
<li class="first"><a href="#" class="blue" onclick="set_style('Clear Blue')"></a></li>
<li><a href="#" class="orange" onclick="set_style('Clear Orange')"></a></li>
<li><a href="#" class="green" onclick="set_style('Clear Green')"></a></li>
<li><a href="#" class="purple" onclick="set_style('Clear Purple')"></a></li>
<li><a href="#" class="grey" onclick="set_style('Clear Grey')"></a></li>
</ul>
</div>
</div> </body>
</html>
|
