From 6c56dd070f904b57bd7dac82d44f39b836e56cbe Mon Sep 17 00:00:00 2001 From: "Edward Z. Yang" Date: Thu, 1 Mar 2007 03:56:08 +0000 Subject: [PATCH] Updated Advanced API docs. git-svn-id: http://htmlpurifier.org/svnroot/htmlpurifier/trunk@769 48356398-32a2-884e-a903-53898d9a118a --- docs/dev-advanced-api.html | 92 ++++++++++++++++++++++++++++++++------ docs/style.css | 11 ++++- 2 files changed, 89 insertions(+), 14 deletions(-) diff --git a/docs/dev-advanced-api.html b/docs/dev-advanced-api.html index a7aff0a2..695c49c4 100644 --- a/docs/dev-advanced-api.html +++ b/docs/dev-advanced-api.html @@ -20,20 +20,86 @@ filtersets: therefore, users must be able to define their own sets of allowed elements, as well as switch in-between doctypes of HTML.

-

Our goals (pending reorganization):

+

Our goals are to let the user:

- +
+
Select
+
    +
  • Doctype
    • +
  • Filtersets: Rich / Plain / Full ...
    • +
  • Collections: Safe / Unsafe / Leniency(?) / Corrections(?) [advanced]
    • +
  • Modules / Tags / Attributes
    • +
+
Customize
+
    +
  • Tags / Attributes / Attribute Types
    • +
  • Filtersets
    • +
  • Root Node
    • +
+
Create
+
    +
  • Modules / Tags / Attributes / Attribute Types
    • +
  • Filtersets
    • +
  • Doctype
    • +
+
-
$Id: dev-optimization.html 655 2007-01-18 22:38:40Z Edward $
+

Select

+ +

Selecting a Doctype

+ +

By default, users will use a doctype-based, permissive but secure +whitelist. They must define a doctype, and this serves +as the first method of determining a filterset.

+ +

This identifier is based +on the name the W3C has given to the document type and not +the DTD identifier.

+ +

This parameter is set via the configuration object:

+ +
$config->set('HTML', 'Doctype', 'XHTML 1.0 Transitional');
+ +

Selecting a Filterset

+ +

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

+ +

By default, HTML Purifier will use the Rich +filterset, which allows as many elements as possible with untrusted +sources. Other possible filtersets could be:

+ +
+
Full
+
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.
+
Plain
+
Provides a minimum set of tags for semantic markup of things + like blog comments.
+
+ +

Extension-authors would be able to define custom filtersets for +other users to use.

+ +

A possible call to select a filterset would be:

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

Selecting Modules / Tags / Attributes

+ +

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.

+ +

This would make use of the same facilities +as a filterset author would use, except that it would go under an +anonymous filterset that would be auto-selected if any of the +relevant module/tag/attribute selection configuration directives were +non-null.

+ +
$Id$
\ No newline at end of file diff --git a/docs/style.css b/docs/style.css index 772577ee..75a3e2f7 100644 --- a/docs/style.css +++ b/docs/style.css @@ -56,4 +56,13 @@ q:before { } q:after { content: close-quote; -} \ No newline at end of file +} + +/* Marks off implementation details interesting only to the person writing + the class described in the spec. */ +.technical {margin-left:2em; } +.technical:before {content:"Technical note: "; font-weight:bold; color:#061; } + +/* Marks off sections that are lacking. */ +.fixme {margin-left:2em; } +.fixme:before {content:"Fix me: "; font-weight:bold; color:#C00; }