df6462395d2d85006ff987a2c93408199ac0c891
[privoxy.git] / doc / webserver / user-manual / templates.html
1 <HTML
2 ><HEAD
3 ><TITLE
4 >Templates</TITLE
5 ><META
6 NAME="GENERATOR"
7 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
8 "><LINK
9 REL="HOME"
10 TITLE="Privoxy 3.1.1 User Manual"
11 HREF="index.html"><LINK
12 REL="PREVIOUS"
13 TITLE="The Filter File"
14 HREF="filter-file.html"><LINK
15 REL="NEXT"
16 TITLE="Contacting the Developers, Bug Reporting and Feature
17 Requests"
18 HREF="contact.html"><LINK
19 REL="STYLESHEET"
20 TYPE="text/css"
21 HREF="../p_doc.css"></HEAD
22 ><BODY
23 CLASS="SECT1"
24 BGCOLOR="#EEEEEE"
25 TEXT="#000000"
26 LINK="#0000FF"
27 VLINK="#840084"
28 ALINK="#0000FF"
29 ><DIV
30 CLASS="NAVHEADER"
31 ><TABLE
32 SUMMARY="Header navigation table"
33 WIDTH="100%"
34 BORDER="0"
35 CELLPADDING="0"
36 CELLSPACING="0"
37 ><TR
38 ><TH
39 COLSPAN="3"
40 ALIGN="center"
41 >Privoxy 3.1.1 User Manual</TH
42 ></TR
43 ><TR
44 ><TD
45 WIDTH="10%"
46 ALIGN="left"
47 VALIGN="bottom"
48 ><A
49 HREF="filter-file.html"
50 ACCESSKEY="P"
51 >Prev</A
52 ></TD
53 ><TD
54 WIDTH="80%"
55 ALIGN="center"
56 VALIGN="bottom"
57 ></TD
58 ><TD
59 WIDTH="10%"
60 ALIGN="right"
61 VALIGN="bottom"
62 ><A
63 HREF="contact.html"
64 ACCESSKEY="N"
65 >Next</A
66 ></TD
67 ></TR
68 ></TABLE
69 ><HR
70 ALIGN="LEFT"
71 WIDTH="100%"></DIV
72 ><DIV
73 CLASS="SECT1"
74 ><H1
75 CLASS="SECT1"
76 ><A
77 NAME="TEMPLATES">10. Templates</H1
78 ><P
79 > All <SPAN
80 CLASS="APPLICATION"
81 >Privoxy</SPAN
82 > built-in pages, i.e. error pages such as the 
83  <A
84 HREF="http://show-the-404-error.page"
85 TARGET="_top"
86 ><SPAN
87 CLASS="QUOTE"
88 >"404 - No Such Domain"</SPAN
89 >
90  error page</A
91 >, the <A
92 HREF="http://ads.bannerserver.example.com/nasty-ads/sponsor.html"
93 TARGET="_top"
94 ><SPAN
95 CLASS="QUOTE"
96 >"BLOCKED"</SPAN
97 >
98  page</A
99 >
100  and all pages of its <A
101 HREF="http://config.privoxy.org/"
102 TARGET="_top"
103 >web-based
104  user interface</A
105 >, are generated from <SPAN
106 CLASS="emphasis"
107 ><I
108 CLASS="EMPHASIS"
109 >templates</I
110 ></SPAN
111 >. 
112  (<SPAN
113 CLASS="APPLICATION"
114 >Privoxy</SPAN
115 > must be running for the above links to work as
116  intended.)</P
117 ><P
118 > These templates are stored in a subdirectory of the <A
119 HREF="config.html#CONFDIR"
120 >configuration
121  directory</A
122 > called <TT
123 CLASS="FILENAME"
124 >templates</TT
125 >. On Unixish platforms,
126  this is typically
127  <A
128 HREF="file:///etc/privoxy/templates/"
129 TARGET="_top"
130 ><TT
131 CLASS="FILENAME"
132 >/etc/privoxy/templates/</TT
133 ></A
134 >.</P
135 ><P
136 > The templates are basically normal HTML files, but with place-holders (called symbols
137  or exports), which <SPAN
138 CLASS="APPLICATION"
139 >Privoxy</SPAN
140 > fills at run time. You can
141  edit the templates with a normal text editor, should you want to customize them.
142  (<SPAN
143 CLASS="emphasis"
144 ><I
145 CLASS="EMPHASIS"
146 >Not recommended for the casual user</I
147 ></SPAN
148 >). Note that
149  just like in configuration files, lines starting with <TT
150 CLASS="LITERAL"
151 >#</TT
152 > are
153  ignored when the templates are filled in.</P
154 ><P
155 > The place-holders are of the form <TT
156 CLASS="LITERAL"
157 >@name@</TT
158 >, and you will
159  find a list of available symbols, which vary from template to template,
160  in the comments at the start of each file. Note that these comments are not
161  always accurate, and that it's probably best to look at the existing HTML
162  code to find out which symbols are supported and what they are filled in with.</P
163 ><P
164 > A special application of this substitution mechanism is to make whole
165  blocks of HTML code disappear when a specific symbol is set. We use this
166  for many purposes, one of them being to include the beta warning in all
167  our user interface (CGI) pages when <SPAN
168 CLASS="APPLICATION"
169 >Privoxy</SPAN
170 >
171  in in an alpha or beta development stage:</P
172 ><P
173 > <TABLE
174 BORDER="0"
175 BGCOLOR="#E0E0E0"
176 WIDTH="100%"
177 ><TR
178 ><TD
179 ><PRE
180 CLASS="SCREEN"
181 >&#60;!-- @if-unstable-start --&#62;
182
183   ... beta warning HTML code goes here ...
184
185 &#60;!-- if-unstable-end@ --&#62;</PRE
186 ></TD
187 ></TR
188 ></TABLE
189 ></P
190 ><P
191 > If the "unstable" symbol is set, everything in between and including
192  <TT
193 CLASS="LITERAL"
194 >@if-unstable-start</TT
195 > and <TT
196 CLASS="LITERAL"
197 >if-unstable-end@</TT
198 >
199  will disappear, leaving nothing but an empty comment:</P
200 ><P
201 > <TABLE
202 BORDER="0"
203 BGCOLOR="#E0E0E0"
204 WIDTH="100%"
205 ><TR
206 ><TD
207 ><PRE
208 CLASS="SCREEN"
209 >&#60;!--  --&#62;</PRE
210 ></TD
211 ></TR
212 ></TABLE
213 ></P
214 ><P
215 > There's also an if-then-else construct and an <TT
216 CLASS="LITERAL"
217 >#include</TT
218 >
219  mechanism, but you'll sure find out if you are inclined to edit the
220  templates ;-)</P
221 ><P
222 > All templates refer to a style located at
223  <A
224 HREF="http://config.privoxy.org/send-stylesheet"
225 TARGET="_top"
226 ><TT
227 CLASS="LITERAL"
228 >http://config.privoxy.org/send-stylesheet</TT
229 ></A
230 >.
231  This is, of course, locally served by <SPAN
232 CLASS="APPLICATION"
233 >Privoxy</SPAN
234 >
235  and the source for it can be found and edited in the
236  <TT
237 CLASS="FILENAME"
238 >cgi-style.css</TT
239 > template.</P
240 ></DIV
241 ><DIV
242 CLASS="NAVFOOTER"
243 ><HR
244 ALIGN="LEFT"
245 WIDTH="100%"><TABLE
246 SUMMARY="Footer navigation table"
247 WIDTH="100%"
248 BORDER="0"
249 CELLPADDING="0"
250 CELLSPACING="0"
251 ><TR
252 ><TD
253 WIDTH="33%"
254 ALIGN="left"
255 VALIGN="top"
256 ><A
257 HREF="filter-file.html"
258 ACCESSKEY="P"
259 >Prev</A
260 ></TD
261 ><TD
262 WIDTH="34%"
263 ALIGN="center"
264 VALIGN="top"
265 ><A
266 HREF="index.html"
267 ACCESSKEY="H"
268 >Home</A
269 ></TD
270 ><TD
271 WIDTH="33%"
272 ALIGN="right"
273 VALIGN="top"
274 ><A
275 HREF="contact.html"
276 ACCESSKEY="N"
277 >Next</A
278 ></TD
279 ></TR
280 ><TR
281 ><TD
282 WIDTH="33%"
283 ALIGN="left"
284 VALIGN="top"
285 >The Filter File</TD
286 ><TD
287 WIDTH="34%"
288 ALIGN="center"
289 VALIGN="top"
290 >&nbsp;</TD
291 ><TD
292 WIDTH="33%"
293 ALIGN="right"
294 VALIGN="top"
295 >Contacting the Developers, Bug Reporting and Feature
296 Requests</TD
297 ></TR
298 ></TABLE
299 ></DIV
300 ></BODY
301 ></HTML
302 >