XML Events .dtd-code { font-family: monospace; background-color: #dfdfdf; white-space: pre; border: #000000; border-style: solid; border-top-width: 1px; border-right-width: 1px; border-bottom-width: 1px; border-left-width: 1px} code { color: green; font-family: monospace; font-weight: bold; } h4 { color: #005A9C; background: white } code.greenmono { color: green; font-family: monospace; font-weight: bold; } .example { border: solid green; border-width: 2px; color: green; font-weight: bold; margin-right: 5%; margin-left: 0; } .bad { border: solid red; border-width: 2px; margin-left: 0; margin-right: 5%; color: rgb(192, 101, 101); } div.navbar { text-align: center; } div.contents { background-color: rgb(204,204,255); padding: 0.5em; border: none; margin-right: 5%; } .tocline { list-style: none; } td { text-align: left } .ins { background-color: yellow } .del { background-color: yellow; text-decoration: line-through } ul.acks { list-style: none } XML Events An Events Syntax for XML W3C Recommendation 14 October 2003 This version: http://www.w3.org/TR/2003/REC-xml-events-20031014 Latest version: http://www.w3.org/TR/xml-events Previous version: http://www.w3.org/TR/2003/PR-xml-events-20030804 Diff-marked version: xml-events-diff.html Editors: Shane McCarron Applied Testing and Technology, Inc. Steven Pemberton CWI W3C ® T. V. Raman IBM Please refer to the errata This document is also available in these non-normative formats: PostScript version PDF version ZIP archive Gzip'd TAR archive The English version of this specification is the only normative version. Non-normative translations Copyright W3C ® MIT ERCIM Keio liability trademark document use software licensing Abstract The XML Events module defined in this specification provides XML languages with the ability to uniformly integrate event listeners and associated event handlers with Document Object Model (DOM) Level 2 event interfaces [ DOM2EVENTS Status of This Document This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index This document is a Recommendation XForms 1.0 Test Suite implementation report This document has been produced by the W3C HTML Working Group Members only HTML Activity HTML Working Group charter Working Group's patent disclosure page Please report errors in this specification to [email protected] archive [email protected] archive Contents 1. Introduction 2. Conformance Requirements 2.1. Document Conformance 2.2. Host Language Conformance 2.3. User Agent Conformance 3. The XML Events Module 3.1. The listener Element 3.1.1. Examples of listener Usage 3.2. Attaching Attributes Directly to the Observer Element 3.2.1. Examples of Using Attributes Attached to an Observer Element 3.3. Attaching Attributes Directly to the Handler Element 3.3.1. Examples of Using Attributes Attached to a Handler Element 3.4. Summary of Observer and Handler Attribute Defaulting 3.5. Event Handlers 3.6. The Basic XML Events Profile 4. Naming Event Types A. DTD Implementation A.1. Qualified Names Module A.2. XML Events Module B. Schema Implementation B.1. Attributes Module B.2. XML Events Module C. References C.1. Normative References C.2. Other References D. Acknowledgments 1.Introduction This section is informative. An event targeted In the DOM model of events [ DOM2EVENTS dispatched capture target bubbling observer Event flow in DOM2: an event targeted at an element (marked 'target') in the tree passes down the tree from the root to the target in the phase called 'capture'. If the event type allows it, the event then travels back up the tree by the same route in a phase called 'bubbling'. Any node in the route, including the root node and the target, may be an 'observer': that is to say, a handler may be attached to it that is activated when the event passes through in either phase. A handler can only listen for one phase. To listen for both you have to attach two handlers. An action handler listener HTML [ HTML4 SVG The process of defining a new version of HTML identified the need for an extensible event specification method. The design requirements were the following: Syntactically expose the DOM event model to an XML document [ XML Provide for new event types without requiring modification to the DOM or the DTD. Allow for integration with other XML languages. The DOM specifies an event model that provides the following features: A generic event system, Means for registering event listeners and handlers, Means for routing events through a tree structure, Access to context information for each event, and A definition of event flow, as sketched above. Element listener This document neither specifies particular events, nor mandates any particular methods of specifying actions. These definitions are left to any markup language using the facilities described here. 2.Conformance Requirements This section is normative The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [ RFC2119 2.1.Document Conformance XML Events is not a stand-alone document type. It is intended to be integrated into other host languages such as XHTML. A conforming XML Events document is a document that requires only the facilities described as mandatory in this specification and the facilities described as mandatory in its host language. Such a document must meet all the following criteria: The document must conform to the constraints expressed in Appendix B - Schema Implementation Appendix A - DTD Implementation The document must contain an xmlns XMLNAMES http://www.w3.org/2001/xml-events <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" xmlns:ev="http://www.w3.org/2001/xml-events" > 2.2.Host Language Conformance When XML Events are included in a host language, all of the facilities required in this specification must be included in the host language. In addition, the elements and attributes defined in this specification must be included in the content model of the host language. 2.3.User Agent Conformance A conforming user agent must support all of the features required in this specification. 3.The XML Events Module This section is normative. This specification defines a module called XML Events. The XML Events module uses the XML namespace [ XMLNAMES http://www.w3.org/2001/xml-events Examples in this document that use the namespace prefix " ev xmlns xmlns:ev="http://www.w3.org/2001/xml-events" The remainder of this section describes the elements and attributes in this module, the semantics, and provides an abstract module definition as required in [ XHTMLMOD The XML Events Module supports the following element and attributes: Element Attributes Minimal Content Model listener event ( NMTOKEN IDREF IDREF URI ID EMPTY Implementations: DTD XML Schema 3.1.The listener Element Element listener EventListener event The required event DOM2EVENTS XML The optional observer id event Attaching Attributes Directly to the Observer Element Attaching Attributes Directly to the Handler Element target The optional target id event target Use of this attribute requires care; for instance, if you specify <listener event="click" observer="para1" target="link1" handler="#clicker"/> where 'para1' is some ancestor of the following node <a id="link1" href="doc.html">The <em>draft</em> document</a> and the user happens to click on the word "draft", the <em> <a> <a> observer="link1" target handler The optional handler Event Handlers event Attaching Attributes Directly to the Handler Element phase The optional phase capture Listener is activated during capturing phase. default Listener is activated during bubbling or target phase. The default behavior is phase="default" Note that not all events bubble, in which case with phase="default" you can only handle the event by making the event's target the observer. propagate The optional propagate stop event propagation stops continue event propagation continues (unless stopped by other means, such as scripting, or by another listener). The default behavior is propagate="continue" defaultAction The optional defaultAction <a> cancel if the event type is cancelable, the default action is cancelled perform the default action is performed (unless cancelled by other means, such as scripting, or by another listener). The default value is defaultAction="perform" Note that not all events are cancelable, in which case this attribute is ignored. id The optional id Note that observer = "<element-id>" event = "<event-type>" begin = "<element-id>.<event-type>" SMIL20 3.1.1.Examples of listener Usage This example attaches the handler in the element at "#doit" activate id="button1" target <listener event="activate" observer="button1" handler="#doit"/> This attaches the handler at #overflow-handler overflow id="expr1" id="prog1" <listener event="overflow" observer="prog1" target="expr1" handler="#overflow-handler"/> This attaches the handler at #popup activate id="embargo" embargo activate <listener event="activate" observer="embargo" handler="#popup" phase="capture" propagate="stop"/> This attaches a handler from another document. <listener event="activate" observer="image1" handler="/handlers/events.xml#activate"/> 3.2.Attaching Attributes Directly to the Observer Element All the attributes from the listener id Namespaces in XML XMLNAMES Note that this means that the <listener> <anyelement ev:event="click" ev:observer="button1" ev:handler="#clicker"/> would have the same effect as <ev:listener event="click" observer="button1" handler="#clicker"/> Nonetheless, for utility the <listener> If the observer handler 3.2.1. Examples of Using Attributes Attached to an Observer Element This first example will attach the handler identified by "#popper" <a> <a href="doc.html" ev:event="activate" ev:handler="#popper" ev:defaultAction="cancel">The document</a> This will attach the handler at #handle-overflow overflow <div ev:event="overflow" ev:handler="#handle-overflow"> ... </div> 3.3.Attaching Attributes Directly to the Handler Element If, when attaching the global attributes to an element, the handler Note that, since the observer target handler If the observer 3.3.1. Examples of Using Attributes Attached to a Handler Element In this case the element is the handler for the submit id="form1" <script type="application/x-javascript" ev:event="submit" ev:observer="form1"> return docheck(event); </script> In this case the <action> q-submit questionnaire <questionnaire submissionURL="/q/tally"> <action ev:event="q-submit"> ... </action> ... </questionnaire> The <script> click <img> <img src="button.gif" alt="OK"> <script ev:event="activate" type="application/x-javascript"> doactivate(event); </script> </img> The <onevent> enterforward <card> <card> <onevent ev:event="enterforward"> <go href="/url"/> </onevent> <p> Hello! </p> </card> The <catch> nomatch <field> <form id="launch_missiles"> <field name="password"> <prompt>What is the code word?</prompt> <grammar> <rule id="root" scope="public">rutabaga</rule> </grammar> <help>It is the name of an obscure vegetable.</help> <catch ev:event="nomatch"> <prompt>Security violation!</prompt> <submit next="apprehend_felon" namelist="user_id"/> </catch> </field> <block> <goto next="#get_city"/> </block> </form> This example shows three handlers for different events. The observer for all three is the <secret> <secret ref="/login/password"> <caption>Please enter your password</caption> <info ev:event="help"> Mail [email protected] in case of problems </info> <info ev:event="hint"> A pet's name </info> <info ev:event="alert"> This field is required </info> </secret> 3.4.Summary of Observer and Handler Attribute Defaulting The following table summarizes which elements play the role of observer or handler if the relevant attribute is omitted. The effect of omitted observer and handler attributes Handler present Handler omitted Observer present (As declared) Element is handler Observer omitted Element is observer Element is handler 3.5.Event Handlers This specification does not require an XML application that uses XML Events to use any particular method for specifying handlers. However, the examples, particularly those in the section on attaching the attributes directly to the handler, are intended to give examples of how they could be specified. It is however recognized that two methods are likely to occur often: scripting (such as XHTML's <script> element) and declarative markup using XML elements (such as WML's <onevent> element). A companion specification will provide markup to support these methods. 3.6.The Basic XML Events Profile The Basic XML Events Profile allows restrictions on the usage of the XML Events Module in order to make processing easier on small devices. The Basic Profile allows the following restrictions on the use of listener listener External Event Handlers The ability to process external event handlers is not required. When the 'handler' attribute on the listener For example, the following is allowed: <listener event="click" target="#button1" handler="#clicker"/> while the following is not required to be processed: <listener event="click" target="#button1" handler="doc2.html#clicker"/> Ordering of Event Bindings The binding of an event handler to an observer may be required to be lexically before the end of the observer element. In other words, a <listener> binding to an observer may not occur after the closing tag of the observer element, and an event handler carrying the attributes to bind it to an observer may also not occur after the closing tag of the observer element. 4.Naming Event Types This section is informative. This specification does not normatively specify how language designers should name events (i.e., the values used in the event However, future versions of DOM Events are likely to allow namespaced event names, so language designers are advised not to use the colon character ":" in event names. A number of event types are defined in DOM2 [ DOM2EVENTS A.DTD Implementation This appendix is normative The DTD implementation of XML Events conforms to the requirements defined in [ XHTMLMOD A.1.Qualified Names Module Note that this module defines the parameter entity %xml-events-attrs.qname; %XML-EVENTS.prefixed; INCLUDE %XML-EVENTS.prefix; <!-- ....................................................................... --> <!-- XML Events Qname Module ............................................ --> <!-- file: xml-events-qname-1.mod
This is XML Events - the Events Module for XML, a definition of access to the DOM events model.
Copyright 2000-2003 W3C (MIT, ERCIM, Keio), All Rights Reserved.
This DTD module is identified by the PUBLIC and SYSTEM identifiers:
PUBLIC "-//W3C//ENTITIES XML Events Qnames 1.0//EN" SYSTEM "http://www.w3.org/MarkUp/DTD/xml-events-qname-1.mod"
Revisions: (none) ....................................................................... -->
<!-- XML Events Qname (Qualified Name) Module
This module is contained in two parts, labeled Section 'A' and 'B':
Section A declares parameter entities to support namespace- qualified names, namespace declarations, and name prefixing for XML Events and extensions.
Section B declares parameter entities used to provide namespace-qualified names for all XML Events element types:
%listener.qname; the xmlns-qualified name for <listener> ...
XML Events extensions would create a module similar to this one. Included in the XML distribution is a template module ('template-qname-1.mod') suitable for this purpose. -->
<!-- Section A: XML Events XML Namespace Framework :::::::::::::::::::: -->
<!-- 1. Declare a %XML-EVENTS.prefixed; conditional section keyword, used to activate namespace prefixing. The default value should inherit '%NS.prefixed;' from the DTD driver, so that unless overridden, the default behavior follows the overall DTD prefixing scheme. --> <!ENTITY % NS.prefixed % XML-EVENTS.prefixed % XML-EVENTS.xmlns % XML-EVENTS.prefix % XML-EVENTS.pfx % XML-EVENTS.pfx % xml-events-qname-extra.mod % XML-EVENTS.xmlns.extra.attrib % xml-events.listener.qname % xml-events.attrs.qname A.2.XML Events Module <!-- ...................................................................... --> <!-- XML Events Module .................................................... --> <!-- file: xml-events-1.mod
This is XML Events - the Events Module for XML. a redefinition of access to the DOM events model.
Copyright 2000-2003 W3C (MIT, ERCIM, Keio), All Rights Reserved.
This DTD module is identified by the PUBLIC and SYSTEM identifiers:
PUBLIC "-//W3C//ENTITIES XML Events 1.0//EN" SYSTEM "http://www.w3.org/MarkUp/DTD/xml-events-1.mod"
Revisions: (none) ....................................................................... -->
<!-- XML Events defines the listener element and its attributes -->
<!ENTITY % xml-events.listener.content %xml-events.listener.qname; B.Schema Implementation This appendix is normative The schema implementation of XML Events conforms to the requirements defined in [ XHTMLSCHEMAMOD B.1.Attributes Module <?xml version="1.0" encoding="UTF-8"?> <xs:schema targetNamespace="http://www.w3.org/2001/xml-events" xmlns:ev="http://www.w3.org/2001/xml-events" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.w3.org/2001/XMLSchema http://www.w3.org/2001/XMLSchema.xsd" elementFormDefault="unqualified" blockDefault="#all" finalDefault="#all" attributeFormDefault="unqualified">
<xs:annotation> <xs:documentation> This is the XML Schema for XML Events global attributes
URI: http://www.w3.org/MarkUp/SCHEMA/xml-events-attribs-1.xsd $Id: xml-events-attribs-1.xsd,v 1.5 2003/08/02 09:36:54 mimasa Exp $ </xs:documentation> <xs:documentation source="xml-events-copyright-1.xsd"/> </xs:annotation>
<xs:annotation> <xs:documentation> XML Event Attributes These "global" event attributes are defined in "Attaching Attributes Directly to the Observer Element" of the XML Events specification. </xs:documentation> </xs:annotation>
<xs:attribute name="event" type="xs:NMTOKEN"/> <xs:attribute name="observer" type="xs:IDREF"/> <xs:attribute name="target" type="xs:IDREF"/> <xs:attribute name="handler" type="xs:anyURI"/> <xs:attribute name="phase" default="default"> <xs:simpleType> <xs:restriction base="xs:NMTOKEN"> <xs:enumeration value="capture"/> <xs:enumeration value="default"/> </xs:restriction> </xs:simpleType> </xs:attribute> <xs:attribute name="propagate" default="continue"> <xs:simpleType> <xs:restriction base="xs:NMTOKEN"> <xs:enumeration value="stop"/> <xs:enumeration value="continue"/> </xs:restriction> </xs:simpleType> </xs:attribute> <xs:attribute name="defaultAction" default="perform"> <xs:simpleType> <xs:restriction base="xs:NMTOKEN"> <xs:enumeration value="cancel"/> <xs:enumeration value="perform"/> </xs:restriction> </xs:simpleType> </xs:attribute>
<xs:attributeGroup name="XmlEvents.attlist"> <xs:attribute ref="ev:event"/> <xs:attribute ref="ev:observer"/> <xs:attribute ref="ev:target"/> <xs:attribute ref="ev:handler"/> <xs:attribute ref="ev:phase"/> <xs:attribute ref="ev:propagate"/> <xs:attribute ref="ev:defaultAction"/> </xs:attributeGroup>
</xs:schema> B.2.XML Events Module <?xml version="1.0" encoding="UTF-8"?> <xs:schema targetNamespace="http://www.w3.org/2001/xml-events" xmlns="http://www.w3.org/2001/xml-events" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.w3.org/2001/XMLSchema http://www.w3.org/2001/XMLSchema.xsd" elementFormDefault="unqualified" blockDefault="#all" finalDefault="#all" attributeFormDefault="unqualified">
<xs:annotation> <xs:documentation> This is the XML Schema for XML Events
URI: http://www.w3.org/MarkUp/SCHEMA/xml-events-1.xsd $Id: xml-events-1.xsd,v 1.6 2003/08/02 09:36:54 mimasa Exp $ </xs:documentation> <xs:documentation source="xml-events-copyright-1.xsd"/> </xs:annotation>
<xs:annotation> <xs:documentation> XML Events element listener This module defines the listener element for XML Events. This element can be used to define event listeners. This module relies upon the XmlEvents.attlist attribute group defined in xml-events-attribs-1.xsd. </xs:documentation> </xs:annotation>
<xs:attributeGroup name="listener.attlist"> <xs:attribute name="event" use="required" type="xs:NMTOKEN"/> <xs:attribute name="observer" type="xs:IDREF"/> <xs:attribute name="target" type="xs:IDREF"/> <xs:attribute name="handler" type="xs:anyURI"/> <xs:attribute name="phase" default="default"> <xs:simpleType> <xs:restriction base="xs:NMTOKEN"> <xs:enumeration value="capture"/> <xs:enumeration value="default"/> </xs:restriction> </xs:simpleType> </xs:attribute> <xs:attribute name="propagate" default="continue"> <xs:simpleType> <xs:restriction base="xs:NMTOKEN"> <xs:enumeration value="stop"/> <xs:enumeration value="continue"/> </xs:restriction> </xs:simpleType> </xs:attribute> <xs:attribute name="defaultAction" default="perform"> <xs:simpleType> <xs:restriction base="xs:NMTOKEN"> <xs:enumeration value="cancel"/> <xs:enumeration value="perform"/> </xs:restriction> </xs:simpleType> </xs:attribute> <xs:attribute name="id" type="xs:ID"/> </xs:attributeGroup>
<xs:complexType name="listener.type"> <xs:attributeGroup ref="listener.attlist"/> </xs:complexType>
<xs:element name=" listener C.References This appendix is normative C.1.Normative References [ DOM2EVENTS " Document Object Model (DOM) Level 2 Events Specification ed. latest version [ XML " Extensible Markup Language (XML) 1.0 (Second Edition) et al. eds. latest version [ SCHEMA " XML Schema Part 2: Datatypes et al. eds. latest version [RFC2119] " Key words for use in RFCs to indicate requirement levels [XMLNAMES] " Namespaces in XML et al. eds. latest version C.2.Other References [ HTML4 " HTML 4.01 Specification et al. eds. latest version [ SMIL20 " Synchronized Multimedia Integration Language (SMIL 2.0) et al. eds. latest version [ SVG " Scalable Vector Graphics (SVG) 1.0 Specification ed. latest version [ XHTML " XHTML™ 1.0: The Extensible HyperText Markup Language (Second Edition) et al. latest version [ XHTMLMOD " Modularization of XHTML™ et al. eds. latest version [ XHTMLSCHEMAMOD " Modularization of XHTML™ in XML Schema et al. eds. work in progress latest version D.Acknowledgments This section is informative. This document was originally edited by Ted Wugofski (Openwave). Special acknowledgments to: Mark Baker (Sun Microsystems), Wayne Carr (Intel Corporation), Warner ten Kate (Philips Electronics), Patrick Schmitz, and Peter Stark (Ericsson) for their significant contributions to the evolution of this specification. At the time of publication, the participants in the W3C HTML Working Group were: Steven Pemberton, CWI W3C Daniel Austin, W. W. Grainger, Inc. Jim Bigelow, Hewlett-Packard Company Mark Birbeck, x-port.net Ltd. Jonny Axelsson, Opera Software Tantek Çelik, Microsoft Corporation Beth Epperson, Netscape/ AOL Masayasu Ishikawa, W3C Shin'ichi Matsui, Panasonic Shane McCarron, Applied Testing and Technology (Invited Expert) Ann Navarro, WebGeek, Inc. Subramanian Peruvemba, Oracle Corporation Sebastian Schnitzenbaumer, SAP AG