home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / tsw / TSW_3.4.0.exe / Apache2 / perl / Syntax.pod < prev    next >
Encoding:
Text File  |  2004-01-30  |  8.2 KB  |  307 lines
  1. #============================================================= -*-perl-*-
  2. #
  3. # Template::Manual::Syntax
  4. #
  5. # DESCRIPTION
  6. #   This section describes the syntax, structure and semantics of the
  7. #   Template Toolkit directives and general presentation language.
  8. #
  9. # AUTHOR
  10. #   Andy Wardley  <abw@andywardley.com>
  11. #
  12. # COPYRIGHT
  13. #   Copyright (C) 1996-2001 Andy Wardley.  All Rights Reserved.
  14. #   Copyright (C) 1998-2001 Canon Research Centre Europe Ltd.
  15. #
  16. #   This module is free software; you can redistribute it and/or
  17. #   modify it under the same terms as Perl itself.
  18. #
  19. # REVISION
  20. #   
  21. #
  22. #========================================================================
  23.  
  24.  
  25. #------------------------------------------------------------------------
  26. # IMPORTANT NOTE
  27. #   This documentation is generated automatically from source
  28. #   templates.  Any changes you make here may be lost.
  29. # 
  30. #   The 'docsrc' documentation source bundle is available for download
  31. #   from http://www.template-toolkit.org/docs.html and contains all
  32. #   the source templates, XML files, scripts, etc., from which the
  33. #   documentation for the Template Toolkit is built.
  34. #------------------------------------------------------------------------
  35.  
  36. =head1 NAME
  37.  
  38. Template::Manual::Syntax - Directive syntax, structure and semantics
  39.  
  40. =head1 DESCRIPTION
  41.  
  42. This section describes the syntax, structure and semantics of the
  43. Template Toolkit directives and general presentation language.
  44.  
  45. =head2 Tag Styles
  46.  
  47. By default, template directives are embedded within the character sequences
  48. '[%' and '%]'.  e.g.
  49.  
  50.     [% PROCESS header %]
  51.   
  52.     <h1>Hello World!</h1>
  53.     <a href="[% page.next %]"><img src="[% icon.next %].gif"></a>
  54.   
  55.     [% PROCESS footer %]
  56.  
  57. You can change the tag characters using the START_TAG, END_TAG and
  58. TAG_STYLE configuration options.  You can also use the TAGS directive
  59. to define a new tag style for the current template file.
  60.  
  61. You can also set the INTERPOLATE option to allow simple variable
  62. references to be embedded directly in templates, prefixed by a '$'.
  63.  
  64.     # INTERPOLATE => 0
  65.     <td>[% name %]</td>  <td>[% email %]</td>
  66.  
  67.     # INTERPOLATE => 1
  68.     <td>$name</td>  <td>$email</td>
  69.  
  70. Directives may be embedded anywhere in a line of text and can be split
  71. across several lines.  Insignificant whitespace is generally ignored
  72. within the directive.
  73.  
  74.     [% INCLUDE header           
  75.        title = 'Hello World' 
  76.        bgcol = '#ffffff' 
  77.     %]
  78.   
  79.     [%INCLUDE menu align='right'%]
  80.   
  81.     Name: [% name %]  ([%id%])
  82.  
  83. =head2 Comments
  84.  
  85. The '#' character is used to indicate comments within a directive.
  86. When placed immediately inside the opening directive tag, it causes
  87. the entire directive to be ignored.
  88.  
  89.     [%# this entire directive is ignored no
  90.         matter how many lines it wraps onto
  91.     %]
  92.  
  93. In any other position, it causes the remainder of the current line to 
  94. be treated as a comment.
  95.  
  96.     [% # this is a comment
  97.        theta = 20      # so is this
  98.        rho   = 30      # <aol>me too!</aol>
  99.     %]
  100.  
  101. =head2 Chomping Whitespace
  102.  
  103. You can add '-' or '+' to the immediate start or end of a directive
  104. tag to control the whitespace chomping options.  See the PRE_CHOMP and
  105. POST_CHOMP options for further details.
  106.  
  107.     [% BLOCK foo -%]        # remove trailing newline
  108.     This is block foo
  109.     [%- END %]            # remove leading newline
  110.  
  111. =head2 Implicit Directives: GET and SET
  112.  
  113. The simplest directives are GET and SET which retrieve and update
  114. variable values respectively.  The GET and SET keywords are actually
  115. optional as the parser is smart enough to see them for what they
  116. really are (but note the caveat below on using side-effect notation).
  117. Thus, you'll generally see:
  118.  
  119.     [% SET foo = 10 %]
  120.     [% GET foo %]
  121.  
  122. written as:
  123.  
  124.     [% foo = 10 %]
  125.     [% foo %]
  126.  
  127. You can also express simple logical statements as implicit GET directives:
  128.  
  129.     [% title or template.title or 'Default Title' %]
  130.  
  131.     [% mode == 'graphics' ? "Graphics Mode Enabled" : "Text Mode" %]
  132.  
  133. All other directives should start with a keyword specified in UPPER
  134. CASE (but see the ANYCASE option).  All directives keywords are in
  135. UPPER CASE to make them visually distinctive and to distinguish them
  136. from variables of the same name but different case.  It is perfectly
  137. valid, for example, to define a variable called 'stop' which is
  138. entirely separate from the STOP directive.
  139.  
  140.     [% stop = 'Clackett Lane Bus Depot' %]
  141.  
  142.     The bus will next stop at [% stop %]    # variable
  143.  
  144.     [% STOP %]                              # directive
  145.  
  146. =head2 Block Directives
  147.  
  148. Directives such as FOREACH, WHILE, BLOCK, FILTER, etc., mark the start
  149. of a block which may contain text or other directives up to the
  150. matching END directive.  Blocks may be nested indefinitely.  The
  151. IF, UNLESS, ELSIF and ELSE directives also define blocks and may be
  152. grouped together in the usual manner.
  153.  
  154.     [% FOREACH item = [ 'foo' 'bar' 'baz' ] %]
  155.        * Item: [% item %]
  156.     [% END %]
  157.   
  158.     [% BLOCK footer %]
  159.        Copyright 2000 [% me %]
  160.        [% INCLUDE company/logo %]
  161.     [% END %]
  162.   
  163.     [% IF foo %]
  164.        [% FOREACH thing = foo.things %]
  165.       [% thing %]
  166.        [% END %]
  167.     [% ELSIF bar %]
  168.        [% INCLUDE barinfo %]
  169.     [% ELSE %]
  170.        do nothing...
  171.     [% END %]
  172.  
  173. Block directives can also be used in a convenient side-effect notation.
  174.  
  175.     [% INCLUDE userinfo FOREACH user = userlist %]
  176.  
  177.     [% INCLUDE debugtxt msg="file: $error.info" 
  178.          IF debugging %] 
  179.  
  180.     [% "Danger Will Robinson" IF atrisk %]
  181.  
  182. versus:
  183.  
  184.     [% FOREACH user = userlist %]
  185.        [% INCLUDE userinfo %]
  186.     [% END %]
  187.  
  188.     [% IF debugging %]
  189.        [% INCLUDE debugtxt msg="file: $error.info" %]
  190.     [% END %]
  191.  
  192.     [% IF atrisk %]
  193.     Danger Will Robinson
  194.     [% END %]
  195.  
  196. =head2 Capturing Block Output
  197.  
  198. The output of a directive can be captured by simply assigning the directive
  199. to a variable.
  200.  
  201.     [% headtext = PROCESS header title="Hello World" %]
  202.  
  203.     [% people = PROCESS userinfo FOREACH user = userlist %]
  204.  
  205. This can be used in conjunction with the BLOCK directive for defining large 
  206. blocks of text or other content.
  207.  
  208.     [% poem = BLOCK %]
  209.        The boy stood on the burning deck,
  210.        His fleece was white as snow.
  211.        A rolling stone gathers no moss,
  212.        And Keith is sure to follow.
  213.     [% END %]
  214.  
  215. Note one important caveat of using this syntax in conjunction with side-effect
  216. notation.  The following directive does not behave as might be expected:
  217.  
  218.     [% var = 'value' IF some_condition %]
  219.  
  220. In this case, the directive is interpreted as (spacing added for clarity)
  221.  
  222.     [% var = IF some_condition %]
  223.        value
  224.     [% END %]
  225.  
  226. rather than
  227.  
  228.     [% IF some_condition %]
  229.        [% var = 'value' %]
  230.     [% END %]
  231.  
  232. The variable is assigned the output of the IF block which returns
  233. 'value' if true, but nothing if false.  In other words, the following
  234. directive will always cause 'var' to be cleared.
  235.  
  236.     [% var = 'value' IF 0 %]
  237.  
  238. To achieve the expected behaviour, the directive should be written as:
  239.  
  240.     [% SET var = 'value' IF some_condition %]
  241.  
  242. =head2 Chaining Filters
  243.  
  244. Multiple FILTER directives can be chained together in sequence.  They
  245. are called in the order defined, piping the output of one into the 
  246. input of the next.
  247.  
  248.     [% PROCESS somefile FILTER truncate(100) FILTER html %]
  249.  
  250. The pipe character, '|', can also be used as an alias for FILTER.
  251.  
  252.     [% PROCESS somefile | truncate(100) | html %]
  253.  
  254. =head2 Multiple Directive Blocks
  255.  
  256. Multiple directives can be included within a single tag when delimited
  257. by semi-colons, ';'.  Note however that the TAGS directive must always
  258. be specified in a tag by itself.
  259.  
  260.     [% IF title; 
  261.           INCLUDE header; 
  262.        ELSE; 
  263.       INCLUDE other/header  title="Some Other Title";
  264.        END
  265.     %]
  266.  
  267. versus
  268.  
  269.     [% IF title %]
  270.        [% INCLUDE header %]
  271.     [% ELSE %]
  272.        [% INCLUDE other/header  title="Some Other Title" %]
  273.     [% END %]
  274.  
  275. =head1 AUTHOR
  276.  
  277. Andy Wardley E<lt>abw@andywardley.comE<gt>
  278.  
  279. L<http://www.andywardley.com/|http://www.andywardley.com/>
  280.  
  281.  
  282.  
  283.  
  284. =head1 VERSION
  285.  
  286. Template Toolkit version 2.13, released on 30 January 2004.
  287.  
  288. =head1 COPYRIGHT
  289.  
  290.   Copyright (C) 1996-2004 Andy Wardley.  All Rights Reserved.
  291.   Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.
  292.  
  293. This module is free software; you can redistribute it and/or
  294. modify it under the same terms as Perl itself.
  295.  
  296.  
  297.  
  298. =cut
  299.  
  300. # Local Variables:
  301. # mode: perl
  302. # perl-indent-level: 4
  303. # indent-tabs-mode: nil
  304. # End:
  305. #
  306. # vim: expandtab shiftwidth=4:
  307.