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