From c5e3796202a19f0e9be52376a7996aaa3b0c1c26 Mon Sep 17 00:00:00 2001 From: "Edward Z. Yang" Date: Wed, 14 Mar 2007 04:56:44 +0000 Subject: [PATCH] Update advanced API docs, link to it from index. git-svn-id: http://htmlpurifier.org/svnroot/htmlpurifier/trunk@808 48356398-32a2-884e-a903-53898d9a118a --- docs/dev-advanced-api.html | 59 +++++++++++++++++++++++++++++++++++++- docs/index.html | 4 +++ 2 files changed, 62 insertions(+), 1 deletion(-) diff --git a/docs/dev-advanced-api.html b/docs/dev-advanced-api.html index 56dbeb04..731397f2 100644 --- a/docs/dev-advanced-api.html +++ b/docs/dev-advanced-api.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Advanced API - HTML Purifier @@ -114,6 +114,23 @@ Currently, we have two modes, which may be used together:

various levels of operation. +

A possible call to select modes would be:

+ +
$config->set('HTML', 'Mode', array('correctional', 'lenient'));
+ +

If modes have extra parameters, a hash might work well:

+ +
$config->set('HTML', 'Mode', array(
+    'correctional' => 9, // strongest level
+    'lenient' => true // this one's just boolean
+));
+ +

Modes may possibly be wrapped up with the filterset declaration:

+ +
$config->set('HTML', 'Filterset', 'Rich: correctional, lenient');
+ +

Further investigation in this field is necessary.

+

Selecting Modules / Tags / Attributes

If this cookie cutter approach doesn't appeal to a user, they may @@ -126,6 +143,46 @@ as a filterset author would use, except that it would go under an relevant module/tag/attribute selection configuration directives were non-null.

+

On the highest level, a user will usually be most interested in +directly specifying which elements and attributes are desired. For +example:

+ +
$config->set('HTML', 'AllowedElements', 'a,b,em,p,blockquote,code,i');
+ +

Attribute declarations could be merged into this declaration as such:

+ +
$config->set('HTML', 'Allowed', 'a[href,title],b,em,p[class],blockquote[cite],code,i');
+ +

...or be kept separate:

+ +
$config->set('HTML', 'AllowedAttributes', 'a.href,a.title,p.class,blockquote.cite');
+ +

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.

+ +

A user may also specify a module to load a class of elements and attributes +into their filterest:

+ +
$config->set('HTML', 'Allowed', 'Hypertext,Core');
+ +

The granularity of these modules is too coarse for +the average user (for example, the core module loads everything from +the essential p tag to the not-so-safe h1 +tag). How do we make this still a viable solution?

+ +

Unified selector

+ +

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:

+ +
function selectFilter($doctype, $filterset, $mode)
+ +

...which is simply a light wrapper over the individual configuration +calls. A custom config file format or text format could also be adopted.

+
$Id$
\ No newline at end of file diff --git a/docs/index.html b/docs/index.html index a239de99..0065c3d6 100644 --- a/docs/index.html +++ b/docs/index.html @@ -54,6 +54,10 @@ conventions.

Optimization
Discusses possible methods of optimizing HTML Purifier.
+
Advanced API
+
Functional specification for HTML Purifier's advanced API for defining +custom filtering behavior.
+

Proposals