diff --git a/docs/dev-advanced-api.html b/docs/dev-advanced-api.html index 907e9e08..c345bdb7 100644 --- a/docs/dev-advanced-api.html +++ b/docs/dev-advanced-api.html @@ -30,7 +30,7 @@ advanced API is oriented specifically for these use-cases.

Select
@@ -38,7 +38,7 @@ advanced API is oriented specifically for these use-cases.

@@ -55,7 +55,7 @@ is essential for standards-compliant output.

This identifier is based on the name the W3C has given to the document type and not -the DTD identifier, although that may be included as an alias.

+the DTD identifier.

This parameter is set via the configuration object:

@@ -71,38 +71,30 @@ be bothered when their pages stop validating.

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.

+specific use-case. This can be done using %HTML.Allowed:

-

The currently un-documented Filterset interface -will offer a way of encapsulating the following declarations, so that -a user can pick a recipe of tags that is thought to be commonly used.

+
$config->set('HTML', 'Allowed', 'a[href|title],em,p,blockquote');
-

In practice, this is the most commonly demanded feature. Most users are -perfectly happy defining a filterset that looks like:

+

The directive %HTML.Allowed is a convenience feature +that may be fully expressed with the legacy interface.

-
$config->setAllowedHTML('a[href,title];em;p;blockquote');
- -

The directive %HTML.Allowed is a convenience function -that may be fully expressed with the legacy interface, and thus is -given its own setter, or implemented by intercepting the set() function -call, parsing, and assigning to the finer grained directives accordingly.

- -

We currently support a separated interface, which also must be preserved:

+

We currently support another interface from older versions:

$config->set('HTML', 'AllowedElements', 'a,em,p,blockquote');
 $config->set('HTML', 'AllowedAttributes', 'a.href,a.title');
-

A user may also choose to allow modules:

+

A user may also choose to allow modules using a specialized +directive:

-
$config->set('HTML', 'AllowedModules', 'Hypertext,Text,Lists'); // or
-$config->setAllowedHTML('Hypertext,Text,Lists');
+
$config->set('HTML', 'AllowedModules', 'Hypertext,Text,Lists');

But it is not expected that this feature will be widely used.

Module selection will work slightly differently from the other AllowedElements and AllowedAttributes directives by -directly modifying the doctype you are operating in. You cannot, -however, add modules: there is a separate interface for that.

+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.

Modules are distinguished from regular elements by the case of their first letter. While XML distinguishes between and allows @@ -117,28 +109,10 @@ HTML Purifier, Tidy functionality involves turning unsupported and deprecated elements into standards-compliant ones, maintaining backwards compatibility, and enforcing best practices.

-

Tidy is optional, when on, it has several coarse -levels of operations, as well as directives that can be used to fine-tune -the output. The coarse levels, set at %HTML.TidyLevel, are:

- -
-
Lenient
-
Preserve any non standards-compliant aspects by transforming - them into standards-compliant equivalents.
-
Correctional
-
Default: Be lenient and enforce good practices.
-
Aggressive
-
Be correctional and transform as many deprecated elements as - possible to CSS forms
-
- -

The distinction between correctional and aggressive is fuzzy, -so the user will also have %HTML.TidyAdd and %HTML.TidyRemove, in -which they may list the names of transforms they want and don't want, -using the broad level as a starting point. The naming convention -has not been established yet, but it will be something along the lines -of 'element.attribute', with globs and special cases supported.

+

This is a complicated feature, and is explained more in depth at +the Tidy documentation page.

+

Customize

@@ -166,32 +141,27 @@ consistency's sake we will mandate this for everything.

Attributes

An attribute is bound to an element by a name and has a specific -AttrDef that validates it. Thus, the interface should -be:

+AttrDef that validates it. The interface is therefore:

function addAttribute($element, $attribute, $attribute_def);
-

With a use-case that looks like:

+

Example of the functionality in action:

-
$def->addAttribute('a', 'rel', new HTMLPurifier_AttrDef_Enum(array('nofollow')));
+
$def->addAttribute('a', 'rel', 'Enum#nofollow');
-

The $attribute_def value can be a little flexible, -to make things simpler. We'll let it also be:

+

The $attribute_def value is flexible, +to make things simpler. It can be a literal object or:

-

Making the previous example written as:

- -
$def->addAttribute('a', 'rel', 'enum(nofollow)');
-

Elements

An element requires certain information as specified by