Base Event Context Information

From W3C XForms Group Wiki (Public)
Jump to: navigation, search

Base Event Context Information

The following could be placed:

  • in section "4.1 Events Overview" or just after
  • or in section "7.11.2 The event() Function"

Each event defines the following context information, made available through the event function:

Property XPath 1.0 Type XPath 2.0 Type Value
bubbles boolean xs:boolean Used to indicate whether or not an event is a bubbling event. If the event can bubble the value is true, else the value is false.
cancelable boolean xs:boolean Used to indicate whether or not an event can have its default action prevented. If the default action can be prevented the value is true, else the value is false.
currentTargetId string xs:string? Used to indicate the EventTarget whose EventListeners are currently being processed. This is particularly useful during capturing and bubbling. NOTE: If the target does not have an id, returns the empty string (XPath 1.0) or an empty sequence (XPath 2.0).
eventPhase string xs:string Used to indicate which phase of event flow is currently being evaluated.
targetId string xs:string? Used to indicate the EventTarget to which the event was originally dispatched. NOTE: If the target does not have an id, returns the empty string (XPath 1.0) or an empty sequence (XPath 2.0).
timeStamp number xs:integer Used to specify the time (in milliseconds relative to the epoch) at which the event was created. Due to the fact that some systems may not provide this information the value of timeStamp may be not available for all events. When not available, a value of 0 will be returned. Examples of epoch time are the time of the system start or 0:0:0 UTC 1st January 1970.
type string xs:string The name of the event (case-insensitive). The name must be an XML name.

The eventPhase property returns one of the following string values:

  • BUBBLING_PHASE
  • AT_TARGET
  • CAPTURING_PHASE

EDITOR'S NOTE: These names are the constant names as defined in DOM Level 2 Events. In the future, if the phase attribute is amended in XML Events 2 to represent all of the above states, then the selected names might be used in preference to the names above.

NOTE: The list of properties follows DOM Level 2 Events, with the exception that target and currentTarget become targetId and currentTargetId and return identifiers instead of Node. The rationale is that not all XForms implementation may provide access to a DOM representation of the user interface.

Other changes to the spec

Section 7.11.2 must change:

"The event context properties available for each event are provided in the sections that describe the events."

to something like:

"The event-specific context properties available for each event are provided in the sections that describe the events."

TODO

  • Make text more spec-ready.
  • Decide if/how XPath 2.0 are integrated into the spec: specifically for all event context information, or in general section/document about XPath 2.0 types?

Result of discussions

  • timeStamp type
    • With XPath 1.0, the number type (double precision) has enough precision to store a number of milliseconds since January 1, 1970 (13 decimals taken, 15-16 decimals available).
    • With XPath 2.0, you would think xs:dateTime would be ideal. DOM 2 does not guarantee a fixed epoch however, so this is not possible. xs:integer is acceptable.
    • Nick suggested using xs:long, but xs:integer is a superset of xs:long and is more widely used.
  • It is acceptable to return an empty string with XPath 1.0 if target / current target doesn't have an id.