@@ -1,6 +1,7 @@
tags
conf/
test-settings.php
+config-schema.php
library/HTMLPurifier/DefinitionCache/Serializer/*/
library/standalone/
library/HTMLPurifier.standalone.php
.gitignore
@@ -37,6 +37,9 @@ NEWS ( CHANGELOG and HISTORY ) HTMLPurifier
! Implement %Attr.AllowedClasses, which allows administrators to restrict
classes users can use to a specified finite set of classes, and
%Attr.ForbiddenClasses, which is the logical inverse.
+! You can now maintain your own configuration schema directories by
+ creating a config-schema.php file or passing an extra argument. Check
+ docs/dev-config-schema.html for more details.
- Fix bug where URIDefinition would not get cleared if it's directives got
changed.
- Fix fatal error in HTMLPurifier_Encoder on certain platforms (probably NetBSD 5.0)
NEWS
@@ -26,7 +26,6 @@ afraid to cast your vote for the next feature to be implemented!
- 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)
- - Implement <area>
FUTURE VERSIONS
---------------
@@ -35,6 +34,8 @@ FUTURE VERSIONS
# Implement untrusted, dangerous elements/attributes
# Implement IDREF support (harder than it seems, since you cannot have
IDREFs to non-existent IDs)
+ - Implement <area> (client and server side image maps are blocking
+ on IDREF support)
# Frameset XHTML 1.0 and HTML 4.01 doctypes
- Figure out how to simultaneously set %CSS.Trusted and %HTML.Trusted (?)
TODO
@@ -18,22 +18,24 @@ TODO:
if (version_compare(PHP_VERSION, '5.2', '<')) exit('PHP 5.2+ required.');
error_reporting(E_ALL | E_STRICT);
-chdir(dirname(__FILE__));
-
// load dual-libraries
-require_once '../extras/HTMLPurifierExtras.auto.php';
-require_once '../library/HTMLPurifier.auto.php';
+require_once dirname(__FILE__) . '/../extras/HTMLPurifierExtras.auto.php';
+require_once dirname(__FILE__) . '/../library/HTMLPurifier.auto.php';
// setup HTML Purifier singleton
HTMLPurifier::getInstance(array(
'AutoFormat.PurifierLinkify' => true
));
-$interchange = HTMLPurifier_ConfigSchema_InterchangeBuilder::buildFromDirectory();
+$builder = new HTMLPurifier_ConfigSchema_InterchangeBuilder();
+$interchange = new HTMLPurifier_ConfigSchema_Interchange();
+$builder->buildDir($interchange);
+$loader = dirname(__FILE__) . '/../config-schema.php';
+if (file_exists($loader)) include $loader;
$interchange->validate();
$style = 'plain'; // use $_GET in the future, careful to validate!
-$configdoc_xml = 'configdoc.xml';
+$configdoc_xml = dirname(__FILE__) . '/configdoc.xml';
$xml_builder = new HTMLPurifier_ConfigSchema_Builder_Xml();
$xml_builder->openURI($configdoc_xml);
@@ -50,13 +52,13 @@ if (!$output) {
}
// write out
-file_put_contents("$style.html", $output);
+file_put_contents(dirname(__FILE__) . "/$style.html", $output);
if (php_sapi_name() != 'cli') {
// output (instant feedback if it's a browser)
echo $output;
} else {
- echo 'Files generated successfully.';
+ echo "Files generated successfully.\n";
}
// vim: et sw=4 sts=4
configdoc/generate.php
@@ -114,7 +114,7 @@ Test.Example</pre>
</tr>
<tr>
<td>VALUE-ALIASES</td>
- <td>'baz' => 'bar'</td>
+ <td>'baz' => 'bar'</td>
<td><em>Optional</em>. Mapping of one value to another, and
should be a comma separated list of keypair duples. This
is only allowed string, istring, text and itext TYPEs.</td>
@@ -213,7 +213,7 @@ Test.Example</pre>
</tr>
<tr>
<td>lookup</td>
- <td>array('key' => true)</td>
+ <td>array('key' => true)</td>
<td>Lookup array, used with <code>isset($var[$key])</code></td>
</tr>
<tr>
@@ -223,7 +223,7 @@ Test.Example</pre>
</tr>
<tr>
<td>hash</td>
- <td>array('key' => 'val')</td>
+ <td>array('key' => 'val')</td>
<td>Associative array of keys to values</td>
</tr>
<tr>
@@ -267,6 +267,41 @@ Test.Example</pre>
If you ever make changes to your configuration directives, you
will need to run this script again.
</p>
+ <h2>Adding in-house schema definitions</h2>
+
+ <p>
+ Placing stuff directly in HTML Purifier's source tree is generally not a
+ good idea, so HTML Purifier 4.0.0+ has some facilities in place to make your
+ life easier.
+ </p>
+
+ <p>
+ The first is to pass an extra parameter to <code>maintenance/generate-schema-cache.php</code>
+ with the location of your directory (relative or absolute path will do). For example,
+ if I'm storing my custom definitions in <em>/var/htmlpurifier/myschema</em>, run:
+ <code>php maintenance/generate-schema-cache.php /var/htmlpurifier/myschema</code>.
+ </p>
+
+ <p>
+ Alternatively, you can create a small loader PHP file in the HTML Purifier base
+ directory named <code>config-schema.php</code> (this is the same directory
+ you would place a <code>test-settings.php</code> file). In this file, add
+ the following line for each directory you want to load:
+ </p>
+
+<pre>$builder->buildDir($interchange, '/var/htmlpurifier/myschema');</pre>
+
+ <p>You can even load a single file using:</p>
+
+<pre>$builder->buildFile($interchange, '/var/htmlpurifier/myschema/MyApp.Directive.txt');</pre>
+
+ <p>Storing custom definitions that you don't plan on sending back upstream in
+ a separate directory is <em>definitely</em> a good idea! Additionally, picking
+ a good namespace can go a long way to saving you grief if you want to use
+ someone else's change, but they picked the same name, or if HTML Purifier
+ decides to add support for a configuration directive that has the same name.</p>
+
+ <!-- TODO: how to name directives that rely on naming conventions -->
<h2>Errors</h2>
docs/dev-config-schema.html
@@ -18,12 +18,11 @@
<div id="home"><a href="http://htmlpurifier.org/">HTML Purifier</a> End-User Documentation</div>
<p>
- You may have heard of the <a href="dev-advanced-api.html">Advanced API</a>.
- If you're interested in reading dry prose and boring functional
- specifications, feel free to click that link to get a no-nonsense overview
- on the Advanced API. For the rest of us, there's this tutorial. By the time
- you're finished reading this, you should have a pretty good idea on
- how to implement custom tags and attributes that HTML Purifier may not have.
+ HTML Purifier has this quirk where if you try to allow certain elements or
+ attributes, HTML Purifier will tell you that it's not supported, and that
+ you should go to the forums to find out how to implement it. Well, this
+ document is how to implement elements and attributes which HTML Purifier
+ doesn't support out of the box.
</p>
<h2>Is it necessary?</h2>
docs/enduser-customize.html
@@ -216,6 +216,7 @@ class HTMLPurifier_Config
/**
* Retrieves all directives, organized by namespace
+ * @warning This is a pretty inefficient function, avoid if you can
*/
public function getAll() {
if (!$this->finalized) $this->autoFinalize();
library/HTMLPurifier/Config.php
@@ -15,10 +15,15 @@ class HTMLPurifier_ConfigSchema_InterchangeBuilder
public static function buildFromDirectory($dir = null) {
$builder = new HTMLPurifier_ConfigSchema_InterchangeBuilder();
$interchange = new HTMLPurifier_ConfigSchema_Interchange();
+ return $builder->buildDir($interchange, $dir);
+ }
- if (!$dir) $dir = HTMLPURIFIER_PREFIX . '/HTMLPurifier/ConfigSchema/schema/';
- $info = parse_ini_file($dir . 'info.ini');
- $interchange->name = $info['name'];
+ public function buildDir($interchange, $dir = null) {
+ if (!$dir) $dir = HTMLPURIFIER_PREFIX . '/HTMLPurifier/ConfigSchema/schema';
+ if (file_exists($dir . '/info.ini')) {
+ $info = parse_ini_file($dir . '/info.ini');
+ $interchange->name = $info['name'];
+ }
$files = array();
$dh = opendir($dir);
@@ -32,7 +37,7 @@ class HTMLPurifier_ConfigSchema_InterchangeBuilder
sort($files);
foreach ($files as $file) {
- $builder->buildFile($interchange, $dir . $file);
+ $this->buildFile($interchange, $dir . '/' . $file);
}
return $interchange;
library/HTMLPurifier/ConfigSchema/InterchangeBuilder.php
@@ -17,6 +17,6 @@ function postfix_is($comp, $subject) {
}
// Load useful stuff like FSTools
-require_once '../extras/HTMLPurifierExtras.auto.php';
+require_once dirname(__FILE__) . '/../extras/HTMLPurifierExtras.auto.php';
// vim: et sw=4 sts=4
maintenance/common.php
@@ -1,9 +1,8 @@
#!/usr/bin/php
<?php
-chdir(dirname(__FILE__));
-require_once 'common.php';
-require_once '../library/HTMLPurifier.auto.php';
+require_once dirname(__FILE__) . '/common.php';
+require_once dirname(__FILE__) . '/../library/HTMLPurifier.auto.php';
assertCli();
/**
@@ -12,13 +11,28 @@ assertCli();
* library/HTMLPurifier/ConfigSchema/schema.ser.
*
* This should be run when new configuration options are added to
- * HTML Purifier. A cached version is available via SVN so this does not
- * normally have to be regenerated.
+ * HTML Purifier. A cached version is available via the repository
+ * so this does not normally have to be regenerated.
+ *
+ * If you have a directory containing custom configuration schema files,
+ * you can simple add a path to that directory as a parameter to
+ * this, and they will get included.
*/
-$target = '../library/HTMLPurifier/ConfigSchema/schema.ser';
+$target = dirname(__FILE__) . '/../library/HTMLPurifier/ConfigSchema/schema.ser';
+
+$builder = new HTMLPurifier_ConfigSchema_InterchangeBuilder();
+$interchange = new HTMLPurifier_ConfigSchema_Interchange();
+
+$builder->buildDir($interchange);
+
+$loader = dirname(__FILE__) . '/../config-schema.php';
+if (file_exists($loader)) include $loader;
+foreach ($_SERVER['argv'] as $i => $dir) {
+ if ($i === 0) continue;
+ $builder->buildDir($interchange, realpath($dir));
+}
-$interchange = HTMLPurifier_ConfigSchema_InterchangeBuilder::buildFromDirectory();
$interchange->validate();
$schema_builder = new HTMLPurifier_ConfigSchema_Builder_ConfigSchema();
maintenance/generate-schema-cache.php
a025203b180fcf53fdd1489844a45bc91e9c1faf
Edward Z. Yang
edwardzyang@thewritingpot.com
http://github.com/ezyang/htmlpurifier/commit/5bf7ac4e9f1798ab6c7bcc9ce299c5bbbb23396f
5bf7ac4e9f1798ab6c7bcc9ce299c5bbbb23396f
2009-05-29T19:16:35-07:00
2009-05-29T19:10:47-07:00
Add docs and facilities for having separate directories of schemas.
Signed-off-by: Edward Z. Yang <edwardzyang@thewritingpot.com>
aaa733ca17e108cad8661e3c4ab691c302198025
Edward Z. Yang
edwardzyang@thewritingpot.com