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