docs/enduser-customize.html

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   3     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   4 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   6 <meta name="description" content="Tutorial for customizing HTML Purifier's tag and attribute sets." />
   7 <link rel="stylesheet" type="text/css" href="style.css" />
   8
   9 <title>Customize - HTML Purifier</title>
  10
  11 </head><body>
  12
  13 <h1 class="subtitled">Customize!</h1>
  14 <div class="subtitle">HTML Purifier is a Swiss-Army Knife</div>
  15
  16 <div id="filing">Filed under End-User</div>
  17 <div id="index">Return to the <a href="index.html">index</a>.</div>
  18 <div id="home"><a href="http://htmlpurifier.org/">HTML Purifier</a> End-User Documentation</div>
  19
  20 <p>
  21   HTML Purifier has this quirk where if you try to allow certain elements or
  22   attributes, HTML Purifier will tell you that it's not supported, and that
  23   you should go to the forums to find out how to implement it. Well, this
  24   document is how to implement elements and attributes which HTML Purifier
  25   doesn't support out of the box.
  26 </p>
  27
  28 <h2>Is it necessary?</h2>
  29
  30 <p>
  31   Before we even write any code, it is paramount to consider whether or
  32   not the code we're writing is necessary or not. HTML Purifier, by default,
  33   contains a large set of elements and attributes: large enough so that
  34   <em>any</em> element or attribute in XHTML 1.0 or 1.1 (and its HTML variants)
  35   that can be safely used by the general public is implemented.
  36 </p>
  37
  38 <p>
  39   So what needs to be implemented? (Feel free to skip this section if
  40   you know what you want).
  41 </p>
  42
  43 <h3>XHTML 1.0</h3>
  44
  45 <p>
  46   All of the modules listed below are based off of the
  47   <a href="http://www.w3.org/TR/2001/REC-xhtml-modularization-20010410/abstract_modules.html#sec_5.2.">modularization of
  48   XHTML</a>, which, while technically for XHTML 1.1, is quite a useful
  49   resource.
  50 </p>
  51
  52 <ul>
  53   <li>Structure</li>
  54   <li>Frames</li>
  55   <li>Applets (deprecated)</li>
  56   <li>Forms</li>
  57   <li>Image maps</li>
  58   <li>Objects</li>
  59   <li>Frames</li>
  60   <li>Events</li>
  61   <li>Meta-information</li>
  62   <li>Style sheets</li>
  63   <li>Link (not hypertext)</li>
  64   <li>Base</li>
  65   <li>Name</li>
  66 </ul>
  67
  68 <p>
  69   If you don't recognize it, you probably don't need it. But the curious
  70   can look all of these modules up in the above-mentioned document.  Note
  71   that inline scripting comes packaged with HTML Purifier (more on this
  72   later).
  73 </p>
  74
  75 <h3>XHTML 1.1</h3>
  76
  77 <p>
  78   As of HTMLPurifier 2.1.0, we have implemented the
  79   <a href="http://www.w3.org/TR/2001/REC-ruby-20010531/">Ruby module</a>,
  80   which defines a set of tags
  81   for publishing short annotations for text, used mostly in Japanese
  82   and Chinese school texts, but applicable for positioning any text (not
  83   limited to translations) above or below other corresponding text.
  84 </p>
  85
  86 <h3>HTML 5</h3>
  87
  88 <p>
  89   <a href="http://www.whatwg.org/specs/web-apps/current-work/">HTML 5</a>
  90   is a fork of HTML 4.01 by WHATWG, who believed that XHTML 2.0 was headed
  91   in the wrong direction.  It too is a working draft, and may change
  92   drastically before publication, but it should be noted that the
  93   <code>canvas</code> tag has been implemented by many browser vendors.
  94 </p>
  95
  96 <h3>Proprietary</h3>
  97
  98 <p>
  99   There are a number of proprietary tags still in the wild. Many of them
 100   have been documented in <a href="ref-proprietary-tags.txt">ref-proprietary-tags.txt</a>,
 101   but there is currently no implementation for any of them.
 102 </p>
 103
 104 <h3>Extensions</h3>
 105
 106 <p>
 107   There are also a number of other XML languages out there that can
 108   be embedded in HTML documents: two of the most popular are MathML and
 109   SVG, and I frequently get requests to implement these.  But they are
 110   expansive, comprehensive specifications, and it would take far too long
 111   to implement them <em>correctly</em> (most systems I've seen go as far
 112   as whitelisting tags and no further; come on, what about nesting!)
 113 </p>
 114
 115 <p>
 116   Word of warning: HTML Purifier is currently <em>not</em> namespace
 117   aware.
 118 </p>
 119
 120 <h2>Giving back</h2>
 121
 122 <p>
 123   As you may imagine from the details above (don't be abashed if you didn't
 124   read it all: a glance over would have done), there's quite a bit that
 125   HTML Purifier doesn't implement.  Recent architectural changes have
 126   allowed HTML Purifier to implement elements and attributes that are not
 127   safe!  Don't worry, they won't be activated unless you set %HTML.Trusted
 128   to true, but they certainly help out users who need to put, say, forms
 129   on their page and don't want to go through the trouble of reading this
 130   and implementing it themself.
 131 </p>
 132
 133 <p>
 134   So any of the above that you implement for your own application could
 135   help out some other poor sap on the other side of the globe.  Help us
 136   out, and send back code so that it can be hammered into a module and
 137   released with the core.  Any code would be greatly appreciated!
 138 </p>
 139
 140 <h2>And now...</h2>
 141
 142 <p>
 143   Enough philosophical talk, time for some code:
 144 </p>
 145
 146 <pre>$config = HTMLPurifier_Config::createDefault();
 147 $config-&gt;set('HTML.DefinitionID', 'enduser-customize.html tutorial');
 148 $config-&gt;set('HTML.DefinitionRev', 1);
 149 if ($def = $config-&gt;maybeGetRawHTMLDefinition()) {
 150     // our code will go here
 151 }</pre>
 152
 153 <p>
 154   Assuming that HTML Purifier has already been properly loaded (hint:
 155   include <code>HTMLPurifier.auto.php</code>), this code will set up
 156   the environment that you need to start customizing the HTML definition.
 157   What's going on?
 158 </p>
 159
 160 <ul>
 161   <li>
 162     The first three lines are regular configuration code:
 163     <ul>
 164       <li>
 165         %HTML.DefinitionID is set to a unique identifier for your
 166         custom HTML definition.  This prevents it from clobbering
 167         other custom definitions on the same installation.
 168       </li>
 169       <li>
 170         %HTML.DefinitionRev is a revision integer of your HTML
 171         definition.  Because HTML definitions are cached, you'll need
 172         to increment this whenever you make a change in order to flush
 173         the cache.
 174       </li>
 175     </ul>
 176   </li>
 177   <li>
 178     The fourth line retrieves a raw <code>HTMLPurifier_HTMLDefinition</code>
 179     object that we will be tweaking.  Interestingly enough, we have
 180     placed it in an if block: this is because
 181     <code>maybeGetRawHTMLDefinition</code>, as its name suggests, may
 182     return a NULL, in which case we should skip doing any
 183     initialization.  This, in fact, will correspond to when our fully
 184     customized object is already in the cache.
 185   </li>
 186 </ul>
 187
 188 <h2>Turn off caching</h2>
 189
 190 <p>
 191   To make development easier, we're going to temporarily turn off
 192   definition caching:
 193 </p>
 194
 195 <pre>$config = HTMLPurifier_Config::createDefault();
 196 $config-&gt;set('HTML.DefinitionID', 'enduser-customize.html tutorial');
 197 $config-&gt;set('HTML.DefinitionRev', 1);
 198 <strong>$config-&gt;set('Cache.DefinitionImpl', null); // TODO: remove this later!</strong>
 199 $def = $config-&gt;getHTMLDefinition(true);</pre>
 200
 201 <p>
 202   A few things should be mentioned about the caching mechanism before
 203   we move on.  For performance reasons, HTML Purifier caches generated
 204   <code>HTMLPurifier_Definition</code> objects in serialized files
 205   stored (by default) in <code>library/HTMLPurifier/DefinitionCache/Serializer</code>.
 206   A lot of processing is done in order to create these objects, so it
 207   makes little sense to repeat the same processing over and over again
 208   whenever HTML Purifier is called.
 209 </p>
 210
 211 <p>
 212   In order to identify a cache entry, HTML Purifier uses three variables:
 213   the library's version number, the value of %HTML.DefinitionRev and
 214   a serial of relevant configuration.  Whenever any of these changes,
 215   a new HTML definition is generated.  Notice that there is no way
 216   for the definition object to track changes to customizations: here, it
 217   is up to you to supply appropriate information to DefinitionID and
 218   DefinitionRev.
 219 </p>
 220
 221 <h2 id="addAttribute">Add an attribute</h2>
 222
 223 <p>
 224   For this example, we're going to implement the <code>target</code> attribute found
 225   on <code>a</code> elements.  To implement an attribute, we have to
 226   ask a few questions:
 227 </p>
 228
 229 <ol>
 230   <li>What element is it found on?</li>
 231   <li>What is its name?</li>
 232   <li>Is it required or optional?</li>
 233   <li>What are valid values for it?</li>
 234 </ol>
 235
 236 <p>
 237   The first three are easy: the element is <code>a</code>, the attribute
 238   is <code>target</code>, and it is not a required attribute. (If it
 239   was required, we'd need to append an asterisk to the attribute name,
 240   you'll see an example of this in the addElement() example).
 241 </p>
 242
 243 <p>
 244   The last question is a little trickier.
 245   Lets allow the special values: _blank, _self, _target and _top.
 246   The form of this is called an <strong>enumeration</strong>, a list of
 247   valid values, although only one can be used at a time.  To translate
 248   this into code form, we write:
 249 </p>
 250
 251 <pre>$config = HTMLPurifier_Config::createDefault();
 252 $config-&gt;set('HTML.DefinitionID', 'enduser-customize.html tutorial');
 253 $config-&gt;set('HTML.DefinitionRev', 1);
 254 $config-&gt;set('Cache.DefinitionImpl', null); // remove this later!
 255 $def = $config-&gt;getHTMLDefinition(true);
 256 <strong>$def->addAttribute('a', 'target', 'Enum#_blank,_self,_target,_top');</strong></pre>
 257
 258 <p>
 259   The <code>Enum#_blank,_self,_target,_top</code> does all the magic.
 260   The string is split into two parts, separated by a hash mark (#):
 261 </p>
 262
 263 <ol>
 264   <li>The first part is the name of what we call an <code>AttrDef</code></li>
 265   <li>The second part is the parameter of the above-mentioned <code>AttrDef</code></li>
 266 </ol>
 267
 268 <p>
 269   If that sounds vague and generic, it's because it is!  HTML Purifier defines
 270   an assortment of different attribute types one can use, and each of these
 271   has their own specialized parameter format.  Here are some of the more useful
 272   ones:
 273 </p>
 274
 275 <table class="table">
 276   <thead>
 277     <tr>
 278       <th>Type</th>
 279       <th>Format</th>
 280       <th>Description</th>
 281     </tr>
 282   </thead>
 283   <tbody>
 284     <tr>
 285       <th>Enum</th>
 286       <td><em>[s:]</em>value1,value2,...</td>
 287       <td>
 288         Attribute with a number of valid values, one of which may be used. When
 289         s: is present, the enumeration is case sensitive.
 290       </td>
 291     </tr>
 292     <tr>
 293       <th>Bool</th>
 294       <td>attribute_name</td>
 295       <td>
 296         Boolean attribute, with only one valid value: the name
 297         of the attribute.
 298       </td>
 299     </tr>
 300     <tr>
 301       <th>CDATA</th>
 302       <td></td>
 303       <td>
 304         Attribute of arbitrary text. Can also be referred to as <strong>Text</strong>
 305         (the specification makes a semantic distinction between the two).
 306       </td>
 307     </tr>
 308     <tr>
 309       <th>ID</th>
 310       <td></td>
 311       <td>
 312         Attribute that specifies a unique ID
 313       </td>
 314     </tr>
 315     <tr>
 316       <th>Pixels</th>
 317       <td></td>
 318       <td>
 319         Attribute that specifies an integer pixel length
 320       </td>
 321     </tr>
 322     <tr>
 323       <th>Length</th>
 324       <td></td>
 325       <td>
 326         Attribute that specifies a pixel or percentage length
 327       </td>
 328     </tr>
 329     <tr>
 330       <th>NMTOKENS</th>
 331       <td></td>
 332       <td>
 333         Attribute that specifies a number of name tokens, example: the
 334         <code>class</code> attribute
 335       </td>
 336     </tr>
 337     <tr>
 338       <th>URI</th>
 339       <td></td>
 340       <td>
 341         Attribute that specifies a URI, example: the <code>href</code>
 342         attribute
 343       </td>
 344     </tr>
 345     <tr>
 346       <th>Number</th>
 347       <td></td>
 348       <td>
 349         Attribute that specifies an positive integer number
 350       </td>
 351     </tr>
 352   </tbody>
 353 </table>
 354
 355 <p>
 356   For a complete list, consult
 357   <a href="http://repo.or.cz/w/htmlpurifier.git?a=blob;hb=HEAD;f=library/HTMLPurifier/AttrTypes.php"><code>library/HTMLPurifier/AttrTypes.php</code></a>;
 358   more information on attributes that accept parameters can be found on their
 359   respective includes in
 360   <a href="http://repo.or.cz/w/htmlpurifier.git?a=tree;hb=HEAD;f=library/HTMLPurifier/AttrDef"><code>library/HTMLPurifier/AttrDef</code></a>.
 361 </p>
 362
 363 <p>
 364   Sometimes, the restrictive list in AttrTypes just doesn't cut it. Don't
 365   sweat: you can also use a fully instantiated object as the value. The
 366   equivalent, verbose form of the above example is:
 367 </p>
 368
 369 <pre>$config = HTMLPurifier_Config::createDefault();
 370 $config-&gt;set('HTML.DefinitionID', 'enduser-customize.html tutorial');
 371 $config-&gt;set('HTML.DefinitionRev', 1);
 372 $config-&gt;set('Cache.DefinitionImpl', null); // remove this later!
 373 $def = $config-&gt;getHTMLDefinition(true);
 374 <strong>$def-&gt;addAttribute('a', 'target', new HTMLPurifier_AttrDef_Enum(
 375   array('_blank','_self','_target','_top')
 376 ));</strong></pre>
 377
 378 <p>
 379   Trust me, you'll learn to love the shorthand.
 380 </p>
 381
 382 <h2>Add an element</h2>
 383
 384 <p>
 385   Adding attributes is really small-fry stuff, though, and it was possible
 386   to add them (albeit a bit more wordy) prior to 2.0. The real gem of
 387   the Advanced API is adding elements. There are five questions to
 388   ask when adding a new element:
 389 </p>
 390
 391 <ol>
 392   <li>What is the element's name?</li>
 393   <li>What content set does this element belong to?</li>
 394   <li>What are the allowed children of this element?</li>
 395   <li>What attributes does the element allow that are general?</li>
 396   <li>What attributes does the element allow that are specific to this element?</li>
 397 </ol>
 398
 399 <p>
 400   It's a mouthful, and you'll be slightly lost if your not familiar with
 401   the HTML specification, so let's explain them step by step.
 402 </p>
 403
 404 <h3>Content set</h3>
 405
 406 <p>
 407   The HTML specification defines two major content sets: Inline
 408   and Block.  Each of these
 409   content sets contain a list of elements: Inline contains things like
 410   <code>span</code> and <code>b</code> while Block contains things like
 411   <code>div</code> and <code>blockquote</code>.
 412 </p>
 413
 414 <p>
 415   These content sets amount to a macro mechanism for HTML definition. Most
 416   elements in HTML are organized into one of these two sets, and most
 417   elements in HTML allow elements from one of these sets.  If we had
 418   to write each element verbatim into each other element's allowed
 419   children, we would have ridiculously large lists; instead we use
 420   content sets to compactify the declaration.
 421 </p>
 422
 423 <p>
 424   Practically speaking, there are several useful values you can use here:
 425 </p>
 426
 427 <table class="table">
 428   <thead>
 429     <tr>
 430       <th>Content set</th>
 431       <th>Description</th>
 432     </tr>
 433   </thead>
 434   <tbody>
 435     <tr>
 436       <th>Inline</th>
 437       <td>Character level elements, text</td>
 438     </tr>
 439     <tr>
 440       <th>Block</th>
 441       <td>Block-like elements, like paragraphs and lists</td>
 442     </tr>
 443     <tr>
 444       <th><em>false</em></th>
 445       <td>
 446         Any element that doesn't fit into the mold, for example <code>li</code>
 447         or <code>tr</code>
 448       </td>
 449     </tr>
 450   </tbody>
 451 </table>
 452
 453 <p>
 454   By specifying a valid value here, all other elements that use that
 455   content set will also allow your element, without you having to do
 456   anything. If you specify <em>false</em>, you'll have to register
 457   your element manually.
 458 </p>
 459
 460 <h3>Allowed children</h3>
 461
 462 <p>
 463   Allowed children defines the elements that this element can contain.
 464   The allowed values may range from none to a complex regexp depending on
 465   your element.
 466 </p>
 467
 468 <p>
 469   If you've ever taken a look at the HTML DTD's before, you may have
 470   noticed declarations like this:
 471 </p>
 472
 473 <pre>&lt;!ELEMENT LI - O (%flow;)*             -- list item --&gt;</pre>
 474
 475 <p>
 476   The <code>(%flow;)*</code> indicates the allowed children of the
 477   <code>li</code> tag: <code>li</code> allows any number of flow
 478   elements as its children. (The <code>- O</code> allows the closing tag to be
 479   omitted, though in XML this is not allowed.) In HTML Purifier,
 480   we'd write it like <code>Flow</code> (here's where the content sets
 481   we were discussing earlier come into play). There are three shorthand
 482   content models you can specify:
 483 </p>
 484
 485 <table class="table">
 486   <thead>
 487     <tr>
 488       <th>Content model</th>
 489       <th>Description</th>
 490     </tr>
 491   </thead>
 492   <tbody>
 493     <tr>
 494       <th>Empty</th>
 495       <td>No children allowed, like <code>br</code> or <code>hr</code></td>
 496     </tr>
 497     <tr>
 498       <th>Inline</th>
 499       <td>Any number of inline elements and text, like <code>span</code></td>
 500     </tr>
 501     <tr>
 502       <th>Flow</th>
 503       <td>Any number of inline elements, block elements and text, like <code>div</code></td>
 504     </tr>
 505   </tbody>
 506 </table>
 507
 508 <p>
 509   This covers 90% of all the cases out there, but what about elements that
 510   break the mold like <code>ul</code>? This guy requires at least one
 511   child, and the only valid children for it are <code>li</code>. The
 512   content model is: <code>Required: li</code>. There are two parts: the
 513   first type determines what <code>ChildDef</code> will be used to validate
 514   content models. The most common values are:
 515 </p>
 516
 517 <table class="table">
 518   <thead>
 519     <tr>
 520       <th>Type</th>
 521       <th>Description</th>
 522     </tr>
 523   </thead>
 524   <tbody>
 525     <tr>
 526       <th>Required</th>
 527       <td>Children must be one or more of the valid elements</td>
 528     </tr>
 529     <tr>
 530       <th>Optional</th>
 531       <td>Children can be any number of the valid elements</td>
 532     </tr>
 533     <tr>
 534       <th>Custom</th>
 535       <td>Children must follow the DTD-style regex</td>
 536     </tr>
 537   </tbody>
 538 </table>
 539
 540 <p>
 541   You can also implement your own <code>ChildDef</code>: this was done
 542   for a few special cases in HTML Purifier such as <code>Chameleon</code>
 543   (for <code>ins</code> and <code>del</code>), <code>StrictBlockquote</code>
 544   and <code>Table</code>.
 545 </p>
 546
 547 <p>
 548   The second part specifies either valid elements or a regular expression.
 549   Valid elements are separated with horizontal bars (|), i.e.
 550   "<code>a | b | c</code>".  Use #PCDATA to represent plain text.
 551   Regular expressions are based off of DTD's style:
 552 </p>
 553
 554 <ul>
 555   <li>Parentheses () are used for grouping</li>
 556   <li>Commas (,) separate elements that should come one after another</li>
 557   <li>Horizontal bars (|) indicate one or the other elements should be used</li>
 558   <li>Plus signs (+) are used for a one or more match</li>
 559   <li>Asterisks (*) are used for a zero or more match</li>
 560   <li>Question marks (?) are used for a zero or one match</li>
 561 </ul>
 562
 563 <p>
 564   For example, "<code>a, b?, (c | d), e+, f*</code>" means "In this order,
 565   one <code>a</code> element, at most one <code>b</code> element,
 566   one <code>c</code> or <code>d</code> element (but not both), one or more
 567   <code>e</code> elements, and any number of <code>f</code> elements."
 568   Regex veterans should be able to jump right in, and those not so savvy
 569   can always copy-paste W3C's content model definitions into HTML Purifier
 570   and hope for the best.
 571 </p>
 572
 573 <p>
 574   A word of warning: while the regex format is extremely flexible on
 575   the developer's side, it is
 576   quite unforgiving on the user's side.  If the user input does not <em>exactly</em>
 577   match the specification, the entire contents of the element will
 578   be nuked.  This is why there is are specific content model types like
 579   Optional and Required: while they could be implemented as <code>Custom:
 580   (valid | elements)*</code>, the custom classes contain special recovery
 581   measures that make sure as much of the user's original content gets
 582   through. HTML Purifier's core, as a rule, does not use Custom.
 583 </p>
 584
 585 <p>
 586   One final note: you can also use Content Sets inside your valid elements
 587   lists or regular expressions. In fact, the three shorthand content models
 588   mentioned above are just that: abbreviations:
 589 </p>
 590
 591 <table class="table">
 592   <thead>
 593     <tr>
 594       <th>Content model</th>
 595       <th>Implementation</th>
 596     </tr>
 597   </thead>
 598   <tbody>
 599     <tr>
 600       <th>Inline</th>
 601       <td>Optional: Inline | #PCDATA</td>
 602     </tr>
 603     <tr>
 604       <th>Flow</th>
 605       <td>Optional: Flow | #PCDATA</td>
 606     </tr>
 607   </tbody>
 608 </table>
 609
 610 <p>
 611   When the definition is compiled, Inline will be replaced with a
 612   horizontal-bar separated list of inline elements. Also, notice that
 613   it does not contain text: you have to specify that yourself.
 614 </p>
 615
 616 <h3>Common attributes</h3>
 617
 618 <p>
 619   Congratulations: you have just gotten over the proverbial hump (Allowed
 620   children). Common attributes is much simpler, and boils down to
 621   one question: does your element have the <code>id</code>, <code>style</code>,
 622   <code>class</code>, <code>title</code> and <code>lang</code> attributes?
 623   If so, you'll want to specify the <code>Common</code> attribute collection,
 624   which contains these five attributes that are found on almost every
 625   HTML element in the specification.
 626 </p>
 627
 628 <p>
 629   There are a few more collections, but they're really edge cases:
 630 </p>
 631
 632 <table class="table">
 633   <thead>
 634     <tr>
 635       <th>Collection</th>
 636       <th>Attributes</th>
 637     </tr>
 638   </thead>
 639   <tbody>
 640     <tr>
 641       <th>I18N</th>
 642       <td><code>lang</code>, possibly <code>xml:lang</code></td>
 643     </tr>
 644     <tr>
 645       <th>Core</th>
 646       <td><code>style</code>, <code>class</code>, <code>id</code> and <code>title</code></td>
 647     </tr>
 648   </tbody>
 649 </table>
 650
 651 <p>
 652   Common is a combination of the above-mentioned collections.
 653 </p>
 654
 655 <p class="aside">
 656   Readers familiar with the modularization may have noticed that the Core
 657   attribute collection differs from that specified by the <a
 658   href="http://www.w3.org/TR/xhtml-modularization/abstract_modules.html#s_commonatts">abstract
 659   modules of the XHTML Modularization 1.1</a>. We believe this section
 660   to be in error, as <code>br</code> permits the use of the <code>style</code>
 661   attribute even though it uses the <code>Core</code> collection, and
 662   the DTD and XML Schemas supplied by W3C support our interpretation.
 663 </p>
 664
 665 <h3>Attributes</h3>
 666
 667 <p>
 668   If you didn't read the <a href="#addAttribute">earlier section on
 669   adding attributes</a>, read it now.  The last parameter is simply
 670   an array of attribute names to attribute implementations, in the exact
 671   same format as <code>addAttribute()</code>.
 672 </p>
 673
 674 <h3>Putting it all together</h3>
 675
 676 <p>
 677   We're going to implement <code>form</code>. Before we embark, lets
 678   grab a reference implementation from over at the
 679   <a href="http://www.w3.org/TR/html4/sgml/loosedtd.html">transitional DTD</a>:
 680 </p>
 681
 682 <pre>&lt;!ELEMENT FORM - - (%flow;)* -(FORM)   -- interactive form --&gt;
 683 &lt;!ATTLIST FORM
 684   %attrs;                              -- %coreattrs, %i18n, %events --
 685   action      %URI;          #REQUIRED -- server-side form handler --
 686   method      (GET|POST)     GET       -- HTTP method used to submit the form--
 687   enctype     %ContentType;  &quot;application/x-www-form-urlencoded&quot;
 688   accept      %ContentTypes; #IMPLIED  -- list of MIME types for file upload --
 689   name        CDATA          #IMPLIED  -- name of form for scripting --
 690   onsubmit    %Script;       #IMPLIED  -- the form was submitted --
 691   onreset     %Script;       #IMPLIED  -- the form was reset --
 692   target      %FrameTarget;  #IMPLIED  -- render in this frame --
 693   accept-charset %Charsets;  #IMPLIED  -- list of supported charsets --
 694   &gt;</pre>
 695
 696 <p>
 697   Juicy! With just this, we can answer four of our five questions:
 698 </p>
 699
 700 <ol>
 701   <li>What is the element's name? <strong>form</strong></li>
 702   <li>What content set does this element belong to? <strong>Block</strong>
 703     (this needs a little sleuthing, I find the easiest way is to search
 704     the DTD for <code>FORM</code> and determine which set it is in.)</li>
 705   <li>What are the allowed children of this element? <strong>One
 706     or more flow elements, but no nested <code>form</code>s</strong></li>
 707   <li>What attributes does the element allow that are general? <strong>Common</strong></li>
 708   <li>What attributes does the element allow that are specific to this element? <strong>A whole bunch, see ATTLIST;
 709     we're going to do the vital ones: <code>action</code>, <code>method</code> and <code>name</code></strong></li>
 710 </ol>
 711
 712 <p>
 713   Time for some code:
 714 </p>
 715
 716 <pre>$config = HTMLPurifier_Config::createDefault();
 717 $config-&gt;set('HTML.DefinitionID', 'enduser-customize.html tutorial');
 718 $config-&gt;set('HTML.DefinitionRev', 1);
 719 $config-&gt;set('Cache.DefinitionImpl', null); // remove this later!
 720 $def = $config-&gt;getHTMLDefinition(true);
 721 $def-&gt;addAttribute('a', 'target', new HTMLPurifier_AttrDef_Enum(
 722   array('_blank','_self','_target','_top')
 723 ));
 724 <strong>$form = $def-&gt;addElement(
 725   'form',   // name
 726   'Block',  // content set
 727   'Flow', // allowed children
 728   'Common', // attribute collection
 729   array( // attributes
 730     'action*' => 'URI',
 731     'method' => 'Enum#get|post',
 732     'name' => 'ID'
 733   )
 734 );
 735 $form-&gt;excludes = array('form' => true);</strong></pre>
 736
 737 <p>
 738   Each of the parameters corresponds to one of the questions we asked.
 739   Notice that we added an asterisk to the end of the <code>action</code>
 740   attribute to indicate that it is required. If someone specifies a
 741   <code>form</code> without that attribute, the tag will be axed.
 742   Also, the extra line at the end is a special extra declaration that
 743   prevents forms from being nested within each other.
 744 </p>
 745
 746 <p>
 747   And that's all there is to it! Implementing the rest of the form
 748   module is left as an exercise to the user; to see more examples
 749   check the <a href="http://repo.or.cz/w/htmlpurifier.git?a=tree;hb=HEAD;f=library/HTMLPurifier/HTMLModule"><code>library/HTMLPurifier/HTMLModule/</code></a> directory
 750   in your local HTML Purifier installation.
 751 </p>
 752
 753 <h2>And beyond...</h2>
 754
 755 <p>
 756   Perceptive users may have realized that, to a certain extent, we
 757   have simply re-implemented the facilities of XML Schema or the
 758   Document Type Definition.  What you are seeing here, however, is
 759   not just an XML Schema or Document Type Definition: it is a fully
 760   expressive method of specifying the definition of HTML that is
 761   a portable superset of the capabilities of the two above-mentioned schema
 762   languages.  What makes HTMLDefinition so powerful is the fact that
 763   if we don't have an implementation for a content model or an attribute
 764   definition, you can supply it yourself by writing a PHP class.
 765 </p>
 766
 767 <p>
 768   There are many facets of HTMLDefinition beyond the Advanced API I have
 769   walked you through today.  To find out more about these, you can
 770   check out these source files:
 771 </p>
 772
 773 <ul>
 774   <li><a href="http://repo.or.cz/w/htmlpurifier.git?a=blob;hb=HEAD;f=library/HTMLPurifier/HTMLModule.php"><code>library/HTMLPurifier/HTMLModule.php</code></a></li>
 775   <li><a href="http://repo.or.cz/w/htmlpurifier.git?a=blob;hb=HEAD;f=library/HTMLPurifier/ElementDef.php"><code>library/HTMLPurifier/ElementDef.php</code></a></li>
 776 </ul>
 777
 778 <h2 id="optimized">Notes for HTML Purifier 4.2.0 and earlier</h3>
 779
 780 <p>
 781     Previously, this tutorial gave some incorrect template code for
 782     editing raw definitions, and that template code will now produce the
 783     error <q>Due to a documentation error in previous version of HTML
 784     Purifier...</q>  Here is how to mechanically transform old-style
 785     code into new-style code.
 786 </p>
 787
 788 <p>
 789     First, identify all code that edits the raw definition object, and
 790     put it together.  Ensure none of this code must be run on every
 791     request; if some sub-part needs to always be run, move it outside
 792     this block.  Here is an example below, with the raw definition
 793     object code bolded.
 794 </p>
 795
 796 <pre>$config = HTMLPurifier_Config::createDefault();
 797 $config-&gt;set('HTML.DefinitionID', 'enduser-customize.html tutorial');
 798 $config-&gt;set('HTML.DefinitionRev', 1);
 799 $def = $config-&gt;getHTMLDefinition(true);
 800 <strong>$def->addAttribute('a', 'target', 'Enum#_blank,_self,_target,_top');</strong>
 801 $purifier = new HTMLPurifier($config);</pre>
 802
 803 <p>
 804     Next, replace the raw definition retrieval with a
 805     maybeGetRawHTMLDefinition method call inside an if conditional, and
 806     place the editing code inside that if block.
 807 </p>
 808
 809 <pre>$config = HTMLPurifier_Config::createDefault();
 810 $config-&gt;set('HTML.DefinitionID', 'enduser-customize.html tutorial');
 811 $config-&gt;set('HTML.DefinitionRev', 1);
 812 <strong>if ($def = $config-&gt;maybeGetRawHTMLDefinition()) {
 813     $def->addAttribute('a', 'target', 'Enum#_blank,_self,_target,_top');
 814 }</strong>
 815 $purifier = new HTMLPurifier($config);</pre>
 816
 817 <p>
 818     And you're done!  Alternatively, if you're OK with not ever caching
 819     your code, the following will still work and not emit warnings.
 820 </p>
 821
 822 <pre>$config = HTMLPurifier_Config::createDefault();
 823 $def = $config-&gt;getHTMLDefinition(true);
 824 $def->addAttribute('a', 'target', 'Enum#_blank,_self,_target,_top');
 825 $purifier = new HTMLPurifier($config);</pre>
 826
 827 <p>
 828     A slightly less efficient version of this was what was going on with
 829     old versions of HTML Purifier.
 830 </p>
 831
 832 <p>
 833     <em>Technical notes:</em> ajh pointed out on <a
 834         href="http://htmlpurifier.org/phorum/read.php?5,5164,5169#msg-5169">in a forum topic</a> that
 835     HTML Purifier appeared to be repeatedly writing to the cache even
 836     when a cache entry already existed.  Investigation lead to the
 837     discovery of the following infelicity: caching of customized
 838     definitions didn't actually work!  The problem was that even though
 839     a cache file would be written out at the end of the process, there
 840     was no way for HTML Purifier to say, <q>Actually, I've already got a
 841         copy of your work, no need to reconfigure your
 842         customizations</q>.  This required the API to change: placing
 843     all of the customizations to the raw definition object in a
 844     conditional which could be skipped.
 845 </p>
 846
 847 </body></html>
 848
 849 <!-- vim: et sw=4 sts=4
 850 -->