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 <div id="toc" class="floated" />
  32
  33 <h2>For First-Time users</h2>
  34
  35 <p>The basic code for getting HTML Purifier setup is very simple:</p>
  36
  37 <pre style="margin-left:2em;"><![CDATA[require_once '/path/to/HTMLPurifier.auto.php';
  38
  39 $config = HTMLPurifier_Config::createDefault();
  40 $purifier = new HTMLPurifier($config);
  41 $clean_html = $purifier->purify($dirty_html);]]></pre>
  42
  43 <p>Replace <code>$dirty_html</code> with the HTML you want to purify
  44 and use <code>$clean_html</code> instead.  While HTML Purifier
  45 has a lot of configuration knobs, the default configuration of
  46 HTML Purifier is quite safe and should work for many users.</p>
  47
  48 <p>It's highly recommended to take a look at the <a href="http://htmlpurifier.org/live/INSTALL">full
  49 install documentation</a> for more information, as it will give advice
  50 on how to make sure HTML Purifier's output is matches your page's character
  51 encoding</p>
  52
  53 <h2>For Advanced Users</h2>
  54
  55 <ul>
  56   <li><a href="docs/">End-User
  57       Documentation</a> &mdash; In-depth documents on how to get
  58       the most out of HTML Purifier. These are located in the <code>docs/</code>
  59       folder of your HTML Purifier installation.</li>
  60   <li><a href="live/configdoc/plain.html">Configuration
  61       documentation</a> &mdash; These are various configuration directives
  62       that can be used to customize HTML Purifier's behavior.</li>
  63   <li><a href="http://htmlpurifier.org/doxygen/html/">Doxygen-generated
  64       Documentation</a> &mdash; No class left undocumented!  Cross-referenced
  65       code!  A must-read for any prospective HTML Purifier hacker.</li>
  66   <li><a href="live/smoketests/printDefinition.php">Print
  67       Definition</a> &mdash; If you want to actually see what HTML Purifier's
  68       filtering rules are, look no further than to this page. You can even
  69       experiment with the configuration to see how things respond to different
  70       directives.</li>
  71 </ul>
  72
  73 <p>
  74   P.S. HTML Purifier's source code is well documented and very readable.
  75   If a question of your isn't answered by any of the above resources,
  76   go to the source! (Or ask in the forums.)
  77 </p>
  78
  79 <h2>For Contributors</h2>
  80
  81 <p>
  82   As is with any open source project, HTML Purifier always is looking for
  83   developers, writers and other folks willing to lend a hand. There are any
  84   number of things to work on! Please, take a moment to
  85   <a href="contribute">find out how
  86   you can help out this project</a>.
  87 </p>
  88
  89 <h2>Frequently Asked Questions</h2>
  90
  91 <h3>What does %HTML.Allowed mean?</h3>
  92
  93 <p>
  94   The percent-dot format is a shorthand for HTML Purifier's configuration
  95   directives. It takes the form of %Namespace.Directive. For
  96   practical purposes, %HTML.Allowed translates into the following PHP
  97   code:
  98 </p>
  99
 100 <pre>$config->set('HTML', 'Allowed', $value);</pre>
 101
 102 <h3>My attributes are mysteriously disappearing!</h3>
 103
 104 <p>
 105   You've probably got <a href="http://php.net/manual/en/security.magicquotes.php">magic quotes</a>
 106   turned on, which is interfering with the single and double-quotes in
 107   <abbr>HTML</abbr> attributes. The usual way to fix this is
 108   <a href="http://php.net/manual/en/security.magicquotes.disabling.php">with
 109   some runtime code or an ini tweak.</a> Be sure not to introduce any
 110   <abbr>SQL</abbr> injection vulnerabilities!
 111 </p>
 112
 113 <h3>How do I prevent foreign characters like ä and <code>&amp;nbsp;</code> from turning into Ã¤?</h3>
 114
 115 <p>
 116   This usually means that HTML Purifier is parsing your code as UTF-8, but
 117   your output encoding is something else. Read up <a href="docs/enduser-utf8.html">this
 118   document on UTF-8</a> to learn how to fix this. (Short answer: use
 119   %Core.Encoding or switch to UTF-8.)
 120 </p>
 121
 122 <h3>I can't use the <code>target</code> or <code>name</code> attribute in my <code>a</code> tags!</h3>
 123
 124 <p>
 125   The <code>target</code> attribute has been deprecated for a long time, so
 126   I highly recommend you look at other ways of, say, opening new windows
 127   when you click a link (my favorites are <q>Don't do it!</q> or, if you
 128   must, JavaScript) But if you must, the
 129   <a href="live/configdoc/plain.html#Attr.AllowedFrameTargets">%Attr.AllowedFrameTargets</a>
 130   directive is what you are looking for.
 131 </p>
 132
 133 <p>
 134   The <code>name</code> attribute is dependent on IDs being enabled.
 135   See <a href="docs/enduser-id.html">this document on enabling user IDs</a> for more information.
 136 </p>
 137
 138 <h3>Is HTML Purifier slow?</h3>
 139
 140 <p>
 141   HTML Purifier isn't exactly light or speedy; this is a tradeoff for the
 142   power and security the library affords. You can combat this by reading
 143   <a href="docs/enduser-slow.html">Speeding up HTML Purifier</a> or using
 144   the <a href="download#Standalone">standalone</a> version.
 145 </p>
 146
 147 <h2>Miscellaneous</h2>
 148
 149 <ul>
 150   <li><a href="live/smoketests/xssAttacks.php"><abbr>XSS</abbr>
 151       Attacks Smoketest</a> &mdash; Tests how well HTML Purifier fares
 152       against RSnake's famous cheatsheet of <abbr>XSS</abbr> attacks.</li>
 153   <li><a href="live/TODO">Roadmap</a>
 154       &mdash; Subject to lots of delays, but it's a glimpse of the future</li>
 155   <li><a href="live/art/">Artwork</a>
 156       &mdash; Extra media goodies.</li>
 157 </ul>
 158
 159 </div>
 160 </div>
 161
 162 </body>
 163 </html>