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.17 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.17 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 >