# 18. XHTML Handler Module

Contents

This section is normative.

The Handler Module defines elements that are used to contain information pertaining to event handler implementations, usually defined in a scripting language. Elements and attributes included in this module are:

Elements | Attributes | Content Model
--- | --- | ---
handler | Common, type | PCDATA | handler

When this module is used, the handler element is added to the Structural and Text content sets of the Structural and Text Modules. In addition, the handler element is added to the content model of the head element defined in the Document Module.

Implementation: RELAX NG

## 18.1. The handler element

Attributes

The Common collection
  A collection of other attribute collections, including: Bi-directional, Core, Edit, Embedding, Events, Forms, Hypertext, I18N, Map, and Metainformation.

type = ContentTypes

  This attribute specifies the allowable content types of the resource referenced by the relevant src URI.

  Example

      <script src="pop" type="application/x-javascript, text/x-newspeak" />

      <style src="midnight" type="text/css, text/x-mystyle" />

      <p src="w3c-logo" type="image/png, image/jpeg;q=0.2">W3C logo</p>

      <span src="logo.png">Our logo</span>

      <span src="theme.mp3" type="audio/x-mpeg">Our theme jingle</span>

The handler element places one or more event handlers within a document. This element may appear any number of times in the head or body of an XHTML document.

The handler may be defined within the contents of the handler element or in an external resource. If the src attribute is not set, user agents must interpret the contents of the element as the handler. If the src has a URI value, user agents must ignore the element's contents and retrieve the handler via the URI. Note that the encoding attribute refers to the character encoding of the handler designated by the src attribute; it does not concern the content of the handler element.

### 18.1.1. Rules for processing handlers

Handlers are evaluated by handler engines that must be known to a user agent.

A user agent must interpret a handler element according to the following precedence rules:

1. The user agent must first try to process the handler element, but not the embedded content.
2. If the user agent is not able to process the handler for any reason (configured not to, no support of the indicated handler type, no access to an external resource, etc.), it must try to process its contents.
3. If the content is inline text it must be evaluated as data of the handler type of the containing handler element.
4. If the content is a handler element, its content should be processed according to these rules.

The syntax of handler data depends on the handler implementation language.

### 18.1.2. Declaration of a handler language

The type attribute must be specified for each handler element instance in a document.

In this example, we include one handler in the header, whose handler is located in an external file and is in the handler language "text/vbscript". The JavaScript code contained in the inner handler will be evaluated if and only if the user agent isn't evaluating the outer handler. We also include one handler in the body, which contains its own handler written in "text/x-perl".

Example

    <html xmlns="http://www.w3.org/2002/06/xhtml2" xml:lang="en">
     <head>
      <title>A document with a handler</title>
      <handler type="text/x-vbscript" src="http://example.org/progs/vbcalc">
       <handler type="text/javascript">
           ...some inline JavaScript...
       </handler>
      </handler>
     </head>
     <body>
        <handler type="text/x-perl">
            ... some Perl script ...
        </handler>
     </body>
    </html>

### 18.1.3. Dynamic modification of documents

Note that the processing model of XML means that the ECMAScript method `document.write` cannot be used in XHTML2. To dynamically generate content in XHTML you have to add elements to the DOM tree using DOM calls [DOM] rather than using `document.write` to generate text that then gets parsed.

Should handler be in its own spec?

XHTML 2 elements are largely semantic in nature. The handler element is a way to bind behaviors to an XHTML 2 document. As such, it should likely be done as part of the XML Events recommendation.