HTML Purifier has this quirk where if you try to allow certain elements or attributes, HTML Purifier will tell you that it's not supported, and that you should go to the forums to find out how to implement it. Well, this document is how to implement elements and attributes which HTML Purifier doesn't support out of the box.
Before we even write any code, it is paramount to consider whether or not the code we're writing is necessary or not. HTML Purifier, by default, contains a large set of elements and attributes: large enough so that any element or attribute in XHTML 1.0 or 1.1 (and its HTML variants) that can be safely used by the general public is implemented.
So what needs to be implemented? (Feel free to skip this section if you know what you want).
All of the modules listed below are based off of the modularization of XHTML, which, while technically for XHTML 1.1, is quite a useful resource.
If you don't recognize it, you probably don't need it. But the curious can look all of these modules up in the above-mentioned document. Note that inline scripting comes packaged with HTML Purifier (more on this later).
As of HTMLPurifier 2.1.0, we have implemented the Ruby module, which defines a set of tags for publishing short annotations for text, used mostly in Japanese and Chinese school texts, but applicable for positioning any text (not limited to translations) above or below other corresponding text.
HTML 5
is a fork of HTML 4.01 by WHATWG, who believed that XHTML 2.0 was headed
in the wrong direction. It too is a working draft, and may change
drastically before publication, but it should be noted that the
canvas tag has been implemented by many browser vendors.
There are a number of proprietary tags still in the wild. Many of them have been documented in ref-proprietary-tags.txt, but there is currently no implementation for any of them.
There are also a number of other XML languages out there that can be embedded in HTML documents: two of the most popular are MathML and SVG, and I frequently get requests to implement these. But they are expansive, comprehensive specifications, and it would take far too long to implement them correctly (most systems I've seen go as far as whitelisting tags and no further; come on, what about nesting!)
Word of warning: HTML Purifier is currently not namespace aware.
As you may imagine from the details above (don't be abashed if you didn't read it all: a glance over would have done), there's quite a bit that HTML Purifier doesn't implement. Recent architectural changes have allowed HTML Purifier to implement elements and attributes that are not safe! Don't worry, they won't be activated unless you set %HTML.Trusted to true, but they certainly help out users who need to put, say, forms on their page and don't want to go through the trouble of reading this and implementing it themself.
So any of the above that you implement for your own application could help out some other poor sap on the other side of the globe. Help us out, and send back code so that it can be hammered into a module and released with the core. Any code would be greatly appreciated!
Enough philosophical talk, time for some code:
$config = HTMLPurifier_Config::createDefault();
$config->set('HTML.DefinitionID', 'enduser-customize.html tutorial');
$config->set('HTML.DefinitionRev', 1);
if ($def = $config->maybeGetRawHTMLDefinition()) {
// our code will go here
}
Assuming that HTML Purifier has already been properly loaded (hint:
include HTMLPurifier.auto.php), this code will set up
the environment that you need to start customizing the HTML definition.
What's going on?
HTMLPurifier_HTMLDefinition
object that we will be tweaking. Interestingly enough, we have
placed it in an if block: this is because
maybeGetRawHTMLDefinition, as its name suggests, may
return a NULL, in which case we should skip doing any
initialization. This, in fact, will correspond to when our fully
customized object is already in the cache.
To make development easier, we're going to temporarily turn off definition caching:
$config = HTMLPurifier_Config::createDefault();
$config->set('HTML.DefinitionID', 'enduser-customize.html tutorial');
$config->set('HTML.DefinitionRev', 1);
$config->set('Cache.DefinitionImpl', null); // TODO: remove this later!
$def = $config->getHTMLDefinition(true);
A few things should be mentioned about the caching mechanism before
we move on. For performance reasons, HTML Purifier caches generated
HTMLPurifier_Definition objects in serialized files
stored (by default) in library/HTMLPurifier/DefinitionCache/Serializer.
A lot of processing is done in order to create these objects, so it
makes little sense to repeat the same processing over and over again
whenever HTML Purifier is called.
In order to identify a cache entry, HTML Purifier uses three variables: the library's version number, the value of %HTML.DefinitionRev and a serial of relevant configuration. Whenever any of these changes, a new HTML definition is generated. Notice that there is no way for the definition object to track changes to customizations: here, it is up to you to supply appropriate information to DefinitionID and DefinitionRev.
For this example, we're going to implement the target attribute found
on a elements. To implement an attribute, we have to
ask a few questions:
The first three are easy: the element is a, the attribute
is target, and it is not a required attribute. (If it
was required, we'd need to append an asterisk to the attribute name,
you'll see an example of this in the addElement() example).
The last question is a little trickier. Lets allow the special values: _blank, _self, _target and _top. The form of this is called an enumeration, a list of valid values, although only one can be used at a time. To translate this into code form, we write:
$config = HTMLPurifier_Config::createDefault();
$config->set('HTML.DefinitionID', 'enduser-customize.html tutorial');
$config->set('HTML.DefinitionRev', 1);
$config->set('Cache.DefinitionImpl', null); // remove this later!
$def = $config->getHTMLDefinition(true);
$def->addAttribute('a', 'target', 'Enum#_blank,_self,_target,_top');
The Enum#_blank,_self,_target,_top does all the magic.
The string is split into two parts, separated by a hash mark (#):
AttrDefAttrDefIf that sounds vague and generic, it's because it is! HTML Purifier defines an assortment of different attribute types one can use, and each of these has their own specialized parameter format. Here are some of the more useful ones:
| Type | Format | Description |
|---|---|---|
| Enum | [s:]value1,value2,... | Attribute with a number of valid values, one of which may be used. When s: is present, the enumeration is case sensitive. |
| Bool | attribute_name | Boolean attribute, with only one valid value: the name of the attribute. |
| CDATA | Attribute of arbitrary text. Can also be referred to as Text (the specification makes a semantic distinction between the two). | |
| ID | Attribute that specifies a unique ID | |
| Pixels | Attribute that specifies an integer pixel length | |
| Length | Attribute that specifies a pixel or percentage length | |
| NMTOKENS |
Attribute that specifies a number of name tokens, example: the
class attribute
|
|
| URI |
Attribute that specifies a URI, example: the href
attribute
|
|
| Number | Attribute that specifies an positive integer number |
For a complete list, consult
library/HTMLPurifier/AttrTypes.php;
more information on attributes that accept parameters can be found on their
respective includes in
library/HTMLPurifier/AttrDef.
Sometimes, the restrictive list in AttrTypes just doesn't cut it. Don't sweat: you can also use a fully instantiated object as the value. The equivalent, verbose form of the above example is:
$config = HTMLPurifier_Config::createDefault();
$config->set('HTML.DefinitionID', 'enduser-customize.html tutorial');
$config->set('HTML.DefinitionRev', 1);
$config->set('Cache.DefinitionImpl', null); // remove this later!
$def = $config->getHTMLDefinition(true);
$def->addAttribute('a', 'target', new HTMLPurifier_AttrDef_Enum(
array('_blank','_self','_target','_top')
));
Trust me, you'll learn to love the shorthand.
Adding attributes is really small-fry stuff, though, and it was possible to add them (albeit a bit more wordy) prior to 2.0. The real gem of the Advanced API is adding elements. There are five questions to ask when adding a new element:
It's a mouthful, and you'll be slightly lost if your not familiar with the HTML specification, so let's explain them step by step.
The HTML specification defines two major content sets: Inline
and Block. Each of these
content sets contain a list of elements: Inline contains things like
span and b while Block contains things like
div and blockquote.
These content sets amount to a macro mechanism for HTML definition. Most elements in HTML are organized into one of these two sets, and most elements in HTML allow elements from one of these sets. If we had to write each element verbatim into each other element's allowed children, we wo