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