doc/webserver/user-manual/templates.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   2 "http://www.w3.org/TR/html4/loose.dtd">
   3 <html>
   4 <head>
   5   <title>Privoxy's Template Files</title>
   6   <meta name="GENERATOR" content="Modular DocBook HTML Stylesheet Version 1.79">
   7   <link rel="HOME" title="Privoxy 3.0.34 User Manual" href="index.html">
   8   <link rel="PREVIOUS" title="Filter Files" href="filter-file.html">
   9   <link rel="NEXT" title="Contacting the Developers, Bug Reporting and Feature Requests" href="contact.html">
  10   <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
  11   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  12   <link rel="STYLESHEET" type="text/css" href="p_doc.css">
  13 </head>
  14 <body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink="#840084" alink="#0000FF">
  15   <div class="NAVHEADER">
  16     <table summary="Header navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
  17       <tr>
  18         <th colspan="3" align="center">Privoxy 3.0.34 User Manual</th>
  19       </tr>
  20       <tr>
  21         <td width="10%" align="left" valign="bottom"><a href="filter-file.html" accesskey="P">Prev</a></td>
  22         <td width="80%" align="center" valign="bottom"></td>
  23         <td width="10%" align="right" valign="bottom"><a href="contact.html" accesskey="N">Next</a></td>
  24       </tr>
  25     </table>
  26     <hr align="left" width="100%">
  27   </div>
  28   <div class="SECT1">
  29     <h1 class="SECT1"><a name="TEMPLATES" id="TEMPLATES">10. Privoxy's Template Files</a></h1>
  30     <p>All <span class="APPLICATION">Privoxy</span> built-in pages, i.e. error pages such as the <a href=
  31     "http://show-the-404-error.page" target="_top"><span class="QUOTE">"404 - No Such Domain"</span> error page</a>,
  32     the <a href="http://ads.bannerserver.example.com/nasty-ads/sponsor.html" target="_top"><span class=
  33     "QUOTE">"BLOCKED"</span> page</a> and all pages of its <a href="http://config.privoxy.org/" target="_top">web-based
  34     user interface</a>, are generated from <span class="emphasis"><i class="EMPHASIS">templates</i></span>.
  35     (<span class="APPLICATION">Privoxy</span> must be running for the above links to work as intended.)</p>
  36     <p>These templates are stored in a subdirectory of the <a href="config.html#CONFDIR">configuration directory</a>
  37     called <tt class="FILENAME">templates</tt>. On Unixish platforms, this is typically <a href=
  38     "file:///etc/privoxy/templates/" target="_top"><tt class="FILENAME">/etc/privoxy/templates/</tt></a>.</p>
  39     <p>The templates are basically normal HTML files, but with place-holders (called symbols or exports), which
  40     <span class="APPLICATION">Privoxy</span> fills at run time. It is possible to edit the templates with a normal text
  41     editor, should you want to customize them. (<span class="emphasis"><i class="EMPHASIS">Not recommended for the
  42     casual user</i></span>). Should you create your own custom templates, you should use the <tt class=
  43     "FILENAME">config</tt> setting <a href="config.html#TEMPLDIR">templdir</a> to specify an alternate location, so
  44     your templates do not get overwritten during upgrades.</p>
  45     <p>Note that just like in configuration files, lines starting with <tt class="LITERAL">#</tt> are ignored when the
  46     templates are filled in.</p>
  47     <p>The place-holders are of the form <tt class="LITERAL">@name@</tt>, and you will find a list of available
  48     symbols, which vary from template to template, in the comments at the start of each file. Note that these comments
  49     are not always accurate, and that it's probably best to look at the existing HTML code to find out which symbols
  50     are supported and what they are filled in with.</p>
  51     <p>A special application of this substitution mechanism is to make whole blocks of HTML code disappear when a
  52     specific symbol is set. We use this for many purposes, one of them being to include the beta warning in all our
  53     user interface (CGI) pages when <span class="APPLICATION">Privoxy</span> is in an alpha or beta development
  54     stage:</p>
  55     <table border="0" bgcolor="#E0E0E0" width="100%">
  56       <tr>
  57         <td>
  58           <pre class="SCREEN">  &lt;!-- @if-unstable-start --&gt;
  59
  60     ... beta warning HTML code goes here ...
  61
  62   &lt;!-- if-unstable-end@ --&gt;</pre>
  63         </td>
  64       </tr>
  65     </table>
  66     <p>If the "unstable" symbol is set, everything in between and including <tt class="LITERAL">@if-unstable-start</tt>
  67     and <tt class="LITERAL">if-unstable-end@</tt> will disappear, leaving nothing but an empty comment:</p>
  68     <table border="0" bgcolor="#E0E0E0" width="100%">
  69       <tr>
  70         <td>
  71           <pre class="SCREEN">  &lt;!--  --&gt;</pre>
  72         </td>
  73       </tr>
  74     </table>
  75     <p>There's also an if-then-else construct and an <tt class="LITERAL">#include</tt> mechanism, but you'll sure find
  76     out if you are inclined to edit the templates ;-)</p>
  77     <p>All templates refer to a style located at <a href="http://config.privoxy.org/send-stylesheet" target=
  78     "_top"><tt class="LITERAL">http://config.privoxy.org/send-stylesheet</tt></a>. This is, of course, locally served
  79     by <span class="APPLICATION">Privoxy</span> and the source for it can be found and edited in the <tt class=
  80     "FILENAME">cgi-style.css</tt> template.</p>
  81   </div>
  82   <div class="NAVFOOTER">
  83     <hr align="left" width="100%">
  84     <table summary="Footer navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
  85       <tr>
  86         <td width="33%" align="left" valign="top"><a href="filter-file.html" accesskey="P">Prev</a></td>
  87         <td width="34%" align="center" valign="top"><a href="index.html" accesskey="H">Home</a></td>
  88         <td width="33%" align="right" valign="top"><a href="contact.html" accesskey="N">Next</a></td>
  89       </tr>
  90       <tr>
  91         <td width="33%" align="left" valign="top">Filter Files</td>
  92         <td width="34%" align="center" valign="top">&nbsp;</td>
  93         <td width="33%" align="right" valign="top">Contacting the Developers, Bug Reporting and Feature Requests</td>
  94       </tr>
  95     </table>
  96   </div>
  97 </body>
  98 </html>