@@ -231,12 +231,12 @@ HTML Purifier uses iconv to support other character encodings, as such, any encoding that iconv supports <http://www.gnu.org/software/libiconv/> HTML Purifier supports with this code: - $config->set('Core', 'Encoding', /* put your encoding here */); + $config->set('Core.Encoding', /* put your encoding here */); An example usage for Latin-1 websites (the most common encoding for English websites): - $config->set('Core', 'Encoding', 'ISO-8859-1'); + $config->set('Core.Encoding', 'ISO-8859-1'); Note that HTML Purifier's support for non-Unicode encodings is crippled by the fact that any character not supported by that encoding will be silently @@ -251,7 +251,7 @@ reason, I do not include the solution in this document). For those of you using HTML 4.01 Transitional, you can disable XHTML output like this: - $config->set('HTML', 'Doctype', 'HTML 4.01 Transitional'); + $config->set('HTML.Doctype', 'HTML 4.01 Transitional'); Other supported doctypes include: @@ -277,14 +277,14 @@ are, respectively, %HTML.Allowed, %URI.MakeAbsolute and %URI.Base, and %AutoFormat.AutoParagraph. The %Namespace.Directive naming convention translates to: - $config->set('Namespace', 'Directive', $value); + $config->set('Namespace.Directive', $value); E.g. - $config->set('HTML', 'Allowed', 'p,b,a[href],i'); - $config->set('URI', 'Base', 'http://www.example.com'); - $config->set('URI', 'MakeAbsolute', true); - $config->set('AutoFormat', 'AutoParagraph', true); + $config->set('HTML.Allowed', 'p,b,a[href],i'); + $config->set('URI.Base', 'http://www.example.com'); + $config->set('URI.MakeAbsolute', true); + $config->set('AutoFormat.AutoParagraph', true); --------------------------------------------------------------------------- @@ -318,11 +318,11 @@ If you are unable or unwilling to give write permissions to the cache directory, you can either disable the cache (and suffer a performance hit): - $config->set('Core', 'DefinitionCache', null); + $config->set('Core.DefinitionCache', null); Or move the cache directory somewhere else (no trailing slash): - $config->set('Cache', 'SerializerPath', '/home/user/absolute/path'); + $config->set('Cache.SerializerPath', '/home/user/absolute/path'); --------------------------------------------------------------------------- @@ -363,8 +363,8 @@ If your website is in a different encoding or doctype, use this code: require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php'; $config = HTMLPurifier_Config::createDefault(); - $config->set('Core', 'Encoding', 'ISO-8859-1'); // replace with your encoding - $config->set('HTML', 'Doctype', 'HTML 4.01 Transitional'); // replace with your doctype + $config->set('Core.Encoding', 'ISO-8859-1'); // replace with your encoding + $config->set('HTML.Doctype', 'HTML 4.01 Transitional'); // replace with your doctype $purifier = new HTMLPurifier($config); $clean_html = $purifier->purify($dirty_html); INSTALL @@ -18,14 +18,13 @@ afraid to cast your vote for the next feature to be implemented! - Incorporate download and resize support as implemented here: http://htmlpurifier.org/phorum/read.php?3,2795,3628 - Think about allowing explicit order of operations hooks for transforms -- Make it dead easy for other authors to maintain their own configuration - pools. Encourage them to namespace them (this flies counter to our - "hey, let's use convention idea", so that's why the "register" extra - field will end up being a good idea: because it means we can forgo - convention for external things +- Add "register" field to config schemas to eliminate dependence on + naming conventions - Make it easy for people to cache their entire configuration (so that they have one script they run to change configuration, and then a stub loader to get that configuration) +- Add examples to everything (make built-in which also automatically + gives output) FUTURE VERSIONS --------------- TODO @@ -17,202 +17,9 @@ <div id="home"><a href="http://htmlpurifier.org/">HTML Purifier</a> End-User Documentation</div> - Warning: This document may be out-of-date. When in doubt, - consult the source code documentation. + Please see <a href="enduser-customize.html">Customize!</a> -HTML Purifier currently natively supports only a subset of HTML's -allowed elements, attributes, and behavior; specifically, this subset -is the set of elements that are safe for untrusted users to use. -However, HTML Purifier is often utilized to ensure standards-compliance -from input that is trusted (making it a sort of Tidy substitute), -and often users need to define new elements or attributes. The -advanced API is oriented specifically for these use-cases. - -Our goals are to let the user: - -<dl> - <dt>Select</dt> - <dd><ul> - <li>Doctype</li> -  - <li>Elements / Attributes / Modules</li> - <li>Tidy</li> - </ul></dd> - <dt>Customize</dt> - <dd><ul> - <li>Attributes</li> - <li>Elements</li> -  - </ul></dd> -</dl> - -<h2>Select</h2> - -For basic use, the user will have to specify some basic parameters. This -is not strictly necessary, as HTML Purifier's default setting will always -output safe code, but is required for standards-compliant output. - -<h3>Selecting a Doctype</h3> - -The first thing to select is the doctype. This -is essential for standards-compliant output. - -This identifier is based -on the name the W3C has given to the document type and not -the DTD identifier. - -This parameter is set via the configuration object: - -<pre>$config->set('HTML', 'Doctype', 'XHTML 1.0 Transitional');</pre> - -Due to historical reasons, the default doctype is XHTML 1.0 -Transitional, however, we really shouldn't be guessing what the user's -doctype is. Fortunantely, people who can't be bothered to set this won't -be bothered when their pages stop validating. - -<h3>Selecting Elements / Attributes / Modules</h3> - -HTML Purifier will, by default, allow as many elements and attributes -as possible. However, a user may decide to roll their own filterset by -selecting modules, elements and attributes to allow for their own -specific use-case. This can be done using %HTML.Allowed: - -<pre>$config->set('HTML', 'Allowed', 'a[href|title],em,p,blockquote');</pre> - -The directive %HTML.Allowed is a convenience feature -that may be fully expressed with the legacy interface. - -We currently support another interface from older versions: - -<pre>$config->set('HTML', 'AllowedElements', 'a,em,p,blockquote'); -$config->set('HTML', 'AllowedAttributes', 'a.href,a.title');</pre> - -A user may also choose to allow modules using a specialized -directive: - -<pre>$config->set('HTML', 'AllowedModules', 'Hypertext,Text,Lists');</pre> - -But it is not expected that this feature will be widely used. - -Module selection will work slightly differently -from the other AllowedElements and AllowedAttributes directives by -directly modifying the doctype you are operating in, in the spirit of -XHTML 1.1's modularization. We stop users from shooting themselves in the -foot by mandating the modules in %HTML.CoreModules be used. - -Modules are distinguished from regular elements by the -case of their first letter. While XML distinguishes between and allows -lower and uppercase letters in element names, XHTML uses only lower-case -element names for sake of consistency. - -<h3>Selecting Tidy</h3> - -The name of this segment of functionality is inspired off of Dave -Ragget's program HTML Tidy, which purported to help clean up HTML. In -HTML Purifier, Tidy functionality involves turning unsupported and -deprecated elements into standards-compliant ones, maintaining -backwards compatibility, and enforcing best practices. - -This is a complicated feature, and is explained more in depth at -<a href="enduser-tidy.html">the Tidy documentation page</a>. - - - -<h2>Customize</h2> - -By reviewing topic posts in the support forum, we determined that -there were two primarily demanded customization features people wanted: -to add an attribute to an existing element, and to add an element. -Thus, we'll want to create convenience functions for these common -use-cases. - -Note that the functions described here are only available if -a raw copy of <code>HTMLPurifier_HTMLDefinition</code> was retrieved. -Furthermore, caching may prevent your changes from immediately -being seen: consult <a href="enduser-customize.html">enduser-customize.html</a> on how -to work around this. - -<h3>Attributes</h3> - -An attribute is bound to an element by a name and has a specific -<code>AttrDef</code> that validates it. The interface is therefore: - -<pre>function addAttribute($element, $attribute, $attribute_def);</pre> - -Example of the functionality in action: - -<pre>$def->addAttribute('a', 'rel', 'Enum#nofollow');</pre> - -The <code>$attribute_def</code> value is flexible, -to make things simpler. It can be a literal object or: - -<ul> -  - <li>String attribute type: We'll use <code>HTMLPurifier_AttrTypes</code> - to resolve it for you. Any data that follows a hash mark (#) will - be used to customize the attribute type: in the example above, - we specify which values for Enum to allow.</li> -</ul> - -<h3>Elements</h3> - -An element requires certain information as specified by -<code>HTMLPurifier_ElementDef</code>. However, not all of it is necessary, -the usual things required are: - -<ul> - <li>Attributes</li> - <li>Content model/type</li> - <li>Registration in a content set</li> -</ul> - -This suggests an API like this: - -<pre>function addElement($element, $type, $contents, - $attr_collections = array(); $attributes = array());</pre> - -Each parameter explained in depth: - -<dl> - <dt><code>$element</code></dt> - <dd>Element name, ex. 'label'</dd> - <dt><code>$type</code></dt> - <dd>Content set to register in, ex. 'Inline' or 'Flow'</dd> - <dt><code>$contents</code></dt> - <dd>Description of allowed children. This is a merged form of - <code>HTMLPurifier_ElementDef</code>'s member variables - <code>$content_model</code> and <code>$content_model_type</code>, - where the form is <q>Type: Model</q>, ex. 'Optional: Inline'. - There are also a number of predefined templates one may use.</dd> - <dt><code>$attr_collections</code></dt> - <dd>Array (or string if only one) of attribute collection(s) to - merge into the attributes array.</dd> - <dt><code>$attributes</code></dt> - <dd>Array of attribute names to attribute definitions, much like - the above-described attribute customization.</dd> -</dl> - -A possible usage: - -<pre>$def->addElement('font', 'Inline', 'Optional: Inline', 'Common', - array('color' => 'Color'));</pre> - -See <code>HTMLPurifier/HTMLModule.php</code> for details. - </body></html> <!-- vim: et sw=4 sts=4 docs/dev-advanced-api.html @@ -155,9 +155,9 @@ <pre>$config = HTMLPurifier_Config::createDefault(); -$config->set('HTML', 'DefinitionID', 'enduser-customize.html tutorial'); -$config->set('HTML', 'DefinitionRev', 1); -$def = $config->getHTMLDefinition(true);</pre> +$config->set('HTML.DefinitionID', 'enduser-customize.html tutorial'); +$config->set('HTML.DefinitionRev', 1); +$def = $config->getHTMLDefinition(true);</pre> Assuming that HTML Purifier has already been properly loaded (hint: @@ -210,10 +210,10 @@ $def = $config->getHTMLDefinition(true);</pre> <pre>$config = HTMLPurifier_Config::createDefault(); -$config->set('HTML', 'DefinitionID', 'enduser-customize.html tutorial'); -$config->set('HTML', 'DefinitionRev', 1); -$config->set('Cache', 'DefinitionImpl', null); // remove this later! -$def = $config->getHTMLDefinition(true);</pre> +$config->set('HTML.DefinitionID', 'enduser-customize.html tutorial'); +$config->set('HTML.DefinitionRev', 1); +$config->set('Cache.DefinitionImpl', null); // TODO: remove this later! +$def = $config->getHTMLDefinition(true);</pre> A few things should be mentioned about the caching mechanism before @@ -266,10 +266,10 @@ $def = $config->getHTMLDefinition(true);</pre> <pre>$config = HTMLPurifier_Config::createDefault(); -$config->set('HTML', 'DefinitionID', 'enduser-customize.html tutorial'); -$config->set('HTML', 'DefinitionRev', 1); -$config->set('Cache', 'DefinitionImpl', null); // remove this later! -$def = $config->getHTMLDefinition(true); +$config->set('HTML.DefinitionID', 'enduser-customize.html tutorial'); +$config->set('HTML.DefinitionRev', 1); +$config->set('Cache.DefinitionImpl', null); // remove this later! +$def = $config->getHTMLDefinition(true); $def->addAttribute('a', 'target', 'Enum#_blank,_self,_target,_top');</pre> @@ -384,11 +384,11 @@ $def = $config->getHTMLDefinition(true); <pre>$config = HTMLPurifier_Config::createDefault(); -$config->set('HTML', 'DefinitionID', 'enduser-customize.html tutorial'); -$config->set('HTML', 'DefinitionRev', 1); -$config->set('Cache', 'DefinitionImpl', null); // remove this later! -$def = $config->getHTMLDefinition(true); -$def->addAttribute('a', 'target', new HTMLPurifier_AttrDef_Enum( +$config->set('HTML.DefinitionID', 'enduser-customize.html tutorial'); +$config->set('HTML.DefinitionRev', 1); +$config->set('Cache.DefinitionImpl', null); // remove this later! +$def = $config->getHTMLDefinition(true); +$def->addAttribute('a', 'target', new HTMLPurifier_AttrDef_Enum( array('_blank','_self','_target','_top') ));</pre> @@ -731,14 +731,14 @@ $def = $config->getHTMLDefinition(true); <pre>$config = HTMLPurifier_Config::createDefault(); -$config->set('HTML', 'DefinitionID', 'enduser-customize.html tutorial'); -$config->set('HTML', 'DefinitionRev', 1); -$config->set('Cache', 'DefinitionImpl', null); // remove this later! -$def = $config->getHTMLDefinition(true); -$def->addAttribute('a', 'target', new HTMLPurifier_AttrDef_Enum( +$config->set('HTML.DefinitionID', 'enduser-customize.html tutorial'); +$config->set('HTML.DefinitionRev', 1); +$config->set('Cache.DefinitionImpl', null); // remove this later! +$def = $config->getHTMLDefinition(true); +$def->addAttribute('a', 'target', new HTMLPurifier_AttrDef_Enum( array('_blank','_self','_target','_top') )); -$form = $def->addElement( +$form = $def->addElement( 'form', // name 'Block', // content set 'Flow', // allowed children @@ -749,7 +749,7 @@ $def->addAttribute('a', 'target', new HTMLPurifier_AttrDef_Enum( 'name' => 'ID' ) ); -$form->excludes = array('form' => true);</pre> +$form->excludes = array('form' => true);</pre> Each of the parameters corresponds to one of the questions we asked. docs/enduser-customize.html @@ -31,7 +31,7 @@ by default. IDs, however, are quite useful functionality to have, so if users start complaining about broken anchors you'll probably want to turn them back on -with %HTML.EnableAttrID. But before you go mucking around with the config +with %Attr.EnableID. But before you go mucking around with the config object, it's probably worth to take some precautions to keep your page validating. Why? @@ -56,8 +56,8 @@ validating. Why? deal with the most obvious solution: preventing users from using any IDs that appear elsewhere on the document. The method is simple: -<pre>$config->set('HTML', 'EnableAttrID', true); -$config->set('Attr', 'IDBlacklist' array( +<pre>$config->set('Attr.EnableID', true); +$config->set('Attr.IDBlacklist' array( 'list', 'of', 'attribute', 'values', 'that', 'are', 'forbidden' ));</pre> @@ -88,8 +88,8 @@ all, they might have simply specified a duplicate ID by accident. This method, too, is quite simple: add a prefix to all user IDs. With this code: -<pre>$config->set('HTML', 'EnableAttrID', true); -$config->set('Attr', 'IDPrefix', 'user_');</pre> +<pre>$config->set('Attr.EnableID', true); +$config->set('Attr.IDPrefix', 'user_');</pre> ...this: @@ -109,7 +109,7 @@ user_ to the beginning." nothing about multiple HTML Purifier outputs on one page. Thus, we have a second configuration value to piggy-back off of: %Attr.IDPrefixLocal: -<pre>$config->set('Attr', 'IDPrefixLocal', 'comment' . $id . '_');</pre> +<pre>$config->set('Attr.IDPrefixLocal', 'comment' . $id . '_');</pre> This new attributes does nothing but append on to regular IDPrefix, but is special in that it is volatile: it's value is determined at run-time and @@ -137,7 +137,7 @@ anchors is beyond me. To revert back to pre-1.2.0 behavior, simply: -<pre>$config->set('HTML', 'EnableAttrID', true);</pre> +<pre>$config->set('Attr.EnableID', true);</pre> Don't come crying to me when your page mysteriously stops validating, though. docs/enduser-id.html @@ -76,7 +76,7 @@ associated with it, although it may change depending on your doctype. change the level of cleaning by setting the %HTML.TidyLevel configuration directive: -<pre>$config->set('HTML', 'TidyLevel', 'heavy'); // burn baby burn!</pre> +<pre>$config->set('HTML.TidyLevel', 'heavy'); // burn baby burn!</pre> <h2>Is the light level really light?</h2> @@ -165,17 +165,17 @@ smoketest</a>. so happy about the br@clear implementation. That's perfectly fine! HTML Purifier will make accomodations: -<pre>$config->set('HTML', 'Doctype', 'XHTML 1.0 Transitional'); -$config->set('HTML', 'TidyLevel', 'heavy'); // all changes, minus... -$config->set('HTML', 'TidyRemove', 'br@clear');</pre> +<pre>$config->set('HTML.Doctype', 'XHTML 1.0 Transitional'); +$config->set('HTML.TidyLevel', 'heavy'); // all changes, minus... +$config->set('HTML.TidyRemove', 'br@clear');</pre> That third line does the magic, removing the br@clear fix from the module, ensuring that <code> </code> will pass through unharmed. The reverse is possible too: -<pre>$config->set('HTML', 'Doctype', 'XHTML 1.0 Transitional'); -$config->set('HTML', 'TidyLevel', 'none'); // no changes, plus... -$config->set('HTML', 'TidyAdd', 'p@align');</pre> +<pre>$config->set('HTML.Doctype', 'XHTML 1.0 Transitional'); +$config->set('HTML.TidyLevel', 'none'); // no changes, plus... +$config->set('HTML.TidyAdd', 'p@align');</pre> In this case, all transformations are shut off, except for the p@align one, which you found handy. docs/enduser-tidy.html @@ -75,7 +75,7 @@ passes through HTML Purifier unharmed. And the corresponding usage: <pre><?php - $config->set('Filter', 'YouTube', true); + $config->set('Filter.YouTube', true); ?></pre> There is a bit going in the two code snippets, so let's explain. docs/enduser-youtube.html 5bf7ac4e9f1798ab6c7bcc9ce299c5bbbb23396f Edward Z. Yang edwardzyang@thewritingpot.com http://github.com/ezyang/htmlpurifier/commit/77b60a4206db5e0d854b47ad4985773381d8ebb1 77b60a4206db5e0d854b47ad4985773381d8ebb1

2009-05-29T20:46:40-07:00

Update documentation to new configuration format. Signed-off-by: Edward Z. Yang <edwardzyang@thewritingpot.com> 708cf4f18397ac37b0e7b43d6c0cc6749a9ed5af Edward Z. Yang edwardzyang@thewritingpot.com