/[gedafe]/trunk/doc/cpptemplate.txt
This is repository of my old source code which isn't updated any more. Go to git.rot13.org for current projects!
ViewVC logotype

Annotation of /trunk/doc/cpptemplate.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1 - (hide annotations)
Mon Feb 14 18:52:26 2005 UTC (14 years, 9 months ago) by dpavlin
File MIME type: text/plain
File size: 6583 byte(s)
import of Gedafe 1.2.2

1 dpavlin 1 Text::CPPTemplate(3) gedafe Text::CPPTemplate(3)
2    
3    
4    
5     NAME
6     Text::CPPTemplate - CPP-Style Templates
7    
8     SYNOPSIS
9     use Text::CPPTemplate;
10    
11     my $templ = new Text::CPPTemplate('/var/web/templates','.html');
12    
13     print $templ->template({
14     PAGE => 'index',
15     ELEMENT => 'header',
16     TITLE => 'Test'
17     });
18    
19     DESCRIPTION
20     CPPTemplate is a templating system using a CPP-style (C
21     Pre-Processor) syntax. CPPTemplate is quite fast so that
22     it can be used in online Applications such as CGI scripts
23     to separate program the code from the HTML. CPPTemplate is
24     not HTML specific, so it can be used for other applica-
25     tions. For performance reasons, the files containing the
26     templates are read only once and are cached for further
27     use. This is especially handy when working with long run-
28     ning scripts which use the same template over and over
29     again. Apache mod_perl is such an environment.
30    
31     An application can use a large number of templates. They
32     could for example represent different parts of output gen-
33     erated by the aplication. Each template can contain vari-
34     ables and CPP style if-then-else structures. When the
35     template gets activated, all the variables will get sub-
36     stituted and the if-then-else structures will get pro-
37     cessed.
38    
39     FILE NAMES
40     When you activate a template, you do not specify a
41     file-name, but only variables. Based on the contents of
42     some special variables, CPPTemplate will try to load an
43     apropriate template file from disk. It tries to do this
44     using a number of different file-names. The first one to
45     exist will be used. A directory where the templates
46     reside and a suffix have to be specified with the "new"
47     method. The following list shows which variables cause
48     CPPTemplate to look for which files:
49    
50     o PAGE_ELEMENT (PAGE and ELEMENT are variables)
51    
52     o ELEMENT
53    
54     o PAGE
55    
56     o "default" (as is, not a variable)
57    
58     In addition, if THEME is specified, the template will be
59     first searched in the subdirectory specified by that vari-
60     able of the templates directory.
61    
62     In the example given in SYNOPSIS, the following files will
63     be opened in turn until one is found to exist (in the
64     directory /var/web/templates): index_header.html,
65     header.html, index.html and default.html.
66    
67     VARIABLE SUBSTITUTION
68     Variables are marked "##var##" in the templates. If no
69     variable is found with that specified name, the ##var##
70     text remains unchanged.
71    
72     CPP-STYLE DIRECTIVES
73     "MiniCPP" directives permit the selection of parts of the
74     template based on some condition. The language is very
75     very basic, it seems to be good-enough for most applica-
76     tions. The following directives are supported:
77    
78     "// comment"
79     The whole line is removed from the output
80    
81     "#ifdef VAR"
82     If variable VAR is defined, the following text will be
83     selected.
84    
85     "#if expr"
86     If the expression "expr" evaluates to true (see
87     "EXPRESSIONS"), the following text will be selected.
88     You can use substitutions in the expression with the
89     syntax '##VAR##'.
90    
91     "#elif expr"
92     If the previous "#if" (or "#elif") expression was
93     false, evaluate this "expr" and if true select the
94     following text.
95    
96     "#else"
97     If the previous "#if" (or "#elif") expression was
98     false, select the following text.
99    
100     "#endif"
101     Ends an "#ifdef" or an "#if".
102    
103     Note that these elements can be nested.
104    
105     The newlines will be removed unless two consecutive lines
106     without MiniCPP directives are found. Spaces and tabs will
107     be removed from the beginning and the end of each line.
108     Use '\ ' (backslash space) to insert spaces at the begin-
109     ning or the end of the line.
110    
111     EXPRESSIONS
112     At the moment only the following expressions are supported
113     (don't laugh :-))
114    
115     A = B
116     If A is equal to B (the text), then the expression is
117     true.
118    
119     A ~ B
120     Match A against the regular expression (perl) B. True
121     if it does match, false otherwise.
122    
123     EXAMPLE
124    
125    
126    
127    
128    
129    
130    
131    
132    
133     #if ##ELEMENT## = ruler
134     <HR>
135     #elif ##ELEMENT## = buttons
136     #ifdef ADD_URL
137     <A href="##ADD_URL##">Add</A>
138     #endif
139     #ifdef PREV_URL
140     <A href="##PREV_URL##">Prev</A>
141     #endif
142     #ifdef NEXT_URL
143     <A href="##NEXT_URL##">Next</A>
144     #endif
145     </P>
146     #endif
147    
148     PER-METHOD DOCUMENTATION
149     "new($templates_dir, $suffix)"
150     Create a new CPPTemplate object. $templates_dir is the
151     directory where the templates are stored and $suffix
152     is a text to append to the file-names.
153    
154     "template(\%vars)"
155     Return a processed template. "\%vars" is a hashref
156     containing the variables used for building the
157     file-name, for the substitutions and the CPP-style
158     directives.
159    
160     SEE ALSO
161     Text::TagTemplate(3)
162    
163     COPYRIGHT
164     Copyright (c) 2000 ETH Zurich, All rights reserved.
165    
166     LICENSE
167     This program is free software; you can redistribute it
168     and/or modify it under the terms of the GNU General Public
169     License as published by the Free Software Foundation;
170     either version 2 of the License, or (at your option) any
171     later version.
172    
173     This program is distributed in the hope that it will be
174     useful, but WITHOUT ANY WARRANTY; without even the implied
175     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
176     PURPOSE. See the GNU General Public License for more
177     details.
178    
179     You should have received a copy of the GNU General Public
180     License along with this program; if not, write to the Free
181     Software Foundation, Inc., 675 Mass Ave, Cambridge, MA
182     02139, USA. This library is free software; you can redis-
183     tribute it and/or modify it under the terms of the GNU
184     Lesser General Public License as published by the Free
185     Software Foundation; either version 2.1 of the License, or
186     (at your option) any later version.
187    
188     AUTHOR
189     David Schweikert <dws@ee.ethz.ch>, Tobi Oetiker
190     <oetiker@ee.ethz.ch>
191    
192    
193    
194     0.3 2000-10-22 Text::CPPTemplate(3)

  ViewVC Help
Powered by ViewVC 1.1.26