doc/webserver/user-manual/templates.html

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