mod_accessibility

Basic Installation

These basic instructions should be sufficient to install and run mod_accessibility. Further details are provided below, but can be ignored for a basic installation.

Download mod_accessibility, and install it in your modules directory.
If you don't already have libxml2, download and install it (eg as /usr/local/lib/libxml2.so).

Configure Apache to load libxml2 and mod_accessibility at startup. Add the following to httpd.conf:


LoadFile	/usr/local/lib/libxml2.so
LoadModule	accessibility_module	modules/mod_accessibility.so

Configure Apache to filter documents with mod_accessibility. For example, to apply it to static HTML documents, use
```
AddOutputFilter	accessibility	.html
```

Working with different handlers

Apache's standard filter control directives are not quite enough. A problem arises when Apache runs a subrequest - e.g. a .var file used to serve the language requested by a user's browser. If we just use AddOutputFilter, then mod_accessibility will run twice - once as required, but also once to parse the .var file.

To prevent this happening, mod_accessibility by default removes itself when a handler other than the default HTML handler is in use. To enable it, the AccessibilityAddHandler is provided (see below). Use this to add support for the handlers you are using: e.g.
AccessibilityAddHandler cgi-script,modxml,asis
will enable it for CGI scripts, XML applications and as-is files. This is additional to the standard Apache configuration.

For more information about the configuration, see the Apache manual. Except for the AccessibilityAddHandler directive, the above requires only standard Apache directives that should be familiar to any server administrator.

Advanced Configuration

Directives

See the configuration page for details of configuring mod_accessibility.

Stylesheets

Most mod_accessibility views preserve your stylesheets. However, the Betsie view suppresses all stylesheets, while the Outline and Links views are metadata rather than full views of a page. For each of these views, mod_accessibility links a CSS stylesheet. You can therefore fine-tune the presentation of these views by writing your own betsie.css, links.css and outline.css.

Other Configuration

If you need something that's not yet available, it may or may not already be work-in-progress or planned. Please ask.

HTTP Client Support

mod_accessibility fetches remote content by HTTP when it resolves a link (for its title), or includes the contents of a frame. It offers a choice of HTTP Client implementations:

xmlNanoHTTP: This, the HTTP Client support from libxml2, is the default. It is a fairly limited but tried-and-tested implementation, and is used by default.
apr_network_io: xmlNanoHTTP has one serious drawback: uses a hard-wired 60-second timeout for HTTP requests. This could lead to a denial-of-service attack on a webserver: if external links were slow to respond, a sufficiently large number of concurrent requests could tie up all available process/threads. To avoid this, we have added very minimal HTTP support using the Apache APR library functions. This is governed by the AccessibilityHTTPTimeout directive. Setting this to any nonzero value will cause mod_accessibility to use the APR library functions. The value is in milliseconds, so for example AccessibilityHTTPTimeout 2500 will set a 2.5 second timeout.

HTTP Proxy Support

xmlNanoHTTP supports HTTP proxies; the mod_accessibility apr_network_io HTTP implementation doesn't. If you wish mod_accessibility to go through a proxy, you should set the HTTP_PROXY environment variable to specify the proxy, and leave AccessibilityHTTPTimeout unset. Your proxy can be configured to take care of timeouts.

Recommended Configuration

It is recommended that you always give your users a choice of whether or not to filter your pages. There are many ways to accomplish this, but the simplest way is to make your documents available at different URLs with and without mod_accessibility configured.

For example, if your server is http://www.example.org/, you could leave that as-is, but configure another virtual server at http://access.example.org/, with identical configuration but with the addition of an AddOutputFilter directive. You could then offer a simple link to each site from the other.

Relationship with other Output Filters

mod_accessibility should be inserted in the output filter chain after any other modules used for content generation - such as mod_include (SSI/.shtml) or XSLT - but before any encoding filters such as mod_gzip or mod_deflate, or of course mod_ssl (secure HTTP encryption), or mod_cache. Apache will take care of the latter automatically, but you need to ensure that it comes after other contents filters.

Good Examples

(mod_accessibility works well after other content filters).


AddOutputFilter INCLUDES;accessibility	.shtml

or

AddOutputFilter modxml-xslt;accessibility	.xml

Bad Examples

(mod_accessibility should not normally be used before other content filters).


AddOutputFilter accessibility;INCLUDES	.shtml

or

AddOutputFilter accessibility;modxml-xslt	.xml

Character Sets and Internationalisation

(Under construction - you can probably safely ignore this).

If your server is correctly configured before you add mod_accessibility, it should work correctly (although we don't have the capability to test this). However, a minor error in your configuration, or a sloppy CGI or PHP script, may cause unexpected results. In technical terms, you should ensure that the charset parameter is set in your Content-Type header.

mod_accessibility generates utf-8 (unicode) output. This should be suitable for most servers, as it is supported by browsers, and supports a very wide range of character sets. If you want to generate a different character set, you can do it by inserting another filter, such as mod_charset or mod_charset_lite, after mod_accessibility.