mirror of
https://github.com/ezyang/htmlpurifier.git
synced 2024-12-22 08:21:52 +00:00
14d98413fd
git-svn-id: http://htmlpurifier.org/svnroot/htmlpurifier/trunk@908 48356398-32a2-884e-a903-53898d9a118a
207 lines
8.0 KiB
HTML
207 lines
8.0 KiB
HTML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
|
<meta name="description" content="Functional specification for HTML Purifier's advanced API for defining custom filtering behavior." />
|
|
<link rel="stylesheet" type="text/css" href="style.css" />
|
|
|
|
<title>Advanced API - HTML Purifier</title>
|
|
|
|
</head><body>
|
|
|
|
<h1>Advanced API</h1>
|
|
|
|
<div id="filing">Filed under Development</div>
|
|
<div id="index">Return to the <a href="index.html">index</a>.</div>
|
|
<div id="home"><a href="http://hp.jpsband.org/">HTML Purifier</a> End-User Documentation</div>
|
|
|
|
<p>It makes no sense to adopt a <q>one-size-fits-all</q> approach to
|
|
filtersets: therefore, users must be able to define their own sets of
|
|
<q>allowed</q> elements, as well as switch in-between doctypes of HTML.</p>
|
|
|
|
<p>Our goals are to let the user:</p>
|
|
|
|
<dl>
|
|
<dt>Select</dt>
|
|
<dd><ul>
|
|
<li>Doctype</li>
|
|
<li>Filtersets: Rich / Plain / Full ...</li>
|
|
<li>Mode: Lenient / Correctional</li>
|
|
<li>Collections (?): Safe / Unsafe</li>
|
|
<li>Tags / Attributes / Modules</li>
|
|
</ul></dd>
|
|
<dt>Customize</dt>
|
|
<dd><ul>
|
|
<li>Tags / Attributes / Attribute Types</li>
|
|
<li>Filtersets</li>
|
|
<li>Root Node</li>
|
|
</ul></dd>
|
|
<dt>Create</dt>
|
|
<dd><ul>
|
|
<li>Modules / Tags / Attributes / Attribute Types</li>
|
|
<li>Filtersets</li>
|
|
<li>Doctype</li>
|
|
</ul></dd>
|
|
</dl>
|
|
|
|
<h2>Select</h2>
|
|
|
|
<h3>Selecting a Doctype</h3>
|
|
|
|
<p>By default, users will use a doctype-based, permissive but secure
|
|
whitelist. They must define a <strong>doctype</strong>, and this serves
|
|
as the first method of determining a filterset.</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 legacy, the default option 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 a Filterset</h3>
|
|
|
|
<p>However, selecting this doctype doesn't mean much, because if we
|
|
adhered exactly to the definition we would be letting XSS and other
|
|
nasties through. HTML Purifier must, in its filterset, allow a subset
|
|
of the doctype, which we shall call a <strong>filterset</strong>.</p>
|
|
|
|
<p>By default, HTML Purifier will use the <strong>Rich</strong>
|
|
filterset, which allows as many elements as possible with untrusted
|
|
sources. Other possible filtersets could be:</p>
|
|
|
|
<dl>
|
|
<dt>Full</dt>
|
|
<dd>Allows the full span of elements in the doctype, good if you want
|
|
HTML Purifier to work as a Tidy substitute but not to strip
|
|
anything out.</dd>
|
|
<dt>Plain</dt>
|
|
<dd>Provides a minimum set of tags for semantic markup of things
|
|
like blog comments.</dd>
|
|
</dl>
|
|
|
|
<p>Extension-authors would be able to define custom filtersets for
|
|
other users to use.</p>
|
|
|
|
<p>A possible call to select a filterset would be:</p>
|
|
|
|
<pre>$config->set('HTML', 'Filterset', 'Rich');</pre>
|
|
|
|
<h3>Selecting Mode</h3>
|
|
|
|
<p>Within filtersets, there are various <strong>modes</strong> of operation.
|
|
These indicate variant behaviors that, while not strictly changing the
|
|
allowed set of elements and attributes, will definitely affect the output.
|
|
Currently, we have two modes, which may be used together:</p>
|
|
|
|
<dl>
|
|
<dt>Lenient</dt>
|
|
<dd>Deprecated elements and attributes will be transformed into
|
|
standards-compliant alternatives when explicitly disallowed. For
|
|
example, in the XHTML 1.0 Strict doctype, a <code>center</code>
|
|
tag would be turned into a <code>div</code> with the CSS property
|
|
<code>text-align:center;</code>, but in XHTML 1.0 Transitional
|
|
the tag would be preserved. This mode is on by default.</dd>
|
|
<dt>Correctional</dt>
|
|
<dd>Deprecated elements and attributes will be transformed into
|
|
standards-compliant alternatives whenever possible. Referring
|
|
back to the previous example, the <code>center</code> tag would
|
|
be transformed in both cases. However, tags without a
|
|
reasonable standards-compliant alternative will be preserved
|
|
in their form. This mode is on by default. It may have
|
|
various levels of operation.</dd>
|
|
</dl>
|
|
|
|
<p>A possible call to select modes would be:</p>
|
|
|
|
<pre>$config->set('HTML', 'Mode', array('correctional', 'lenient'));</pre>
|
|
|
|
<p>If modes have extra parameters, a hash might work well:</p>
|
|
|
|
<pre>$config->set('HTML', 'Mode', array(
|
|
'correctional' => 9, // strongest level
|
|
'lenient' => true // this one's just boolean
|
|
));</pre>
|
|
|
|
<p>Modes may possibly be wrapped up with the filterset declaration:</p>
|
|
|
|
<pre>$config->set('HTML', 'Filterset', 'Rich: correctional, lenient');</pre>
|
|
|
|
<p>Further investigation in this field is necessary.</p>
|
|
|
|
<p>With regards to the various levels of operation conjectured in the
|
|
Correctional mode, this is prompted by the fact that a user may want to
|
|
correct certain problems but not others, for example, fix the <code>center</code>
|
|
tag but not the <code>u</code> tag, both of which are deprecated.
|
|
Having an integer <q>level</q> will not work very well for such fine
|
|
grained tweaking, but an array of specific settings might.</p>
|
|
|
|
<h3>Selecting Tags / Attributes / Modules</h3>
|
|
|
|
<p>If this cookie cutter approach doesn't appeal to a user, they may
|
|
decide to roll their own filterset by selecting modules, tags and
|
|
attributes to allow.</p>
|
|
|
|
<p class="technical">This would make use of the same facilities
|
|
as a filterset author would use, except that it would go under an
|
|
<q>anonymous</q> filterset that would be auto-selected if any of the
|
|
relevant module/tag/attribute selection configuration directives were
|
|
non-null.</p>
|
|
|
|
<p>In practice, this is the most commonly demanded feature. Most users are
|
|
perfectly happy defining a filterset that looks like:</p>
|
|
|
|
<pre>$config->setAllowedHTML('a[href,title],em,p,blockquote');</pre>
|
|
|
|
<p>We currently support a separated interface, which also must be preserved:</p>
|
|
|
|
<pre>$config->set('HTML', 'AllowedTags', 'a,em,p,blockquote');
|
|
$config->set('HTML', 'AllowedAttributes', 'a.href,a.title');</pre>
|
|
|
|
<p class="technical">The directive %HTML.Allowed is a convenience function
|
|
that may be fully expressed with the legacy interface, and thus is
|
|
given its own setter.</p>
|
|
|
|
<p>A user may also choose to allow modules:</p>
|
|
|
|
<pre>$config->set('HTML', 'AllowedModules', 'Hypertext,Text,Lists'); // or
|
|
$config->setAllowedHTML('Hypertext,Text,Lists');</pre>
|
|
|
|
<p>But it is not expected that this feature will be widely used.</p>
|
|
|
|
<p class="fixme">The granularity of these modules is too coarse for
|
|
the average user (for example, the core module loads everything from
|
|
the essential <code>p</code> tag to the not-so-safe <code>h1</code>
|
|
tag). How do we make this still a viable solution?</p>
|
|
|
|
<p class="technical">Modules are distinguished from regular tags by the
|
|
case of their first letter. While XML distinguishes between lower and uppercase
|
|
letters, in practice, most well-known XML languages use only lower-case
|
|
tag names for sake of consistency.</p>
|
|
|
|
<p class="technical">Considering that, internally speaking, as mandated by
|
|
the XHTML 1.1 Modularization specification, we have organized our
|
|
elements around modules, considerable gymnastics will be needed to
|
|
get this sort of functionality working.</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, $mode)</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>
|
|
|
|
<div id="version">$Id$</div>
|
|
|
|
</body></html> |