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