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.8 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.8 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 >10. Privoxy's Template Files</A
  81 ></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. It
 145  is possible to edit the templates with a normal text editor, should you want
 146  to customize them. (<SPAN
 147 CLASS="emphasis"
 148 ><I
 149 CLASS="EMPHASIS"
 150 >Not recommended for the casual
 151  user</I
 152 ></SPAN
 153 >). Should you create your own custom templates, you should use
 154  the <TT
 155 CLASS="FILENAME"
 156 >config</TT
 157 > setting <A
 158 HREF="config.html#TEMPLDIR"
 159 >templdir</A
 160 >
 161  to specify an alternate location, so your templates do not get overwritten
 162  during upgrades.
 163  </P
 164 ><P
 165 > Note that just like in configuration files, lines starting
 166  with <TT
 167 CLASS="LITERAL"
 168 >#</TT
 169 > are ignored when the templates are filled in.</P
 170 ><P
 171 > The place-holders are of the form <TT
 172 CLASS="LITERAL"
 173 >@name@</TT
 174 >, and you will
 175  find a list of available symbols, which vary from template to template,
 176  in the comments at the start of each file. Note that these comments are not
 177  always accurate, and that it's probably best to look at the existing HTML
 178  code to find out which symbols are supported and what they are filled in with.</P
 179 ><P
 180 > A special application of this substitution mechanism is to make whole
 181  blocks of HTML code disappear when a specific symbol is set. We use this
 182  for many purposes, one of them being to include the beta warning in all
 183  our user interface (CGI) pages when <SPAN
 184 CLASS="APPLICATION"
 185 >Privoxy</SPAN
 186 >
 187  is in an alpha or beta development stage:</P
 188 ><P
 189 > <TABLE
 190 BORDER="0"
 191 BGCOLOR="#E0E0E0"
 192 WIDTH="100%"
 193 ><TR
 194 ><TD
 195 ><PRE
 196 CLASS="SCREEN"
 197 >&#60;!-- @if-unstable-start --&#62;
 198
 199   ... beta warning HTML code goes here ...
 200
 201 &#60;!-- if-unstable-end@ --&#62;</PRE
 202 ></TD
 203 ></TR
 204 ></TABLE
 205 ></P
 206 ><P
 207 > If the "unstable" symbol is set, everything in between and including
 208  <TT
 209 CLASS="LITERAL"
 210 >@if-unstable-start</TT
 211 > and <TT
 212 CLASS="LITERAL"
 213 >if-unstable-end@</TT
 214 >
 215  will disappear, leaving nothing but an empty comment:</P
 216 ><P
 217 > <TABLE
 218 BORDER="0"
 219 BGCOLOR="#E0E0E0"
 220 WIDTH="100%"
 221 ><TR
 222 ><TD
 223 ><PRE
 224 CLASS="SCREEN"
 225 >&#60;!--  --&#62;</PRE
 226 ></TD
 227 ></TR
 228 ></TABLE
 229 ></P
 230 ><P
 231 > There's also an if-then-else construct and an <TT
 232 CLASS="LITERAL"
 233 >#include</TT
 234 >
 235  mechanism, but you'll sure find out if you are inclined to edit the
 236  templates ;-)</P
 237 ><P
 238 > All templates refer to a style located at
 239  <A
 240 HREF="http://config.privoxy.org/send-stylesheet"
 241 TARGET="_top"
 242 ><TT
 243 CLASS="LITERAL"
 244 >http://config.privoxy.org/send-stylesheet</TT
 245 ></A
 246 >.
 247  This is, of course, locally served by <SPAN
 248 CLASS="APPLICATION"
 249 >Privoxy</SPAN
 250 >
 251  and the source for it can be found and edited in the
 252  <TT
 253 CLASS="FILENAME"
 254 >cgi-style.css</TT
 255 > template.</P
 256 ></DIV
 257 ><DIV
 258 CLASS="NAVFOOTER"
 259 ><HR
 260 ALIGN="LEFT"
 261 WIDTH="100%"><TABLE
 262 SUMMARY="Footer navigation table"
 263 WIDTH="100%"
 264 BORDER="0"
 265 CELLPADDING="0"
 266 CELLSPACING="0"
 267 ><TR
 268 ><TD
 269 WIDTH="33%"
 270 ALIGN="left"
 271 VALIGN="top"
 272 ><A
 273 HREF="filter-file.html"
 274 ACCESSKEY="P"
 275 >Prev</A
 276 ></TD
 277 ><TD
 278 WIDTH="34%"
 279 ALIGN="center"
 280 VALIGN="top"
 281 ><A
 282 HREF="index.html"
 283 ACCESSKEY="H"
 284 >Home</A
 285 ></TD
 286 ><TD
 287 WIDTH="33%"
 288 ALIGN="right"
 289 VALIGN="top"
 290 ><A
 291 HREF="contact.html"
 292 ACCESSKEY="N"
 293 >Next</A
 294 ></TD
 295 ></TR
 296 ><TR
 297 ><TD
 298 WIDTH="33%"
 299 ALIGN="left"
 300 VALIGN="top"
 301 >Filter Files</TD
 302 ><TD
 303 WIDTH="34%"
 304 ALIGN="center"
 305 VALIGN="top"
 306 >&nbsp;</TD
 307 ><TD
 308 WIDTH="33%"
 309 ALIGN="right"
 310 VALIGN="top"
 311 >Contacting the Developers, Bug Reporting and Feature
 312 Requests</TD
 313 ></TR
 314 ></TABLE
 315 ></DIV
 316 ></BODY
 317 ></HTML
 318 >