Customize!

You may have heard of the Advanced API. If you're interested in reading dry prose and boring functional specifications, feel free to click that link to get a no-nonsense overview on the Advanced API. For the rest of us, there's this tutorial. By the time you're finished reading this, you should have a pretty good idea on how to implement custom tags and attributes that HTML Purifier may not have.

Is it necessary?

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 (and its HTML variant) 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).

XHTML 1.0

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.

• Structure
• Frames
• Applets (deprecated)
• Forms
• Image maps
• Objects
• Frames
• Events
• Meta-information
• Style sheets
• Link (not hypertext)
• Base
• Name

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

XHTML 1.1

We have not implemented the Ruby module, which defines a set of tags for publishing short annotations for text, used mostly in Japanese and Chinese school texts.

XHTML 2.0

XHTML 2.0 is still a working draft, so any elements introduced in the specification have not been implemented and will not be implemented until we get a recommendation or proposal. Because XHTML 2.0 is an entirely new markup language, implementing rules for it will be no easy task.

HTML 5

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.

Proprietary

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.

Extensions

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.

Giving back

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!

And now...

Enough philosophical talk, time for some code:

$config = HTMLPurifier_Config::createDefault();
$config->set('HTML', 'DefinitionID', 'enduser-customize.html tutorial');
$config->set('HTML', 'DefinitionRev', 1);
$def =& $config->getHTMLDefinition(true);

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?

• The first three lines are regular configuration code:
  • %HTML.DefinitionID is set to a unique identifier for your custom HTML definition. This prevents it from clobbering other custom definitions on the same installation.
  • %HTML.DefinitionRev is a revision integer of your HTML definition. Because HTML definitions are cached, you'll need to increment this whenever you make a change in order to flush the cache.
• The fourth line retrieves a raw HTMLPurifier_HTMLDefinition object that we will be tweaking. If the parameter was removed, we would be retrieving a fully formed definition object, which is somewhat useless for customization purposes.

Broken backwards-compatibility

Those of you who have already been twiddling around with the raw HTML definition object, you'll be noticing that you're getting an error when you attempt to retrieve the raw definition object without specifying a DefinitionID. It is vital to caching (see below) that you make a unique name for your customized definition, so make up something right now and things will operate again.

Turn off caching

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('Core', 'DefinitionCache', null); // 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.

Add an attribute

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:

1. What element is it found on?
2. What is its name?
3. What are valid values for it?

The first two are easy: the element is a and the attribute is target. The third 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('Core', 'DefinitionCache', 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 (#):

1. The first part is the name of what we call an AttrDef
2. The second part is the parameter of the above-mentioned AttrDef

If 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:

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('Core', 'DefinitionCache', 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.

Add an element

To be written...