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