mirrors/htmlpurifier
0
0
Fork 0
mirror of https://github.com/ezyang/htmlpurifier.git synced 2024-11-09 15:28:40 +00:00
Code Releases Activity

Update documentation to new configuration format.

Browse Source 
Signed-off-by: Edward Z. Yang <edwardzyang@thewritingpot.com>
This commit is contained in:
Edward Z. Yang 2009-05-29 23:46:40 -04:00
parent 5bf7ac4e9f
commit 77b60a4206
7 changed files with 55 additions and 249 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
INSTALL
View File

@ -231,12 +231,12 @@ HTML Purifier uses iconv to support other character encodings, as such,
any encoding that iconv supports <http://www.gnu.org/software/libiconv/> any encoding that iconv supports <http://www.gnu.org/software/libiconv/>
HTML Purifier supports with this code: HTML Purifier supports with this code:
$config->set('Core', 'Encoding', /* put your encoding here */); $config->set('Core.Encoding', /* put your encoding here */);
An example usage for Latin-1 websites (the most common encoding for English An example usage for Latin-1 websites (the most common encoding for English
websites): websites):
$config->set('Core', 'Encoding', 'ISO-8859-1'); $config->set('Core.Encoding', 'ISO-8859-1');
Note that HTML Purifier's support for non-Unicode encodings is crippled by the Note that HTML Purifier's support for non-Unicode encodings is crippled by the
fact that any character not supported by that encoding will be silently fact that any character not supported by that encoding will be silently
@ -251,7 +251,7 @@ reason, I do not include the solution in this document).
For those of you using HTML 4.01 Transitional, you can disable For those of you using HTML 4.01 Transitional, you can disable
XHTML output like this: XHTML output like this:
$config->set('HTML', 'Doctype', 'HTML 4.01 Transitional'); $config->set('HTML.Doctype', 'HTML 4.01 Transitional');
Other supported doctypes include: Other supported doctypes include:
@ -277,14 +277,14 @@ are, respectively, %HTML.Allowed, %URI.MakeAbsolute and %URI.Base, and
%AutoFormat.AutoParagraph. The %Namespace.Directive naming convention %AutoFormat.AutoParagraph. The %Namespace.Directive naming convention
translates to: translates to:
$config->set('Namespace', 'Directive', $value); $config->set('Namespace.Directive', $value);
E.g. E.g.
$config->set('HTML', 'Allowed', 'p,b,a[href],i'); $config->set('HTML.Allowed', 'p,b,a[href],i');
$config->set('URI', 'Base', 'http://www.example.com'); $config->set('URI.Base', 'http://www.example.com');
$config->set('URI', 'MakeAbsolute', true); $config->set('URI.MakeAbsolute', true);
$config->set('AutoFormat', 'AutoParagraph', true); $config->set('AutoFormat.AutoParagraph', true);
--------------------------------------------------------------------------- ---------------------------------------------------------------------------
@ -318,11 +318,11 @@ If you are unable or unwilling to give write permissions to the cache
directory, you can either disable the cache (and suffer a performance directory, you can either disable the cache (and suffer a performance
hit): hit):
$config->set('Core', 'DefinitionCache', null); $config->set('Core.DefinitionCache', null);
Or move the cache directory somewhere else (no trailing slash): Or move the cache directory somewhere else (no trailing slash):
$config->set('Cache', 'SerializerPath', '/home/user/absolute/path'); $config->set('Cache.SerializerPath', '/home/user/absolute/path');
--------------------------------------------------------------------------- ---------------------------------------------------------------------------
@ -363,8 +363,8 @@ If your website is in a different encoding or doctype, use this code:
require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php'; require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
$config = HTMLPurifier_Config::createDefault(); $config = HTMLPurifier_Config::createDefault();
$config->set('Core', 'Encoding', 'ISO-8859-1'); // replace with your encoding $config->set('Core.Encoding', 'ISO-8859-1'); // replace with your encoding
$config->set('HTML', 'Doctype', 'HTML 4.01 Transitional'); // replace with your doctype $config->set('HTML.Doctype', 'HTML 4.01 Transitional'); // replace with your doctype
$purifier = new HTMLPurifier($config); $purifier = new HTMLPurifier($config);
$clean_html = $purifier->purify($dirty_html); $clean_html = $purifier->purify($dirty_html);

9
TODO
View File

@ -18,14 +18,13 @@ afraid to cast your vote for the next feature to be implemented!
- Incorporate download and resize support as implemented here: - Incorporate download and resize support as implemented here:
http://htmlpurifier.org/phorum/read.php?3,2795,3628 http://htmlpurifier.org/phorum/read.php?3,2795,3628
- Think about allowing explicit order of operations hooks for transforms - Think about allowing explicit order of operations hooks for transforms
- Make it dead easy for other authors to maintain their own configuration - Add "register" field to config schemas to eliminate dependence on
pools. Encourage them to namespace them (this flies counter to our naming conventions
"hey, let's use convention idea", so that's why the "register" extra
field will end up being a good idea: because it means we can forgo
convention for external things
- Make it easy for people to cache their entire configuration (so that - Make it easy for people to cache their entire configuration (so that
they have one script they run to change configuration, and then a stub they have one script they run to change configuration, and then a stub
loader to get that configuration) loader to get that configuration)
- Add examples to everything (make built-in which also automatically
gives output)
FUTURE VERSIONS FUTURE VERSIONS
--------------- ---------------

195
docs/dev-advanced-api.html
View File

@ -17,202 +17,9 @@
<div id="home"><a href="http://htmlpurifier.org/">HTML Purifier</a> End-User Documentation</div> <div id="home"><a href="http://htmlpurifier.org/">HTML Purifier</a> End-User Documentation</div>
<p> <p>
<strong>Warning:</strong> This document may be out-of-date. When in doubt, Please see <a href="enduser-customize.html">Customize!</a>
consult the source code documentation.
</p> </p>
<p>HTML Purifier currently natively supports only a subset of HTML's
allowed elements, attributes, and behavior; specifically, this subset
is the set of elements that are safe for untrusted users to use.
However, HTML Purifier is often utilized to ensure standards-compliance
from input that is trusted (making it a sort of Tidy substitute),
and often users need to define new elements or attributes. The
advanced API is oriented specifically for these use-cases.</p>
<p>Our goals are to let the user:</p>
<dl>
<dt>Select</dt>
<dd><ul>
<li>Doctype</li>
<!-- <li>Filterset</li> -->
<li>Elements / Attributes / Modules</li>
<li>Tidy</li>
</ul></dd>
<dt>Customize</dt>
<dd><ul>
<li>Attributes</li>
<li>Elements</li>
<!--<li>Doctypes</li>-->
</ul></dd>
</dl>
<h2>Select</h2>
<p>For basic use, the user will have to specify some basic parameters. This
is not strictly necessary, as HTML Purifier's default setting will always
output safe code, but is required for standards-compliant output.</p>
<h3>Selecting a Doctype</h3>
<p>The first thing to select is the <strong>doctype</strong>. This
is essential for standards-compliant output.</p>
<p class="technical">This identifier is based
on the name the W3C has given to the document type and <em>not</em>
the DTD identifier.</p>
<p>This parameter is set via the configuration object:</p>
<pre>$config->set('HTML', 'Doctype', 'XHTML 1.0 Transitional');</pre>
<p>Due to historical reasons, the default doctype is XHTML 1.0
Transitional, however, we really shouldn't be guessing what the user's
doctype is. Fortunantely, people who can't be bothered to set this won't
be bothered when their pages stop validating.</p>
<h3>Selecting Elements / Attributes / Modules</h3>
<p>HTML Purifier will, by default, allow as many elements and attributes
as possible. However, a user may decide to roll their own filterset by
selecting modules, elements and attributes to allow for their own
specific use-case. This can be done using %HTML.Allowed:</p>
<pre>$config->set('HTML', 'Allowed', 'a[href|title],em,p,blockquote');</pre>
<p class="technical">The directive %HTML.Allowed is a convenience feature
that may be fully expressed with the legacy interface.</p>
<p>We currently support another interface from older versions:</p>
<pre>$config->set('HTML', 'AllowedElements', 'a,em,p,blockquote');
$config->set('HTML', 'AllowedAttributes', 'a.href,a.title');</pre>
<p>A user may also choose to allow modules using a specialized
directive:</p>
<pre>$config->set('HTML', 'AllowedModules', 'Hypertext,Text,Lists');</pre>
<p>But it is not expected that this feature will be widely used.</p>
<p class="technical">Module selection will work slightly differently
from the other AllowedElements and AllowedAttributes directives by
directly modifying the doctype you are operating in, in the spirit of
XHTML 1.1's modularization. We stop users from shooting themselves in the
foot by mandating the modules in %HTML.CoreModules be used.</p>
<p class="technical">Modules are distinguished from regular elements by the
case of their first letter. While XML distinguishes between and allows
lower and uppercase letters in element names, XHTML uses only lower-case
element names for sake of consistency.</p>
<h3>Selecting Tidy</h3>
<p>The name of this segment of functionality is inspired off of Dave
Ragget's program HTML Tidy, which purported to help clean up HTML. In
HTML Purifier, Tidy functionality involves turning unsupported and
deprecated elements into standards-compliant ones, maintaining
backwards compatibility, and enforcing best practices.</p>
<p>This is a complicated feature, and is explained more in depth at
<a href="enduser-tidy.html">the Tidy documentation page</a>.</p>
<!--
<h3>Unified selector</h3>
<p>Because selecting each and every one of these configuration options
is a chore, we may wish to offer a specialized configuration method
for selecting a filterset. Possibility:</p>
<pre>function selectFilter($doctype, $filterset, $tidy)</pre>
<p>...which is simply a light wrapper over the individual configuration
calls. A custom config file format or text format could also be adopted.</p>
-->
<h2>Customize</h2>
<p>By reviewing topic posts in the support forum, we determined that
there were two primarily demanded customization features people wanted:
to add an attribute to an existing element, and to add an element.
Thus, we'll want to create convenience functions for these common
use-cases.</p>
<p>Note that the functions described here are only available if
a raw copy of <code>HTMLPurifier_HTMLDefinition</code> was retrieved.
Furthermore, caching may prevent your changes from immediately
being seen: consult <a href="enduser-customize.html">enduser-customize.html</a> on how
to work around this.</p>
<h3>Attributes</h3>
<p>An attribute is bound to an element by a name and has a specific
<code>AttrDef</code> that validates it. The interface is therefore:</p>
<pre>function addAttribute($element, $attribute, $attribute_def);</pre>
<p>Example of the functionality in action:</p>
<pre>$def->addAttribute('a', 'rel', 'Enum#nofollow');</pre>
<p>The <code>$attribute_def</code> value is flexible,
to make things simpler. It can be a literal object or:</p>
<ul>
<!--<li>Class name: We'll instantiate it for you</li>
<li>Function name: We'll create an <code>HTMLPurifier_AttrDef_Anonymous</code>
class with that function registered as a callback.</li>-->
<li>String attribute type: We'll use <code>HTMLPurifier_AttrTypes</code>
to resolve it for you. Any data that follows a hash mark (#) will
be used to customize the attribute type: in the example above,
we specify which values for Enum to allow.</li>
</ul>
<h3>Elements</h3>
<p>An element requires certain information as specified by
<code>HTMLPurifier_ElementDef</code>. However, not all of it is necessary,
the usual things required are:</p>
<ul>
<li>Attributes</li>
<li>Content model/type</li>
<li>Registration in a content set</li>
</ul>
<p>This suggests an API like this:</p>
<pre>function addElement($element, $type, $contents,
$attr_collections = array(); $attributes = array());</pre>
<p>Each parameter explained in depth:</p>
<dl>
<dt><code>$element</code></dt>
<dd>Element name, ex. 'label'</dd>
<dt><code>$type</code></dt>
<dd>Content set to register in, ex. 'Inline' or 'Flow'</dd>
<dt><code>$contents</code></dt>
<dd>Description of allowed children. This is a merged form of
<code>HTMLPurifier_ElementDef</code>'s member variables
<code>$content_model</code> and <code>$content_model_type</code>,
where the form is <q>Type: Model</q>, ex. 'Optional: Inline'.
There are also a number of predefined templates one may use.</dd>
<dt><code>$attr_collections</code></dt>
<dd>Array (or string if only one) of attribute collection(s) to
merge into the attributes array.</dd>
<dt><code>$attributes</code></dt>
<dd>Array of attribute names to attribute definitions, much like
the above-described attribute customization.</dd>
</dl>
<p>A possible usage:</p>
<pre>$def->addElement('font', 'Inline', 'Optional: Inline', 'Common',
array('color' => 'Color'));</pre>
<p>See <code>HTMLPurifier/HTMLModule.php</code> for details.</p>
</body></html> </body></html>
<!-- vim: et sw=4 sts=4 <!-- vim: et sw=4 sts=4

46
docs/enduser-customize.html
View File

@ -155,9 +155,9 @@
</p> </p>
<pre>$config = HTMLPurifier_Config::createDefault(); <pre>$config = HTMLPurifier_Config::createDefault();
$config->set('HTML', 'DefinitionID', 'enduser-customize.html tutorial'); $config-&gt;set('HTML.DefinitionID', 'enduser-customize.html tutorial');
$config->set('HTML', 'DefinitionRev', 1); $config-&gt;set('HTML.DefinitionRev', 1);
$def = $config->getHTMLDefinition(true);</pre> $def = $config-&gt;getHTMLDefinition(true);</pre>
<p> <p>
Assuming that HTML Purifier has already been properly loaded (hint: Assuming that HTML Purifier has already been properly loaded (hint:
@ -210,10 +210,10 @@ $def = $config->getHTMLDefinition(true);</pre>
</p> </p>
<pre>$config = HTMLPurifier_Config::createDefault(); <pre>$config = HTMLPurifier_Config::createDefault();
$config->set('HTML', 'DefinitionID', 'enduser-customize.html tutorial'); $config-&gt;set('HTML.DefinitionID', 'enduser-customize.html tutorial');
$config->set('HTML', 'DefinitionRev', 1); $config-&gt;set('HTML.DefinitionRev', 1);
<strong>$config->set('Cache', 'DefinitionImpl', null); // remove this later!</strong> <strong>$config-&gt;set('Cache.DefinitionImpl', null); // TODO: remove this later!</strong>
$def = $config->getHTMLDefinition(true);</pre> $def = $config-&gt;getHTMLDefinition(true);</pre>
<p> <p>
A few things should be mentioned about the caching mechanism before A few things should be mentioned about the caching mechanism before
@ -266,10 +266,10 @@ $def = $config->getHTMLDefinition(true);</pre>
</p> </p>
<pre>$config = HTMLPurifier_Config::createDefault(); <pre>$config = HTMLPurifier_Config::createDefault();
$config->set('HTML', 'DefinitionID', 'enduser-customize.html tutorial'); $config-&gt;set('HTML.DefinitionID', 'enduser-customize.html tutorial');
$config->set('HTML', 'DefinitionRev', 1); $config-&gt;set('HTML.DefinitionRev', 1);
$config->set('Cache', 'DefinitionImpl', null); // remove this later! $config-&gt;set('Cache.DefinitionImpl', null); // remove this later!
$def = $config->getHTMLDefinition(true); $def = $config-&gt;getHTMLDefinition(true);
<strong>$def->addAttribute('a', 'target', 'Enum#_blank,_self,_target,_top');</strong></pre> <strong>$def->addAttribute('a', 'target', 'Enum#_blank,_self,_target,_top');</strong></pre>
<p> <p>
@ -384,11 +384,11 @@ $def = $config->getHTMLDefinition(true);
</p> </p>
<pre>$config = HTMLPurifier_Config::createDefault(); <pre>$config = HTMLPurifier_Config::createDefault();
$config->set('HTML', 'DefinitionID', 'enduser-customize.html tutorial'); $config-&gt;set('HTML.DefinitionID', 'enduser-customize.html tutorial');
$config->set('HTML', 'DefinitionRev', 1); $config-&gt;set('HTML.DefinitionRev', 1);
$config->set('Cache', 'DefinitionImpl', null); // remove this later! $config-&gt;set('Cache.DefinitionImpl', null); // remove this later!
$def = $config->getHTMLDefinition(true); $def = $config-&gt;getHTMLDefinition(true);
<strong>$def->addAttribute('a', 'target', new HTMLPurifier_AttrDef_Enum( <strong>$def-&gt;addAttribute('a', 'target', new HTMLPurifier_AttrDef_Enum(
array('_blank','_self','_target','_top') array('_blank','_self','_target','_top')
));</strong></pre> ));</strong></pre>
@ -731,14 +731,14 @@ $def = $config->getHTMLDefinition(true);
</p> </p>
<pre>$config = HTMLPurifier_Config::createDefault(); <pre>$config = HTMLPurifier_Config::createDefault();
$config->set('HTML', 'DefinitionID', 'enduser-customize.html tutorial'); $config-&gt;set('HTML.DefinitionID', 'enduser-customize.html tutorial');
$config->set('HTML', 'DefinitionRev', 1); $config-&gt;set('HTML.DefinitionRev', 1);
$config->set('Cache', 'DefinitionImpl', null); // remove this later! $config-&gt;set('Cache.DefinitionImpl', null); // remove this later!
$def = $config->getHTMLDefinition(true); $def = $config-&gt;getHTMLDefinition(true);
$def->addAttribute('a', 'target', new HTMLPurifier_AttrDef_Enum( $def-&gt;addAttribute('a', 'target', new HTMLPurifier_AttrDef_Enum(
array('_blank','_self','_target','_top') array('_blank','_self','_target','_top')
)); ));
<strong>$form = $def->addElement( <strong>$form = $def-&gt;addElement(
'form', // name 'form', // name
'Block', // content set 'Block', // content set
'Flow', // allowed children 'Flow', // allowed children
@ -749,7 +749,7 @@ $def->addAttribute('a', 'target', new HTMLPurifier_AttrDef_Enum(
'name' => 'ID' 'name' => 'ID'
) )
); );
$form->excludes = array('form' => true);</strong></pre> $form-&gt;excludes = array('form' => true);</strong></pre>
<p> <p>
Each of the parameters corresponds to one of the questions we asked. Each of the parameters corresponds to one of the questions we asked.

14
docs/enduser-id.html
View File

@ -31,7 +31,7 @@ by default.</p>
<p>IDs, however, are quite useful functionality to have, so if users start <p>IDs, however, are quite useful functionality to have, so if users start
complaining about broken anchors you'll probably want to turn them back on complaining about broken anchors you'll probably want to turn them back on
with %HTML.EnableAttrID. But before you go mucking around with the config with %Attr.EnableID. But before you go mucking around with the config
object, it's probably worth to take some precautions to keep your page object, it's probably worth to take some precautions to keep your page
validating. Why?</p> validating. Why?</p>
@ -56,8 +56,8 @@ validating. Why?</p>
deal with the most obvious solution: preventing users from using any IDs that deal with the most obvious solution: preventing users from using any IDs that
appear elsewhere on the document. The method is simple:</p> appear elsewhere on the document. The method is simple:</p>
<pre>$config->set('HTML', 'EnableAttrID', true); <pre>$config-&gt;set('Attr.EnableID', true);
$config->set('Attr', 'IDBlacklist' array( $config-&gt;set('Attr.IDBlacklist' array(
'list', 'of', 'attribute', 'values', 'that', 'are', 'forbidden' 'list', 'of', 'attribute', 'values', 'that', 'are', 'forbidden'
));</pre> ));</pre>
@ -88,8 +88,8 @@ all, they might have simply specified a duplicate ID by accident.</p>
<p>This method, too, is quite simple: add a prefix to all user IDs. With this <p>This method, too, is quite simple: add a prefix to all user IDs. With this
code:</p> code:</p>
<pre>$config->set('HTML', 'EnableAttrID', true); <pre>$config-&gt;set('Attr.EnableID', true);
$config->set('Attr', 'IDPrefix', 'user_');</pre> $config-&gt;set('Attr.IDPrefix', 'user_');</pre>
<p>...this:</p> <p>...this:</p>
@ -109,7 +109,7 @@ user_ to the beginning.&quot;</p>
nothing about multiple HTML Purifier outputs on one page. Thus, we have nothing about multiple HTML Purifier outputs on one page. Thus, we have
a second configuration value to piggy-back off of: %Attr.IDPrefixLocal:</p> a second configuration value to piggy-back off of: %Attr.IDPrefixLocal:</p>
<pre>$config->set('Attr', 'IDPrefixLocal', 'comment' . $id . '_');</pre> <pre>$config-&gt;set('Attr.IDPrefixLocal', 'comment' . $id . '_');</pre>
<p>This new attributes does nothing but append on to regular IDPrefix, but is <p>This new attributes does nothing but append on to regular IDPrefix, but is
special in that it is volatile: it's value is determined at run-time and special in that it is volatile: it's value is determined at run-time and
@ -137,7 +137,7 @@ anchors is beyond me.</p>
<p>To revert back to pre-1.2.0 behavior, simply:</p> <p>To revert back to pre-1.2.0 behavior, simply:</p>
<pre>$config->set('HTML', 'EnableAttrID', true);</pre> <pre>$config-&gt;set('Attr.EnableID', true);</pre>
<p>Don't come crying to me when your page mysteriously stops validating, though.</p> <p>Don't come crying to me when your page mysteriously stops validating, though.</p>

14
docs/enduser-tidy.html
View File

@ -76,7 +76,7 @@ associated with it, although it may change depending on your doctype.</p>
change the level of cleaning by setting the %HTML.TidyLevel configuration change the level of cleaning by setting the %HTML.TidyLevel configuration
directive:</p> directive:</p>
<pre>$config->set('HTML', 'TidyLevel', 'heavy'); // burn baby burn!</pre> <pre>$config-&gt;set('HTML.TidyLevel', 'heavy'); // burn baby burn!</pre>
<h2>Is the light level really light?</h2> <h2>Is the light level really light?</h2>
@ -165,17 +165,17 @@ smoketest</a>.</p>
so happy about the br@clear implementation. That's perfectly fine! so happy about the br@clear implementation. That's perfectly fine!
HTML Purifier will make accomodations:</p> HTML Purifier will make accomodations:</p>
<pre>$config->set('HTML', 'Doctype', 'XHTML 1.0 Transitional'); <pre>$config-&gt;set('HTML.Doctype', 'XHTML 1.0 Transitional');
$config->set('HTML', 'TidyLevel', 'heavy'); // all changes, minus... $config-&gt;set('HTML.TidyLevel', 'heavy'); // all changes, minus...
<strong>$config->set('HTML', 'TidyRemove', 'br@clear');</strong></pre> <strong>$config-&gt;set('HTML.TidyRemove', 'br@clear');</strong></pre>
<p>That third line does the magic, removing the br@clear fix <p>That third line does the magic, removing the br@clear fix
from the module, ensuring that <code>&lt;br clear="both" /&gt;</code> from the module, ensuring that <code>&lt;br clear="both" /&gt;</code>
will pass through unharmed. The reverse is possible too:</p> will pass through unharmed. The reverse is possible too:</p>
<pre>$config->set('HTML', 'Doctype', 'XHTML 1.0 Transitional'); <pre>$config-&gt;set('HTML.Doctype', 'XHTML 1.0 Transitional');
$config->set('HTML', 'TidyLevel', 'none'); // no changes, plus... $config-&gt;set('HTML.TidyLevel', 'none'); // no changes, plus...
<strong>$config->set('HTML', 'TidyAdd', 'p@align');</strong></pre> <strong>$config-&gt;set('HTML.TidyAdd', 'p@align');</strong></pre>
<p>In this case, all transformations are shut off, except for the p@align <p>In this case, all transformations are shut off, except for the p@align
one, which you found handy.</p> one, which you found handy.</p>

2
docs/enduser-youtube.html
View File

@ -75,7 +75,7 @@ passes through HTML Purifier <em>unharmed</em>.
<p>And the corresponding usage:</p> <p>And the corresponding usage:</p>
<pre>&lt;?php <pre>&lt;?php
$config->set('Filter', 'YouTube', true); $config-&gt;set('Filter.YouTube', true);
?&gt;</pre> ?&gt;</pre>
<p>There is a bit going in the two code snippets, so let's explain.</p> <p>There is a bit going in the two code snippets, so let's explain.</p>