XHTML 2 is dead. Long live XHTML 2.
[htmlpurifier.git] / 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" />
9 <title>Customize - HTML Purifier</title>
11 </head><body>
13 <h1 class="subtitled">Customize!</h1>
14 <div class="subtitle">HTML Purifier is a Swiss-Army Knife</div>
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>
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>
28 <h2>Is it necessary?</h2>
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>
38 <p>
39 So what needs to be implemented? (Feel free to skip this section if
40 you know what you want).
41 </p>
43 <h3>XHTML 1.0</h3>
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>
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>
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>
75 <h3>XHTML 1.1</h3>
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>
86 <h3>HTML 5</h3>
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>
96 <h3>Proprietary</h3>
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>
104 <h3>Extensions</h3>
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>
116 Word of warning: HTML Purifier is currently <em>not</em> namespace
117 aware.
118 </p>
120 <h2>Giving back</h2>
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>
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>
140 <h2>And now...</h2>
143 Enough philosophical talk, time for some code:
144 </p>
146 <pre>$config = HTMLPurifier_Config::createDefault();
147 $config-&gt;set('HTML.DefinitionID', 'enduser-customize.html tutorial');
148 $config-&gt;set('HTML.DefinitionRev', 1);
149 $def = $config-&gt;getHTMLDefinition(true);</pre>
152 Assuming that HTML Purifier has already been properly loaded (hint:
153 include <code>HTMLPurifier.auto.php</code>), this code will set up
154 the environment that you need to start customizing the HTML definition.
155 What's going on?
156 </p>
158 <ul>
159 <li>
160 The first three lines are regular configuration code:
161 <ul>
162 <li>
163 %HTML.DefinitionID is set to a unique identifier for your
164 custom HTML definition. This prevents it from clobbering
165 other custom definitions on the same installation.
166 </li>
167 <li>
168 %HTML.DefinitionRev is a revision integer of your HTML
169 definition. Because HTML definitions are cached, you'll need
170 to increment this whenever you make a change in order to flush
171 the cache.
172 </li>
173 </ul>
174 </li>
175 <li>
176 The fourth line retrieves a raw <code>HTMLPurifier_HTMLDefinition</code>
177 object that we will be tweaking. If the parameter was removed, we
178 would be retrieving a fully formed definition object, which is somewhat
179 useless for customization purposes.
180 </li>
181 </ul>
183 <h3>Broken backwards-compatibility</h3>
186 Those of you who have already been twiddling around with the raw
187 HTML definition object, you'll be noticing that you're getting an error
188 when you attempt to retrieve the raw definition object without specifying
189 a DefinitionID. It is vital to caching (see below) that you make a unique
190 name for your customized definition, so make up something right now and
191 things will operate again.
192 </p>
194 <h2>Turn off caching</h2>
197 To make development easier, we're going to temporarily turn off
198 definition caching:
199 </p>
201 <pre>$config = HTMLPurifier_Config::createDefault();
202 $config-&gt;set('HTML.DefinitionID', 'enduser-customize.html tutorial');
203 $config-&gt;set('HTML.DefinitionRev', 1);
204 <strong>$config-&gt;set('Cache.DefinitionImpl', null); // TODO: remove this later!</strong>
205 $def = $config-&gt;getHTMLDefinition(true);</pre>
208 A few things should be mentioned about the caching mechanism before
209 we move on. For performance reasons, HTML Purifier caches generated
210 <code>HTMLPurifier_Definition</code> objects in serialized files
211 stored (by default) in <code>library/HTMLPurifier/DefinitionCache/Serializer</code>.
212 A lot of processing is done in order to create these objects, so it
213 makes little sense to repeat the same processing over and over again
214 whenever HTML Purifier is called.
215 </p>
218 In order to identify a cache entry, HTML Purifier uses three variables:
219 the library's version number, the value of %HTML.DefinitionRev and
220 a serial of relevant configuration. Whenever any of these changes,
221 a new HTML definition is generated. Notice that there is no way
222 for the definition object to track changes to customizations: here, it
223 is up to you to supply appropriate information to DefinitionID and
224 DefinitionRev.
225 </p>
227 <h2 id="addAttribute">Add an attribute</h2>
230 For this example, we're going to implement the <code>target</code> attribute found
231 on <code>a</code> elements. To implement an attribute, we have to
232 ask a few questions:
233 </p>
235 <ol>
236 <li>What element is it found on?</li>
237 <li>What is its name?</li>
238 <li>Is it required or optional?</li>
239 <li>What are valid values for it?</li>
240 </ol>
243 The first three are easy: the element is <code>a</code>, the attribute
244 is <code>target</code>, and it is not a required attribute. (If it
245 was required, we'd need to append an asterisk to the attribute name,
246 you'll see an example of this in the addElement() example).
247 </p>
250 The last question is a little trickier.
251 Lets allow the special values: _blank, _self, _target and _top.
252 The form of this is called an <strong>enumeration</strong>, a list of
253 valid values, although only one can be used at a time. To translate
254 this into code form, we write:
255 </p>
257 <pre>$config = HTMLPurifier_Config::createDefault();
258 $config-&gt;set('HTML.DefinitionID', 'enduser-customize.html tutorial');
259 $config-&gt;set('HTML.DefinitionRev', 1);
260 $config-&gt;set('Cache.DefinitionImpl', null); // remove this later!
261 $def = $config-&gt;getHTMLDefinition(true);
262 <strong>$def->addAttribute('a', 'target', 'Enum#_blank,_self,_target,_top');</strong></pre>
265 The <code>Enum#_blank,_self,_target,_top</code> does all the magic.
266 The string is split into two parts, separated by a hash mark (#):
267 </p>
269 <ol>
270 <li>The first part is the name of what we call an <code>AttrDef</code></li>
271 <li>The second part is the parameter of the above-mentioned <code>AttrDef</code></li>
272 </ol>
275 If that sounds vague and generic, it's because it is! HTML Purifier defines
276 an assortment of different attribute types one can use, and each of these
277 has their own specialized parameter format. Here are some of the more useful
278 ones:
279 </p>
281 <table class="table">
282 <thead>
283 <tr>
284 <th>Type</th>
285 <th>Format</th>
286 <th>Description</th>
287 </tr>
288 </thead>
289 <tbody>
290 <tr>
291 <th>Enum</th>
292 <td><em>[s:]</em>value1,value2,...</td>
293 <td>
294 Attribute with a number of valid values, one of which may be used. When
295 s: is present, the enumeration is case sensitive.
296 </td>
297 </tr>
298 <tr>
299 <th>Bool</th>
300 <td>attribute_name</td>
301 <td>
302 Boolean attribute, with only one valid value: the name
303 of the attribute.
304 </td>
305 </tr>
306 <tr>
307 <th>CDATA</th>
308 <td></td>
309 <td>
310 Attribute of arbitrary text. Can also be referred to as <strong>Text</strong>
311 (the specification makes a semantic distinction between the two).
312 </td>
313 </tr>
314 <tr>
315 <th>ID</th>
316 <td></td>
317 <td>
318 Attribute that specifies a unique ID
319 </td>
320 </tr>
321 <tr>
322 <th>Pixels</th>
323 <td></td>
324 <td>
325 Attribute that specifies an integer pixel length
326 </td>
327 </tr>
328 <tr>
329 <th>Length</th>
330 <td></td>
331 <td>
332 Attribute that specifies a pixel or percentage length
333 </td>
334 </tr>
335 <tr>
336 <th>NMTOKENS</th>
337 <td></td>
338 <td>
339 Attribute that specifies a number of name tokens, example: the
340 <code>class</code> attribute
341 </td>
342 </tr>
343 <tr>
344 <th>URI</th>
345 <td></td>
346 <td>
347 Attribute that specifies a URI, example: the <code>href</code>
348 attribute
349 </td>
350 </tr>
351 <tr>
352 <th>Number</th>
353 <td></td>
354 <td>
355 Attribute that specifies an positive integer number
356 </td>
357 </tr>
358 </tbody>
359 </table>
362 For a complete list, consult
363 <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>;
364 more information on attributes that accept parameters can be found on their
365 respective includes in
366 <a href="http://repo.or.cz/w/htmlpurifier.git?a=tree;hb=HEAD;f=library/HTMLPurifier/AttrDef"><code>library/HTMLPurifier/AttrDef</code></a>.
367 </p>
370 Sometimes, the restrictive list in AttrTypes just doesn't cut it. Don't
371 sweat: you can also use a fully instantiated object as the value. The
372 equivalent, verbose form of the above example is:
373 </p>
375 <pre>$config = HTMLPurifier_Config::createDefault();
376 $config-&gt;set('HTML.DefinitionID', 'enduser-customize.html tutorial');
377 $config-&gt;set('HTML.DefinitionRev', 1);
378 $config-&gt;set('Cache.DefinitionImpl', null); // remove this later!
379 $def = $config-&gt;getHTMLDefinition(true);
380 <strong>$def-&gt;addAttribute('a', 'target', new HTMLPurifier_AttrDef_Enum(
381 array('_blank','_self','_target','_top')
382 ));</strong></pre>
385 Trust me, you'll learn to love the shorthand.
386 </p>
388 <h2>Add an element</h2>
391 Adding attributes is really small-fry stuff, though, and it was possible
392 to add them (albeit a bit more wordy) prior to 2.0. The real gem of
393 the Advanced API is adding elements. There are five questions to
394 ask when adding a new element:
395 </p>
397 <ol>
398 <li>What is the element's name?</li>
399 <li>What content set does this element belong to?</li>
400 <li>What are the allowed children of this element?</li>
401 <li>What attributes does the element allow that are general?</li>
402 <li>What attributes does the element allow that are specific to this element?</li>
403 </ol>
406 It's a mouthful, and you'll be slightly lost if your not familiar with
407 the HTML specification, so let's explain them step by step.
408 </p>
410 <h3>Content set</h3>
413 The HTML specification defines two major content sets: Inline
414 and Block. Each of these
415 content sets contain a list of elements: Inline contains things like
416 <code>span</code> and <code>b</code> while Block contains things like
417 <code>div</code> and <code>blockquote</code>.
418 </p>
421 These content sets amount to a macro mechanism for HTML definition. Most
422 elements in HTML are organized into one of these two sets, and most
423 elements in HTML allow elements from one of these sets. If we had
424 to write each element verbatim into each other element's allowed
425 children, we would have ridiculously large lists; instead we use
426 content sets to compactify the declaration.
427 </p>
430 Practically speaking, there are several useful values you can use here:
431 </p>
433 <table class="table">
434 <thead>
435 <tr>
436 <th>Content set</th>
437 <th>Description</th>
438 </tr>
439 </thead>
440 <tbody>
441 <tr>
442 <th>Inline</th>
443 <td>Character level elements, text</td>
444 </tr>
445 <tr>
446 <th>Block</th>
447 <td>Block-like elements, like paragraphs and lists</td>
448 </tr>
449 <tr>
450 <th><em>false</em></th>
451 <td>
452 Any element that doesn't fit into the mold, for example <code>li</code>
453 or <code>tr</code>
454 </td>
455 </tr>
456 </tbody>
457 </table>
460 By specifying a valid value here, all other elements that use that
461 content set will also allow your element, without you having to do
462 anything. If you specify <em>false</em>, you'll have to register
463 your element manually.
464 </p>
466 <h3>Allowed children</h3>
469 Allowed children defines the elements that this element can contain.
470 The allowed values may range from none to a complex regexp depending on
471 your element.
472 </p>
475 If you've ever taken a look at the HTML DTD's before, you may have
476 noticed declarations like this:
477 </p>
479 <pre>&lt;!ELEMENT LI - O (%flow;)* -- list item --&gt;</pre>
482 The <code>(%flow;)*</code> indicates the allowed children of the
483 <code>li</code> tag: <code>li</code> allows any number of flow
484 elements as its children. (The <code>- O</code> allows the closing tag to be
485 omitted, though in XML this is not allowed.) In HTML Purifier,
486 we'd write it like <code>Flow</code> (here's where the content sets
487 we were discussing earlier come into play). There are three shorthand
488 content models you can specify:
489 </p>
491 <table class="table">
492 <thead>
493 <tr>
494 <th>Content model</th>
495 <th>Description</th>
496 </tr>
497 </thead>
498 <tbody>
499 <tr>
500 <th>Empty</th>
501 <td>No children allowed, like <code>br</code> or <code>hr</code></td>
502 </tr>
503 <tr>
504 <th>Inline</th>
505 <td>Any number of inline elements and text, like <code>span</code></td>
506 </tr>
507 <tr>
508 <th>Flow</th>
509 <td>Any number of inline elements, block elements and text, like <code>div</code></td>
510 </tr>
511 </tbody>
512 </table>
515 This covers 90% of all the cases out there, but what about elements that
516 break the mold like <code>ul</code>? This guy requires at least one
517 child, and the only valid children for it are <code>li</code>. The
518 content model is: <code>Required: li</code>. There are two parts: the
519 first type determines what <code>ChildDef</code> will be used to validate
520 content models. The most common values are:
521 </p>
523 <table class="table">
524 <thead>
525 <tr>
526 <th>Type</th>
527 <th>Description</th>
528 </tr>
529 </thead>
530 <tbody>
531 <tr>
532 <th>Required</th>
533 <td>Children must be one or more of the valid elements</td>
534 </tr>
535 <tr>
536 <th>Optional</th>
537 <td>Children can be any number of the valid elements</td>
538 </tr>
539 <tr>
540 <th>Custom</th>
541 <td>Children must follow the DTD-style regex</td>
542 </tr>
543 </tbody>
544 </table>
547 You can also implement your own <code>ChildDef</code>: this was done
548 for a few special cases in HTML Purifier such as <code>Chameleon</code>
549 (for <code>ins</code> and <code>del</code>), <code>StrictBlockquote</code>
550 and <code>Table</code>.
551 </p>
554 The second part specifies either valid elements or a regular expression.
555 Valid elements are separated with horizontal bars (|), i.e.
556 "<code>a | b | c</code>". Use #PCDATA to represent plain text.
557 Regular expressions are based off of DTD's style:
558 </p>
560 <ul>
561 <li>Parentheses () are used for grouping</li>
562 <li>Commas (,) separate elements that should come one after another</li>
563 <li>Horizontal bars (|) indicate one or the other elements should be used</li>
564 <li>Plus signs (+) are used for a one or more match</li>
565 <li>Asterisks (*) are used for a zero or more match</li>
566 <li>Question marks (?) are used for a zero or one match</li>
567 </ul>
570 For example, "<code>a, b?, (c | d), e+, f*</code>" means "In this order,
571 one <code>a</code> element, at most one <code>b</code> element,
572 one <code>c</code> or <code>d</code> element (but not both), one or more
573 <code>e</code> elements, and any number of <code>f</code> elements."
574 Regex veterans should be able to jump right in, and those not so savvy
575 can always copy-paste W3C's content model definitions into HTML Purifier
576 and hope for the best.
577 </p>
580 A word of warning: while the regex format is extremely flexible on
581 the developer's side, it is
582 quite unforgiving on the user's side. If the user input does not <em>exactly</em>
583 match the specification, the entire contents of the element will
584 be nuked. This is why there is are specific content model types like
585 Optional and Required: while they could be implemented as <code>Custom:
586 (valid | elements)*</code>, the custom classes contain special recovery
587 measures that make sure as much of the user's original content gets
588 through. HTML Purifier's core, as a rule, does not use Custom.
589 </p>
592 One final note: you can also use Content Sets inside your valid elements
593 lists or regular expressions. In fact, the three shorthand content models
594 mentioned above are just that: abbreviations:
595 </p>
597 <table class="table">
598 <thead>
599 <tr>
600 <th>Content model</th>
601 <th>Implementation</th>
602 </tr>
603 </thead>
604 <tbody>
605 <tr>
606 <th>Inline</th>
607 <td>Optional: Inline | #PCDATA</td>
608 </tr>
609 <tr>
610 <th>Flow</th>
611 <td>Optional: Flow | #PCDATA</td>
612 </tr>
613 </tbody>
614 </table>
617 When the definition is compiled, Inline will be replaced with a
618 horizontal-bar separated list of inline elements. Also, notice that
619 it does not contain text: you have to specify that yourself.
620 </p>
622 <h3>Common attributes</h3>
625 Congratulations: you have just gotten over the proverbial hump (Allowed
626 children). Common attributes is much simpler, and boils down to
627 one question: does your element have the <code>id</code>, <code>style</code>,
628 <code>class</code>, <code>title</code> and <code>lang</code> attributes?
629 If so, you'll want to specify the <code>Common</code> attribute collection,
630 which contains these five attributes that are found on almost every
631 HTML element in the specification.
632 </p>
635 There are a few more collections, but they're really edge cases:
636 </p>
638 <table class="table">
639 <thead>
640 <tr>
641 <th>Collection</th>
642 <th>Attributes</th>
643 </tr>
644 </thead>
645 <tbody>
646 <tr>
647 <th>I18N</th>
648 <td><code>lang</code>, possibly <code>xml:lang</code></td>
649 </tr>
650 <tr>
651 <th>Core</th>
652 <td><code>style</code>, <code>class</code>, <code>id</code> and <code>title</code></td>
653 </tr>
654 </tbody>
655 </table>
658 Common is a combination of the above-mentioned collections.
659 </p>
661 <p class="aside">
662 Readers familiar with the modularization may have noticed that the Core
663 attribute collection differs from that specified by the <a
664 href="http://www.w3.org/TR/xhtml-modularization/abstract_modules.html#s_commonatts">abstract
665 modules of the XHTML Modularization 1.1</a>. We believe this section
666 to be in error, as <code>br</code> permits the use of the <code>style</code>
667 attribute even though it uses the <code>Core</code> collection, and
668 the DTD and XML Schemas supplied by W3C support our interpretation.
669 </p>
671 <h3>Attributes</h3>
674 If you didn't read the <a href="#addAttribute">earlier section on
675 adding attributes</a>, read it now. The last parameter is simply
676 an array of attribute names to attribute implementations, in the exact
677 same format as <code>addAttribute()</code>.
678 </p>
680 <h3>Putting it all together</h3>
683 We're going to implement <code>form</code>. Before we embark, lets
684 grab a reference implementation from over at the
685 <a href="http://www.w3.org/TR/html4/sgml/loosedtd.html">transitional DTD</a>:
686 </p>
688 <pre>&lt;!ELEMENT FORM - - (%flow;)* -(FORM) -- interactive form --&gt;
690 %attrs; -- %coreattrs, %i18n, %events --
691 action %URI; #REQUIRED -- server-side form handler --
692 method (GET|POST) GET -- HTTP method used to submit the form--
693 enctype %ContentType; &quot;application/x-www-form-urlencoded&quot;
694 accept %ContentTypes; #IMPLIED -- list of MIME types for file upload --
695 name CDATA #IMPLIED -- name of form for scripting --
696 onsubmit %Script; #IMPLIED -- the form was submitted --
697 onreset %Script; #IMPLIED -- the form was reset --
698 target %FrameTarget; #IMPLIED -- render in this frame --
699 accept-charset %Charsets; #IMPLIED -- list of supported charsets --
700 &gt;</pre>
703 Juicy! With just this, we can answer four of our five questions:
704 </p>
706 <ol>
707 <li>What is the element's name? <strong>form</strong></li>
708 <li>What content set does this element belong to? <strong>Block</strong>
709 (this needs a little sleuthing, I find the easiest way is to search
710 the DTD for <code>FORM</code> and determine which set it is in.)</li>
711 <li>What are the allowed children of this element? <strong>One
712 or more flow elements, but no nested <code>form</code>s</strong></li>
713 <li>What attributes does the element allow that are general? <strong>Common</strong></li>
714 <li>What attributes does the element allow that are specific to this element? <strong>A whole bunch, see ATTLIST;
715 we're going to do the vital ones: <code>action</code>, <code>method</code> and <code>name</code></strong></li>
716 </ol>
719 Time for some code:
720 </p>
722 <pre>$config = HTMLPurifier_Config::createDefault();
723 $config-&gt;set('HTML.DefinitionID', 'enduser-customize.html tutorial');
724 $config-&gt;set('HTML.DefinitionRev', 1);
725 $config-&gt;set('Cache.DefinitionImpl', null); // remove this later!
726 $def = $config-&gt;getHTMLDefinition(true);
727 $def-&gt;addAttribute('a', 'target', new HTMLPurifier_AttrDef_Enum(
728 array('_blank','_self','_target','_top')
730 <strong>$form = $def-&gt;addElement(
731 'form', // name
732 'Block', // content set
733 'Flow', // allowed children
734 'Common', // attribute collection
735 array( // attributes
736 'action*' => 'URI',
737 'method' => 'Enum#get|post',
738 'name' => 'ID'
741 $form-&gt;excludes = array('form' => true);</strong></pre>
744 Each of the parameters corresponds to one of the questions we asked.
745 Notice that we added an asterisk to the end of the <code>action</code>
746 attribute to indicate that it is required. If someone specifies a
747 <code>form</code> without that attribute, the tag will be axed.
748 Also, the extra line at the end is a special extra declaration that
749 prevents forms from being nested within each other.
750 </p>
753 And that's all there is to it! Implementing the rest of the form
754 module is left as an exercise to the user; to see more examples
755 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
756 in your local HTML Purifier installation.
757 </p>
759 <h2>And beyond...</h2>
762 Perceptive users may have realized that, to a certain extent, we
763 have simply re-implemented the facilities of XML Schema or the
764 Document Type Definition. What you are seeing here, however, is
765 not just an XML Schema or Document Type Definition: it is a fully
766 expressive method of specifying the definition of HTML that is
767 a portable superset of the capabilities of the two above-mentioned schema
768 languages. What makes HTMLDefinition so powerful is the fact that
769 if we don't have an implementation for a content model or an attribute
770 definition, you can supply it yourself by writing a PHP class.
771 </p>
774 There are many facets of HTMLDefinition beyond the Advanced API I have
775 walked you through today. To find out more about these, you can
776 check out these source files:
777 </p>
779 <ul>
780 <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>
781 <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>
782 </ul>
784 </body></html>
786 <!-- vim: et sw=4 sts=4