docs.xhtml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   3     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   4 <html
   5   xmlns="http://www.w3.org/1999/xhtml"
   6   xmlns:xi="http://www.w3.org/2001/XInclude"
   7   xml:lang="en">
   8 <head>
   9   <title>Documentation - HTML Purifier</title>
  10   <xi:include href="common-meta.xml" xpointer="xpointer(/*/node())" />
  11   <meta name="description" content="Documentation for HTML Purifier." />
  12   <meta name="keywords" content="HTMLPurifier, HTML Purifier, HTML, filter, filtering, standards, compliant, documentation, docs, manual" />
  13 </head>
  14 <body>
  15
  16 <xi:include href="common-header.xml" xpointer="xpointer(/*/node())" />
  17
  18 <div id="main">
  19 <h1 id="title">Documentation</h1>
  20
  21 <div id="content">
  22
  23 <p>
  24   HTML Purifier's documentation is organized by topic. New users should
  25   read the <a href="live/INSTALL">INSTALL</a> file that comes with your
  26   HTML Purifier download. Any questions about HTML Purifier can be asked
  27   at the <a href="http://htmlpurifier.org/phorum/">support forums</a> (no
  28   registration required!)
  29 </p>
  30
  31 <h2>For Advanced Users</h2>
  32
  33 <ul>
  34   <li><a href="docs/">End-User
  35       Documentation</a> &mdash; In-depth documents on how to get
  36       the most out of HTML Purifier. These are located in the <code>docs/</code>
  37       folder of your HTML Purifier installation.</li>
  38   <li><a href="live/configdoc/plain.html">Configuration
  39       documentation</a> &mdash; These are various configuration directives
  40       that can be used to customize HTML Purifier's behavior.</li>
  41   <li><a href="http://htmlpurifier.org/doxygen/html/">Doxygen-generated
  42       Documentation</a> &mdash; No class left undocumented!  Cross-referenced
  43       code!  A must-read for any prospective HTML Purifier hacker.
  44       (close by, <a href="http://htmlpurifier.org/phpdoc/">PHPDoc-generated
  45       Documentation.</a>)</li>
  46   <li><a href="live/smoketests/printDefinition.php">Print
  47       Definition</a> &mdash; If you want to actually see what HTML Purifier's
  48       filtering rules are, look no further than to this page. You can even
  49       experiment with the configuration to see how things respond to different
  50       directives.</li>
  51 </ul>
  52
  53 <p>
  54   P.S. HTML Purifier's source code is well documented and very readable.
  55   If a question of your isn't answered by any of the above resources,
  56   go to the source! (Or ask in the forums.)
  57 </p>
  58
  59 <h2>Frequently Asked Questions</h2>
  60
  61 <h3>What does %HTML.Allowed mean?</h3>
  62
  63 <p>
  64   The percent-dot format is a shorthand for HTML Purifier's configuration
  65   directives. It takes the form of %Namespace.Directive. For
  66   practical purposes, %HTML.Allowed translates into the following PHP
  67   code:
  68 </p>
  69
  70 <pre>$config->set('HTML', 'Allowed', $value);</pre>
  71
  72 <h3>My attributes are mysteriously disappearing!</h3>
  73
  74 <p>
  75   You've probably got <a href="http://php.net/manual/en/security.magicquotes.php">magic quotes</a>
  76   turned on, which is interfering with the single and double-quotes in
  77   <abbr>HTML</abbr> attributes. The usual way to fix this is
  78   <a href="http://php.net/manual/en/security.magicquotes.disabling.php">with
  79   some runtime code or an ini tweak.</a> Be sure not to introduce any
  80   <abbr>SQL</abbr> injection vulnerabilities!
  81 </p>
  82
  83 <h3>How do I prevent foreign characters like ä and <code>&amp;nbsp</code> from turning into Ã¤?</h3>
  84
  85 <p>
  86   This usually means that HTML Purifier is parsing your code as UTF-8, but
  87   your output encoding is something else. Read up <a href="docs/enduser-utf8.html">this
  88   document on UTF-8</a> to learn how to fix this. (Short answer: use
  89   %Core.Encoding or switch to UTF-8.)
  90 </p>
  91
  92 <h3>I can't use the <code>target</code> or <code>name</code> attribute in my <code>a</code> tags!</h3>
  93
  94 <p>
  95   The <code>target</code> attribute has been deprecated for a long time, so
  96   I highly recommend you look at other ways of, say, opening new windows
  97   when you click a link (my favorites are <q>Don't do it!</q> or, if you
  98   must, JavaScript) But if you must, the
  99   <a href="live/configdoc/plain.html#Attr.AllowedFrameTargets">%Attr.AllowedFrameTargets</a>
 100   directive is what you are looking for.
 101 </p>
 102
 103 <p>
 104   The <code>name</code> attribute is dependent on IDs being enabled.
 105   See <a href="docs/enduser-id.html">this document on enabling user IDs</a> for more information.
 106 </p>
 107
 108 <h3>Is HTML Purifier slow?</h3>
 109
 110 <p>
 111   HTML Purifier isn't exactly light or speedy; this is a tradeoff for the
 112   power and security the library affords. You can combat this by reading
 113   <a href="docs/enduser-slow.html">Speeding up HTML Purifier</a> or using
 114   the <a href="download.html#Standalone">standalone</a> version.
 115 </p>
 116
 117 <h2>Miscellaneous</h2>
 118
 119 <ul>
 120   <li><a href="live/smoketests/xssAttacks.php"><abbr>XSS</abbr>
 121       Attacks Smoketest</a> &mdash; Tests how well HTML Purifier fares
 122       against RSnake's famous cheatsheet of <abbr>XSS</abbr> attacks.</li>
 123   <li><a href="live/TODO">Roadmap</a>
 124       &mdash; Subject to lots of delays, but it's a glimpse of the future</li>
 125   <li><a href="live/art/">Artwork</a>
 126       &mdash; Extra media goodies.</li>
 127 </ul>
 128
 129 </div>
 130 </div>
 131
 132 </body>
 133 </html>