Fix two bugs with caching of customized raw definitions.
[htmlpurifier.git] / docs / enduser-customize.html
blob7e1ffa2601987ad84398a5cc5b0823897a82723b
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 if ($def = $config-&gt;maybeGetRawHTMLDefinition()) {
150 // our code will go here
151 }</pre>
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>
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>
188 <h2>Turn off caching</h2>
191 To make development easier, we're going to temporarily turn off
192 definition caching:
193 </p>
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>
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>
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>
221 <h2 id="addAttribute">Add an attribute</h2>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
379 Trust me, you'll learn to love the shorthand.
380 </p>
382 <h2>Add an element</h2>
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>
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>
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>
404 <h3>Content set</h3>
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>
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>
424 Practically speaking, there are several useful values you can use here:
425 </p>
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>
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>
460 <h3>Allowed children</h3>
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>
469 If you've ever taken a look at the HTML DTD's before, you may have
470 noticed declarations like this:
471 </p>
473 <pre>&lt;!ELEMENT LI - O (%flow;)* -- list item --&gt;</pre>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
616 <h3>Common attributes</h3>
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>
629 There are a few more collections, but they're really edge cases:
630 </p>
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>
652 Common is a combination of the above-mentioned collections.
653 </p>
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>
665 <h3>Attributes</h3>
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>
674 <h3>Putting it all together</h3>
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>
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>
697 Juicy! With just this, we can answer four of our five questions:
698 </p>
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>
713 Time for some code:
714 </p>
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')
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'
735 $form-&gt;excludes = array('form' => true);</strong></pre>
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>
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>
753 <h2>And beyond...</h2>
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>
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>
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>
778 <h2 id="optimized">Notes for HTML Purifier 4.2.0 and earlier</h3>
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>
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>
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>
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>
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>
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>
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>
828 A slightly less efficient version of this was what was going on with
829 old versions of HTML Purifier.
830 </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>
847 </body></html>
849 <!-- vim: et sw=4 sts=4