2007-02-28 04:42:08 +00:00
|
|
|
<?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." />
|
|
|
|
|
<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>
|
|
|
|
|
|
2007-03-01 03:56:08 +00:00
|
|
|
<p>Our goals are to let the user:</p>
|
|
|
|
|
|
|
|
|
|
<dl>
|
|
|
|
|
<dt>Select</dt>
|
|
|
|
|
<dd><ul>
|
|
|
|
|
<li>Doctype</li>
|
|
|
|
|
<li>Filtersets: Rich / Plain / Full ...</li>
|
2007-03-12 03:53:09 +00:00
|
|
|
<li>Mode: Lenient / Correctional</li>
|
|
|
|
|
<li>Collections (?): Safe / Unsafe</li>
|
2007-03-01 03:56:08 +00:00
|
|
|
<li>Modules / Tags / Attributes</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>
|
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
2007-03-12 03:53:09 +00:00
|
|
|
<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>
|
|
|
|
|
|
2007-03-01 03:56:08 +00:00
|
|
|
<h3>Selecting Modules / Tags / Attributes</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>
|
|
|
|
|
|
|
|
|
|
<div id="version">$Id$</div>
|
2007-02-28 04:42:08 +00:00
|
|
|
|
|
|
|
|
</body></html>
|
