Release 4.7.0
[htmlpurifier-web.git] / docs.xhtml
blob21d2ad67a57a960965e7df4392a94bff1d2dc0b2
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>
16 <xi:include href="common-header.xml" xpointer="xpointer(/*/node())" />
18 <div id="main">
19 <h1 id="title">Documentation</h1>
21 <div id="content">
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>
31 <div id="toc" class="floated" />
33 <h2>For First-Time users</h2>
35 <p>The basic code for getting HTML Purifier setup is very simple:</p>
37 <pre style="margin-left:2em;"><![CDATA[require_once '/path/to/HTMLPurifier.auto.php';
39 $config = HTMLPurifier_Config::createDefault();
40 $purifier = new HTMLPurifier($config);
41 $clean_html = $purifier->purify($dirty_html);]]></pre>
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>
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>
53 <h2>For Advanced Users</h2>
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>
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>
79 <h2>For Contributors</h2>
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>
89 <h2>Frequently Asked Questions</h2>
91 <h3>What does %HTML.Allowed mean?</h3>
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>
100 <pre>$config->set('HTML', 'Allowed', $value);</pre>
102 <h3>My attributes are mysteriously disappearing!</h3>
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>
113 <h3>How do I prevent foreign characters like ä and <code>&amp;nbsp;</code> from turning into ä?</h3>
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>
122 <h3>I can't use the <code>target</code> or <code>name</code> attribute in my <code>a</code> tags!</h3>
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>
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>
138 <h3>Is HTML Purifier slow?</h3>
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>
147 <h2>Miscellaneous</h2>
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>
159 </div>
160 </div>
162 </body>
163 </html>