Você não pode selecionar mais de 25 tópicos Os tópicos devem começar com uma letra ou um número, podem incluir traços ('-') e podem ter até 35 caracteres.

851 linhas
29KB

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