Просмотр архива Htmlpurifier


The Modularization of HTMLDefinition in HTML Purifier

WARNING: This
document was drafted before the implementation of this
    system, and
some implementation details may have evolved over time.

HTML Purifier
uses the modularization of
XHTML
<http://www.w3.org/TR/xhtml-modularization/> to organize the
internals
of HTMLDefinition into a more manageable and extensible fashion.
Rather
than have one super-object, HTMLDefinition is split into
HTMLModules,
each of which are responsible for defining elements, their
attributes,
and other properties (for a more indepth coverage,
see
/library/HTMLPurifier/HTMLModule.php's docblock comments). These
modules
are managed by HTMLModuleManager.

Modules that we don't support
but could support are:

    * 5.6. Table Modules
          o 5.6.1.
Basic Tables Module [?]
    * 5.8. Client-side Image Map Module [?]
    *
5.9. Server-side Image Map Module [?]
    * 5.12. Target Module [?]
    *
5.21. Name Identification Module [deprecated]

These modules would be
implemented as "unsafe":

    * 5.2. Core Modules
          o
5.2.1. Structure Module
    * 5.3. Applet Module
    * 5.5. Forms
Modules
          o 5.5.1. Basic Forms Module
          o 5.5.2. Forms
Module
    * 5.10. Object Module
    * 5.11. Frames Module
    * 5.13.
Iframe Module
    * 5.14. Intrinsic Events Module
    * 5.15.
Metainformation Module
    * 5.16. Scripting Module
    * 5.17. Style
Sheet Module
    * 5.19. Link Module
    * 5.20. Base Module

We will
not be using W3C's XML Schemas or DTDs directly due to the lack
of robust
tools for handling them (the main problem is that all the
current parsers
are usually PHP 5 only and solely-validating, not
correcting).

This
system may be generalized and ported over for CSS.

== General Use-Case
==

The outwards API of HTMLDefinition has been largely preserved,
not
only for backwards-compatibility but also by design.
Instead,
HTMLDefinition can be retrieved "raw", in which it
loads a structure
that closely resembles the modules of XHTML 1.1. This
structure is very
dynamic, making it easy to make cascading changes to
global content
sets or remove elements in bulk.

However, once HTML
Purifier needs the actual definition, it retrieves
a finalized version of
HTMLDefinition. The finalized definition involves
processing the modules
into a form that it is optimized for multiple
calls. This final version is
immutable and, even if editable, would
be extremely hard to change.

So,
some code taking advantage of the XHTML modularization may look
like
this:

<?php
    $config = HTMLPurifier_Config::createDefault();
   
$def =& $config->getHTMLDefinition(true); // reference to raw
   
$def->addElement('marquee', 'Block', 'Flow', 'Common');
    $purifier =
new HTMLPurifier($config);
    $purifier->purify($html); // now the
definition is finalized
?>

== Inclusions ==

One of the nice
features of HTMLDefinition is that piggy-backing off
of global attribute
and content sets is extremely easy to do.

=== Attributes
===

HTMLModule->elements[$element]->attr stores attribute
information for the
specific attributes of $element. This is quite close
to the final
API that HTML Purifier interfaces with, but there's an
important
extra feature: attr may also contain a array with a member index
zero.

<?php
    HTMLModule->elements[$element]->attr[0] =
array('AttrSet');
?>

Rather than map the attribute key 0 to an array
(which should be
an AttrDef), it defines a number of attribute collections
that should
be merged into this elements attribute array.

Furthermore,
the value of an attribute key, attribute value pair need
not be a fully
fledged AttrDef object. They can also be a string, which
signifies a
AttrDef that is looked up from a centralized registry
AttrTypes. This
allows more concise attribute definitions that look
more like W3C's
declarations, as well as offering a centralized point
for modifying the
behavior of one attribute type. And, of course, the
old method of manually
instantiating an AttrDef still works.

=== Attribute Collections
===

Attribute collections are stored and processed in the
AttrCollections
object, which is responsible for performing the inclusions
signified
by the 0 index. These attribute collections, too, are mutable,
by
using HTMLModule->attr_collections. You may add new attributes
to a
collection or define an entirely new collection for your module's
use.
Inclusions can also be cumulative.

Attribute collections allow us to get
rid of so called "global attributes"
(which actually aren't so
global).

=== Content Models and ChildDef ===

An implementation of the
above-mentioned attributes and attribute
collections was applied to the
ChildDef system. HTML Purifier uses
a proprietary system called ChildDef
for performance and flexibility
reasons, but this does not line up very
well with W3C's notion of
regexps for defining the allowed children of an
element.

HTMLPurifier->elements[$element]->content_model
and
HTMLPurifier->elements[$element]->content_model_type store
information
about the final ChildDef that will be stored
in
HTMLPurifier->elements[$element]->child (we use a different
variable
because the two forms are sufficiently
different).

$content_model is an abstract, string representation of the
internal
state of ChildDef, while $content_model_type is a string
identifier
of which ChildDef subclass to instantiate. $content_model is
processed
by substituting all content set identifiers (capitalized element
names)
with their contents. It is then parsed and passed into the
appropriate
ChildDef class, as defined by the
ContentSets->getChildDef() or the
custom fallback
HTMLModule->getChildDef() for custom child definitions
not in the
core.

You'll need to use these facilities if you plan on referencing a
content
set like "Inline" or "Block", and using them
is recommended even if you're
not due to their conciseness.

A few notes
on $content_model: it's structure can be as complicated
as you want, but
the pipe symbol (|) is reserved for defining possible
choices, due to the
content sets implementation. For example, a content
model that looks
like:

"Inline -> Block -> a"

...when the Inline
content set is defined as "span | b" and the Block
content set
is defined as "div | blockquote", will expand into:

"span
| b -> div | blockquote -> a"

The custom
HTMLModule->getChildDef() function will need to be able to
then feed
this information to ChildDef in a usable manner.

=== Content Sets
===

Content sets can be altered using HTMLModule->content_sets, an
associative
array of content set names to content set contents. If the
content set
already exists, your values are appended on to it (great for,
say,
registering the font tag as an inline element), otherwise it
is
created. They are substituted into content_model.

    vim: et sw=4
sts=4