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.27 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.27 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 ><TABLE
 192 BORDER="0"
 193 BGCOLOR="#E0E0E0"
 194 WIDTH="100%"
 195 ><TR
 196 ><TD
 197 ><PRE
 198 CLASS="SCREEN"
 199 >&#60;!-- @if-unstable-start --&#62;
 200
 201   ... beta warning HTML code goes here ...
 202
 203 &#60;!-- if-unstable-end@ --&#62;</PRE
 204 ></TD
 205 ></TR
 206 ></TABLE
 207 ><P
 208 > If the "unstable" symbol is set, everything in between and including
 209  <TT
 210 CLASS="LITERAL"
 211 >@if-unstable-start</TT
 212 > and <TT
 213 CLASS="LITERAL"
 214 >if-unstable-end@</TT
 215 >
 216  will disappear, leaving nothing but an empty comment:</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 > There's also an if-then-else construct and an <TT
 231 CLASS="LITERAL"
 232 >#include</TT
 233 >
 234  mechanism, but you'll sure find out if you are inclined to edit the
 235  templates ;-)</P
 236 ><P
 237 > All templates refer to a style located at
 238  <A
 239 HREF="http://config.privoxy.org/send-stylesheet"
 240 TARGET="_top"
 241 ><TT
 242 CLASS="LITERAL"
 243 >http://config.privoxy.org/send-stylesheet</TT
 244 ></A
 245 >.
 246  This is, of course, locally served by <SPAN
 247 CLASS="APPLICATION"
 248 >Privoxy</SPAN
 249 >
 250  and the source for it can be found and edited in the
 251  <TT
 252 CLASS="FILENAME"
 253 >cgi-style.css</TT
 254 > template.</P
 255 ></DIV
 256 ><DIV
 257 CLASS="NAVFOOTER"
 258 ><HR
 259 ALIGN="LEFT"
 260 WIDTH="100%"><TABLE
 261 SUMMARY="Footer navigation table"
 262 WIDTH="100%"
 263 BORDER="0"
 264 CELLPADDING="0"
 265 CELLSPACING="0"
 266 ><TR
 267 ><TD
 268 WIDTH="33%"
 269 ALIGN="left"
 270 VALIGN="top"
 271 ><A
 272 HREF="filter-file.html"
 273 ACCESSKEY="P"
 274 >Prev</A
 275 ></TD
 276 ><TD
 277 WIDTH="34%"
 278 ALIGN="center"
 279 VALIGN="top"
 280 ><A
 281 HREF="index.html"
 282 ACCESSKEY="H"
 283 >Home</A
 284 ></TD
 285 ><TD
 286 WIDTH="33%"
 287 ALIGN="right"
 288 VALIGN="top"
 289 ><A
 290 HREF="contact.html"
 291 ACCESSKEY="N"
 292 >Next</A
 293 ></TD
 294 ></TR
 295 ><TR
 296 ><TD
 297 WIDTH="33%"
 298 ALIGN="left"
 299 VALIGN="top"
 300 >Filter Files</TD
 301 ><TD
 302 WIDTH="34%"
 303 ALIGN="center"
 304 VALIGN="top"
 305 >&nbsp;</TD
 306 ><TD
 307 WIDTH="33%"
 308 ALIGN="right"
 309 VALIGN="top"
 310 >Contacting the Developers, Bug Reporting and Feature
 311 Requests</TD
 312 ></TR
 313 ></TABLE
 314 ></DIV
 315 ></BODY
 316 ></HTML
 317 >