diff options
Diffstat (limited to 'test/data/html/web-apps.html')
-rw-r--r-- | test/data/html/web-apps.html | 41271 |
1 files changed, 0 insertions, 41271 deletions
diff --git a/test/data/html/web-apps.html b/test/data/html/web-apps.html deleted file mode 100644 index d685320..0000000 --- a/test/data/html/web-apps.html +++ /dev/null @@ -1,41271 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> - -<html lang=en-GB-hixie> - <head> - <title>HTML 5</title> - <link href="/style/specification" rel=stylesheet type="text/css"> - <link href="/images/icon" rel=icon> - - <style type="text/css"> - h4 + .element { margin-top: -2.5em; padding-top: 2em; } - h4 + p + .element { margin-top: -5em; padding-top: 4em; } - .element { background: #EEFFEE; color: black; margin: 0 0 1em -1em; padding: 0 1em 0.25em 0.75em; border-left: solid #99FF99 0.25em; -padding: 0; /* that last decl is for IE6. Try removing it, it's hilarious! */ } - .proposal { border: blue solid; padding: 1em; } - table.matrix, table.matrix td { border: none; text-align: right; } - table.matrix { margin-left: 2em; } - </style> - - <body class=draft> - <div class=head> - <p><a class=logo href="http://www.whatwg.org/" rel=home><img alt=WHATWG - src="/images/logo"></a></p> - - <h1 id=html-5>HTML 5</h1> - - <h2 class="no-num no-toc" id=working>Working Draft — 14 June 2007</h2> - - <p>You can take part in this work. <a - href="http://www.whatwg.org/mailing-list">Join the working group's - discussion list.</a></p> - - <p><strong>Web designers!</strong> We have a <a - href="http://blog.whatwg.org/faq/">FAQ</a>, a <a - href="http://forums.whatwg.org/">forum</a>, and a <a - href="http://www.whatwg.org/mailing-list#help">help mailing list</a> for - you!</p> - - <dl> - <dt>One-page version: - - <dd><a - href="http://www.whatwg.org/specs/web-apps/current-work/">http://www.whatwg.org/specs/web-apps/current-work/</a> - - <dt>Multiple-page version: - - <dd><a - href="http://www.whatwg.org/specs/web-apps/current-work/multipage/">http://www.whatwg.org/specs/web-apps/current-work/multipage/</a> - - <dt>Version history: - - <dd>Twitter messages (non-editorial changes only): <a - href="http://twitter.com/WHATWG">http://twitter.com/WHATWG</a> - - <dd>Commit-Watchers mailing list: <a - href="http://lists.whatwg.org/listinfo.cgi/commit-watchers-whatwg.org">http://lists.whatwg.org/listinfo.cgi/commit-watchers-whatwg.org</a> - - <dd>Interactive Web interface: <a - href="http://html5.org/tools/web-apps-tracker">http://html5.org/tools/web-apps-tracker</a> - - <dd>Subversion interface: <a - href="http://svn.whatwg.org/">http://svn.whatwg.org/</a> - - <dt>Editor: - - <dd>Ian Hickson, Google, ian@hixie.ch - </dl> - - <p class=copyright>© Copyright 2004-2007 Apple Computer, Inc., - Mozilla Foundation, and Opera Software ASA.</p> - - <p class=copyright>You are granted a license to use, reproduce and create - derivative works of this document.</p> - </div> - - <hr> - - <h2 class="no-num no-toc" id=abstract>Abstract</h2> - - <p>This specification introduces features to HTML and the DOM that ease the - authoring of Web-based applications. Additions include the context menus, - a direct-mode graphics canvas, inline popup windows, and server-sent - events. - - <h2 class="no-num no-toc" id=status>Status of this document</h2> - - <p><strong>This is a work in progress!</strong> This document is changing - on a daily if not hourly basis in response to comments and as a general - part of its development process. Comments are very welcome, please send - them to <a href="mailto:whatwg@whatwg.org">whatwg@whatwg.org</a>. Thank - you. - - <p>Implementors should be aware that this specification is not stable. - <strong>Implementors who are not taking part in the discussions are likely - to find the specification changing out from under them in incompatible - ways.</strong> Vendors interested in implementing this specification - before it eventually reaches the call for implementations should join the - <a href="/mailing-list">WHATWG mailing list</a> and take part in the - discussions. - - <p>This specification is also being produced by the <a - href="http://www.w3.org/html/wg">W3C HTML WG</a>. The two specifications - are identical from the table of contents onwards. - - <p>This specification is intended to replace (be the new version of) what - was previously the HTML4, XHTML 1.x, and DOM2 HTML specifications. - - <h3 class="no-num no-toc" id=stability0>Stability</h3> - - <p>Different parts of this specification are at different levels of - maturity. - - <div id=stability></div> - - <p class=big-issue>Known issues are usually marked like this. There are - some spec-wide issues that have not yet been addressed: case-sensitivity - is a very poorly handled topic right now, and the firing of events needs - to be unified (right now some bubble, some don't, they all use different - text to fire events, etc). - - <h2 class="no-num no-toc" id=contents>Table of contents</h2> - <!--begin-toc--> - - <ul class=toc> - <li><a href="#introduction"><span class=secno>1. </span>Introduction</a> - <ul class=toc> - <li><a href="#scope"><span class=secno>1.1. </span>Scope</a> - <ul class=toc> - <li><a href="#relationship"><span class=secno>1.1.1. - </span>Relationship to HTML 4.01, XHTML 1.1, DOM2 HTML</a> - - <li><a href="#relationship0"><span class=secno>1.1.2. - </span>Relationship to XHTML2</a> - - <li><a href="#relationship1"><span class=secno>1.1.3. - </span>Relationship to XUL, Flash, Silverlight, and other proprietary - UI languages</a> - </ul> - - <li><a href="#structure"><span class=secno>1.2. </span>Structure of this - specification</a> - <ul class=toc> - <li><a href="#how-to"><span class=secno>1.2.1. </span>How to read this - specification</a> - </ul> - - <li><a href="#conformance"><span class=secno>1.3. </span>Conformance - requirements</a> - <ul class=toc> - <li><a href="#common"><span class=secno>1.3.1. </span>Common - conformance requirements for APIs exposed to JavaScript</a> - - <li><a href="#dependencies"><span class=secno>1.3.2. - </span>Dependencies</a> - - <li><a href="#features"><span class=secno>1.3.3. </span>Features - defined in other specifications</a> - </ul> - - <li><a href="#terminology"><span class=secno>1.4. </span>Terminology</a> - - <ul class=toc> - <li><a href="#html-vs"><span class=secno>1.4.1. </span>HTML vs - XHTML</a> - </ul> - </ul> - - <li><a href="#dom"><span class=secno>2. </span>The Document Object - Model</a> - <ul class=toc> - <li><a href="#documents"><span class=secno>2.1. </span>Documents</a> - <ul class=toc> - <li><a href="#security"><span class=secno>2.1.1. </span>Security</a> - - <li><a href="#resource"><span class=secno>2.1.2. </span>Resource - metadata management</a> - </ul> - - <li><a href="#elements"><span class=secno>2.2. </span>Elements</a> - <ul class=toc> - <li><a href="#reflecting"><span class=secno>2.2.1. </span>Reflecting - content attributes in DOM attributes</a> - </ul> - - <li><a href="#common0"><span class=secno>2.3. </span>Common DOM - interfaces</a> - <ul class=toc> - <li><a href="#collections"><span class=secno>2.3.1. - </span>Collections</a> - <ul class=toc> - <li><a href="#htmlcollection"><span class=secno>2.3.1.1. - </span>HTMLCollection</a> - - <li><a href="#htmlformcontrolscollection"><span class=secno>2.3.1.2. - </span>HTMLFormControlsCollection</a> - - <li><a href="#htmloptionscollection"><span class=secno>2.3.1.3. - </span>HTMLOptionsCollection</a> - </ul> - - <li><a href="#domtokenlist"><span class=secno>2.3.2. - </span>DOMTokenList</a> - - <li><a href="#dom-feature"><span class=secno>2.3.3. </span>DOM feature - strings</a> - </ul> - - <li><a href="#dom-tree"><span class=secno>2.4. </span>DOM tree - accessors</a> - - <li><a href="#dynamic"><span class=secno>2.5. </span>Dynamic markup - insertion</a> - <ul class=toc> - <li><a href="#controlling"><span class=secno>2.5.1. </span>Controlling - the input stream</a> - - <li><a href="#dynamic0"><span class=secno>2.5.2. </span>Dynamic markup - insertion in HTML</a> - - <li><a href="#dynamic1"><span class=secno>2.5.3. </span>Dynamic markup - insertion in XML</a> - </ul> - - <li><a href="#apis-in"><span class=secno>2.6. </span>APIs in HTML - documents</a> - </ul> - - <li><a href="#semantics"><span class=secno>3. </span>Semantics and - structure of HTML elements</a> - <ul class=toc> - <li><a href="#semantics-intro"><span class=secno>3.1. - </span>Introduction</a> - - <li><a href="#common1"><span class=secno>3.2. </span>Common - microsyntaxes</a> - <ul class=toc> - <li><a href="#common2"><span class=secno>3.2.1. </span>Common parser - idioms</a> - - <li><a href="#boolean"><span class=secno>3.2.2. </span>Boolean - attributes</a> - - <li><a href="#numbers"><span class=secno>3.2.3. </span>Numbers</a> - <ul class=toc> - <li><a href="#unsigned"><span class=secno>3.2.3.1. </span>Unsigned - integers</a> - - <li><a href="#signed"><span class=secno>3.2.3.2. </span>Signed - integers</a> - - <li><a href="#real-numbers"><span class=secno>3.2.3.3. </span>Real - numbers</a> - - <li><a href="#ratios"><span class=secno>3.2.3.4. </span>Ratios</a> - - <li><a href="#percentages-and-dimensions"><span class=secno>3.2.3.5. - </span>Percentages and dimensions</a> - - <li><a href="#lists"><span class=secno>3.2.3.6. </span>Lists of - integers</a> - </ul> - - <li><a href="#dates"><span class=secno>3.2.4. </span>Dates and - times</a> - <ul class=toc> - <li><a href="#specific"><span class=secno>3.2.4.1. </span>Specific - moments in time</a> - - <li><a href="#vaguer"><span class=secno>3.2.4.2. </span>Vaguer - moments in time</a> - </ul> - - <li><a href="#time-offsets"><span class=secno>3.2.5. </span>Time - offsets</a> - - <li><a href="#tokens"><span class=secno>3.2.6. </span>Tokens</a> - - <li><a href="#keywords"><span class=secno>3.2.7. </span>Keywords and - enumerated attributes</a> - - <li><a href="#syntax-references"><span class=secno>3.2.8. - </span>References</a> - </ul> - - <li><a href="#documents0"><span class=secno>3.3. </span>Documents and - document fragments</a> - <ul class=toc> - <li><a href="#semantics0"><span class=secno>3.3.1. - </span>Semantics</a> - - <li><a href="#structure0"><span class=secno>3.3.2. - </span>Structure</a> - - <li><a href="#kinds"><span class=secno>3.3.3. </span>Kinds of - elements</a> - <ul class=toc> - <li><a href="#block-level"><span class=secno>3.3.3.1. - </span>Block-level elements</a> - - <li><a href="#inline-level"><span class=secno>3.3.3.2. - </span>Inline-level content</a> - - <li><a href="#transparent"><span class=secno>3.3.3.3. - </span>Transparent content models</a> - - <li><a href="#determining"><span class=secno>3.3.3.4. - </span>Determining if a particular element contains block-level - elements or inline-level content</a> - - <li><a href="#interactive0"><span class=secno>3.3.3.5. - </span>Interactive elements</a> - - <li><a href="#paragraphs"><span class=secno>3.3.3.6. - </span>Paragraphs</a> - </ul> - </ul> - - <li><a href="#global"><span class=secno>3.4. </span>Global - attributes</a> - <ul class=toc> - <li><a href="#the-id"><span class=secno>3.4.1. </span>The - <code>id</code> attribute</a> - - <li><a href="#the-title"><span class=secno>3.4.2. </span>The - <code>title</code> attribute</a> - - <li><a href="#the-lang"><span class=secno>3.4.3. </span>The - <code>lang</code> (HTML only) and <code>xml:lang</code> (XML only) - attributes</a> - - <li><a href="#the-dir"><span class=secno>3.4.4. </span>The - <code>dir</code> attribute</a> - - <li><a href="#classes"><span class=secno>3.4.5. </span>The - <code>class</code> attribute</a> - - <li><a href="#the-irrelevant"><span class=secno>3.4.6. </span>The - <code>irrelevant</code> attribute</a> - </ul> - - <li><a href="#interaction"><span class=secno>3.5. </span>Interaction</a> - - <ul class=toc> - <li><a href="#activation"><span class=secno>3.5.1. - </span>Activation</a> - - <li><a href="#focus"><span class=secno>3.5.2. </span>Focus</a> - <ul class=toc> - <li><a href="#focus-management"><span class=secno>3.5.2.1. - </span>Focus management</a> - - <li><a href="#sequential"><span class=secno>3.5.2.2. - </span>Sequential focus navigation</a> - </ul> - - <li><a href="#scrolling"><span class=secno>3.5.3. </span>Scrolling - elements into view</a> - </ul> - - <li><a href="#the-root"><span class=secno>3.6. </span>The root - element</a> - <ul class=toc> - <li><a href="#the-html"><span class=secno>3.6.1. </span>The - <code>html</code> element</a> - </ul> - - <li><a href="#document"><span class=secno>3.7. </span>Document - metadata</a> - <ul class=toc> - <li><a href="#the-head"><span class=secno>3.7.1. </span>The - <code>head</code> element</a> - - <li><a href="#the-title0"><span class=secno>3.7.2. </span>The - <code>title</code> element</a> - - <li><a href="#the-base"><span class=secno>3.7.3. </span>The - <code>base</code> element</a> - - <li><a href="#the-link"><span class=secno>3.7.4. </span>The - <code>link</code> element</a> - - <li><a href="#meta"><span class=secno>3.7.5. </span>The - <code>meta</code> element</a> - <ul class=toc> - <li><a href="#standard"><span class=secno>3.7.5.1. </span>Standard - metadata names</a> - - <li><a href="#other"><span class=secno>3.7.5.2. </span>Other - metadata names</a> - - <li><a href="#pragma"><span class=secno>3.7.5.3. </span>Pragma - directives</a> - - <li><a href="#charset"><span class=secno>3.7.5.4. </span>Specifying - and establishing the document's character encoding</a> - </ul> - - <li><a href="#the-style"><span class=secno>3.7.6. </span>The - <code>style</code> element</a> - - <li><a href="#styling"><span class=secno>3.7.7. </span>Styling</a> - </ul> - - <li><a href="#sections"><span class=secno>3.8. </span>Sections</a> - <ul class=toc> - <li><a href="#the-body"><span class=secno>3.8.1. </span>The - <code>body</code> element</a> - - <li><a href="#the-section"><span class=secno>3.8.2. </span>The - <code>section</code> element</a> - - <li><a href="#the-nav"><span class=secno>3.8.3. </span>The - <code>nav</code> element</a> - - <li><a href="#the-article"><span class=secno>3.8.4. </span>The - <code>article</code> element</a> - - <li><a href="#the-blockquote"><span class=secno>3.8.5. </span>The - <code>blockquote</code> element</a> - - <li><a href="#the-aside"><span class=secno>3.8.6. </span>The - <code>aside</code> element</a> - - <li><a href="#the-h1"><span class=secno>3.8.7. </span>The - <code>h1</code>, <code>h2</code>, <code>h3</code>, <code>h4</code>, - <code>h5</code>, and <code>h6</code> elements</a> - - <li><a href="#the-header"><span class=secno>3.8.8. </span>The - <code>header</code> element</a> - - <li><a href="#the-footer"><span class=secno>3.8.9. </span>The - <code>footer</code> element</a> - - <li><a href="#the-address"><span class=secno>3.8.10. </span>The - <code>address</code> element</a> - - <li><a href="#headings"><span class=secno>3.8.11. </span>Headings and - sections</a> - <ul class=toc> - <li><a href="#outlines"><span class=secno>3.8.11.1. </span>Creating - an outline</a> - - <li><a href="#associatedSection"><span class=secno>3.8.11.2. - </span>Determining which heading and section applies to a - particular node</a> - - <li><a href="#distinguishing"><span class=secno>3.8.11.3. - </span>Distinguishing site-wide headers from page headers</a> - </ul> - </ul> - - <li><a href="#prose"><span class=secno>3.9. </span>Prose</a> - <ul class=toc> - <li><a href="#the-p"><span class=secno>3.9.1. </span>The - <code>p</code> element</a> - - <li><a href="#the-hr"><span class=secno>3.9.2. </span>The - <code>hr</code> element</a> - - <li><a href="#the-br"><span class=secno>3.9.3. </span>The - <code>br</code> element</a> - - <li><a href="#the-dialog"><span class=secno>3.9.4. </span>The - <code>dialog</code> element</a> - </ul> - - <li><a href="#preformatted"><span class=secno>3.10. </span>Preformatted - text</a> - <ul class=toc> - <li><a href="#the-pre"><span class=secno>3.10.1. </span>The - <code>pre</code> element</a> - </ul> - - <li><a href="#lists0"><span class=secno>3.11. </span>Lists</a> - <ul class=toc> - <li><a href="#the-ol"><span class=secno>3.11.1. </span>The - <code>ol</code> element</a> - - <li><a href="#the-ul"><span class=secno>3.11.2. </span>The - <code>ul</code> element</a> - - <li><a href="#the-li"><span class=secno>3.11.3. </span>The - <code>li</code> element</a> - - <li><a href="#the-dl"><span class=secno>3.11.4. </span>The - <code>dl</code> element</a> - - <li><a href="#the-dt"><span class=secno>3.11.5. </span>The - <code>dt</code> element</a> - - <li><a href="#the-dd"><span class=secno>3.11.6. </span>The - <code>dd</code> element</a> - </ul> - - <li><a href="#phrase"><span class=secno>3.12. </span>Phrase elements</a> - - <ul class=toc> - <li><a href="#the-a"><span class=secno>3.12.1. </span>The - <code>a</code> element</a> - - <li><a href="#the-q"><span class=secno>3.12.2. </span>The - <code>q</code> element</a> - - <li><a href="#the-cite"><span class=secno>3.12.3. </span>The - <code>cite</code> element</a> - - <li><a href="#the-em"><span class=secno>3.12.4. </span>The - <code>em</code> element</a> - - <li><a href="#the-strong"><span class=secno>3.12.5. </span>The - <code>strong</code> element</a> - - <li><a href="#the-small"><span class=secno>3.12.6. </span>The - <code>small</code> element</a> - - <li><a href="#the-m"><span class=secno>3.12.7. </span>The - <code>m</code> element</a> - - <li><a href="#the-dfn"><span class=secno>3.12.8. </span>The - <code>dfn</code> element</a> - - <li><a href="#the-abbr"><span class=secno>3.12.9. </span>The - <code>abbr</code> element</a> - - <li><a href="#the-time"><span class=secno>3.12.10. </span>The - <code>time</code> element</a> - - <li><a href="#the-meter"><span class=secno>3.12.11. </span>The - <code>meter</code> element</a> - - <li><a href="#the-progress"><span class=secno>3.12.12. </span>The - <code>progress</code> element</a> - - <li><a href="#the-code"><span class=secno>3.12.13. </span>The - <code>code</code> element</a> - - <li><a href="#the-var"><span class=secno>3.12.14. </span>The - <code>var</code> element</a> - - <li><a href="#the-samp"><span class=secno>3.12.15. </span>The - <code>samp</code> element</a> - - <li><a href="#the-kbd"><span class=secno>3.12.16. </span>The - <code>kbd</code> element</a> - - <li><a href="#the-sup"><span class=secno>3.12.17. </span>The - <code>sup</code> and <code>sub</code> elements</a> - - <li><a href="#the-span"><span class=secno>3.12.18. </span>The - <code>span</code> element</a> - - <li><a href="#the-i"><span class=secno>3.12.19. </span>The - <code>i</code> element</a> - - <li><a href="#the-b"><span class=secno>3.12.20. </span>The - <code>b</code> element</a> - - <li><a href="#the-bdo"><span class=secno>3.12.21. </span>The - <code>bdo</code> element</a> - </ul> - - <li><a href="#edits"><span class=secno>3.13. </span>Edits</a> - <ul class=toc> - <li><a href="#the-ins"><span class=secno>3.13.1. </span>The - <code>ins</code> element</a> - - <li><a href="#the-del"><span class=secno>3.13.2. </span>The - <code>del</code> element</a> - - <li><a href="#attributes"><span class=secno>3.13.3. </span>Attributes - common to <code>ins</code> and <code>del</code> elements</a> - </ul> - - <li><a href="#embedded"><span class=secno>3.14. </span>Embedded - content</a> - <ul class=toc> - <li><a href="#the-figure"><span class=secno>3.14.1. </span>The - <code>figure</code> element</a> - - <li><a href="#the-img"><span class=secno>3.14.2. </span>The - <code>img</code> element</a> - - <li><a href="#the-iframe"><span class=secno>3.14.3. </span>The - <code>iframe</code> element</a> - - <li><a href="#the-embed"><span class=secno>3.14.4. </span>The - <code>embed</code> element</a> - - <li><a href="#the-object"><span class=secno>3.14.5. </span>The - <code>object</code> element</a> - - <li><a href="#the-param"><span class=secno>3.14.6. </span>The - <code>param</code> element</a> - - <li><a href="#video"><span class=secno>3.14.7. </span>The - <code>video</code> element</a> - <ul class=toc> - <li><a href="#video0"><span class=secno>3.14.7.1. </span>Video and - audio codecs for <code>video</code> elements</a> - </ul> - - <li><a href="#audio"><span class=secno>3.14.8. </span>The - <code>audio</code> element</a> - <ul class=toc> - <li><a href="#audio0"><span class=secno>3.14.8.1. </span>Audio - codecs for <code>audio</code> elements</a> - </ul> - - <li><a href="#media"><span class=secno>3.14.9. </span>Media - elements</a> - <ul class=toc> - <li><a href="#error"><span class=secno>3.14.9.1. </span>Error - codes</a> - - <li><a href="#location"><span class=secno>3.14.9.2. </span>Location - of the media resource</a> - - <li><a href="#network0"><span class=secno>3.14.9.3. </span>Network - states</a> - - <li><a href="#loading"><span class=secno>3.14.9.4. </span>Loading - the media resource</a> - - <li><a href="#offsets"><span class=secno>3.14.9.5. </span>Offsets - into the media resource</a> - - <li><a href="#the-ready"><span class=secno>3.14.9.6. </span>The - ready states</a> - - <li><a href="#playing"><span class=secno>3.14.9.7. </span>Playing - the media resource</a> - - <li><a href="#seeking"><span class=secno>3.14.9.8. - </span>Seeking</a> - - <li><a href="#cue-points"><span class=secno>3.14.9.9. </span>Cue - points</a> - - <li><a href="#user-interface"><span class=secno>3.14.9.10. - </span>User interface</a> - - <li><a href="#time-range"><span class=secno>3.14.9.11. </span>Time - range</a> - - <li><a href="#mediaevents"><span class=secno>3.14.9.12. </span>Event - summary</a> - - <li><a href="#security0"><span class=secno>3.14.9.13. - </span>Security and privacy considerations</a> - </ul> - - <li><a href="#the-source"><span class=secno>3.14.10. </span>The - <code>source</code> element</a> - - <li><a href="#the-canvas"><span class=secno>3.14.11. </span>The - <code>canvas</code> element</a> - <ul class=toc> - <li><a href="#the-2d"><span class=secno>3.14.11.1. </span>The 2D - context</a> - <ul class=toc> - <li><a href="#the-canvas0"><span class=secno>3.14.11.1.1. - </span>The canvas state</a> - - <li><a href="#transformations"><span class=secno>3.14.11.1.2. - </span>Transformations</a> - - <li><a href="#compositing"><span class=secno>3.14.11.1.3. - </span>Compositing</a> - - <li><a href="#colors"><span class=secno>3.14.11.1.4. </span>Colors - and styles</a> - - <li><a href="#line-styles"><span class=secno>3.14.11.1.5. - </span>Line styles</a> - - <li><a href="#shadows"><span class=secno>3.14.11.1.6. - </span>Shadows</a> - - <li><a href="#simple"><span class=secno>3.14.11.1.7. </span>Simple - shapes (rectangles)</a> - - <li><a href="#complex"><span class=secno>3.14.11.1.8. - </span>Complex shapes (paths)</a> - - <li><a href="#images"><span class=secno>3.14.11.1.9. - </span>Images</a> - - <li><a href="#pixel"><span class=secno>3.14.11.1.10. </span>Pixel - manipulation</a> - - <li><a href="#drawing"><span class=secno>3.14.11.1.11. - </span>Drawing model</a> - </ul> - </ul> - - <li><a href="#the-map"><span class=secno>3.14.12. </span>The - <code>map</code> element</a> - - <li><a href="#the-area"><span class=secno>3.14.13. </span>The - <code>area</code> element</a> - - <li><a href="#image-maps"><span class=secno>3.14.14. </span>Image - maps</a> - </ul> - - <li><a href="#tabular"><span class=secno>3.15. </span>Tabular data</a> - <ul class=toc> - <li><a href="#the-table"><span class=secno>3.15.1. </span>The - <code>table</code> element</a> - - <li><a href="#the-caption"><span class=secno>3.15.2. </span>The - <code>caption</code> element</a> - - <li><a href="#the-colgroup"><span class=secno>3.15.3. </span>The - <code>colgroup</code> element</a> - - <li><a href="#the-col"><span class=secno>3.15.4. </span>The - <code>col</code> element</a> - - <li><a href="#the-tbody"><span class=secno>3.15.5. </span>The - <code>tbody</code> element</a> - - <li><a href="#the-thead"><span class=secno>3.15.6. </span>The - <code>thead</code> element</a> - - <li><a href="#the-tfoot"><span class=secno>3.15.7. </span>The - <code>tfoot</code> element</a> - - <li><a href="#the-tr"><span class=secno>3.15.8. </span>The - <code>tr</code> element</a> - - <li><a href="#the-td"><span class=secno>3.15.9. </span>The - <code>td</code> element</a> - - <li><a href="#the-th"><span class=secno>3.15.10. </span>The - <code>th</code> element</a> - - <li><a href="#processing"><span class=secno>3.15.11. </span>Processing - model</a> - <ul class=toc> - <li><a href="#forming"><span class=secno>3.15.11.1. </span>Forming a - table</a> - - <li><a href="#header-and-data-cell-semantics"><span - class=secno>3.15.11.2. </span>Forming relationships between data - cells and header cells</a> - </ul> - </ul> - - <li><a href="#forms"><span class=secno>3.16. </span>Forms</a> - <ul class=toc> - <li><a href="#the-form"><span class=secno>3.16.1. </span>The - <code>form</code> element</a> - - <li><a href="#the-fieldset"><span class=secno>3.16.2. </span>The - <code>fieldset</code> element</a> - - <li><a href="#the-input"><span class=secno>3.16.3. </span>The - <code>input</code> element</a> - - <li><a href="#the-button"><span class=secno>3.16.4. </span>The - <code>button</code> element</a> - - <li><a href="#the-label"><span class=secno>3.16.5. </span>The - <code>label</code> element</a> - - <li><a href="#the-select"><span class=secno>3.16.6. </span>The - <code>select</code> element</a> - - <li><a href="#the-datalist"><span class=secno>3.16.7. </span>The - <code>datalist</code> element</a> - - <li><a href="#the-optgroup"><span class=secno>3.16.8. </span>The - <code>optgroup</code> element</a> - - <li><a href="#the-option"><span class=secno>3.16.9. </span>The - <code>option</code> element</a> - - <li><a href="#the-textarea"><span class=secno>3.16.10. </span>The - <code>textarea</code> element</a> - - <li><a href="#the-output"><span class=secno>3.16.11. </span>The - <code>output</code> element</a> - - <li><a href="#processing0"><span class=secno>3.16.12. - </span>Processing model</a> - <ul class=toc> - <li><a href="#form-submission"><span class=secno>3.16.12.1. - </span>Form submission</a> - </ul> - </ul> - - <li><a href="#scripting0"><span class=secno>3.17. </span>Scripting</a> - <ul class=toc> - <li><a href="#script"><span class=secno>3.17.1. </span>The - <code>script</code> element</a> - <ul class=toc> - <li><a href="#scriptingLanguages"><span class=secno>3.17.1.1. - </span>Scripting languages</a> - </ul> - - <li><a href="#the-noscript"><span class=secno>3.17.2. </span>The - <code>noscript</code> element</a> - - <li><a href="#the-event-source"><span class=secno>3.17.3. </span>The - <code>event-source</code> element</a> - </ul> - - <li><a href="#interactive"><span class=secno>3.18. </span>Interactive - elements</a> - <ul class=toc> - <li><a href="#the-details"><span class=secno>3.18.1. </span>The - <code>details</code> element</a> - - <li><a href="#datagrid"><span class=secno>3.18.2. </span>The - <code>datagrid</code> element</a> - <ul class=toc> - <li><a href="#the-datagrid"><span class=secno>3.18.2.1. </span>The - <code>datagrid</code> data model</a> - - <li><a href="#how-rows"><span class=secno>3.18.2.2. </span>How rows - are identified</a> - - <li><a href="#the-data"><span class=secno>3.18.2.3. </span>The data - provider interface</a> - - <li><a href="#the-default"><span class=secno>3.18.2.4. </span>The - default data provider</a> - <ul class=toc> - <li><a href="#commonDefaultDataGridMethodDefinitions"><span - class=secno>3.18.2.4.1. </span>Common default data provider - method definitions for cells</a> - </ul> - - <li><a href="#populating"><span class=secno>3.18.2.5. - </span>Populating the <code>datagrid</code> element</a> - - <li><a href="#updating"><span class=secno>3.18.2.6. </span>Updating - the <code>datagrid</code></a> - - <li><a href="#requirements"><span class=secno>3.18.2.7. - </span>Requirements for interactive user agents</a> - - <li><a href="#the-selection"><span class=secno>3.18.2.8. </span>The - selection</a> - - <li><a href="#columns"><span class=secno>3.18.2.9. </span>Columns - and captions</a> - </ul> - - <li><a href="#the-command"><span class=secno>3.18.3. </span>The - <code>command</code> element</a> - - <li><a href="#menus"><span class=secno>3.18.4. </span>The - <code>menu</code> element</a> - <ul class=toc> - <li><a href="#menus-intro"><span class=secno>3.18.4.1. - </span>Introduction</a> - - <li><a href="#building"><span class=secno>3.18.4.2. </span>Building - menus</a> - - <li><a href="#context"><span class=secno>3.18.4.3. </span>Context - menus</a> - - <li><a href="#toolbars"><span class=secno>3.18.4.4. - </span>Toolbars</a> - </ul> - - <li><a href="#commands"><span class=secno>3.18.5. </span>Commands</a> - <ul class=toc> - <li><a href="#using"><span class=secno>3.18.5.1. </span>Using the - <code>a</code> element to define a command</a> - - <li><a href="#using0"><span class=secno>3.18.5.2. </span>Using the - <code>button</code> element to define a command</a> - - <li><a href="#using1"><span class=secno>3.18.5.3. </span>Using the - <code>input</code> element to define a command</a> - - <li><a href="#using2"><span class=secno>3.18.5.4. </span>Using the - <code>option</code> element to define a command</a> - - <li><a href="#using3"><span class=secno>3.18.5.5. </span>Using the - <code>command</code> element to define a command</a> - </ul> - </ul> - - <li><a href="#miscellaneous"><span class=secno>3.19. - </span>Miscellaneous elements</a> - <ul class=toc> - <li><a href="#the-legend"><span class=secno>3.19.1. </span>The - <code>legend</code> element</a> - - <li><a href="#the-div"><span class=secno>3.19.2. </span>The - <code>div</code> element</a> - </ul> - </ul> - - <li><a href="#web-browsers"><span class=secno>4. </span>Web browsers</a> - <ul class=toc> - <li><a href="#windows"><span class=secno>4.1. </span>Browsing - contexts</a> - <ul class=toc> - <li><a href="#nested"><span class=secno>4.1.1. </span>Nested browsing - contexts</a> - - <li><a href="#auxiliary"><span class=secno>4.1.2. </span>Auxiliary - browsing contexts</a> - - <li><a href="#secondary"><span class=secno>4.1.3. </span>Secondary - browsing contexts</a> - - <li><a href="#threads"><span class=secno>4.1.4. </span>Threads</a> - - <li><a href="#browsing"><span class=secno>4.1.5. </span>Browsing - context names</a> - </ul> - - <li><a href="#the-default0"><span class=secno>4.2. </span>The default - view</a> - <ul class=toc> - <li><a href="#security1"><span class=secno>4.2.1. </span>Security</a> - - <li><a href="#constructors"><span class=secno>4.2.2. - </span>Constructors</a> - - <li><a href="#apis-for"><span class=secno>4.2.3. </span>APIs for - creating and navigating browsing contexts by name</a> - - <li><a href="#accessing"><span class=secno>4.2.4. </span>Accessing - other browsing contexts</a> - </ul> - - <li><a href="#history"><span class=secno>4.3. </span>Session history and - navigation</a> - <ul class=toc> - <li><a href="#the-session"><span class=secno>4.3.1. </span>The session - history of browsing contexts</a> - - <li><a href="#the-history"><span class=secno>4.3.2. </span>The - <code>History</code> interface</a> - - <li><a href="#activating"><span class=secno>4.3.3. </span>Activating - state objects</a> - - <li><a href="#the-location"><span class=secno>4.3.4. </span>The - <code>Location</code> interface</a> - <ul class=toc> - <li><a href="#security2"><span class=secno>4.3.4.1. - </span>Security</a> - </ul> - - <li><a href="#history-notes"><span class=secno>4.3.5. - </span>Implementation notes for session history</a> - </ul> - - <li><a href="#links"><span class=secno>4.4. </span>Links</a> - <ul class=toc> - <li><a href="#hyperlink"><span class=secno>4.4.1. </span>Hyperlink - elements</a> - - <li><a href="#following"><span class=secno>4.4.2. </span>Following - hyperlinks</a> - <ul class=toc> - <li><a href="#hyperlink0"><span class=secno>4.4.2.1. - </span>Hyperlink auditing</a> - </ul> - - <li><a href="#linkTypes"><span class=secno>4.4.3. </span>Link - types</a> - <ul class=toc> - <li><a href="#link-type"><span class=secno>4.4.3.1. </span>Link type - "<code>alternate</code>"</a> - - <li><a href="#link-type0"><span class=secno>4.4.3.2. </span>Link - type "<code>archives</code>"</a> - - <li><a href="#link-type1"><span class=secno>4.4.3.3. </span>Link - type "<code>author</code>"</a> - - <li><a href="#link-type2"><span class=secno>4.4.3.4. </span>Link - type "<code>bookmark</code>"</a> - - <li><a href="#link-type3"><span class=secno>4.4.3.5. </span>Link - type "<code>contact</code>"</a> - - <li><a href="#link-type4"><span class=secno>4.4.3.6. </span>Link - type "<code>external</code>"</a> - - <li><a href="#link-type5"><span class=secno>4.4.3.7. </span>Link - type "<code>feed</code>"</a> - - <li><a href="#link-type6"><span class=secno>4.4.3.8. </span>Link - type "<code>help</code>"</a> - - <li><a href="#link-type7"><span class=secno>4.4.3.9. </span>Link - type "<code>icon</code>"</a> - - <li><a href="#link-type8"><span class=secno>4.4.3.10. </span>Link - type "<code>license</code>"</a> - - <li><a href="#link-type9"><span class=secno>4.4.3.11. </span>Link - type "<code>nofollow</code>"</a> - - <li><a href="#link-type10"><span class=secno>4.4.3.12. </span>Link - type "<code>pingback</code>"</a> - - <li><a href="#link-type11"><span class=secno>4.4.3.13. </span>Link - type "<code>prefetch</code>"</a> - - <li><a href="#link-type12"><span class=secno>4.4.3.14. </span>Link - type "<code>search</code>"</a> - - <li><a href="#link-type13"><span class=secno>4.4.3.15. </span>Link - type "<code>stylesheet</code>"</a> - - <li><a href="#link-type14"><span class=secno>4.4.3.16. </span>Link - type "<code>sidebar</code>"</a> - - <li><a href="#link-type15"><span class=secno>4.4.3.17. </span>Link - type "<code>tag</code>"</a> - - <li><a href="#hierarchical"><span class=secno>4.4.3.18. - </span>Hierarchical link types</a> - <ul class=toc> - <li><a href="#link-type16"><span class=secno>4.4.3.18.1. - </span>Link type "<code>first</code>"</a> - - <li><a href="#link-type17"><span class=secno>4.4.3.18.2. - </span>Link type "<code>index</code>"</a> - - <li><a href="#link-type18"><span class=secno>4.4.3.18.3. - </span>Link type "<code>last</code>"</a> - - <li><a href="#link-type19"><span class=secno>4.4.3.18.4. - </span>Link type "<code>next</code>"</a> - - <li><a href="#link-type20"><span class=secno>4.4.3.18.5. - </span>Link type "<code>prev</code>"</a> - - <li><a href="#link-type21"><span class=secno>4.4.3.18.6. - </span>Link type "<code>up</code>"</a> - </ul> - - <li><a href="#other0"><span class=secno>4.4.3.19. </span>Other link - types</a> - </ul> - </ul> - - <li><a href="#interfaces"><span class=secno>4.5. </span>Interfaces for - URI manipulation</a> - - <li><a href="#navigating"><span class=secno>4.6. </span>Navigating - across documents</a> - <ul class=toc> - <li><a href="#read-html"><span class=secno>4.6.1. </span>Page load - processing model for HTML files</a> - - <li><a href="#read-xml"><span class=secno>4.6.2. </span>Page load - processing model for XML files</a> - - <li><a href="#read-text"><span class=secno>4.6.3. </span>Page load - processing model for text files</a> - - <li><a href="#read-image"><span class=secno>4.6.4. </span>Page load - processing model for images</a> - - <li><a href="#read-plugin"><span class=secno>4.6.5. </span>Page load - processing model for content that uses plugins</a> - - <li><a href="#non-DOM-inline-content"><span class=secno>4.6.6. - </span>Page load processing model for inline content that doesn't - have a DOM</a> - - <li><a href="#scroll-to-fragid"><span class=secno>4.6.7. - </span>Scrolling to a fragment identifier</a> - </ul> - - <li><a href="#content-type-sniffing"><span class=secno>4.7. - </span>Determining the type of a new resource in a browsing context</a> - - <ul class=toc> - <li><a href="#content-type0"><span class=secno>4.7.1. - </span>Content-Type sniffing: text or binary</a> - - <li><a href="#content-type1"><span class=secno>4.7.2. - </span>Content-Type sniffing: unknown type</a> - - <li><a href="#content-type2"><span class=secno>4.7.3. - </span>Content-Type sniffing: image</a> - - <li><a href="#content-type3"><span class=secno>4.7.4. - </span>Content-Type sniffing: feed or HTML</a> - - <li><a href="#content-type"><span class=secno>4.7.5. - </span>Content-Type metadata</a> - </ul> - - <li><a href="#user-prompts"><span class=secno>4.8. </span>User - prompts</a> - - <li><a href="#scripting"><span class=secno>4.9. </span>Scripting</a> - <ul class=toc> - <li><a href="#running"><span class=secno>4.9.1. </span>Running - executable code</a> - - <li><a href="#origin"><span class=secno>4.9.2. </span>Origin</a> - - <li><a href="#security3"><span class=secno>4.9.3. </span>Security - exceptions</a> - - <li><a href="#javascript-protocol"><span class=secno>4.9.4. </span>The - <code title="">javascript:</code> protocol</a> - - <li><a href="#events"><span class=secno>4.9.5. </span>Events</a> - <ul class=toc> - <li><a href="#event-handler-attributes"><span class=secno>4.9.5.1. - </span>Event handler attributes</a> - - <li><a href="#event"><span class=secno>4.9.5.2. </span>Event - firing</a> - - <li><a href="#events0"><span class=secno>4.9.5.3. </span>Events and - the <code>Window</code> object</a> - - <li><a href="#runtime-script-errors"><span class=secno>4.9.5.4. - </span>Runtime script errors</a> - </ul> - </ul> - - <li><a href="#browser"><span class=secno>4.10. </span>Browser state</a> - <ul class=toc> - <li><a href="#offline"><span class=secno>4.10.1. </span>Offline Web - applications</a> - - <li><a href="#custom-handlers"><span class=secno>4.10.2. </span>Custom - protocol and content handlers</a> - <ul class=toc> - <li><a href="#security4"><span class=secno>4.10.2.1. </span>Security - and privacy</a> - - <li><a href="#sample-handler-impl"><span class=secno>4.10.2.2. - </span>Sample user interface</a> - </ul> - </ul> - - <li><a href="#storage"><span class=secno>4.11. </span>Client-side - session and persistent storage of name/value pairs</a> - <ul class=toc> - <li><a href="#introduction0"><span class=secno>4.11.1. - </span>Introduction</a> - - <li><a href="#the-storage"><span class=secno>4.11.2. </span>The - <code>Storage</code> interface</a> - - <li><a href="#the-storageitem"><span class=secno>4.11.3. </span>The - <code>StorageItem</code> interface</a> - - <li><a href="#the-sessionstorage"><span class=secno>4.11.4. </span>The - <code title=dom-sessionStorage>sessionStorage</code> attribute</a> - - <li><a href="#the-globalstorage"><span class=secno>4.11.5. </span>The - <code title=dom-globalStorage>globalStorage</code> attribute</a> - - <li><a href="#the-storage0"><span class=secno>4.11.6. </span>The <code - title=event-storage>storage</code> event</a> - - <li><a href="#miscellaneous0"><span class=secno>4.11.7. - </span>Miscellaneous implementation requirements for storage - areas</a> - <ul class=toc> - <li><a href="#disk-space"><span class=secno>4.11.7.1. </span>Disk - space</a> - - <li><a href="#threads0"><span class=secno>4.11.7.2. - </span>Threads</a> - </ul> - - <li><a href="#security5"><span class=secno>4.11.8. </span>Security and - privacy</a> - <ul class=toc> - <li><a href="#user-tracking"><span class=secno>4.11.8.1. </span>User - tracking</a> - - <li><a href="#cookie"><span class=secno>4.11.8.2. </span>Cookie - resurrection</a> - - <li><a href="#integrity"><span class=secno>4.11.8.3. - </span>Integrity of "public" storage areas</a> - - <li><a href="#cross-protocol"><span class=secno>4.11.8.4. - </span>Cross-protocol and cross-port attacks</a> - - <li><a href="#dns-spoofing"><span class=secno>4.11.8.5. </span>DNS - spoofing attacks</a> - - <li><a href="#cross-directory"><span class=secno>4.11.8.6. - </span>Cross-directory attacks</a> - - <li><a href="#public"><span class=secno>4.11.8.7. </span>Public - storage areas corresponding to hosts</a> - - <li><a href="#storage0"><span class=secno>4.11.8.8. </span>Storage - areas in the face of untrusted higher-level domains that do not - correspond to public storage areas</a> - - <li><a href="#storage1"><span class=secno>4.11.8.9. </span>Storage - areas in the face of untrusted subdomains</a> - - <li><a href="#implementation"><span class=secno>4.11.8.10. - </span>Implementation risks</a> - </ul> - </ul> - - <li><a href="#sql"><span class=secno>4.12. </span>Client-side database - storage</a> - <ul class=toc> - <li><a href="#introduction1"><span class=secno>4.12.1. - </span>Introduction</a> - - <li><a href="#executing"><span class=secno>4.12.2. </span>Executing - SQL statements</a> - - <li><a href="#database"><span class=secno>4.12.3. </span>Database - query results</a> - - <li><a href="#privacy"><span class=secno>4.12.4. </span>Privacy</a> - - <li><a href="#security6"><span class=secno>4.12.5. </span>Security</a> - - <ul class=toc> - <li><a href="#user-agents"><span class=secno>4.12.5.1. </span>User - agents</a> - - <li><a href="#sql-injection"><span class=secno>4.12.5.2. </span>SQL - injection</a> - </ul> - </ul> - </ul> - - <li><a href="#editing"><span class=secno>5. </span>Editing</a> - <ul class=toc> - <li><a href="#editing-intro"><span class=secno>5.1. - </span>Introduction</a> - - <li><a href="#contenteditable"><span class=secno>5.2. </span>The <code - title=attr-contenteditable>contenteditable</code> attribute</a> - <ul class=toc> - <li><a href="#user-editing"><span class=secno>5.2.1. </span>User - editing actions</a> - - <li><a href="#making"><span class=secno>5.2.2. </span>Making entire - documents editable</a> - </ul> - - <li><a href="#dnd"><span class=secno>5.3. </span>Drag and drop</a> - <ul class=toc> - <li><a href="#the-dragevent"><span class=secno>5.3.1. </span>The - <code>DragEvent</code> and <code>DataTransfer</code> interfaces</a> - - <li><a href="#events1"><span class=secno>5.3.2. </span>Events fired - during a drag-and-drop action</a> - - <li><a href="#drag-and-drop"><span class=secno>5.3.3. - </span>Drag-and-drop processing model</a> - <ul class=toc> - <li><a href="#when-the"><span class=secno>5.3.3.1. </span>When the - drag-and-drop operation starts or ends in another document</a> - - <li><a href="#when-the0"><span class=secno>5.3.3.2. </span>When the - drag-and-drop operation starts or ends in another application</a> - </ul> - - <li><a href="#the-draggable"><span class=secno>5.3.4. </span>The - <code>draggable</code> attribute</a> - - <li><a href="#copy-and"><span class=secno>5.3.5. </span>Copy and - paste</a> - <ul class=toc> - <li><a href="#copy-to"><span class=secno>5.3.5.1. </span>Copy to - clipboard</a> - - <li><a href="#cut-to"><span class=secno>5.3.5.2. </span>Cut to - clipboard</a> - - <li><a href="#paste"><span class=secno>5.3.5.3. </span>Paste from - clipboard</a> - - <li><a href="#paste0"><span class=secno>5.3.5.4. </span>Paste from - selection</a> - </ul> - - <li><a href="#security7"><span class=secno>5.3.6. </span>Security - risks in the drag-and-drop model</a> - </ul> - - <li><a href="#undo"><span class=secno>5.4. </span>Undo history</a> - <ul class=toc> - <li><a href="#the-undomanager"><span class=secno>5.4.1. </span>The - <code>UndoManager</code> interface</a> - - <li><a href="#undo-moving"><span class=secno>5.4.2. </span>Undo: - moving back in the undo transaction history</a> - - <li><a href="#redo-moving"><span class=secno>5.4.3. </span>Redo: - moving forward in the undo transaction history</a> - - <li><a href="#the-undomanagerevent"><span class=secno>5.4.4. - </span>The <code>UndoManagerEvent</code> interface and the <code - title=event-undo>undo</code> and <code title=event-redo>redo</code> - events</a> - - <li><a href="#implementation0"><span class=secno>5.4.5. - </span>Implementation notes</a> - </ul> - - <li><a href="#command"><span class=secno>5.5. </span>Command APIs</a> - - <li><a href="#selection"><span class=secno>5.6. </span>The text - selection APIs</a> - <ul class=toc> - <li><a href="#documentSelection"><span class=secno>5.6.1. </span>APIs - for the browsing context selection</a> - - <li><a href="#textFieldSelection"><span class=secno>5.6.2. </span>APIs - for the text field selections</a> - </ul> - </ul> - - <li><a href="#comms"><span class=secno>6. </span>Communication</a> - <ul class=toc> - <li><a href="#event0"><span class=secno>6.1. </span>Event - definitions</a> - - <li><a href="#server-sent-events"><span class=secno>6.2. - </span>Server-sent DOM events</a> - <ul class=toc> - <li><a href="#the-remoteeventtarget"><span class=secno>6.2.1. - </span>The <code>RemoteEventTarget</code> interface</a> - - <li><a href="#connecting"><span class=secno>6.2.2. </span>Connecting - to an event stream</a> - - <li><a href="#parsing0"><span class=secno>6.2.3. </span>Parsing an - event stream</a> - - <li><a href="#event-stream-interpretation"><span class=secno>6.2.4. - </span>Interpreting an event stream</a> - - <li><a href="#notes"><span class=secno>6.2.5. </span>Notes</a> - </ul> - - <li><a href="#network"><span class=secno>6.3. </span>Network - connections</a> - <ul class=toc> - <li><a href="#network-intro"><span class=secno>6.3.1. - </span>Introduction</a> - - <li><a href="#the-connection"><span class=secno>6.3.2. </span>The - <code>Connection</code> interface</a> - - <li><a href="#connection"><span class=secno>6.3.3. </span>Connection - Events</a> - - <li><a href="#tcp-connections"><span class=secno>6.3.4. </span>TCP - connections</a> - - <li><a href="#broadcast"><span class=secno>6.3.5. </span>Broadcast - connections</a> - <ul class=toc> - <li><a href="#broadcasting"><span class=secno>6.3.5.1. - </span>Broadcasting over TCP/IP</a> - - <li><a href="#bluetooth-broadcast"><span class=secno>6.3.5.2. - </span>Broadcasting over Bluetooth</a> - - <li><a href="#irda-broadcast"><span class=secno>6.3.5.3. - </span>Broadcasting over IrDA</a> - </ul> - - <li><a href="#peer-to-peer"><span class=secno>6.3.6. - </span>Peer-to-peer connections</a> - <ul class=toc> - <li><a href="#peer-to-peer0"><span class=secno>6.3.6.1. - </span>Peer-to-peer connections over TCP/IP</a> - - <li><a href="#bluetooth-peer"><span class=secno>6.3.6.2. - </span>Peer-to-peer connections over Bluetooth</a> - - <li><a href="#irda-peer"><span class=secno>6.3.6.3. - </span>Peer-to-peer connections over IrDA</a> - </ul> - - <li><a href="#the-common"><span class=secno>6.3.7. </span>The common - protocol for TCP-based connections</a> - <ul class=toc> - <li><a href="#clients"><span class=secno>6.3.7.1. </span>Clients - connecting over TCP</a> - - <li><a href="#servers"><span class=secno>6.3.7.2. </span>Servers - accepting connections over TCP</a> - - <li><a href="#sending"><span class=secno>6.3.7.3. </span>Sending and - receiving data over TCP</a> - </ul> - - <li><a href="#network-security"><span class=secno>6.3.8. - </span>Security</a> - - <li><a href="#network-other-specs"><span class=secno>6.3.9. - </span>Relationship to other standards</a> - </ul> - - <li><a href="#crossDocumentMessages"><span class=secno>6.4. - </span>Cross-document messaging</a> - <ul class=toc> - <li><a href="#processing1"><span class=secno>6.4.1. </span>Processing - model</a> - </ul> - </ul> - - <li><a href="#repetition"><span class=secno>7. </span>Repetition - templates</a> - - <li><a href="#syntax"><span class=secno>8. </span>The HTML syntax</a> - <ul class=toc> - <li><a href="#writing"><span class=secno>8.1. </span>Writing HTML - documents</a> - <ul class=toc> - <li><a href="#the-doctype"><span class=secno>8.1.1. </span>The - DOCTYPE</a> - - <li><a href="#elements0"><span class=secno>8.1.2. </span>Elements</a> - <ul class=toc> - <li><a href="#start"><span class=secno>8.1.2.1. </span>Start - tags</a> - - <li><a href="#end-tags"><span class=secno>8.1.2.2. </span>End - tags</a> - - <li><a href="#attributes0"><span class=secno>8.1.2.3. - </span>Attributes</a> - - <li><a href="#optional"><span class=secno>8.1.2.4. </span>Optional - tags</a> - - <li><a href="#restrictions"><span class=secno>8.1.2.5. - </span>Restrictions on content models</a> - </ul> - - <li><a href="#text"><span class=secno>8.1.3. </span>Text</a> - <ul class=toc> - <li><a href="#newlines"><span class=secno>8.1.3.1. - </span>Newlines</a> - </ul> - - <li><a href="#character"><span class=secno>8.1.4. </span>Character - entity references</a> - - <li><a href="#comments"><span class=secno>8.1.5. </span>Comments</a> - </ul> - - <li><a href="#parsing"><span class=secno>8.2. </span>Parsing HTML - documents</a> - <ul class=toc> - <li><a href="#overview"><span class=secno>8.2.1. </span>Overview of - the parsing model</a> - - <li><a href="#the-input0"><span class=secno>8.2.2. </span>The input - stream</a> - - <li><a href="#tokenisation"><span class=secno>8.2.3. - </span>Tokenisation</a> - <ul class=toc> - <li><a href="#tokenising"><span class=secno>8.2.3.1. - </span>Tokenising entities</a> - </ul> - - <li><a href="#tree-construction"><span class=secno>8.2.4. </span>Tree - construction</a> - <ul class=toc> - <li><a href="#the-initial"><span class=secno>8.2.4.1. </span>The - initial phase</a> - - <li><a href="#the-root0"><span class=secno>8.2.4.2. </span>The root - element phase</a> - - <li><a href="#the-main"><span class=secno>8.2.4.3. </span>The main - phase</a> - <ul class=toc> - <li><a href="#the-stack"><span class=secno>8.2.4.3.1. </span>The - stack of open elements</a> - - <li><a href="#the-list"><span class=secno>8.2.4.3.2. </span>The - list of active formatting elements</a> - - <li><a href="#creating"><span class=secno>8.2.4.3.3. - </span>Creating and inserting HTML elements</a> - - <li><a href="#closing"><span class=secno>8.2.4.3.4. </span>Closing - elements that have implied end tags</a> - - <li><a href="#the-element"><span class=secno>8.2.4.3.5. </span>The - element pointers</a> - - <li><a href="#the-insertion"><span class=secno>8.2.4.3.6. - </span>The insertion mode</a> - - <li><a href="#how-to0"><span class=secno>8.2.4.3.7. </span>How to - handle tokens in the main phase</a> - </ul> - - <li><a href="#the-trailing"><span class=secno>8.2.4.4. </span>The - trailing end phase</a> - </ul> - - <li><a href="#the-end"><span class=secno>8.2.5. </span>The End</a> - </ul> - - <li><a href="#namespaces"><span class=secno>8.3. </span>Namespaces</a> - - <li><a href="#entities"><span class=secno>8.4. </span>Entities</a> - </ul> - - <li><a href="#wysiwyg"><span class=secno>9. </span>WYSIWYG editors</a> - <ul class=toc> - <li><a href="#presentational"><span class=secno>9.1. - </span>Presentational markup</a> - <ul class=toc> - <li><a href="#wysiwyg0"><span class=secno>9.1.1. </span>WYSIWYG - signature</a> - - <li><a href="#the-font"><span class=secno>9.1.2. </span>The - <code>font</code> element</a> - </ul> - </ul> - - <li><a href="#rendering"><span class=secno>10. </span>Rendering</a> - <ul class=toc> - <li><a href="#rendering0"><span class=secno>10.1. </span>Rendering and - the DOM</a> - </ul> - - <li><a href="#no"><span class=secno>11. </span>Things that you can't do - with this specification because they are better handled using other - technologies that are further described herein</a> - <ul class=toc> - <li><a href="#localisation"><span class=secno>11.1. - </span>Localisation</a> - - <li><a href="#declarative"><span class=secno>11.2. </span>Declarative 2D - vector graphics and animation</a> - - <li><a href="#declarative0"><span class=secno>11.3. </span>Declarative - 3D scenes</a> - - <li><a href="#timers"><span class=secno>11.4. </span>Timers</a> - - <li><a href="#events2"><span class=secno>11.5. </span>Events</a> - </ul> - - <li class=no-num><a href="#references">References</a> - - <li class=no-num><a href="#acknowledgements">Acknowledgements</a> - </ul> - <!--end-toc--> - - <hr> - - <h2 id=introduction><span class=secno>1. </span>Introduction</h2> - - <p><em>This section is non-normative.</em> - - <p>The World Wide Web's markup language has always been HTML. HTML was - primarily designed as a language for semantically describing scientific - documents, although its general design and adaptations over the years has - enabled it to be used to describe a number of other types of documents. - - <p>The main area that has not been adequately addressed by HTML is a vague - subject referred to as Web Applications. This specification attempts to - rectify this, while at the same time updating the HTML specifications to - address issues raised in the past few years. - - <h3 id=scope><span class=secno>1.1. </span>Scope</h3> - - <p><em>This section is non-normative.</em> - - <p>This specification is limited to providing a semantic-level markup - language and associated semantic-level scripting APIs for authoring - accessible pages on the Web ranging from static documents to dynamic - applications. - - <p>The scope of this specification does not include addressing presentation - concerns (although default rendering rules for Web browsers are included - at the end of this specification). - - <p>The scope of this specification does not include documenting every HTML - or DOM feature supported by Web browsers. Browsers support many features - that are considered to be very bad for accessibility or that are otherwise - inappropriate. For example, the <code>blink</code> element is clearly - presentational and authors wishing to cause text to blink should instead - use CSS. - - <p>The scope of this specification is not to describe an entire operating - system. In particular, hardware configuration software, image manipulation - tools, and applications that users would be expected to use with high-end - workstations on a daily basis are out of scope. In terms of applications, - this specification is targeted specifically at applications that would be - expected to be used by users on an occasional basis, or regularly but from - disparate locations, with low CPU requirements. For instance online - purchasing systems, searching systems, games (especially multiplayer - online games), public telephone books or address books, communications - software (e-mail clients, instant messaging clients, discussion software), - document editing software, etc. - - <p>For sophisticated cross-platform applications, there already exist - several proprietary solutions (such as Mozilla's XUL and Macromedia's - Flash). These solutions are evolving faster than any standards process - could follow, and the requirements are evolving even faster. These systems - are also significantly more complicated to specify, and are orders of - magnitude more difficult to achieve interoperability with, than the - solutions described in this document. Platform-specific solutions for such - sophisticated applications (for example the MacOS X Core APIs) are even - further ahead. - - <h4 id=relationship><span class=secno>1.1.1. </span>Relationship to HTML - 4.01, XHTML 1.1, DOM2 HTML</h4> - - <p><em>This section is non-normative.</em> - - <p>This specification represents a new version of HTML4 and XHTML1, along - with a new version of the associated DOM2 HTML API. Migration from HTML4 - or XHTML1 to the format and APIs described in this specification should in - most cases be straightforward, as care has been taken to ensure that - backwards-compatibility is retained.</p> - <!-- XXX refs --> - - <p>This specification will eventually supplant Web Forms 2.0 as well. <a - href="#refsWF2">[WF2]</a> - - <h4 id=relationship0><span class=secno>1.1.2. </span>Relationship to XHTML2</h4> - - <p><em>This section is non-normative.</em> - - <p>XHTML2 <a href="#refsXHTML2">[XHTML2]</a> defines a new HTML vocabulary - with better features for hyperlinks, multimedia content, annotating - document edits, rich metadata, declarative interactive forms, and - describing the semantics of human literary works such as poems and - scientific papers. - - <p>However, it lacks elements to express the semantics of many of the - non-document types of content often seen on the Web. For instance, forum - sites, auction sites, search engines, online shops, and the like, do not - fit the document metaphor well, and are not covered by XHTML2. - - <p><em>This</em> specification aims to extend HTML so that it is also - suitable in these contexts. - - <p>XHTML2 and this specification use different namespaces and therefore can - both be implemented in the same XML processor. - - <h4 id=relationship1><span class=secno>1.1.3. </span>Relationship to XUL, - Flash, Silverlight, and other proprietary UI languages</h4> - - <p><em>This section is non-normative.</em> - - <p>This specification is independent of the various proprietary UI - languages that various vendors provide. As an open, vender-neutral - language, HTML provides for a solution to the same problems without the - risk of vendor lock-in. - - <h3 id=structure><span class=secno>1.2. </span>Structure of this - specification</h3> - - <p><em>This section is non-normative.</em> - - <p>This specification is divided into the following important sections: - - <dl> - <dt><a href="#dom">The DOM</a> - - <dd>The DOM, or Document Object Model, provides a base for the rest of the - specification. - - <dt><a href="#semantics">The Semantics</a> - - <dd>Documents are built from elements. These elements form a tree using - the DOM. Each element also has a predefined meaning, which is explained - in this section. User agent requirements for how to handle each element - are also given, along with rules for authors on how to use the element. - - <dt><a href="#windows">Browsing Contexts</a> - - <dd>HTML documents do not exist in a vacuum — this section defines - many of the features that affect environments that deal with multiple - pages, links between pages, and running scripts. - - <dt>APIs - - <dd><a href="#editing">The Editing APIs</a>: HTML documents can provide a - number of mechanisms for users to modify content, which are described in - this section. - - <dd><a href="#comms">The Communication APIs</a>: Applications written in - HTML often require mechanisms to communicate with remote servers, as well - as communicating with other applications from different domains running - on the same client. - - <dd><a href="#repetition">Repetition Templates</a>: A mechanism to support - repeating sections in forms. - - <dt><a href="#syntax">The Language Syntax</a> - - <dd>All of these features would be for naught if they couldn't be - represented in a serialised form and sent to other people, and so this - section defines the syntax of HTML, along with rules for how to parse - HTML. - </dl> - - <p>There are also a couple of appendices, defining <a href="#wysiwyg">shims - for WYSIWYG editors</a>, <a href="#rendering">rendering rules</a> for Web - browsers, and listing <a href="#no">areas that are out of scope</a> for - this specification. - - <h4 id=how-to><span class=secno>1.2.1. </span>How to read this - specification</h4> - - <p>This specification should be read like all other specifications. First, - it should be read cover-to-cover, multiple times. Then, it should be read - backwards at least once. Then it should be read by picking random sections - from the contents list and following all the cross-references. - - <h3 id=conformance><span class=secno>1.3. </span>Conformance requirements</h3> - - <p>All diagrams, examples, and notes in this specification are - non-normative, as are all sections explicitly marked non-normative. - Everything else in this specification is normative. - - <p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the - normative parts of this document are to be interpreted as described in - RFC2119. For readability, these words do not appear in all uppercase - letters in this specification. <a href="#refsRFC2119">[RFC2119]</a></p> - <!-- XXX but they should be marked up --> - - <p>This specification describes the conformance criteria for user agents - (relevant to implementors) and documents (relevant to authors and - authoring tool implementors). - - <p class=note>There is no implied relationship between document conformance - requirements and implementation conformance requirements. User agents are - not free to handle non-conformant documents as they please; the processing - model described in this specification applies to implementations - regardless of the conformity of the input documents.</p> - <!--XXX quite possible that - this is stated twice. check for whether this is a dupe. --> - - <p>User agents fall into several (overlapping) categories with different - conformance requirements. - - <dl> - <dt id=interactive>Web browsers and other interactive user agents - - <dd> - <p>Web browsers that support <a href="#xhtml5">XHTML</a> must process - elements and attributes from the <a href="#html-namespace0">HTML - namespace</a> found in <a href="#xml-documents">XML documents</a> as - described in this specification, so that users can interact with them, - unless the semantics of those elements have been overridden by other - specifications.</p> - - <p class=example>A conforming XHTML processor would, upon finding an - XHTML <code><a href="#script0">script</a></code> element in an XML - document, execute the script contained in that element. However, if the - element is found within an XSLT transformation sheet (assuming the UA - also supports XSLT), then the processor would instead treat the <code><a - href="#script0">script</a></code> element as an opaque element that - forms part of the transform.</p> - - <p>Web browsers that support <a href="#html5" title=HTML5>HTML</a> must - process documents labelled as <code>text/html</code> as described in - this specification, so that users can interact with them.</p> - - <dt id=non-interactive>Non-interactive presentation user agents - - <dd> - <p>User agents that process HTML and XHTML documents purely to render - non-interactive versions of them must comply to the same conformance - criteria as Web browsers, except that they are exempt from requirements - regarding user interaction.</p> - - <p class=note>Typical examples of non-interactive presentation user - agents are printers (static UAs) and overhead displays (dynamic UAs). It - is expected that most static non-interactive presentation user agents - will also opt to <a href="#non-scripted">lack scripting support</a>.</p> - - <p class=example>A non-interactive but dynamic presentation UA would - still execute scripts, allowing forms to be dynamically submitted, and - so forth. However, since the concept of "focus" is irrelevant when the - user cannot interact with the document, the UA would not need to support - any of the focus-related DOM APIs.</p> - - <dt><dfn id=non-scripted>User agents with no scripting support</dfn> - - <dd> - <p>Implementations that do not support scripting (or which have their - scripting features <a href="#scripting1" title="scripting is - disabled">disabled</a>) are exempt from supporting the events and DOM - interfaces mentioned in this specification. For the parts of this - specification that are defined in terms of an events model or in terms - of the DOM, such user agents must still act as if events and the DOM - were supported.</p> - - <p class=note>Scripting can form an integral part of an application. Web - browsers that do not support scripting, or that have scripting disabled, - might be unable to fully convey the author's intent.</p> - - <dt>Conformance checkers - - <dd id=conformance-checkers> - <p>Conformance checkers must verify that a document conforms to the - applicable conformance criteria described in this specification. - Conformance checkers are exempt from detecting errors that require - interpretation of the author's intent (for example, while a document is - non-conforming if the content of a <code><a - href="#blockquote">blockquote</a></code> element is not a quote, - conformance checkers do not have to check that <code><a - href="#blockquote">blockquote</a></code> elements only contain quoted - material).</p> - - <p>Conformance checkers must check that the input document conforms when - <a href="#scripting1">scripting is disabled</a>, and should also check - that the input document conforms when <a href="#scripting2">scripting is - enabled</a>. (This is only a "SHOULD" and not a "MUST" requirement - because it has been proven to be impossible. <a - href="#refsHALTINGPROBLEM">[HALTINGPROBLEM]</a>)</p> - <!-- XXX - [Computable] On computable numbers, with an application to the - Entscheidungsproblem. Alan M. Turing. In Proceedings of the London - Mathematical Society, series 2, volume 42, pages 230-265. London - Mathematical Society, - 1937. http://www.turingarchive.org/browse.php/B/12 (referenced: - 2007-03-03) - --> - - <p>The term "HTML5 validator" can be used to refer to a conformance - checker that itself conforms to the applicable requirements of this - specification.</p> - - <div class=note> - <p>XML DTDs cannot express all the conformance requirements of this - specification. Therefore, a validating XML processor and a DTD cannot - constitute a conformance checker. Also, since neither of the two - authoring formats defined in this specification are applications of - SGML, a validating SGML system cannot constitute a conformance checker - either.</p> - - <p>To put it another way, there are three types of conformance criteria:</p> - - <ol> - <li>Criteria that can be expressed in a DTD. - - <li>Criteria that cannot be expressed by a DTD, but can still be - checked by a machine. - - <li>Criteria that can only be checked by a human. - </ol> - - <p>A conformance checker must check for the first two. A simple - DTD-based validator only checks for the first class of errors and is - therefore not a conforming conformance checker according to this - specification.</p> - </div> - - <dt>Data mining tools - - <dd id=data-mining> - <p>Applications and tools that process HTML and XHTML documents for - reasons other than to either render the documents or check them for - conformance should act in accordance to the semantics of the documents - that they process.</p> - - <p class=example>A tool that generates <span title="sections and - headings">document outlines</span> but increases the nesting level for - each paragraph and does not increase the nesting level for each section - would not be conforming.</p> - - <dt id=editors>Authoring tools and markup generators - - <dd> - <p>Authoring tools and markup generators must generate conforming - documents. Conformance criteria that apply to authors also apply to - authoring tools, where appropriate.</p> - - <p>Authoring tools are exempt from the strict requirements of using - elements only for their specified purpose, but only to the extent that - authoring tools are not yet able to determine author intent.</p> - - <p class=example>For example, it is not conforming to use an <code><a - href="#address">address</a></code> element for arbitrary contact - information; that element can only be used for marking up contact - information for the author of the document or section. However, since an - authoring tools is likely unable to determine the difference, an - authoring tool is exempt from that requirement.</p> - - <p class=note>In terms of conformance checking, an editor is therefore - required to output documents that conform to the same extent that a - conformance checker will verify.</p> - - <p>When an authoring tool is used to edit a non-conforming document, it - may preserve the conformance errors in sections of the document that - were not edited during the editing session (i.e. an editing tool is - allowed to round-trip errorneous content). However, an authoring tool - must not claim that the output is conformant if errors have been so - preserved.</p> - - <p>Authoring tools are expected to come in two broad varieties: tools - that work from structure or semantic data, and tools that work on a - What-You-See-Is-What-You-Get media-specific editing basis (WYSIWYG).</p> - - <p>The former is the preferred mechanism for tools that author HTML, - since the structure in the source information can be used to make - informed choices regarding which HTML elements and attributes are most - appropriate.</p> - - <p>However, WYSIWYG tools are legitimate, and this specification <a - href="#wysiwyg1" title="WYSIWYG editors">makes certain concessions to - WYSIWYG editors</a>.</p> - - <p>All authoring tools, whether WYSIWYG or not, should make a best effort - attempt at enabling users to create well-structured, semantically rich, - media-independent content.</p> - </dl> - - <p>Some conformance requirements are phrased as requirements on elements, - attributes, methods or objects. Such requirements fall into two - categories; those describing content model restrictions, and those - describing implementation behaviour. The former category of requirements - are requirements on documents and authoring tools. The second category are - requirements on user agents. - - <p>Conformance requirements phrased as algorithms or specific steps may be - implemented in any manner, so long as the end result is equivalent. (In - particular, the algorithms defined in this specification are intended to - be easy to follow, and not intended to be performant.) - - <p id=hardwareLimitations>User agents may impose implementation-specific - limits on otherwise unconstrained inputs, e.g. to prevent denial of - service attacks, to guard against running out of memory, or to work around - platform-specific limitations. - - <p>For compatibility with existing content and prior specifications, this - specification describes two authoring formats: one based on XML (referred - to as <dfn id=xhtml5 title=XHTML>XHTML5</dfn>), and one using a <a - href="#parsing">custom format</a> inspired by SGML (referred to as <dfn - id=html5>HTML5</dfn>). Implementations may support only one of these two - formats, although supporting both is encouraged. - - <p id=authors-using-xhtml><a href="#xhtml5">XHTML</a> documents (<a - href="#xml-documents">XML documents</a> using elements from the <a - href="#html-namespace0">HTML namespace</a>) that use the new features - described in this specification and that are served over the wire (e.g. by - HTTP) must be sent using an XML MIME type such as - <code>application/xml</code> or <code>application/xhtml+xml</code> and - must not be served as <code>text/html</code>. <a - href="#refsRFC3023">[RFC3023]</a> - - <p>Such XML documents may contain a <code>DOCTYPE</code> if desired, but - this is not required to conform to this specification. - - <p class=note>According to the XML specification, XML processors are not - guaranteed to process the external DTD subset referenced in the DOCTYPE. - This means, for example, that using entities for characters in XHTML - documents is unsafe (except for &lt;, &gt;, &amp;, &quot; - and &apos;). For interoperability, authors are advised to avoid - optional features of XML. - - <p id=authors-using-html><a href="#html5" title=HTML5>HTML documents</a>, - if they are served over the wire (e.g. by HTTP) must be labelled with the - <code>text/html</code> MIME type.</p> - <!-- - XXX update RFC 2854 --> - - <p id=entity-references>The language in this specification assumes that the - user agent expands all entity references, and therefore does not include - entity reference nodes in the DOM. If user agents do include entity - reference nodes in the DOM, then user agents must handle them as if they - were fully expanded when implementing this specification. For example, if - a requirement talks about an element's child text nodes, then any text - nodes that are children of an entity reference that is a child of that - element would be used as well.</p> - <!-- XXX unexpandable entities? --> - - <h4 id=common><span class=secno>1.3.1. </span>Common conformance - requirements for APIs exposed to JavaScript</h4> - - <p class=big-issue>A lot of arrays/lists/<span>collection</span>s in this - spec assume zero-based indexes but use the term "<var - title="">index</var>th" liberally. We should define those to be zero-based - and be clearer about this. - - <p>Unless other specified, if a DOM attribute that is a floating point - number type (<code title="">float</code>) is assigned an Infinity or - Not-a-Number value, a <code title=big-issue>NOT_SUPPORTED_ERR</code> - exception must be raised. - - <p>Unless other specified, if a DOM attribute that is a signed numberic - type is assigned a negative value, a <code - title=big-issue>NOT_SUPPORTED_ERR</code> exception must be raised. - - <p>Unless other specified, if a method with an argument that is a floating - point number type (<code title="">float</code>) is passed an Infinity or - Not-a-Number value, a <code title=big-issue>NOT_SUPPORTED_ERR</code> - exception must be raised. - - <p>Unless other specified, if a method is passed fewer arguments than is - defined for that method in its IDL definition, a <code - title=big-issue>NOT_SUPPORTED_ERR</code> exception must be raised. - - <p>Unless other specified, if a method is passed more arguments than is - defined for that method in its IDL definition, the excess arguments must - be ignored. - - <p>Unless other specified, if a method is expecting, as one of its - arguments, as defined by its IDL definition, an object implementing a - particular interface <var title="">X</var>, and the argument passed is an - object whose [[Class]] property is neither that interface <var - title="">X</var>, nor the name of an interface <var title="">Y</var> where - this specification requires that all objects implementing interface <var - title="">Y</var> also implement interface <var title="">X</var>, nor the - name of an interface that inherits from the expected interface <var - title="">X</var>, then a <code title="">TYPE_MISMATCH_ERR</code> exception - must be raised. - - <p class=big-issue>Anything else? Passing the wrong type of object, maybe? - Implied conversions to int/float? - - <h4 id=dependencies><span class=secno>1.3.2. </span>Dependencies</h4> - - <p>This specification relies on several other underlying specifications. - - <dl> - <dt>XML - - <dd> - <p>Implementations that support XHTML5 must support some version of XML, - as well as its corresponding namespaces specification, because XHTML5 - uses an XML serialisation with namespaces. <a href="#refsXML">[XML]</a> - <a href="#refsXMLNAMES">[XMLNAMES]</a></p> - - <dt>XML Base - - <dd> - <p id=xmlBase>User agents must follow the rules given by XML Base to - resolve relative URIs in HTML and XHTML fragments. That is the mechanism - used in this specification for resolving relative URIs in DOM trees. <a - href="#refsXMLBASE">[XMLBASE]</a></p> - - <p class=note>It is possible for <code - title=attr-xml-base>xml:base</code> attributes to be present even in - HTML fragments, as such attributes can be added dynamically using - script.</p> - - <dt>DOM - - <dd> - <p>Implementations must support some version of DOM Core and DOM Events, - because this specification is defined in terms of the DOM, and some of - the features are defined as extensions to the DOM Core interfaces. <a - href="#refsDOM3CORE">[DOM3CORE]</a> <a - href="#refsDOM3CORE">[DOM3EVENTS]</a></p> - - <dt>ECMAScript - - <dd> - <p>Implementations that use ECMAScript to implement the APIs defined in - this specification must implement them in a manner consistent with the - ECMAScript Bindings for DOM Specifications specification, as this - specification uses that specification's terminology. <a - href="#refsEBFD">[EBFD]</a></p> - </dl> - - <p>This specification does not require support of any particular network - transport protocols, image formats, audio formats, video formats, style - sheet language, scripting language, or any of the DOM and WebAPI - specifications beyond those described above. However, the language - described by this specification is biased towards CSS as the styling - language, ECMAScript as the scripting language, and HTTP as the network - protocol, and several features assume that those languages and protocols - are in use. - - <h4 id=features><span class=secno>1.3.3. </span>Features defined in other - specifications</h4> - - <p>Some elements are defined in terms of their DOM <dfn - id=textcontent><code>textContent</code></dfn> attribute. This is an - attribute defined on the <code>Node</code> interface in DOM3 Core. <a - href="#refsDOM3CORE">[DOM3CORE]</a> - - <p class=big-issue>Should textContent be defined differently for dir="" and - <bdo>? Should we come up with an alternative to textContent that - handles those and other things, like alt=""?</p> - <!-- This section is currently here exclusively so that we crossref - to textContent. XXX also add event-click, event-change, - event-DOMActivate, etc, here, and just have the section be a general - "defined in other specifications" section --> - - <p>The term <dfn id=activation0>activation behavior</dfn> is used as - defined in the DOM3 Events specification. <a - href="#refsDOM3EVENTS">[DOM3EVENTS]</a> <span class=big-issue>At the time - of writing, DOM3 Events hadn't yet been updated to define that - phrase.</span> - - <p id=alternate-style-sheets>The rules for handling alternative style - sheets are defined in the CSS object model specification. <a - href="#CSSOM">[CSSOM]</a> - - <p class=big-issue>See <a - href="http://dev.w3.org/cvsweb/~checkout~/csswg/cssom/Overview.html?rev=1.35&content-type=text/html;%20charset=utf-8">http://dev.w3.org/cvsweb/~checkout~/csswg/cssom/Overview.html?rev=1.35&content-type=text/html;%20charset=utf-8</a> - - <p>Certain features are defined in terms of CSS <color> values. When - the CSS value <code title="">currentColor</code> is specified in this - context, the "computed value of the 'color' property" for the purposes of - determining the computed value of the <code title="">currentColor</code> - keyword is the computed value of the 'color' property on the element in - question. <a href="#refsCSS3COLOR">[CSS3COLOR]</a> - - <p class=example>If a canvas gradient's <code - title=dom-canvasgradient-addColorStop><a - href="#addcolorstop">addColorStop()</a></code> method is called with the - <code title="">currentColor</code> keyword as the color, then the computed - value of the 'color' property on the <code><a - href="#canvas">canvas</a></code> element is the one that is used. - - <h3 id=terminology><span class=secno>1.4. </span>Terminology</h3> - - <p>This specification refers to both HTML and XML attributes and DOM - attributes, often in the same context. When it is not clear which is being - referred to, they are referred to as <dfn id=content>content - attributes</dfn> for HTML and XML attributes, and <dfn - id=dom-attributes>DOM attributes</dfn> for those from the DOM. Similarly, - the term "properties" is used for both ECMAScript object properties and - CSS properties. When these are ambiguous they are qualified as object - properties and CSS properties respectively. - - <p id=html-namespace>To ease migration from HTML to XHTML, UAs conforming - to this specification will place elements in HTML in the - <code>http://www.w3.org/1999/xhtml</code> namespace, at least for the - purposes of the DOM and CSS. The term "<dfn id=elements1>elements in the - HTML namespace</dfn>", or "<dfn id=html-elements>HTML elements</dfn>" for - short, when used in this specification, thus refers to both HTML and XHTML - elements. - - <p>Unless otherwise stated, all elements defined or mentioned in this - specification are in the <code>http://www.w3.org/1999/xhtml</code> - namespace, and all attributes defined or mentioned in this specification - have no namespace (they are in the per-element partition). - - <p>The term <a href="#html-">HTML documents</a> is sometimes used in - contrast with <a href="#xml-documents">XML documents</a> to mean - specifically documents that were parsed using an <a href="#html-0">HTML - parser</a> (as opposed to using an XML parser or created purely through - the DOM). - - <p>Generally, when the specification states that a feature applies to HTML - or XHTML, it also includes the other. When a feature specifically only - applies to one of the two languages, it is called out by explicitly - stating that it does not apply to the other format, as in "for HTML, ... - (this does not apply to XHTML)". - - <p>This specification uses the term <em>document</em> to refer to any use - of HTML, ranging from short static documents to long essays or reports - with rich multimedia, as well as to fully-fledged interactive - applications. - - <p>For readability, the term URI is used to refer to both ASCII URIs and - Unicode IRIs, as those terms are defined by <a - href="#refsRFC3986">[RFC3986]</a> and <a href="#refsRFC3987">[RFC3987]</a> - respectively. On the rare occasions where IRIs are not allowed but ASCII - URIs are, this is called out explicitly. - - <p>The term <dfn id=root-element>root element</dfn>, when not qualified to - explicitly refer to the document's root element, means the furthest - ancestor element node of whatever node is being discussed, or the node - itself is there is none. When the node is a part of the document, then - that is indeed the document's root element. However, if the node is not - currently part of the document tree, the root element will be an orphaned - node. - - <p>An element is said to have been <dfn id=inserted title="insert an - element into a document">inserted into a document</dfn> when its <a - href="#root-element">root element</a> changes and is now the document's <a - href="#root-element">root element</a>. - - <p>The term <dfn id=tree-order>tree order</dfn> means a pre-order, - depth-first traversal of DOM nodes involved (through the <code - title="">parentNode</code>/<code title="">childNodes</code> relationship). - - <p>When it is stated that some element or attribute is <dfn id=ignored - title=ignore>ignored</dfn>, or treated as some other value, or handled as - if it was something else, this refers only to the processing of the node - after it is in the DOM. A user agent must not mutate the DOM in such - situations. - - <p>When an XML name, such as an attribute or element name, is referred to - in the form <code><var title="">prefix</var>:<var - title="">localName</var></code>, as in <code>xml:id</code> or - <code>svg:rect</code>, it refers to a name with the local name <var - title="">localName</var> and the namespace given by the prefix, as defined - by the following table: - - <dl> - <dt><code title="">xml</code> - - <dd><code>http://www.w3.org/XML/1998/namespace</code> - - <dt><code title="">html</code> - - <dd><code>http://www.w3.org/1999/xhtml</code> - - <dt><code title="">svg</code> - - <dd><code>http://www.w3.org/2000/svg</code> - </dl> - - <p>For simplicity, terms such as <em>shown</em>, <em>displayed</em>, and - <em>visible</em> might sometimes be used when referring to the way a - document is rendered to the user. These terms are not meant to imply a - visual medium; they must be considered to apply to other media in - equivalent ways. - - <p>Various DOM interfaces are defined in this specification using - pseudo-IDL. This looks like OMG IDL but isn't. For instance, method - overloading is used, and types from the W3C DOM specifications are used - without qualification. Language-specific bindings for these abstract - interface definitions must be derived in the way consistent with W3C DOM - specifications. Some interface-specific binding information for ECMAScript - is included in this specification. - - <p class=big-issue>The current situation with IDL blocks is pitiful. IDL is - totally inadequate to properly represent what objects have to look like in - JS; IDL can't say if a member is enumerable, what the indexing behaviour - is, what the stringification behaviour is, what behaviour setting a member - whose type is a particular interface should be (e.g. setting of - document.location or element.className), what constructor an object - implementing an interface should claim to have, how overloads work, etc. I - think we should make the IDL blocks non-normative, and/or replace them - with something else that is better for JS while still being clear on how - it applies to other languages. However, we do need to have something that - says what types the methods take as arguments, since we have to raise - exceptions if they are wrong. - - <p>The construction "a <code>Foo</code> object", where <code>Foo</code> is - actually an interface, is sometimes used instead of the more accurate "an - object implementing the interface <code>Foo</code>". - - <p>A DOM attribute is said to be <em>getting</em> when its value is being - retrieved (e.g. by author script), and is said to be <em>setting</em> when - a new value is assigned to it. - - <p>If a DOM object is said to be <dfn id=live>live</dfn>, then that means - that any attributes returning that object must always return the same - object (not a new object each time), and the attributes and methods on - that object must operate on the actual underlying data, not a snapshot of - the data.</p> - <!-- XXX should define "same instance of" to mean JS===. --> - - <p>The terms <em>fire</em> and <em>dispatch</em> are used interchangeably - in the context of events, as in the DOM Events specifications. <a - href="#refsDOM3EVENTS">[DOM3EVENTS]</a> - - <p>The term <dfn id=text-node>text node</dfn> refers to any - <code>Text</code> node, including <code>CDATASection</code> nodes (any - <code>Node</code> with node type 3 or 4). - - <p>Some of the algorithms in this specification, for historical reasons, - require the user agent to <dfn id=pause>pause</dfn> until some condition - has been met. While a user agent is paused, it must ensure that no scripts - execute (e.g. no event handlers, no timers, etc). User agents should - remain responsive to user input while paused, however. - - <h4 id=html-vs><span class=secno>1.4.1. </span>HTML vs XHTML</h4> - - <p><em>This section is non-normative.</em> - - <p>This specification defines an abstract language for describing documents - and applications, and some APIs for interacting with in-memory - representations of resources that use this language. - - <p>The in-memory representation is known as "DOM5 HTML", or "the DOM" for - short. - - <p>There are various concrete syntaxes that can be used to transmit - resources that use this abstract language, two of which are defined in - this specification. - - <p>The first such concrete syntax is "HTML5". This is the format - recommended for most authors. It is compatible with all legacy Web - browsers. If a document is transmitted with the MIME type <code - title="">text/html</code>, then it will be processed as an "HTML5" - document by Web browsers. - - <p>The second concrete syntax uses XML, and is known as "XHTML5". When a - document is transmitted with an XML MIME type, such as <code - title="">application/xhtml+xml</code>, then it is processed by an XML - processor by Web browsers, and treated as an "XHTML5" document. Generally - speaking, authors are discouraged from trying to use XML on the Web, - because XML has much stricter syntax rules than the "HTML5" variant - described above, and is relatively newer and therefore less mature. - - <p>The "DOM5 HTML", "HTML5", and "XHTML5" representations cannot all - represent the same content. For example, namespaces cannot be represented - using "HTML5", but they are supported in "DOM5 HTML" and "XHTML5". - Similarly, documents that use the <code><a - href="#noscript">noscript</a></code> feature can be represented using - "HTML5", but cannot be represented with "XHTML5" and "DOM5 HTML". Comments - that contain the string "<code title="">--></code>" can be represented - in "DOM5 HTML" but not in "HTML5" and "XHTML5". And so forth. - - <h2 id=dom><span class=secno>2. </span>The Document Object Model</h2> - - <p>The Document Object Model (DOM) is a representation — a model - — of a document and its content. <a - href="#refsDOM3CORE">[DOM3CORE]</a> The DOM is not just an API; the - conformance criteria of HTML implementations are defined, in this - specification, in terms of operations on the DOM. - - <p>This specification defines the language represented in the DOM by - features together called DOM5 HTML. DOM5 HTML consists of DOM Core - <code>Document</code> nodes and DOM Core <code>Element</code> nodes, along - with text nodes and other content. - - <p>Elements in the DOM represent things; that is, they have intrinsic - <em>meaning</em>, also known as semantics. - - <p class=example>For example, a <code><a href="#p">p</a></code> element - represents a paragraph. - - <p>In addition, documents and elements in the DOM host APIs that extend the - DOM Core APIs, providing new features to application developers using DOM5 - HTML. - - <h3 id=documents><span class=secno>2.1. </span>Documents</h3> - - <p>Every XML and HTML document in an HTML UA is represented by a - <code>Document</code> object. <a href="#refsDOM3CORE">[DOM3CORE]</a> - - <p><code>Document</code> objects are assumed to be <dfn - id=xml-documents>XML documents</dfn> unless they are flagged as being <dfn - id=html->HTML documents</dfn> when they are created. Whether a document is - an <a href="#html-" title="HTML documents">HTML document</a> or an <a - href="#xml-documents" title="XML documents">XML document</a> affects the - behaviour of certain APIs, as well as a few CSS rendering rules. <a - href="#refsCSS21">[CSS21]</a> - - <p class=note>A <code>Document</code> object created by the <code - title="">createDocument()</code> API on the <code>DOMImplementation</code> - object is initially an <a href="#xml-documents" title="XML documents">XML - document</a>, but can be made into an <a href="#html-" title="HTML - documents">HTML document</a> by calling <code title=dom-document-open><a - href="#open">document.open()</a></code> on it. - - <p>All <code>Document</code> objects (in user agents implementing this - specification) must also implement the <code><a - href="#htmldocument">HTMLDocument</a></code> interface, available using - binding-specific methods. (This is the case whether or not the document in - question is an <a href="#html-" title="HTML documents">HTML document</a> - or indeed whether it contains any <a href="#html-elements">HTML - elements</a> at all.) <code>Document</code> objects must also implement - the document-level interface of any other namespaces found in the document - that the UA supports. For example, if an HTML implementation also supports - SVG, then the <code>Document</code> object must implement <code><a - href="#htmldocument">HTMLDocument</a></code> and <code>SVGDocument</code>. - - <p class=note>Because the <code><a - href="#htmldocument">HTMLDocument</a></code> interface is now obtained - using binding-specific casting methods instead of simply being the primary - interface of the document object, it is no longer defined as inheriting - from <code>Document</code>. - - <pre class=idl>interface <dfn id=htmldocument>HTMLDocument</dfn> { - // <a href="#resource0">Resource metadata management</a> - readonly attribute <a href="#location2">Location</a> <a href="#location0" title=dom-document-location>location</a>; - readonly attribute DOMString <a href="#url" title=dom-document-URL>URL</a>; - attribute DOMString <a href="#domain" title=dom-document-domain>domain</a>; - readonly attribute DOMString <a href="#referrer" title=dom-document-referrer>referrer</a>; - attribute DOMString <a href="#cookie0" title=dom-document-cookie>cookie</a>; - readonly attribute DOMString <a href="#lastmodified" title=dom-document-lastModified>lastModified</a>; - - // <a href="#dom-tree0">DOM tree accessors</a> - attribute DOMString <a href="#document.title" title=dom-document-title>title</a>; - attribute DOMString <a href="#dir1" title=dom-document-dir>dir</a>; - attribute <a href="#htmlelement">HTMLElement</a> <a href="#body" title=dom-document-body>body</a>; - readonly attribute <a href="#htmlcollection0">HTMLCollection</a> <a href="#images0" title=dom-document-images>images</a>; -<!-- readonly attribute <span>HTMLCollection</span> <span title="dom-document-applets">applets</span>; ---> readonly attribute <a href="#htmlcollection0">HTMLCollection</a> <a href="#links0" title=dom-document-links>links</a>; - readonly attribute <a href="#htmlcollection0">HTMLCollection</a> <a href="#forms0" title=dom-document-forms>forms</a>; - readonly attribute <a href="#htmlcollection0">HTMLCollection</a> <a href="#anchors" title=dom-document-anchors>anchors</a>; - NodeList <a href="#getelementsbyname" title=dom-document-getElementsByName>getElementsByName</a>(in DOMString elementName); - NodeList <a href="#getelementsbyclassname" title=dom-document-getElementsByClassName>getElementsByClassName</a>(in DOMString[] classNames); - - // <a href="#dynamic2">Dynamic markup insertion</a> - attribute DOMString <a href="#innerhtml" title=dom-innerHTML>innerHTML</a>; - void <a href="#open" title=dom-document-open>open</a>(); - void <a href="#open" title=dom-document-open>open</a>(in DOMString type); - void <a href="#open" title=dom-document-open>open</a>(in DOMString type, in DOMString replace); - void <a href="#open" title=dom-document-open>open</a>(in DOMString url, in DOMString name, in DOMString features); - void <a href="#open" title=dom-document-open>open</a>(in DOMString url, in DOMString name, in DOMString features, in bool replace); - void <a href="#close" title=dom-document-close>close</a>(); - void <a href="#document.write" title=dom-document-write>write</a>(in DOMString text); - void <a href="#document.writeln" title=dom-document-writeln>writeln</a>(in DOMString text); - - // <a href="#interaction0">Interaction</a> - readonly attribute <span>Element</span> <a href="#activeelement" title=dom-document-activeElement>activeElement</a>; - readonly attribute boolean <a href="#hasfocus" title=dom-document-hasFocus>hasFocus</a>; - - // <a href="#command1" title=concept-command>Commands</a> - readonly attribute <a href="#htmlcollection0">HTMLCollection</a> <a href="#commands0" title=dom-document-commands>commands</a>; - - // <a href="#editing0">Editing</a> - attribute boolean <a href="#designMode" title=dom-document-designMode>designMode</a>; - boolean <a href="#execCommand" title=dom-document-execCommand>execCommand</a>(in DOMString commandId); - boolean <a href="#execCommand" title=dom-document-execCommand>execCommand</a>(in DOMString commandId, in boolean doShowUI); - boolean <a href="#execCommand" title=dom-document-execCommand>execCommand</a>(in DOMString commandId, in boolean doShowUI, in DOMString value); - <a href="#selection1">Selection</a> <a href="#getselection0" title=dom-document-getSelection>getSelection</a>(); - - // <a href="#cross-document">Cross-document messaging</a> - void <a href="#postmessage" title=dom-document-postMessage>postMessage</a>(in DOMString message); -<!-- XXX we're not done here. - XXX see e.g. http://lxr.mozilla.org/seamonkey/source/dom/public/idl/html/nsIDOMNSHTMLDocument.idl - XXX see e.g. http://trac.webkit.org/projects/webkit/browser/trunk/WebCore/dom/Document.cpp - XXX see e.g. http://trac.webkit.org/projects/webkit/browser/trunk/WebCore/html/HTMLDocument.cpp - --> -};</pre> - - <p>Since the <code><a href="#htmldocument">HTMLDocument</a></code> - interface holds methods and attributes related to a number of disparate - features, the members of this interface are described in various different - sections. - - <h4 id=security><span class=secno>2.1.1. </span>Security</h4> - - <p>User agents must raise a <a href="#security8">security exception</a> - whenever any of the members of an <code><a - href="#htmldocument">HTMLDocument</a></code> object are accessed by - scripts whose <a href="#origin0">origin</a> is not the same as the - <code>Document</code>'s origin, with the following exceptions: - - <ul> - <li>The <code title=dom-document-postMessage><a - href="#postmessage">postMessage()</a></code> method must be allowed to be - called from any script. - </ul> - - <p class=big-issue>We may want to just put postMessage on Window instead of - Document, as that reduces the XSS risk. - - <h4 id=resource><span class=secno>2.1.2. </span><dfn id=resource0>Resource - metadata management</dfn></h4> - - <p>The <dfn id=url title=dom-document-URL><code>URL</code></dfn> attribute - must return <span>the document's address</span><!-- XXX - xref -->. - - <p>The <dfn id=domain title=dom-document-domain><code>domain</code></dfn> - attribute must be initialised to <span>the document's domain</span>, if it - has one, and null otherwise. On getting, the attribute must return its - current value. On setting, if the new value is an allowed value (as - defined below), the attribute's value must be changed to the new value. If - the new value is not an allowed value, then a <a - href="#security8">security exception</a> must be raised instead. - - <p>A new value is an allowed value for the <code - title=dom-document-domain><a href="#domain">document.domain</a></code> - attribute if it is equal to the attribute's current value, or if the new - value, prefixed by a U+002E FULL STOP ("."), exactly matches the end of - the current value. If the current value is null, new values other than - null will never be allowed. - - <p>If the <code>Document</code> object's <span title="the document's - address">address</span><!-- XXX xref --> is hierarchical and uses a - server-based naming authority, then its <dfn id=domain0 title="document's - domain">domain</dfn> is the <hostname> part of that address. - Otherwise, it has no domain. - - <p class=note>The <code title=dom-document-domain><a - href="#domain">domain</a></code> attribute is used to enable pages on - different hosts of a domain to access each others' DOMs<span - class=big-issue>, though this is not yet defined by this - specification</span>.</p> - <!-- XXX xref --> - <!--XXX - http://lxr.mozilla.org/seamonkey/source/content/html/document/src/nsHTMLDocument.cpp - search for ::GetDomain ::SetDomain - http://trac.webkit.org/projects/webkit/browser/trunk/WebCore/dom/Document.cpp - search for ::domain ::setDomain - --> - - <p>The <dfn id=referrer - title=dom-document-referrer><code>referrer</code></dfn> attribute must - return either the URI of the page which <a href="#navigate" - title=navigate>navigated</a> the <a href="#browsing0">browsing context</a> - to the current document (if any), or the empty string (if there is no such - originating page, or if the UA has been configured not to report - referrers). - - <p class=note>In the case of HTTP, the <code title=dom-document-referrer><a - href="#referrer">referrer</a></code> DOM attribute will match the - <code>Referer</code> (sic) header that was sent when fetching the current - page. - - <p>The <dfn id=cookie0 title=dom-document-cookie><code>cookie</code></dfn> - attribute must, on getting, return the same string as the value of the - <code title="">Cookie</code> HTTP header it would include if fetching the - resource indicated by <span>the document's address</span> over HTTP, as - per RFC 2109 section 4.3.4. <a href="#refsRFC2109">[RFC2109]</a> - - <p>On setting, the <code title=dom-document-cookie><a - href="#cookie0">cookie</a></code> attribute must cause the user agent to - act as it would when processing cookies if it had just attempted to fetch - <span>the document's address</span> over HTTP, and had received a response - with a <code>Set-Cookie</code> header whose value was the specified value, - as per RFC 2109 sections 4.3.1, 4.3.2, and 4.3.3. <a - href="#refsRFC2109">[RFC2109]</a> - - <p class=note>Since the <code title=dom-document-cookie><a - href="#cookie0">cookie</a></code> attribute is accessible across frames, - the path restrictions on cookies are only a tool to help manage which - cookies are sent to which parts of the site, and are not in any way a - security feature. - - <p>The <dfn id=lastmodified - title=dom-document-lastModified><code>lastModified</code></dfn> attribute, - on getting, must return the date and time of the <code>Document</code>'s - source file's last modification, in the user's local timezone, in the - following format: - - <ol> - <li> The month component of the date. - - <li> A U+002F SOLIDUS character ('/'). - - <li> The day component of the date. - - <li> A U+002F SOLIDUS character ('/'). - - <li> The last two digits of the year component of the date. - - <li> A U+0020 SPACE character. - - <li> The hours component of the time. - - <li> A U+003A COLON character (':'). - - <li> The minutes component of the time. - - <li> A U+003A COLON character (':'). - - <li> The seconds component of the time. - </ol> - - <p>All the numeric components above must be given as two digits in the - range U+0030 DIGIT ZERO to U+0039 DIGIT NINE representing the number in - base ten, zero-padded if necessary. - - <p>The <code>Document</code>'s source file's last modification date and - time must be derived from relevant features of the networking protocols - used, e.g. from the value of the HTTP <code title="">Last-Modified</code> - header of the document, or from metadata in the filesystem for local - files. If the last modification date and time are not known, the attribute - must return the string <code title="">01/01/1970 00:00:00</code>. - - <h3 id=elements><span class=secno>2.2. </span>Elements</h3> - - <p>The nodes representing <a href="#html-elements">HTML elements</a> in the - DOM must implement, and expose to scripts, the interfaces listed for them - in the relevant sections of this specification. This includes <a - href="#xhtml5">XHTML</a> elements in <a href="#xml-documents">XML - documents</a>, even when those documents are in another context (e.g. - inside an XSLT transform). - - <p>The basic interface, from which all the <a href="#html-elements">HTML - elements</a>' interfaces inherit, and which must be used by elements that - have no additional requirements, is the <code><a - href="#htmlelement">HTMLElement</a></code> interface. - - <pre - class=idl>interface <dfn id=htmlelement>HTMLElement</dfn> : <span>Element</span> { - // <a href="#dom-tree0">DOM tree accessors</a> - NodeList <a href="#getelementsbyclassname0" title=dom-getElementsByClassName>getElementsByClassName</a>(in DOMString[] classNames); - - // <a href="#dynamic2">Dynamic markup insertion</a> - attribute DOMString <a href="#innerhtml" title=dom-innerHTML>innerHTML</a>; - - // <span>Metadata attributes</span> - attribute DOMString <a href="#id0" title=dom-id>id</a>; - attribute DOMString <a href="#title0" title=dom-title>title</a>; - attribute DOMString <a href="#lang0" title=dom-lang>lang</a>; - attribute DOMString <a href="#dir0" title=dom-dir>dir</a>; - attribute <span>DOMString</span> <a href="#classname" title=dom-className>className</a>; - readonly attribute <a href="#domtokenlist0">DOMTokenList</a> <a href="#classlist" title=dom-classList>classList</a>; - - // <a href="#interaction0">Interaction</a> - attribute boolean <a href="#irrelevant0" title=dom-irrelevant>irrelevant</a>; - attribute long <a href="#tabindex0" title=dom-tabindex>tabIndex</a>; - void <a href="#click" title=dom-click>click</a>(); - void <a href="#focus0" title=dom-focus>focus</a>(); - void <a href="#blur" title=dom-blur>blur</a>(); - void <a href="#scrollintoview" title=dom-scrollIntoView>scrollIntoView</a>(); - void <a href="#scrollintoview" title=dom-scrollIntoView>scrollIntoView</a>(in boolean top); - - // <a href="#command1" title=concept-command>Commands</a> - attribute <a href="#htmlmenuelement">HTMLMenuElement</a> <a href="#contextmenu0" title=dom-contextMenu>contextMenu</a>; - - // <a href="#editing0">Editing</a> - attribute boolean <a href="#draggable0" title=dom-draggable>draggable</a>; - attribute DOMString <a href="#contenteditable1" title=dom-contentEditable>contentEditable</a>; - - // <a href="#event3">event handler DOM attributes</a> - attribute <span>EventListener</span> <a href="#onabort" title=handler-onabort>onabort</a>; - attribute <span>EventListener</span> <a href="#onbeforeunload" title=handler-onbeforeunload>onbeforeunload</a>; - attribute <span>EventListener</span> <a href="#onblur" title=handler-onblur>onblur</a>; - attribute <span>EventListener</span> <a href="#onchange" title=handler-onchange>onchange</a>; - attribute <span>EventListener</span> <a href="#onclick" title=handler-onclick>onclick</a>; - attribute <span>EventListener</span> <a href="#oncontextmenu" title=handler-oncontextmenu>oncontextmenu</a>; - attribute <span>EventListener</span> <a href="#ondblclick" title=handler-ondblclick>ondblclick</a>; - attribute <span>EventListener</span> <a href="#ondrag" title=handler-ondrag>ondrag</a>; - attribute <span>EventListener</span> <a href="#ondragend" title=handler-ondragend>ondragend</a>; - attribute <span>EventListener</span> <a href="#ondragenter" title=handler-ondragenter>ondragenter</a>; - attribute <span>EventListener</span> <a href="#ondragleave" title=handler-ondragleave>ondragleave</a>; - attribute <span>EventListener</span> <a href="#ondragover" title=handler-ondragover>ondragover</a>; - attribute <span>EventListener</span> <a href="#ondragstart" title=handler-ondragstart>ondragstart</a>; - attribute <span>EventListener</span> <a href="#ondrop" title=handler-ondrop>ondrop</a>; - attribute <span>EventListener</span> <a href="#onerror" title=handler-onerror>onerror</a>; - attribute <span>EventListener</span> <a href="#onfocus" title=handler-onfocus>onfocus</a>; - attribute <span>EventListener</span> <a href="#onkeydown" title=handler-onkeydown>onkeydown</a>; - attribute <span>EventListener</span> <a href="#onkeypress" title=handler-onkeypress>onkeypress</a>; - attribute <span>EventListener</span> <a href="#onkeyup" title=handler-onkeyup>onkeyup</a>; - attribute <span>EventListener</span> <a href="#onload" title=handler-onload>onload</a>; - attribute <span>EventListener</span> <a href="#onmessage" title=handler-onmessage>onmessage</a>; - attribute <span>EventListener</span> <a href="#onmousedown" title=handler-onmousedown>onmousedown</a>; - attribute <span>EventListener</span> <a href="#onmousemove" title=handler-onmousemove>onmousemove</a>; - attribute <span>EventListener</span> <a href="#onmouseout" title=handler-onmouseout>onmouseout</a>; - attribute <span>EventListener</span> <a href="#onmouseover" title=handler-onmouseover>onmouseover</a>; - attribute <span>EventListener</span> <a href="#onmouseup" title=handler-onmouseup>onmouseup</a>; - attribute <span>EventListener</span> <a href="#onmousewheel" title=handler-onmousewheel>onmousewheel</a>; - attribute <span>EventListener</span> <a href="#onresize" title=handler-onresize>onresize</a>; - attribute <span>EventListener</span> <a href="#onscroll" title=handler-onscroll>onscroll</a>; - attribute <span>EventListener</span> <a href="#onselect" title=handler-onselect>onselect</a>; - attribute <span>EventListener</span> <a href="#onsubmit" title=handler-onsubmit>onsubmit</a>; - attribute <span>EventListener</span> <a href="#onunload" title=handler-onunload>onunload</a>; - -};</pre> - - <p>As with the <code><a href="#htmldocument">HTMLDocument</a></code> - interface, the <code><a href="#htmlelement">HTMLElement</a></code> - interface holds methods and attributes related to a number of disparate - features, and the members of this interface are therefore described in - various different sections of this specification. - - <h4 id=reflecting><span class=secno>2.2.1. </span>Reflecting content - attributes in DOM attributes</h4> - - <p>Some <span title="DOM attribute">DOM attributes</span> are defined to - <dfn id=reflect>reflect</dfn> a particular <span>content attribute</span>. - This means that on getting, the DOM attribute returns the current value of - the content attribute, and on setting, the DOM attribute changes the value - of the content attribute to the given value. - - <p>If a reflecting DOM attribute is a <code>DOMString</code> attribute - whose content attribute is defined to contain a URI, then on getting, the - DOM attribute must return the value of the content attribute, resolved to - an absolute URI, and on setting, must set the content attribute to the - specified literal value. If the content attribute is absent, the DOM - attribute must return the default value, if the content attribute has one, - or else the empty string. - - <p>If a reflecting DOM attribute is a <code>DOMString</code> whose content - attribute is an <a href="#enumerated">enumerated attribute</a>, and the - DOM attribute is <dfn id=limited>limited to only known values</dfn>, then, - on getting, the DOM attribute must return the value associated with the - state the attribute is in (in its canonical case), or the empty string if - the attribute is in a state that has no associated keyword value; and on - setting, if the new value case-insensitively matches one of the keywords - given for that attribute, then the content attribute must be set to that - value, otherwise, if the new value is the empty string, then the content - attribute must be removed, otherwise, the setter must raise a - <code>SYNTAX_ERR</code> exception. - - <p>If a reflecting DOM attribute is a <code>DOMString</code> but doesn't - fall into any of the above categories, then the getting and setting must - be done in a transparent, case-preserving manner. - - <p>If a reflecting DOM attribute is a boolean attribute, then the DOM - attribute must return true if the attribute is set, and false if it is - absent. On setting, the content attribute must be removed if the DOM - attribute is set to false, and must be set to have the same value as its - name if the DOM attribute is set to true. (This corresponds to the rules - for <a href="#boolean0" title="boolean attribute">boolean content - attributes</a>.) - - <p>If a reflecting DOM attribute is a signed integer type - (<code>long</code>) then the content attribute must be parsed according to - <a href="#rules0" title="rules for parsing integers">the rules for parsing - signed integers</a> first. If that fails, or if the attribute is absent, - the default value must be returned instead, or 0 if there is no default - value. On setting, the given value must be converted to a string - representing the number as a <a href="#valid0">valid integer</a> in base - ten and then that string must be used as the new content attribute value. - - <p>If a reflecting DOM attribute is an <em>unsigned</em> integer type - (<code>unsigned long</code>) then the content attribute must be parsed - according to <a href="#rules" title="rules for parsing non-negative - integers">the rules for parsing unsigned integers</a> first. If that - fails, or if the attribute is absent, the default value must be returned - instead, or 0 if there is no default value. On setting, the given value - must be converted to a string representing the number as a <a - href="#valid">valid non-negative integer</a> in base ten and then that - string must be used as the new content attribute value. - - <p>If a reflecting DOM attribute is an unsigned integer type - (<code>unsigned long</code>) that is <dfn id=limited0>limited to only - positive non-zero numbers</dfn>, then the behavior is similar to the - previous case, but zero is not allowed. On getting, the content attribute - must first be parsed according to <a href="#rules" title="rules for - parsing non-negative integers">the rules for parsing unsigned - integers</a>, and if that fails, or if the attribute is absent, the - default value must be returned instead, or 1 if there is no default value. - On setting, if the value is zero, the user agent must fire an - <code>INDEX_SIZE_ERR</code> exception. Otherwise, the given value must be - converted to a string representing the number as a <a href="#valid">valid - non-negative integer</a> in base ten and then that string must be used as - the new content attribute value. - - <p>If a reflecting DOM attribute is a floating point number type - (<code>float</code>) and the content attribute is defined to contain a - time offset, then the content attribute must be parsed according to <a - href="#rules4" title="rules for parsing time offsets">the rules for - parsing time ofsets</a> first. If that fails, or if the attribute is - absent, the default value must be returned instead, or the not-a-number - value (NaN) if there is no default value. On setting, the given value must - be converted to a string using the <a href="#time-offset">time offset - serialisation rules</a>, and that string must be used as the new content - attribute value. - - <p>If a reflecting DOM attribute is of the type <code><a - href="#domtokenlist0">DOMTokenList</a></code>, then on getting it must - return a <code><a href="#domtokenlist0">DOMTokenList</a></code> object - whose underlying string is the element's corresponding content attribute. - When the <code><a href="#domtokenlist0">DOMTokenList</a></code> object - mutates its underlying string, the attribute must itself be immediately - mutated. When the attribute is absent, then the string represented by the - <code><a href="#domtokenlist0">DOMTokenList</a></code> object is the empty - string; when the object mutates this empty string, the user agent must - first add the corresponding content attribute, and then mutate that - attribute instead. <code><a href="#domtokenlist0">DOMTokenList</a></code> - attributes are always read-only. The same <code><a - href="#domtokenlist0">DOMTokenList</a></code> object must be returned - every time for each attribute. - - <p>If a reflecting DOM attribute has the type <code><a - href="#htmlelement">HTMLElement</a></code>, or an interface that descends - from <code><a href="#htmlelement">HTMLElement</a></code>, then, on - getting, it must run the following algorithm (stopping at the first point - where a value is returned): - - <ol> - <li>If the corresponding content attribute is absent, then the DOM - attribute must return null. - - <li>Let <var title="">candidate</var> be the element that the <code - title="">document.getElementById()</code> method would find if it was - passed as its argument the current value of the corresponding content - attribute. - - <li>If <var title="">candidate</var> is null, or if it is not - type-compatible with the DOM attribute, then the DOM attribute must - return null. - - <li>Otherwise, it must return <var title="">candidate</var>. - </ol> - - <p>On setting, if the given element has an <code title=attr-id><a - href="#id">id</a></code> attribute, then the content attribute must be set - to the value of that <code title=attr-id><a href="#id">id</a></code> - attribute. Otherwise, the DOM attribute must be set to the empty string.</p> - <!-- XXX or raise an exception? --> - - <h3 id=common0><span class=secno>2.3. </span>Common DOM interfaces</h3> - - <h4 id=collections><span class=secno>2.3.1. </span>Collections</h4> - - <p>The <code><a href="#htmlcollection0">HTMLCollection</a></code>, <code><a - href="#htmlformcontrolscollection0">HTMLFormControlsCollection</a></code>, - and <code><a - href="#htmloptionscollection0">HTMLOptionsCollection</a></code> interfaces - represent various lists of DOM nodes. Collectively, objects implementing - these interfaces are called <dfn id=collections0>collections</dfn>. - - <p>When a <a href="#collections0" title=collections>collection</a> is - created, a filter and a root are associated with the collection. - - <p class=example>For example, when the <code><a - href="#htmlcollection0">HTMLCollection</a></code> object for the <code - title=dom-document-images><a href="#images0">document.images</a></code> - attribute is created, it is associated with a filter that selects only - <code><a href="#img">img</a></code> elements, and rooted at the root of - the document. - - <p>The <span>collection</span> then <dfn id=represents title="representated - by the collection">represents</dfn> a <a href="#live">live</a> view of the - subtree rooted at the collection's root, containing only nodes that match - the given filter. The view is linear. In the absence of specific - requirements to the contrary, the nodes within the collection must be - sorted in <a href="#tree-order">tree order</a>. - - <p class=note>The <code title=dom-table-rows><a - href="#rows">rows</a></code> list is not in tree order. - - <p>An attribute that returns a collection must return the same object every - time it is retrieved. - - <h5 id=htmlcollection><span class=secno>2.3.1.1. </span>HTMLCollection</h5> - - <p>The <code><a href="#htmlcollection0">HTMLCollection</a></code> interface - represents a generic <span>collection</span> of elements. - - <pre class=idl>interface <dfn id=htmlcollection0>HTMLCollection</dfn> { - readonly attribute unsigned long <a href="#length" title=dom-HTMLCollection-length>length</a>; - Element <a href="#itemindex" title=dom-HTMLCollection-item>item</a>(in unsigned long index); - Element <a href="#nameditem" title=dom-HTMLCollection-namedItem>namedItem</a>(in DOMString name); -};</pre> - - <p>The <dfn id=length - title=dom-HTMLCollection-length><code>length</code></dfn> attribute must - return the number of nodes <span>represented by the collection</span>. - - <p>The <dfn id=itemindex title=dom-HTMLCollection-item><code>item(<var - title="">index</var>)</code></dfn> method must return the <var - title="">index</var>th node in the collection. If there is no <var - title="">index</var>th node in the collection, then the method must return - null. - - <p>The <dfn id=nameditem - title=dom-HTMLCollection-namedItem><code>namedItem(<var - title="">key</var>)</code></dfn> method must return the first node in the - collection that matches the following requirements: - - <ul> - <li>It is an <code><a href="#a">a</a></code>, <code>applet</code>, - <code><a href="#area">area</a></code>, <code>form</code>, <code><a - href="#img">img</a></code>, or <code><a href="#object">object</a></code> - element with a <code title=attr-name>name</code> attribute equal to <var - title="">key</var>, or, - - <li>It is an HTML element of any kind with an <code title=attr-id><a - href="#id">id</a></code> attribute equal to <var title="">key</var>. - (Non-HTML elements, even if they have IDs, are not searched for the - purposes of <code title=dom-HTMLCollection-namedItem><a - href="#nameditem">namedItem()</a></code>.) - </ul> - - <p>If no such elements are found, then the method must return null. - - <p>In ECMAScript implementations, objects that implement the <code><a - href="#htmlcollection0">HTMLCollection</a></code> interface must also have - a [[Get]] method that, when invoked with a property name that is a number, - acts like the <code title=dom-HTMLCollection-item><a - href="#itemindex">item()</a></code> method would when invoked with that - argument, and when invoked with a property name that is a string, acts - like the <code title=dom-HTMLCollection-namedItem><a - href="#nameditem">namedItem()</a></code> method would when invoked with - that argument. - - <h5 id=htmlformcontrolscollection><span class=secno>2.3.1.2. - </span>HTMLFormControlsCollection</h5> - - <p>The <code><a - href="#htmlformcontrolscollection0">HTMLFormControlsCollection</a></code> - interface represents a <span>collection</span> of form controls. - - <pre - class=idl>interface <dfn id=htmlformcontrolscollection0>HTMLFormControlsCollection</dfn> { - readonly attribute unsigned long <a href="#length0" title=dom-HTMLFormControlsCollection-length>length</a>; - <a href="#htmlelement">HTMLElement</a> <a href="#itemindex0" title=dom-HTMLFormControlsCollection-item>item</a>(in unsigned long index); - Object <a href="#nameditem0" title=dom-HTMLFormControlsCollection-namedItem>namedItem</a>(in DOMString name); -};</pre> - - <p>The <dfn id=length0 - title=dom-HTMLFormControlsCollection-length><code>length</code></dfn> - attribute must return the number of nodes <span>represented by the - collection</span>. - - <p>The <dfn id=itemindex0 - title=dom-HTMLFormControlsCollection-item><code>item(<var - title="">index</var>)</code></dfn> method must return the <var - title="">index</var>th node in the collection. If there is no <var - title="">index</var>th node in the collection, then the method must return - null. - - <p>The <dfn id=nameditem0 - title=dom-HTMLFormControlsCollection-namedItem><code>namedItem(<var - title="">key</var>)</code></dfn> method must act according to the - following algorithm: - - <ol> - <li>If, at the time the method is called, there is exactly one node in the - collection that has either an <code title=attr-id><a - href="#id">id</a></code> attribute or a <code title=attr-name>name</code> - attribute equal to <var title="">key</var>, then return that node and - stop the algorithm. - - <li>Otherwise, if there are no nodes in the collection that have either an - <code title=attr-id><a href="#id">id</a></code> attribute or a <code - title=attr-name>name</code> attribute equal to <var title="">key</var>, - then return null and stop the algorithm. - - <li>Otherwise, create a <code>NodeList</code> object representing a live - view of the <code><a - href="#htmlformcontrolscollection0">HTMLFormControlsCollection</a></code> - object, further filtered so that the only nodes in the - <code>NodeList</code> object are those that have either an <code - title=attr-id><a href="#id">id</a></code> attribute or a <code - title=attr-name>name</code> attribute equal to <var title="">key</var>. - The nodes in the <code>NodeList</code> object must be sorted in <a - href="#tree-order">tree order</a>. - - <li>Return that <code>NodeList</code> object. - </ol> - - <p>In the ECMAScript DOM binding, objects implementing the <code><a - href="#htmlformcontrolscollection0">HTMLFormControlsCollection</a></code> - interface must support being dereferenced using the square bracket - notation, such that dereferencing with an integer index is equivalent to - invoking the <code title=dom-HTMLFormControlsCollection-item><a - href="#itemindex0">item()</a></code> method with that index, and such that - dereferencing with a string index is equivalent to invoking the <code - title=dom-HTMLFormControlsCollection-namedItem><a - href="#nameditem0">namedItem()</a></code> method with that index.</p> - <!-- -http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E...%0A%3Cform%20name%3D%22a%22%3E%3Cinput%20id%3D%22x%22%20name%3D%22y%22%3E%3Cinput%20name%3D%22x%22%20id%3D%22y%22%3E%3C/form%3E%0A%3Cscript%3E%0A%20%20var%20x%3B%0A%20%20w%28x%20%3D%20document.forms%5B%27a%27%5D%5B%27x%27%5D%29%3B%0A%20%20w%28x.length%29%3B%0A%20%20x%5B0%5D.parentNode.removeChild%28x%5B0%5D%29%3B%0A%20%20w%28x.length%29%3B%0A%20%20w%28x%20%3D%3D%20document.forms%5B%27a%27%5D%5B%27x%27%5D%29%3B%0A%3C/script%3E%0A ---> - - <h5 id=htmloptionscollection><span class=secno>2.3.1.3. - </span>HTMLOptionsCollection</h5> - - <p>The <code><a - href="#htmloptionscollection0">HTMLOptionsCollection</a></code> interface - represents a list of <code>option</code> elements. - - <pre - class=idl>interface <dfn id=htmloptionscollection0>HTMLOptionsCollection</dfn> { - attribute unsigned long <a href="#length1" title=dom-HTMLOptionsCollection-length>length</a>; - HTMLOptionElement <a href="#itemindex1" title=dom-HTMLOptionsCollection-item>item</a>(in unsigned long index); - Object <a href="#nameditem1" title=dom-HTMLOptionsCollection-namedItem>namedItem</a>(in DOMString name); -};</pre> - - <p>On getting, the <dfn id=length1 - title=dom-HTMLOptionsCollection-length><code>length</code></dfn> attribute - must return the number of nodes <span>represented by the - collection</span>. - - <p>On setting, the behaviour depends on whether the new value is equal to, - greater than, or less than the number of nodes <span>represented by the - collection</span> at that time. If the number is the same, then setting - the attribute must do nothing. If the new value is greater, then <var - title="">n</var> new <code>option</code> elements with no attributes and - no child nodes must be appended to the <code>select</code> element on - which the <code><a - href="#htmloptionscollection0">HTMLOptionsCollection</a></code> is rooted, - where <var title="">n</var> is the difference between the two numbers (new - value minus old value). If the new value is lower, then the last <var - title="">n</var> nodes in the collection must be removed from their parent - nodes, where <var title="">n</var> is the difference between the two - numbers (old value minus new value). - - <p class=note>Setting <code title=dom-HTMLOptionsCollection-length><a - href="#length1">length</a></code> never removes or adds any - <code>optgroup</code> elements, and never adds new children to existing - <code>optgroup</code> elements (though it can remove children from them). - - <p>The <dfn id=itemindex1 - title=dom-HTMLOptionsCollection-item><code>item(<var - title="">index</var>)</code></dfn> method must return the <var - title="">index</var>th node in the collection. If there is no <var - title="">index</var>th node in the collection, then the method must return - null. - - <p>The <dfn id=nameditem1 - title=dom-HTMLOptionsCollection-namedItem><code>namedItem(<var - title="">key</var>)</code></dfn> method must act according to the - following algorithm: - - <ol> - <li>If, at the time the method is called, there is exactly one node in the - collection that has either an <code title=attr-id><a - href="#id">id</a></code> attribute or a <code title=attr-name>name</code> - attribute equal to <var title="">key</var>, then return that node and - stop the algorithm. - - <li>Otherwise, if there are no nodes in the collection that have either an - <code title=attr-id><a href="#id">id</a></code> attribute or a <code - title=attr-name>name</code> attribute equal to <var title="">key</var>, - then return null and stop the algorithm. - - <li>Otherwise, create a <code>NodeList</code> object representing a live - view of the <code><a - href="#htmloptionscollection0">HTMLOptionsCollection</a></code> object, - further filtered so that the only nodes in the <code>NodeList</code> - object are those that have either an <code title=attr-id><a - href="#id">id</a></code> attribute or a <code - title=attr-option-name>name</code> attribute equal to <var - title="">key</var>. The nodes in the <code>NodeList</code> object must be - sorted in <a href="#tree-order">tree order</a>. - - <li>Return that <code>NodeList</code> object. - </ol> - - <p>In the ECMAScript DOM binding, objects implementing the <code><a - href="#htmloptionscollection0">HTMLOptionsCollection</a></code> interface - must support being dereferenced using the square bracket notation, such - that dereferencing with an integer index is equivalent to invoking the - <code title=dom-HTMLOptionsCollection-item><a - href="#itemindex1">item()</a></code> method with that index, and such that - dereferencing with a string index is equivalent to invoking the <code - title=dom-HTMLOptionsCollection-namedItem><a - href="#nameditem1">namedItem()</a></code> method with that index.</p> - <!-- see also http://ln.hixie.ch/?start=1161042744&count=1 --> - - <p class=big-issue>We may want to add <code>add()</code> and - <code>remove()</code> methods here too because IE implements - HTMLSelectElement and HTMLOptionsCollection on the same object, and so - people use them almost interchangeably in the wild. - - <h4 id=domtokenlist><span class=secno>2.3.2. </span>DOMTokenList</h4> - - <p>The <code><a href="#domtokenlist0">DOMTokenList</a></code> interface - represents an interface to an underlying string that consists of an <a - href="#unordered">unordered set of space-separated tokens</a>. - - <p>Which string underlies a particular <code><a - href="#domtokenlist0">DOMTokenList</a></code> object is defined when the - object is created. It might be a content attribute (e.g. the string that - underlies the <code title=dom-classList><a - href="#classlist">classList</a></code> object is the <code - title=attr-class><a href="#class">class</a></code> attribute), or it might - be an anonymous string (e.g. when a <code><a - href="#domtokenlist0">DOMTokenList</a></code> object is passed to an - author-implemented callback in the <code><a - href="#datagrid0">datagrid</a></code> APIs). - - <pre class=idl>interface <dfn id=domtokenlist0>DOMTokenList</dfn> { - readonly attribute unsigned long <a href="#length2" title=dom-tokenlist-length>length</a>; - DOMString <a href="#itemindex2" title=dom-tokenlist-item>item</a>(in unsigned long index); - boolean <a href="#hastoken" title=dom-tokenlist-has>has</a>(in DOMString token); - void <a href="#remove" title=dom-tokenlist-add>add</a>(in DOMString token); - void <span title=dom-tokenlist-remove>remove</span>(in DOMString token); - boolean <a href="#toggle" title=dom-tokenlist-toggle>toggle</a>(in DOMString token); -};</pre> - - <p>The <dfn id=length2 title=dom-tokenlist-length><code>length</code></dfn> - attribute must return the number of <em>unique</em> tokens that result - from <a href="#split" title="split a string on spaces">splitting the - underlying string on spaces</a>. - - <p>The <dfn id=itemindex2 title=dom-tokenlist-item><code>item(<var - title="">index</var>)</code></dfn> method must <a href="#split" - title="split a string on spaces">split the underlying string on - spaces</a>, sort the resulting list of tokens by Unicode - codepoint<!-- XXX that's - basically nonsense. What sort order do we want here? It should be - the cheapest one possible that is well-defined for all Unicode. -->, - remove exact duplicates, and then return the <var title="">index</var>th - item in this list. If <var title="">index</var> is equal to or greater - than the number of tokens, then the method must return null. - - <p>In ECMAScript implementations, objects that implement the <code><a - href="#domtokenlist0">DOMTokenList</a></code> interface must also have a - [[Get]] method that, when invoked with a property name that is a number, - acts like the <code title=dom-tokenlist-item><a - href="#itemindex2">item()</a></code> method would when invoked with that - argument. - - <p>The <dfn id=hastoken title=dom-tokenlist-has><code>has(<var - title="">token</var>)</code></dfn> method must run the following - algorithm: - - <ol> - <li>If the <var title="">token</var> argument contains any - spaces<!-- XXX elaborate -->, then raise an - <code>INVALID_CHARACTER_ERR</code> exception and stop the algorithm. - - <li>Otherwise, <a href="#split" title="split a string on spaces">split the - underlying string on spaces</a> to get the list of tokens in the object's - underlying string. - - <li>If the token indicated by <var title="">token</var> is one of the - tokens in the object's underlying string then return true and stop this - algorithm. - - <li>Otherwise, return false. - </ol> - - <p>The <dfn id=addtoken title=dom-tokenlist-add><code>add(<var - title="">token</var>)</code></dfn> method must run the following - algorithm: - - <ol> - <li>If the <var title="">token</var> argument contains any - spaces<!-- XXX elaborate -->, then raise an - <code>INVALID_CHARACTER_ERR</code> exception and stop the algorithm. - - <li>Otherwise, <a href="#split" title="split a string on spaces">split the - underlying string on spaces</a> to get the list of tokens in the object's - underlying string. - - <li>If the given <var title="">token</var> is already one of the tokens in - the <code><a href="#domtokenlist0">DOMTokenList</a></code> object's - underlying string then stop the algorithm. - - <li>Otherwise, if the last character of the <code><a - href="#domtokenlist0">DOMTokenList</a></code> object's underlying string - is not a <a href="#space">space character</a>, then append a U+0020 SPACE - character to the end of that string. - - <li>Append the value of <var title="">token</var> to the end of the - <code><a href="#domtokenlist0">DOMTokenList</a></code> object's - underlying string. - </ol> - - <p>The <dfn id=remove title=dom-tokenlist-add><code>remove(<var - title="">token</var>)</code></dfn> method must run the following - algorithm: - - <ol> - <li>If the <var title="">token</var> argument contains any <a - href="#space" title="space character">spaces</a>, then raise an - <code>INVALID_CHARACTER_ERR</code> exception and stop the algorithm. - - <li>Otherwise, <a href="#remove0" title="remove a token from a - string">remove the given <var title="">token</var> from the underlying - string</a>. - </ol> - - <p>The <dfn id=toggle title=dom-tokenlist-toggle><code>toggle(<var - title="">token</var>)</code></dfn> method must run the following - algorithm: - - <ol> - <li>If the <var title="">token</var> argument contains any - spaces<!-- XXX elaborate -->, then raise an - <code>INVALID_CHARACTER_ERR</code> exception and stop the algorithm. - - <li>Otherwise, <a href="#split" title="split a string on spaces">split the - underlying string on spaces</a> to get the list of tokens in the object's - underlying string. - - <li>If the given <var title="">token</var> is already one of the tokens in - the <code><a href="#domtokenlist0">DOMTokenList</a></code> object's - underlying string then <a href="#remove0" title="remove a token from a - string">remove the given <var title="">token</var> from the underlying - string</a>, and stop the algorithm, returning false. - - <li>Otherwise, if the last character of the <code><a - href="#domtokenlist0">DOMTokenList</a></code> object's underlying string - is not a <a href="#space">space character</a>, then append a U+0020 SPACE - character to the end of that string. - - <li>Append the value of <var title="">token</var> to the end of the - <code><a href="#domtokenlist0">DOMTokenList</a></code> object's - underlying string. - - <li>Return true. - </ol> - - <p>In the ECMAScript DOM binding, objects implementing the <code><a - href="#domtokenlist0">DOMTokenList</a></code> interface must stringify to - the object's underlying string representation. - - <h4 id=dom-feature><span class=secno>2.3.3. </span>DOM feature strings</h4> - - <p>DOM3 Core defines mechanisms for checking for interface support, and for - obtaining implementations of interfaces, using <a - href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#DOMFeatures">feature - strings</a>. <a href="#refsDOM3CORE">[DOM3CORE]</a> - - <p>A DOM application can use the <dfn id=hasfeature - title=hasFeature><code>hasFeature(<var title="">feature</var>, <var - title="">version</var>)</code></dfn> method of the - <code>DOMImplementation</code> interface with parameter values "<code - title="">HTML</code>" and "<code>5.0</code>" (respectively) to determine - whether or not this module is supported by the implementation. In addition - to the feature string "<code title="">HTML</code>", the feature string - "<code title="">XHTML</code>" (with version string "<code>5.0</code>") can - be used to check if the implementation supports XHTML. User agents should - respond with a true value when the <code><a - href="#hasfeature">hasFeature</a></code> method is queried with these - values. Authors are cautioned, however, that UAs returning true might not - be perfectly compliant, and that UAs returning false might well have - support for features in this specification; in general, therefore, use of - this method is discouraged. - - <p>The values "<code title="">HTML</code>" and "<code - title="">XHTML</code>" (both with version "<code>5.0</code>") should also - be supported in the context of the <code>getFeature()</code> and - <code>isSupported()</code> methods, as defined by DOM3 Core. - - <p class=note>The interfaces defined in this specification are not always - supersets of the interfaces defined in DOM2 HTML; some features that were - formerly deprecated, poorly supported, rarely used or considered - unnecessary have been removed. Therefore it is not guarenteed that an - implementation that supports "<code title="">HTML</code>" - "<code>5.0</code>" also supports "<code title="">HTML</code>" - "<code>2.0</code>". - - <h3 id=dom-tree><span class=secno>2.4. </span><dfn id=dom-tree0>DOM tree - accessors</dfn></h3> - - <p><dfn id=the-html0>The <code>html</code> element</dfn> of a document is - the document's root element, if there is one and it's an <code><a - href="#html">html</a></code> element, or null otherwise. - - <p><dfn id=the-head0>The <code>head</code> element</dfn> of a document is - the first <code><a href="#head">head</a></code> element that is a child of - <a href="#the-html0">the <code>html</code> element</a>, if there is one, - or null otherwise. - - <p><dfn id=the-title1>The <code>title</code> element</dfn> of a document is - the first <code><a href="#title1">title</a></code> element that is a child - of <a href="#the-head0">the <code>head</code> element</a>, if there is - one, or null otherwise. - - <p>The <dfn id=document.title - title=dom-document-title><code>title</code></dfn> attribute must, on - getting, run the following algorithm: - - <ol> - <li> - <p>If the <a href="#root-element">root element</a> is an <code>svg</code> - element in the "<code title="">http://www.w3.org/2000/svg</code>" - namespace, and the user agent supports SVG, then the getter must return - the value that would have been returned by the DOM attribute of the same - name on the <code>SVGDocument</code> interface. - - <li> - <p>Otherwise, it must return a concatenation of the data of all the child - <a href="#text-node" title="text node">text nodes</a> of <a - href="#the-title1">the <code>title</code> element</a>, in tree order, or - the empty string if <a href="#the-title1">the <code>title</code> - element</a> is null. - </ol> - - <p>On setting, the following algorithm must be run: - - <ol> - <li> - <p>If the <a href="#root-element">root element</a> is an <code>svg</code> - element in the "<code title="">http://www.w3.org/2000/svg</code>" - namespace, and the user agent supports SVG, then the setter must defer - to the setter for the DOM attribute of the same name on the - <code>SVGDocument</code> interface. Stop the algorithm here. - - <li>If <a href="#the-head0">the <code>head</code> element</a> is null, - then the attribute must do nothing. Stop the algorithm here. - - <li>If <a href="#the-title1">the <code>title</code> element</a> is null, - then a new <code><a href="#title1">title</a></code> element must be - created and appended to <a href="#the-head0">the <code>head</code> - element</a>. - - <li>The children of <a href="#the-title1">the <code>title</code> - element</a> (if any) must all be removed. - - <li>A single <code>Text</code> node whose data is the new value being - assigned must be appended to <a href="#the-title1">the <code>title</code> - element</a>. - </ol> - - <p>The <code title=dom-document-title><a - href="#document.title">title</a></code> attribute on the <code><a - href="#htmldocument">HTMLDocument</a></code> interface should shadow the - attribute of the same name on the <code>SVGDocument</code> interface when - the user agent supports both HTML and SVG. - - <p><dfn id=the-body0>The body element</dfn> of a document is the first - child of <a href="#the-html0">the <code>html</code> element</a> that is - either a <code><a href="#body0">body</a></code> element or a - <code>frameset</code> element. If there is no such element, it is null. If - the body element is null, then when the specification requires that events - be fired at "the body element", they must instead be fired at the - <code>Document</code> object. - - <p>The <dfn id=body title=dom-document-body><code>body</code></dfn> - attribute, on getting, must return <a href="#the-body0">the body - element</a> of the document (either a <code><a - href="#body0">body</a></code> element, a <code>frameset</code> element, or - null). On setting, the following algorithm must be followed: - - <ol> - <li>If the new value is not a <code><a href="#body0">body</a></code> or - <code>frameset</code> element, then raise a - <code>HIERARCHY_REQUEST_ERR</code> exception and abort these steps. - - <li>Otherwise, if the new value is the same as <a href="#the-body0">the - body element</a>, do nothing. Abort these steps. - - <li>Otherwise, if <a href="#the-body0">the body element</a> is not null, - then replace that element with the new value in the DOM, as if the root - element's <code title="">replaceChild()</code> method had been called - with the new value and <a href="#the-body0" title="the body element">the - incumbent body element</a> as its two arguments respectively, then abort - these steps. - - <li>Otherwise, the <a href="#the-body0">the body element</a> is null. - Append the new value to the root element. - </ol> - <!--XXX - http://lxr.mozilla.org/seamonkey/source/content/html/document/src/nsHTMLDocument.cpp - search for ::GetBody ::SetBody - http://trac.webkit.org/projects/webkit/browser/trunk/WebCore/html/HTMLDocument.cpp - search for ::setBody - http://trac.webkit.org/projects/webkit/browser/trunk/WebCore/dom/Document.cpp - search for ::body - --> - - <p>The <dfn id=images0 title=dom-document-images><code>images</code></dfn> - attribute must return an <code><a - href="#htmlcollection0">HTMLCollection</a></code> rooted at the - <code>Document</code> node, whose filter matches only <code><a - href="#img">img</a></code> elements. - - <p>The <dfn id=links0 title=dom-document-links><code>links</code></dfn> - attribute must return an <code><a - href="#htmlcollection0">HTMLCollection</a></code> rooted at the - <code>Document</code> node, whose filter matches only <code><a - href="#a">a</a></code> elements with <code title=attr-hyperlink-href><a - href="#href6">href</a></code> attributes and <code><a - href="#area">area</a></code> elements with <code - title=attr-hyperlink-href><a href="#href6">href</a></code> attributes. - - <p>The <dfn id=forms0 title=dom-document-forms><code>forms</code></dfn> - attribute must return an <code><a - href="#htmlcollection0">HTMLCollection</a></code> rooted at the - <code>Document</code> node, whose filter matches only <code>form</code> - elements. - - <p>The <dfn id=anchors - title=dom-document-anchors><code>anchors</code></dfn> attribute must - return an <code><a href="#htmlcollection0">HTMLCollection</a></code> - rooted at the <code>Document</code> node, whose filter matches only - <code><a href="#a">a</a></code> elements with <code - title=attr-a-name>name</code> attributes.</p> - <!-- XXX note that such elements are - non-conforming --> - - <p>The <dfn id=getelementsbyname - title=dom-document-getElementsByName><code>getElementsByName(<var - title="">name</var>)</code></dfn> method a string <var - title="">name</var>, and must return a live <code>NodeList</code> - containing all the <code><a href="#a">a</a></code>, <code>applet</code>, - <code>button</code>, <code>form</code>, <!-- frame? frameset? - XXX--><code><a - href="#iframe">iframe</a></code>, <code><a href="#img">img</a></code>, - <code>input</code>, <code><a href="#map">map</a></code>, <code><a - href="#meta0">meta</a></code>, <code><a - href="#object">object</a></code>,<!-- param? - XXX--> <code>select</code>, - and <code>textarea</code> elements in that document that have a <code - title="">name</code> attribute whose value is - equal<!-- XXX case sensitivity --> to the <var title="">name</var> - argument.</p> - <!-- XXX what about XHTML? --> - - <p>The <dfn id=getelementsbyclassname - title=dom-document-getElementsByClassName><code>getElementsByClassName(<var - title="">classNames</var>)</code></dfn> method takes an array of strings - representing classes. When called, the method must return a live - <code>NodeList</code> object containing all the elements in the document - that have all the classes specified in that array. If the array is empty, - then the method must return an empty <code>NodeList</code>. - - <p>HTML, XHTML, SVG and MathML elements define which classes they are in by - having an attribute in the per-element partition with the name <code - title="">class</code> containing a space-separated list of classes to - which the element belongs. Other specifications may also allow elements in - their namespaces to be labelled as being in specific classes. UAs must not - assume that all attributes of the name <code>class</code> for elements in - any namespace work in this way, however, and must not assume that such - attributes, when used as global attributes, label other elements as being - in specific classes. - - <div class=example> - <p>Given the following XHTML fragment:</p> - - <pre><div id="example"> - <p id="p1" class="aaa bbb"/> - <p id="p2" class="aaa ccc"/> - <p id="p3" class="bbb ccc"/> -</div></pre> - - <p>A call to - <code>document.getElementById('example').getElementsByClassName('aaa')</code> - would return a <code>NodeList</code> with the two paragraphs - <code>p1</code> and <code>p2</code> in it.</p> - - <p>A call to <code>getElementsByClassName(['ccc', 'bbb'])</code> would - only return one node, however, namely <code>p3</code>. A call to - <code>document.getElementById('example').getElementsByClassName('ccc - bbb')</code> would return the same thing.</p> - - <p>A call to <code>getElementsByClassName(['aaa bbb'])</code> would return - no nodes; none of the elements above are in the "aaa bbb" class.</p> - - <p>A call to <code>getElementsByClassName([''])</code> would also return - no nodes, since none of the nodes are in the "" class (indeed, in HTML, - it is impossible to specify that an element is in the "" class).</p> - </div> - - <p>The <dfn id=getelementsbyclassname0 - title=dom-getElementsByClassName><code>getElementsByClassName()</code></dfn> - method on the <code><a href="#htmlelement">HTMLElement</a></code> - interface must return the nodes that the <code><a - href="#htmldocument">HTMLDocument</a></code> <code - title=dom-document-getElementsByClassName><a - href="#getelementsbyclassname">getElementsByClassName()</a></code> method - would return, excluding any elements that are not descendants of the - <code><a href="#htmlelement">HTMLElement</a></code> object on which the - method was invoked.</p> - <!-- XXX -> * xGetParentElementByClassName(rootElement, className, tagName) - -> Navigates upwards until we hit a parent element with the given class name and -> optional tag name. ---> - - <p class=note>The <code title=dom-document-dir><a - href="#dir1">dir</a></code> attribute on the <code><a - href="#htmldocument">HTMLDocument</a></code> interface is defined along - with the <code title=attr-dir><a href="#dir">dir</a></code> content - attribute. - - <h3 id=dynamic><span class=secno>2.5. </span><dfn id=dynamic2>Dynamic - markup insertion</dfn></h3> - - <p>The <code title=dom-document-write><a - href="#document.write">document.write()</a></code> family of methods and - the <code title=dom-innerHTML><a href="#innerhtml">innerHTML</a></code> - family of DOM attributes enable script authors to dynamically insert - markup into the document. - - <p class=issue>bz argues that innerHTML should be called something else on - XML documents and XML elements. Is the sanity worth the migration pain? - - <p>Because these APIs interact with the parser, their behaviour varies - depending on whether they are used with <a href="#html-">HTML - documents</a> (and the <a href="#html-0">HTML parser</a>) or XHTML in <a - href="#xml-documents">XML documents</a> (and the <span>XML parser</span>). - The following table cross-references the various versions of these APIs. - - <table> - <thead> - <tr> - <td> - - <th><dfn id=document.write - title=dom-document-write><code>document.write()</code></dfn> - - <th><dfn id=innerhtml title=dom-innerHTML><code>innerHTML</code></dfn> - - <tbody> - <tr> - <th>For documents that are <a href="#html-">HTML documents</a> - - <td><a href="#document.write0" - title=dom-document-write-HTML><code>document.write()</code> in HTML</a> - - <td><a href="#innerhtml0" - title=dom-innerHTML-HTML><code>innerHTML</code> in HTML</a> - - <tr> - <th>For documents that are <a href="#xml-documents">XML documents</a> - - <td><a href="#document.write1" - title=dom-document-write-XML><code>document.write()</code> in XML</a> - - <td><a href="#innerhtml2" title=dom-innerHTML-XML><code>innerHTML</code> - in XML</a> - </table> - - <p>Regardless of the parsing mode, the <dfn id=document.writeln - title=dom-document-writeln><code>document.writeln(<var - title="">s</var>)</code></dfn> method must call the <code - title=dom-document-write><a - href="#document.write">document.write()</a></code> method with the same - argument <var title="">s</var>, and then call the <code - title=dom-document-write><a - href="#document.write">document.write()</a></code> method with, as its - argument, a string consisting of a single line feed character (U+000A). - - <h4 id=controlling><span class=secno>2.5.1. </span>Controlling the input - stream</h4> - - <p>The <dfn id=open title=dom-document-open><code>open()</code></dfn> - method comes in several variants with different numbers of arguments. - - <p>When called with two or fewer arguments, the method must act as follows: - - <ol> - <li> - <p>Let <var title="">type</var> be the value of the first argument, if - there is one, or "<code>text/html</code>" otherwise. - - <li> - <p>Let <var title="">replace</var> be true if there is a second argument - and it has the value "replace"<!-- case-insensitive. XXX - -->, and - false otherwise. - - <li> - <p>If the document has an <span>active parser</span><!-- XXX xref - --> - that isn't a <a href="#script-created">script-created parser</a>, and - the <a href="#insertion">insertion point</a> associated with that - parser's <a href="#input0">input stream</a> is not undefined (that is, - it <em>does</em> point to somewhere in the input stream), then the - method does nothing. Abort these steps.</p> - - <p class=note>This basically causes <code title=dom-document-open><a - href="#open">document.open()</a></code> to be ignored when it's called - in an inline script found during the parsing of data sent over the - network, while still letting it have an effect when called - asynchronously or on a document that is itself being spoon-fed using - these APIs.</p> - - <li> - <p class=big-issue>onbeforeunload, onunload - - <li> - <p>If the document has an <span>active parser</span><!--XXX - xref-->, - then stop that parser, and throw away any pending content in the input - stream. <span class=big-issue>what about if it doesn't, because it's - either like a text/plain, or Atom, or PDF, or XHTML, or image document, - or something?</span> - </li> - <!-- XXX see - also innerHTML in HTML --> - - <li> - <p>Remove all child nodes of the document. - - <li> - <p>Create a new <a href="#html-0">HTML parser</a> and associate it with - the document. This is a <dfn id=script-created>script-created - parser</dfn> (meaning that it can be closed by the <code - title=dom-document-open><a href="#open">document.open()</a></code> and - <code title=dom-document-close><a - href="#close">document.close()</a></code> methods, and that the - tokeniser will wait for an explicit call to <code - title=dom-document-close><a href="#close">document.close()</a></code> - before emitting an end-of-file token). - - <li>Mark the document as being an <a href="#html-" title="HTML - documents">HTML document</a> (it might already be so-marked).</li> - <!-- text/plain handling --> - - <li> - <p>If <var title="">type</var> does not have the value - "<code>text/html</code>"<!-- XXX matched how? - -->, then act as if the - tokeniser had emitted a <code><a href="#pre">pre</a></code> element - start tag, then set the <a href="#html-0">HTML parser</a>'s <a - href="#tokenisation0">tokenisation</a> stage's <a - href="#content2">content model flag</a> to <em>PLAINTEXT</em>. - - <li> - <p>If <var title="">replace</var> is false, then: - - <ol> - <li>Remove all the entries in the <a href="#browsing0">browsing - context</a>'s <a href="#session">session history</a> after the <a - href="#current0">current entry</a> in its <code>Document</code>'s - <code><a href="#history1">History</a></code> object - - <li>Remove any earlier entries that share the same <code>Document</code> - - <li>Add a new entry just before the last entry that is associated with - the text that was parsed by the previous parser associated with the - <code>Document</code> object, as well as the state of the document at - the start of these steps. (This allows the user to step backwards in - the session history to see the page before it was blown away by the - <code title=dom-document-open><a - href="#open">document.open()</a></code> call.) - </ol> - - <li> - <p>Finally, set the <a href="#insertion">insertion point</a> to point at - just before the end of the <a href="#input0">input stream</a> (which at - this point will be empty). - </ol> - - <p class=big-issue>We shouldn't hard-code <code>text/plain</code> there. We - should do it some other way, e.g. hand off to the section on - content-sniffing and handling of incoming data streams, the part that - defines how this all works when stuff comes over the network.</p> - <!-- XXX Should we support XML/XHTML as a type to that method? --> - - <p>When called with three or more arguments, the <code - title=dom-document-open><a href="#open">open()</a></code> method on the - <code><a href="#htmldocument">HTMLDocument</a></code> object must call the - <code title=dom-open><a href="#open2">open()</a></code> method on the - <code><a href="#window">Window</a></code> interface of the object returned - by the <code title=dom-document-defaultView>defaultView</code> attribute - of the <code>DocumentView</code> interface of the <code><a - href="#htmldocument">HTMLDocument</a></code> object, with the same - arguments as the original call to the <code title=dom-document-open><a - href="#open">open()</a></code> method. If the <code - title=dom-document-defaultView>defaultView</code> attribute of the - <code>DocumentView</code> interface of the <code><a - href="#htmldocument">HTMLDocument</a></code> object is null, then the - method must raise an <code>INVALID_ACCESS_ERR</code> exception. - - <p>The <dfn id=close title=dom-document-close><code>close()</code></dfn> - method must do nothing if there is no <a - href="#script-created">script-created parser</a> associated with the - document. If there is such a parser, then, when the method is called, the - user agent must insert an <a href="#explicit">explicit "EOF" character</a> - at the <a href="#insertion">insertion point</a> of the parser's <a - href="#input0">input stream</a>. - - <h4 id=dynamic0><span class=secno>2.5.2. </span>Dynamic markup insertion in - HTML</h4> - - <p>In HTML, the <dfn id=document.write0 - title=dom-document-write-HTML><code>document.write(<var - title="">s</var>)</code></dfn> method must act as follows: - - <ol> - <li> - <p>If the <a href="#insertion">insertion point</a> is undefined, the - <code title=dom-document-open><a href="#open">open()</a></code> method - must be called (with no arguments) on the <code - title=Document>document</code> object. The <a - href="#insertion">insertion point</a> will point at just before the end - of the (empty) <a href="#input0">input stream</a>.</p> - - <li> - <p>The string <var title="">s</var> must be inserted into the <a - href="#input0">input stream</a><!-- XXX xref --> just before the <a - href="#insertion">insertion point</a>.</p> - - <li> - <p>If there is <a href="#the-script" title="the script that will execute - as soon as the parser resumes">a script that will execute as soon as the - parser resumes</a>, then the method must now return without further - processing of the <a href="#input0">input stream</a>.</p> - - <li> - <p>Otherwise, the tokeniser must process the characters that were - inserted, one at a time, processing resulting tokens as they are - emitted, and stopping when the tokeniser reaches the insertion point or - when the processing of the tokeniser is aborted by the tree construction - stage (this can happen if a <code><a href="#script0">script</a></code> - start tag token is emitted by the tokeniser). - - <p class=note>If the <code title=dom-document-write-HTML><a - href="#document.write0">document.write()</a></code> method was called - from script executing inline (i.e. executing because the parser parsed a - set of <code><a href="#script0">script</a></code> tags), then this is a - <a href="#nestedParsing">reentrant invocation of the parser</a>.</p> - - <li> - <p>Finally, the method must return.</p> - </ol> - - <p>In HTML, the <dfn id=innerhtml0 - title=dom-innerHTML-HTML><code>innerHTML</code></dfn> DOM attribute of all - <code><a href="#htmlelement">HTMLElement</a></code> and <code><a - href="#htmldocument">HTMLDocument</a></code> nodes returns a serialisation - of the node's children using the <span>HTML syntax</span><!-- XXX xref - -->. - On setting, it replaces the node's children with new nodes that result - from parsing the given value. The formal definitions follow. - - <p>On getting, the <code title=dom-innerHTML-HTML><a - href="#innerhtml0">innerHTML</a></code> DOM attribute must return the - result of running the following algorithm: - - <ol> - <li> - <p>Let <var title="">s</var> be a string, and initialise it to the empty - string. - - <li> - <p>For each child node <var title="">child</var>, in <a - href="#tree-order">tree order</a>, append the appropriate string from - the following list to <var title="">s</var>:</p> - - <dl class=switch> - <dt>If the child node is an <code title="">Element</code> - - <dd> - <p>Append a U+003C LESS-THAN SIGN (<code title=""><</code>) - character, followed by the element's tag name. (For nodes created by - the <a href="#html-0">HTML parser</a>, <code - title="">Document.createElement()</code>, or <code - title="">Document.renameNode()</code>, the tag name will be - lowercase.)</p> - - <p>For each attribute that the element has, append a U+0020 SPACE - character, the attribute's name (which, for attributes set by the <a - href="#html-0">HTML parser</a> or by <code - title="">Element.setAttributeNode()</code> or <code - title="">Element.setAttribute()</code>, will be lowercase), a U+003D - EQUALS SIGN (<code title="">=</code>) character, a U+0022 QUOTATION - MARK (<code title="">"</code>) character, the attribute's value, - <a href="#escapingString" title="escaping a string">escaped as - described below</a>, and a second U+0022 QUOTATION MARK (<code - title="">"</code>) character.</p> - - <p>While the exact order of attributes is UA-defined, and may depend on - factors such as the order that the attributes were given in the - original markup, the sort order must be stable, such that consecutive - calls to <code title=dom-innerHTML-HTML><a - href="#innerhtml0">innerHTML</a></code> serialise an element's - attributes in the same order.</p> - - <p>Append a U+003E GREATER-THAN SIGN (<code title="">></code>) - character.</p> - - <p>If the child node is an <code><a href="#area">area</a></code>, - <code><a href="#base">base</a></code>, <code>basefont</code>, - <code>bgsound</code>, <code><a href="#br">br</a></code>, <code><a - href="#col">col</a></code>, <code><a href="#embed">embed</a></code>, - <code>frame</code>, <code><a href="#hr">hr</a></code>, <code><a - href="#img">img</a></code>, <code>input</code>, <code><a - href="#link">link</a></code>, <code><a href="#meta0">meta</a></code>, - <code><a href="#param">param</a></code>, <code>spacer</code>, or - <code>wbr</code> element, then continue on to the next child node at - this point.</p> - <!-- also, i guess: - image, isindex, and keygen, but we don't list those because we - don't consider those "elements", more "macros", and thus we - should never serialise them --> - <!-- XXX when we get around to - it, add event-source --> - <p>Otherwise, append the value of the <var title="">child</var> - element's <code title=dom-innerHTML-HTML><a - href="#innerhtml0">innerHTML</a></code> DOM attribute (thus recursing - into this algorithm for that element), followed by a U+003C LESS-THAN - SIGN (<code title=""><</code>) character, a U+002F SOLIDUS (<code - title="">/</code>) character, the element's tag name again, and - finally a U+003E GREATER-THAN SIGN (<code title="">></code>) - character.</p> - - <dt>If the child node is a <code title="">Text</code> or <code - title="">CDATASection</code> node - - <dd> - <p>If one of the ancestors of the child node is a <code><a - href="#style">style</a></code>, <code><a - href="#script0">script</a></code>, <code>xmp</code>, <code><a - href="#iframe">iframe</a></code>, <code>noembed</code>, - <code>noframes</code>, or <code><a - href="#noscript">noscript</a></code> element, then append the value of - the <var title="">child</var> node's <code title="">data</code> DOM - attribute literally.</p> - <!-- note about noscript: because this is defining an API, it - can assume that scripting is enabled, and that thus the - <noscript> element in the DOM will have been parsed in the - scripting-enabled mode, and that thus the text node is raw - markup --> - - <p>Otherwise, append the value of the <var title="">child</var> node's - <code title="">data</code> DOM attribute, <a href="#escapingString" - title="escaping a string">escaped as described below</a>.</p> - - <dt>If the child node is a <code title="">Comment</code> - - <dd> - <p>Append the literal string <code><!--</code> (U+003C LESS-THAN - SIGN, U+0021 EXCLAMATION MARK, U+002D HYPHEN-MINUS, U+002D - HYPHEN-MINUS), followed by the value of the <var title="">child</var> - node's <code title="">data</code> DOM attribute, followed by the - literal string <code>--></code> (U+002D HYPHEN-MINUS, U+002D - HYPHEN-MINUS, U+003E GREATER-THAN SIGN).</p> - - <dt>If the child node is a <code title="">DocumentType</code> - - <dd> - <p>Append the literal string <code><!DOCTYPE</code> (U+003C - LESS-THAN SIGN, U+0021 EXCLAMATION MARK, U+0044 LATIN CAPITAL LETTER - D, U+004F LATIN CAPITAL LETTER O, U+0043 LATIN CAPITAL LETTER C, - U+0054 LATIN CAPITAL LETTER T, U+0059 LATIN CAPITAL LETTER Y, U+0050 - LATIN CAPITAL LETTER P, U+0045 LATIN CAPITAL LETTER E), followed by a - space (U+0020 SPACE), followed by the value of the <var - title="">child</var> node's <code title="">name</code> DOM attribute, - followed by the literal string <code>></code> (U+003E GREATER-THAN - SIGN).</p> - </dl> - - <p>Other nodes types (e.g. <code title="">Attr</code>) cannot occur as - children of elements. If they do, the <code title=dom-innerHTML-HTML><a - href="#innerhtml0">innerHTML</a></code> attribute must raise an - <code>INVALID_STATE_ERR</code> exception.</p> - - <li> - <p>The result of the algorithm is the string <var title="">s</var>. - </ol> - - <p><dfn id=escapingString>Escaping a string</dfn> (for the purposes of the - algorithm above) consists of replacing any occurances of the "<code - title="">&</code>" character by the string "<code - title="">&amp;</code>", any occurances of the "<code - title=""><</code>" character by the string "<code - title="">&lt;</code>", any occurances of the "<code - title="">></code>" character by the string "<code - title="">&gt;</code>", and any occurances of the "<code - title="">"</code>" character by the string "<code - title="">&quot;</code>". - - <p class=note>Entity reference nodes are <a - href="#entity-references">assumed to be expanded</a> by the user agent, - and are therefore not covered in the algorithm above. - - <p class=note>If the element's contents are not conformant, it is possible - that the roundtripping through <code title=dom-innerHTML-HTML><a - href="#innerhtml0">innerHTML</a></code> will not work. For instance, if - the element is a <code>textarea</code> element to which a <code - title="">Comment</code> node has been appended, then assigning <code - title=dom-innerHTML-HTML><a href="#innerhtml0">innerHTML</a></code> to - itself will result in the comment being displayed in the text field. - Similarly, if, as a result of DOM manipulation, the element contains a - comment that contains the literal string "<code title="">--></code>", - then when the result of serialising the element is parsed, the comment - will be truncated at that point and the rest of the comment will be - interpreted as markup. Another example would be making a <code><a - href="#script0">script</a></code> element contain a text node with the - text string "<code></script></code>". - - <p>On setting, if the node is a document, the <code - title=dom-innerHTML-HTML><a href="#innerhtml0">innerHTML</a></code> DOM - attribute must run the following algorithm: - - <ol> - <li> - <p>Otherwise, if the document has an <span>active - parser</span><!--XXX xref-->, then stop that parser, and throw away any - pending content in the input stream. <span class=big-issue>what about if - it doesn't, because it's either like a text/plain, or Atom, or PDF, or - XHTML, or image document, or something?</span></p> - <!-- XXX see also document.open() --> - - <li> - <p>The user agent must remove the children nodes of the - <code>Document</code> whose <code title=dom-innerHTML-HTML><a - href="#innerhtml0">innerHTML</a></code> attribute is being set.</p> - - <li> - <p>The user agent must create a new <a href="#html-0">HTML parser</a>, in - its initial state, and associate it with the <code>Document</code> node.</p> - </li> - <!-- redundant, the document is forcably already so labelled if we get here - <li> - - <p>The user agent must mark the <code>Document</code> object as - being an <span title="HTML documents">HTML document</span>.</p> - - </li> ---> - - <li> - <p>The user agent must place into the <a href="#input0">input stream</a> - for the <a href="#html-0">HTML parser</a> just created the string being - assigned into the <code title=dom-innerHTML-HTML><a - href="#innerhtml0">innerHTML</a></code> attribute.</p> - - <li> - <p>The user agent must start the parser and let it run until it has - consumed all the characters just inserted into the input stream. (The - <code>Document</code> node will have been populated with elements and a - <code title=event-load><a href="#load0">load</a></code> event will have - fired on <a href="#the-body0" title="the body element">its body - element</a>.)</p> - </ol> - - <p>Otherwise, if the node is an element, then setting the <code - title=dom-innerHTML-HTML><a href="#innerhtml0">innerHTML</a></code> DOM - attribute must cause the following algorithm to run instead: - - <ol> - <li> - <p>The user agent must create a new <code>Document</code> node, and mark - it as being an <a href="#html-" title="HTML documents">HTML - document</a>.</p> - - <p>The user agent must create a new <a href="#html-0">HTML parser</a>, - and associate it with the just created <code>Document</code> node.</p> - - <p class=note>Parts marked <dfn id=innerhtml1 title="innerHTML - case"><code>innerHTML</code> case</dfn> in algorithms in the parser - section are parts that only occur if the parser was created for the - purposes of handling the setting of an element's <code - title=dom-innerHTML-HTML><a href="#innerhtml0">innerHTML</a></code> - attribute. The algorithms have been annotated with such markings for - informational purposes only; such markings have no normative weight. If - it is possible for a condition described as an <a - href="#innerhtml1"><code>innerHTML</code> case</a> to occur even when - the parser wasn't created for the purposes of handling an element's - <code title=dom-innerHTML-HTML><a - href="#innerhtml0">innerHTML</a></code> attribute, then that is an error - in the specification.</p> - - <li> - <p>The user agent must set the <a href="#html-0">HTML parser</a>'s <a - href="#tokenisation0">tokenisation</a> stage's <a - href="#content2">content model flag</a> according to the name of the - element whose <code title=dom-innerHTML-HTML><a - href="#innerhtml0">innerHTML</a></code> attribute is being set, as - follows:</p> - - <dl class=switch> - <dt>If it is a <code><a href="#title1">title</a></code> or - <code>textarea</code> element - - <dd>Set the <a href="#content2">content model flag</a> to - <em>RCDATA</em>. - - <dt>If it is a <code><a href="#style">style</a></code>, <code><a - href="#script0">script</a></code>, <code>xmp</code>, <code><a - href="#iframe">iframe</a></code>, <code>noembed</code>, - <code>noframes</code>, or <code><a href="#noscript">noscript</a></code> - element - - <dd>Set the <a href="#content2">content model flag</a> to - <em>CDATA</em>.</dd> - <!-- note about noscript: we set it to CDATA here because if - someone is setting innerHTML, then we know scripting is enabled, - so the noscript element will be in CDATA mode --> - - <dt>If it is a <code>plaintext</code> element - - <dd>Set the <a href="#content2">content model flag</a> to - <em>PLAINTEXT</em>. - - <dt>Otherwise - - <dd>Set the <a href="#content2">content model flag</a> to - <em>PCDATA</em>. - </dl> - - <li> - <p>The user agent must switch the <a href="#html-0">HTML parser</a>'s <a - href="#tree-construction0">tree construction</a> stage to <a - href="#the-main0">the main phase</a>. - - <li> - <p>Let <var title="">root</var> be a new <code><a - href="#html">html</a></code> element with no attributes.</p> - - <li> - <p>The user agent must append the element <var title="">root</var> to the - <code>Document</code> node created above.</p> - - <li> - <p>The user agent must set up the parser's <a href="#stack">stack of open - elements</a> so that it contains just the single element <var - title="">root</var>.</p> - - <li> - <p>The user agent must <a href="#reset" title="reset the insertion mode - appropriately">reset the parser's insertion mode appropriately</a>.</p> - - <li> - <p>The user agent must set the parser's <a - href="#form-element"><code>form</code> element pointer</a> to the - nearest node to the element whose <code title=dom-innerHTML-HTML><a - href="#innerhtml0">innerHTML</a></code> attribute is being set that is a - <code>form</code> element (going straight up the ancestor chain, and - including the element itself, if it is a <code>form</code> element), or, - if there is no such <code>form</code> element, to null.</p> - - <li> - <p>The user agent must place into the <a href="#input0">input stream</a> - for the <a href="#html-0">HTML parser</a> just created the string being - assigned into the <code title=dom-innerHTML-HTML><a - href="#innerhtml0">innerHTML</a></code> attribute.</p> - - <li> - <p>The user agent must start the parser and let it run until it has - consumed all the characters just inserted into the input stream.</p> - - <li> - <p>The user agent must remove the children of the element whose <code - title=dom-innerHTML-HTML><a href="#innerhtml0">innerHTML</a></code> - attribute is being set.</p> - - <li> - <p>The user agent must move all the child nodes of the <var - title="">root</var> element to the element whose <code - title=dom-innerHTML-HTML><a href="#innerhtml0">innerHTML</a></code> - attribute is being set, preserving their order.</p> - </ol> - <!-- XXX must make sure we spec that innerHTML causes mutation - events to fire, but document.write() doesn't. (the latter is already - req-stated in the parser section, btw) --> - <!-- http://msdn.microsoft.com/workshop/author/dhtml/reference/properties/innerhtml.asp --> - <!-- http://lxr.mozilla.org/seamonkey/source/content/html/content/src/nsGenericHTMLElement.cpp#879 - note script execution disabled - http://lxr.mozilla.org/seamonkey/source/content/base/src/nsContentUtils.cpp#3308 - http://trac.webkit.org/projects/webkit/browser/trunk/WebCore/html/HTMLElement.cpp#L295 - http://trac.webkit.org/projects/webkit/browser/trunk/WebCore/html/HTMLElement.cpp#L242 - http://trac.webkit.org/projects/webkit/browser/trunk/WebCore/html/HTMLTokenizer.cpp#L1742 - --> - - <h4 id=dynamic1><span class=secno>2.5.3. </span>Dynamic markup insertion in - XML</h4> - - <p>In an XML context, the <dfn id=document.write1 - title=dom-document-write-XML><code>document.write(<var - title="">s</var>)</code></dfn> method must raise an - <code>INVALID_ACCESS_ERR</code> exception.</p> - <!-- - For XHTML: content must be well-formed. Where does - it insert? Immediately after the script that called document.write()?</p> - how do we handle async scripts vs sync scripts? - -Consider: -data:text/xml,<script xmlns="http://www.w3.org/1999/xhtml"><![CDATA[ document.write('<foo>Test</foo>'); ]]></script> -data:text/xml,<script xmlns="http://www.w3.org/1999/xhtml"><![CDATA[ alert('test'); alert(document.write); try { document.write('<foo>Test</foo>'); alert(document.childNodes.length); } catch (e) { alert(e); } ]]></script> - ---> - - <p>The <dfn id=innerhtml2 - title=dom-innerHTML-XML><code>innerHTML</code></dfn> attributes, on the - other hand, in an XML context, are usable. - - <p>On getting, the <code title=dom-innerHTML-XML><a - href="#innerhtml2">innerHTML</a></code> DOM attribute on <code><a - href="#htmlelement">HTMLElement</a></code>s and <code><a - href="#htmldocument">HTMLDocument</a></code>s, in an XML context, must - return an XML namespace-well-formed internal general parsed entity - representation of the element or document. User agents may adjust prefixes - and namespace declarations in the serialisation (and indeed might be - forced to do so in some cases to obtain namespace-well-formed XML). <a - href="#refsXML">[XML]</a> <a href="#refsXMLNS">[XMLNS]</a> - - <p>On setting, in an XML context, the <code title=dom-innerHTML-HTML><a - href="#innerhtml0">innerHTML</a></code> DOM attribute on must run the - following algorithm: - - <ol> - <li> - <p>The user agent must create a new <span>XML parser</span>.</p> - - <li> - <p>If the <code title=dom-innerHTML-XML><a - href="#innerhtml2">innerHTML</a></code> attribute is being set on an - element, the user agent must <span>feed the parser</span> just created - the string corresponding to the start tag of that element, declaring all - the namespace prefixes that are in scope on that element in the DOM, as - well as declaring the default namespace (if any) that is in scope on - that element in the DOM.</p> - - <li> - <p>The user agent must <span>feed the parser</span> just created the - string being assigned into the <code title=dom-innerHTML-HTML><a - href="#innerhtml0">innerHTML</a></code> attribute.</p> - - <li> - <p>If the <code title=dom-innerHTML-XML><a - href="#innerhtml2">innerHTML</a></code> attribute is being set on an - element, the user agent must <span>feed the parser</span> the string - corresponding to the end tag of that element.</p> - - <li> - <p>If the parser found a well-formedness error, the attribute's setter - must raise a <code>SYNTAX_ERR</code> exception and abort these steps.</p> - - <li> - <p>The user agent must remove the children nodes of the node whose <code - title=dom-innerHTML-XML><a href="#innerhtml2">innerHTML</a></code> - attribute is being set.</p> - - <li> - <p>If the attribute is being set on a <code>Document</code> node, let - <var title="">new children</var> be the children of the document, - preserving their order. Otherwise, the attribute is being set on an - <code>Element</code> node; let <var title="">new children</var> be the - children of the the document's root element, preserving their order.</p> - - <li> - <p>If the attribute is being set on a <code>Document</code> node, let - <var title="">target document</var> be that <code>Document</code> node. - Otherwise, the attribute is being set on an <code>Element</code> node; - let <var title="">target document</var> be the <code - title="">ownerDocument</code> of that <code>Element</code>.</p> - - <li> - <p>Set the <code title="">ownerDocument</code> of all the nodes in <var - title="">new children</var> to the <var title="">target document</var>.</p> - - <li> - <p>Append all the <var title="">new children</var> nodes to the node - whose <code title=dom-innerHTML-HTML><a - href="#innerhtml0">innerHTML</a></code> attribute is being set, - preserving their order.</p> - </ol> - - <h3 id=apis-in><span class=secno>2.6. </span>APIs in HTML documents</h3> - <!-- XXX case-sensitivity training required here. --> - - <p>For <a href="#html-">HTML documents</a>, and for <a - href="#html-elements">HTML elements</a> in <a href="#html-">HTML - documents</a>, certain APIs defined in DOM3 Core become case-insensitive - or case-changing, as sometimes defined in DOM3 Core, and as summarised or - required below. <a href="#refsDOM3CORE">[DOM3CORE]</a>. - - <p>This does not apply to <a href="#xml-documents">XML documents</a> or to - elements that are not in the <a href="#html-namespace0">HTML namespace</a> - despite being in <a href="#html-">HTML documents</a>. - - <dl> - <dt><code title="">Element.tagName</code>, <code - title="">Node.nodeName</code>, and <code title="">Node.localName</code> - - <dd> - <p>These attributes return tag names in all uppercase<!-- XXX - xref--> - and attribute names in all lowercase<!-- XXX xref -->, regardless of the - case with which they were created.</p> - - <dt><code title="">Document.createElement()</code> - - <dd> - <p>The canonical form of HTML markup is all-lowercase; thus, this method - will lowercase<!-- XXX xref --> the argument before creating the - requisite element. Also, the element created must be in the <a - href="#html-namespace0">HTML namespace</a>.</p> - - <p class=note>This doesn't apply to <code - title="">Document.createElementNS()</code>. Thus, it is possible, by - passing this last method a tag name in the wrong case, to create an - element that claims to have the tag name of an HTML element, but doesn't - support its interfaces, because it really has another tag name not - accessible from the DOM APIs.</p> - - <dt><code title="">Element.setAttributeNode()</code> - - <dd> - <p>When an <code>Attr</code> node is set on an <a href="#html-elements" - title="HTML elements">HTML element</a>, it must have its name - lowercased<!-- XXX xref --> before the element is affected.</p> - - <p class=note>This doesn't apply to <code - title="">Document.setAttributeNodeNS()</code>.</p> - - <dt><code title="">Element.setAttribute()</code> - - <dd> - <p>When an attribute is set on an <a href="#html-elements" title="HTML - elements">HTML element</a>, the name argument must be - lowercased<!-- XXX xref - --> before the element is affected.</p> - - <p class=note>This doesn't apply to <code - title="">Document.setAttributeNS()</code>.</p> - - <dt><code title="">Document.getElementsByTagName()</code> and <code - title="">Element.getElementsByTagName()</code> - - <dd> - <p>These methods (but not their namespaced counterparts) must compare the - given argument case-insensitively<!-- XXX xref --> when looking at <a - href="#html-elements" title="HTML elements">HTML elements</a>, and - case-sensitively otherwise.</p> - - <p class=note>Thus, in an <a href="#html-" title="HTML documents">HTML - document</a> with nodes in multiple namespaces, these methods will be - both case-sensitive and case-insensitive at the same time.</p> - - <dt><code title="">Document.renameNode()</code> - - <dd> - <p>If the new namespace is the <a href="#html-namespace0">HTML - namespace</a>, then the new qualified name must be lowercased before the - rename takes place.<!-- XXX xref --></p> - </dl> - - <h2 id=semantics><span class=secno>3. </span>Semantics and structure of - HTML elements</h2> - - <h3 id=semantics-intro><span class=secno>3.1. </span>Introduction</h3> - - <p><em>This section is non-normative.</em> - - <p class=big-issue>An introduction to marking up a document. - - <h3 id=common1><span class=secno>3.2. </span>Common microsyntaxes</h3> - - <p>There are various places in HTML that accept particular data types, such - as dates or numbers. This section describes what the conformance criteria - for content in those formats is, and how to parse them.</p> - <!-- XXX need to define how to handle U+000A LINE FEED and U+000D - CARRIAGE RETURN in attributes (for HTML) --> - - <p class=big-issue>Need to go through the whole spec and make sure all the - attribute values are clearly defined either in terms of microsyntaxes or - in terms of other specs, or as "Text" or some such. - - <h4 id=common2><span class=secno>3.2.1. </span>Common parser idioms</h4> - - <p>The <dfn id=space title="space character">space characters</dfn>, for - the purposes of this specification, are U+0020 SPACE, U+0009 CHARACTER - TABULATION (tab), U+000A LINE FEED (LF), U+000B LINE TABULATION, U+000C - FORM FEED (FF), and U+000D CARRIAGE RETURN (CR). - - <p>Some of the micro-parsers described below follow the pattern of having - an <var title="">input</var> variable that holds the string being parsed, - and having a <var title="">position</var> variable pointing at the next - character to parse in <var title="">input</var>. - - <p>For parsers based on this pattern, a step that requires the user agent - to <dfn id=collect>collect a sequence of characters</dfn> means that the - following algorithm must be run, with <var title="">characters</var> being - the set of characters that can be collected: - - <ol> - <li> - <p>Let <var title="">input</var> and <var title="">position</var> be the - same variables as those of the same name in the algorithm that invoked - these steps. - - <li> - <p>Let <var title="">result</var> be the empty string. - - <li> - <p>While <var title="">position</var> doesn't point past the end of <var - title="">input</var> and the character at <var title="">position</var> - is one of the <var title="">characters</var>, append that character to - the end of <var title="">result</var> and advance <var - title="">position</var> to the next character in <var - title="">input</var>. - - <li> - <p>Return <var title="">result</var>. - </ol> - - <p>The step <dfn id=skip-whitespace>skip whitespace</dfn> means that the - user agent must <a href="#collect">collect a sequence of characters</a> - that are <a href="#space" title="space character">space characters</a>. - The step <dfn id=skip->skip Zs characters</dfn> means that the user agent - must <a href="#collect">collect a sequence of characters</a> that are in - the Unicode character class Zs. In both cases, the collected characters - are not used. <a href="#refsUNICODE">[UNICODE]</a> - - <h4 id=boolean><span class=secno>3.2.2. </span>Boolean attributes</h4> - - <p>A number of attributes in HTML5 are <dfn id=boolean0 title="boolean - attribute">boolean attributes</dfn>. The presence of a boolean attribute - on an element represents the true value, and the absence of the attribute - represents the false value. - - <p>If the attribute is present, its value must either be the empty string - or the attribute's canonical name, exactly, with no leading or trailing - whitespace, and in lowercase. - - <h4 id=numbers><span class=secno>3.2.3. </span>Numbers</h4> - - <h5 id=unsigned><span class=secno>3.2.3.1. </span>Unsigned integers</h5> - - <p>A string is a <dfn id=valid>valid non-negative integer</dfn> if it - consists of one of more characters in the range U+0030 DIGIT ZERO (0) to - U+0039 DIGIT NINE (9). - - <p>The <dfn id=rules>rules for parsing non-negative integers</dfn> are as - given in the following algorithm. When invoked, the steps must be followed - in the order given, aborting at the first step that returns a value. This - algorithm will either return zero, a positive integer, or an error. - Leading spaces are ignored. Trailing spaces and indeed any trailing - garbage characters are ignored. - - <ol> - <li> - <p>Let <var title="">input</var> be the string being parsed. - - <li> - <p>Let <var title="">position</var> be a pointer into <var - title="">input</var>, initially pointing at the start of the string. - - <li> - <p>Let <var title="">value</var> have the value 0. - - <li> - <p><a href="#skip-whitespace">Skip whitespace.</a> - - <li> - <p>If <var title="">position</var> is past the end of <var - title="">input</var>, return an error. - - <li> - <p>If the next character is not one of U+0030 DIGIT ZERO (0) .. U+0039 - DIGIT NINE (9), then return an error. - </li> - <!-- Ok. At this point we know we have a number. It might have - trailing garbage which we'll ignore, but it's a number, and we - won't return an error. --> - - <li> - <p>If the next character is one of U+0030 DIGIT ZERO (0) .. U+0039 DIGIT - NINE (9):</p> - - <ol> - <li>Multiply <var title="">value</var> by ten. - - <li>Add the value of the current character (0..9) to <var - title="">value</var>. - - <li>Advance <var title="">position</var> to the next character. - - <li>If <var title="">position</var> is not past the end of <var - title="">input</var>, return to the top of step 7 in the overall - algorithm (that's the step within which these substeps find - themselves). - </ol> - - <li> - <p>Return <var title="">value</var>. - </ol> - - <h5 id=signed><span class=secno>3.2.3.2. </span>Signed integers</h5> - - <p>A string is a <dfn id=valid0>valid integer</dfn> if it consists of one - of more characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE - (9), optionally prefixed with a U+002D HYPHEN-MINUS ("-") character. - - <p>The <dfn id=rules0>rules for parsing integers</dfn> are similar to the - rules for non-negative integers, and are as given in the following - algorithm. When invoked, the steps must be followed in the order given, - aborting at the first step that returns a value. This algorithm will - either return an integer or an error. Leading spaces are ignored. Trailing - spaces and trailing garbage characters are ignored. - - <ol> - <li> - <p>Let <var title="">input</var> be the string being parsed. - - <li> - <p>Let <var title="">position</var> be a pointer into <var - title="">input</var>, initially pointing at the start of the string. - - <li> - <p>Let <var title="">value</var> have the value 0. - - <li> - <p>Let <var title="">sign</var> have the value "positive". - - <li> - <p><a href="#skip-whitespace">Skip whitespace.</a> - - <li> - <p>If <var title="">position</var> is past the end of <var - title="">input</var>, return an error. - - <li> - <p>If the character indicated by <var title="">position</var> (the first - character) is a U+002D HYPHEN-MINUS ("-") character:</p> - - <ol> - <li>Let <var title="">sign</var> be "negative". - - <li>Advance <var title="">position</var> to the next character. - - <li>If <var title="">position</var> is past the end of <var - title="">input</var>, return an error. - </ol> - - <li> - <p>If the next character is not one of U+0030 DIGIT ZERO (0) .. U+0039 - DIGIT NINE (9), then return an error. - </li> - <!-- Ok. At this point we know we have a number. It might have - trailing garbage which we'll ignore, but it's a number, and we - won't return an error. --> - - <li> - <p>If the next character is one of U+0030 DIGIT ZERO (0) .. U+0039 DIGIT - NINE (9):</p> - - <ol> - <li>Multiply <var title="">value</var> by ten. - - <li>Add the value of the current character (0..9) to <var - title="">value</var>. - - <li>Advance <var title="">position</var> to the next character. - - <li>If <var title="">position</var> is not past the end of <var - title="">input</var>, return to the top of step 9 in the overall - algorithm (that's the step within which these substeps find - themselves). - </ol> - - <li> - <p>If <var title="">sign</var> is "positive", return <var - title="">value</var>, otherwise return 0-<var title="">value</var>. - </ol> - - <h5 id=real-numbers><span class=secno>3.2.3.3. </span>Real numbers</h5> - - <p>A string is a <dfn id=valid1>valid floating point number</dfn> if it - consists of one of more characters in the range U+0030 DIGIT ZERO (0) to - U+0039 DIGIT NINE (9), optionally with a single U+002E FULL STOP (".") - character somewhere (either before these numbers, in between two numbers, - or after the numbers), all optionally prefixed with a U+002D HYPHEN-MINUS - ("-") character. - - <p>The <dfn id=rules1>rules for parsing floating point number values</dfn> - are as given in the following algorithm. As with the previous algorithms, - when this one is invoked, the steps must be followed in the order given, - aborting at the first step that returns a value. This algorithm will - either return a number or an error. Leading spaces are ignored. Trailing - spaces and garbage characters are ignored. - - <ol> - <li> - <p>Let <var title="">input</var> be the string being parsed. - - <li> - <p>Let <var title="">position</var> be a pointer into <var - title="">input</var>, initially pointing at the start of the string. - - <li> - <p>Let <var title="">value</var> have the value 0. - - <li> - <p>Let <var title="">sign</var> have the value "positive". - - <li> - <p><a href="#skip-whitespace">Skip whitespace.</a> - - <li> - <p>If <var title="">position</var> is past the end of <var - title="">input</var>, return an error. - - <li> - <p>If the character indicated by <var title="">position</var> (the first - character) is a U+002D HYPHEN-MINUS ("-") character:</p> - - <ol> - <li>Let <var title="">sign</var> be "negative". - - <li>Advance <var title="">position</var> to the next character. - - <li>If <var title="">position</var> is past the end of <var - title="">input</var>, return an error. - </ol> - - <li> - <p>If the next character is not one of U+0030 DIGIT ZERO (0) .. U+0039 - DIGIT NINE (9) or U+002E FULL STOP ("."), then return an error. - - <li> - <p>If the next character is U+002E FULL STOP ("."), but either that is - the last character or the character after that one is not one of U+0030 - DIGIT ZERO (0) .. U+0039 DIGIT NINE (9), then return an error. - </li> - <!-- Ok. At this point we know we have a number. It might have - trailing garbage which we'll ignore, but it's a number, and we - won't return an error. --> - - <li> - <p>If the next character is one of U+0030 DIGIT ZERO (0) .. U+0039 DIGIT - NINE (9):</p> - - <ol> - <li>Multiply <var title="">value</var> by ten. - - <li>Add the value of the current character (0..9) to <var - title="">value</var>. - - <li>Advance <var title="">position</var> to the next character. - - <li>If <var title="">position</var> is past the end of <var - title="">input</var>, then if <var title="">sign</var> is "positive", - return <var title="">value</var>, otherwise return 0-<var - title="">value</var>. - - <li>Otherwise return to the top of step 10 in the overall algorithm - (that's the step within which these substeps find themselves). - </ol> - - <li> - <p>Otherwise, if the next character is not a U+002E FULL STOP ("."), then - if <var title="">sign</var> is "positive", return <var - title="">value</var>, otherwise return 0-<var title="">value</var>. - - <li> - <p>The next character is a U+002E FULL STOP ("."). Advance <var - title="">position</var> to the character after that. - - <li> - <p>Let <var title="">divisor</var> be 1. - - <li> - <p>If the next character is one of U+0030 DIGIT ZERO (0) .. U+0039 DIGIT - NINE (9):</p> - - <ol> - <li>Multiply <var title="">divisor</var> by ten. - - <li>Add the value of the current character (0..9) divided by <var - title="">divisor</var>, to <var title="">value</var>. - - <li>Advance <var title="">position</var> to the next character. - - <li>If <var title="">position</var> is past the end of <var - title="">input</var>, then if <var title="">sign</var> is "positive", - return <var title="">value</var>, otherwise return 0-<var - title="">value</var>. - - <li>Otherwise return to the top of step 14 in the overall algorithm - (that's the step within which these substeps find themselves). - </ol> - - <li> - <p>Otherwise, if <var title="">sign</var> is "positive", return <var - title="">value</var>, otherwise return 0-<var title="">value</var>. - </ol> - - <h5 id=ratios><span class=secno>3.2.3.4. </span>Ratios</h5> - - <p class=note>The algorithms described in this section are used by the - <code><a href="#progress">progress</a></code> and <code><a - href="#meter">meter</a></code> elements. - - <p>A <dfn id=valid2>valid denominator punctuation character</dfn> is one of - the characters from the table below. There is <dfn id=a-value - title="values associated with denominator punctuation characters">a value - associated with each denominator punctuation character</dfn>, as shown in - the table below. - - <table> - <thead> - <tr> - <th colspan=2>Denominator Punctuation Character - - <th>Value - - <tbody> - <tr> - <td>U+0025 PERCENT SIGN - - <td>% - - <td>100 - - <tr> - <td>U+066A ARABIC PERCENT SIGN - - <td>٪ - - <td>100 - - <tr> - <td>U+FE6A SMALL PERCENT SIGN - - <td>﹪ - - <td>100 - - <tr> - <td>U+FF05 FULLWIDTH PERCENT SIGN - - <td>% - - <td>100 - - <tr> - <td>U+2030 PER MILLE SIGN - - <td>‰ - - <td>1000 - - <tr> - <td>U+2031 PER TEN THOUSAND SIGN - - <td>‱ - - <td>10000 - </table> - - <p>The <dfn id=steps>steps for finding one or two numbers of a ratio in a - string</dfn> are as follows: - - <ol> - <li>If the string is empty, then return nothing and abort these steps. - - <li><a href="#find-a">Find a number</a> in the string according to the - algorithm below, starting at the start of the string. - - <li>If the sub-algorithm in step 2 returned nothing or returned an error - condition, return nothing and abort these steps. - - <li>Set <var title="">number1</var> to the number returned by the - sub-algorithm in step 2. - - <li>Starting with the character immediately after the last one examined by - the sub-algorithm in step 2, skip any characters in the string that are - in the Unicode character class Zs (this might match zero characters). <a - href="#refsUNICODE">[UNICODE]</a> - - <li>If there are still further characters in the string, and the next - character in the string is a <a href="#valid2">valid denominator - punctuation character</a>, set <var title="">denominator</var> to that - character. - - <li>If the string contains any other characters in the range U+0030 DIGIT - ZERO to U+0039 DIGIT NINE, but <var title="">denominator</var> was given - a value in the step 6, return nothing and abort these steps. - - <li>Otherwise, if <var title="">denominator</var> was given a value in - step 6, return <var title="">number1</var> and <var - title="">denominator</var> and abort these steps. - - <li><a href="#find-a">Find a number</a> in the string again, starting - immediately after the last character that was examined by the - sub-algorithm in step 2. - - <li>If the sub-algorithm in step 9 returned nothing or an error condition, - return nothing and abort these steps. - - <li>Set <var title="">number2</var> to the number returned by the - sub-algorithm in step 9. - - <li>If there are still further characters in the string, and the next - character in the string is a <a href="#valid2">valid denominator - punctuation character</a>, return nothing and abort these steps. - - <li>If the string contains any other characters in the range U+0030 DIGIT - ZERO to U+0039 DIGIT NINE, return nothing and abort these steps. - - <li>Otherwise, return <var title="">number1</var> and <var - title="">number2</var>. - </ol> - <!-- XXX again, this should say "positive number" --> - - <p>The algorithm to <dfn id=find-a>find a number</dfn> is as follows. It is - given a string and a starting position, and returns either nothing, a - number, or an error condition. - - <ol> - <li>Starting at the given starting position, ignore all characters in the - given string until the first character that is either a U+002E FULL STOP - or one of the ten characters in the range U+0030 DIGIT ZERO to U+0039 - DIGIT NINE. - - <li>If there are no such characters, return nothing and abort these steps. - - <li>Starting with the character matched in step 1, collect all the - consecutive characters that are either a U+002E FULL STOP or one of the - ten characters in the range U+0030 DIGIT ZERO to U+0039 DIGIT NINE, and - assign this string of one or more characters to <var - title="">string</var>. - - <li>If <var title="">string</var> contains more than one U+002E FULL STOP - character then return an error condition and abort these steps. - - <li>Parse <var title="">string</var> according to the <a - href="#rules1">rules for parsing floating point number values</a>, to - obtain <var title="">number</var>. This step cannot fail (<var - title="">string</var> is guarenteed to be a <a href="#valid1">valid - floating point number</a>). - - <li>Return <var title="">number</var>. - </ol> - - <h5 id=percentages-and-dimensions><span class=secno>3.2.3.5. - </span>Percentages and dimensions</h5> - - <p class=big-issue><dfn id=valid3 title="valid non-negative - percentage">valid non-negative percentages</dfn>, <dfn id=rules2>rules for - parsing dimension values</dfn> (only used by height/width on img, embed, - object — maybe they should do the same as canvas, then this wouldn't - even be needed) - - <h5 id=lists><span class=secno>3.2.3.6. </span>Lists of integers</h5> - - <p>A <dfn id=valid4>valid list of integers</dfn> is a number of <a - href="#valid0" title="valid integer">valid integers</a> separated by - U+002C COMMA characters, with no other characters (e.g. no <a - href="#space" title="space character">space characters</a>). In addition, - there might be restrictions on the number of integers that can be given, - or on the range of values allowed. - - <p>The <dfn id=rules3>rules for parsing a list of integers</dfn> are as - follows: - - <ol> - <li> - <p>Let <var title="">input</var> be the string being parsed. - - <li> - <p>Let <var title="">position</var> be a pointer into <var - title="">input</var>, initially pointing at the start of the string. - - <li> - <p>Let <var title="">numbers</var> be an initially empty list of - integers. This list will be the result of this algorithm. - - <li> - <p>If there is a character in the string <var title="">input</var> at - position <var title="">position</var>, and it is either U+002C COMMA - character or a U+0020 SPACE character, then advance <var - title="">position</var> to the next character in <var - title="">input</var>, or to beyond the end of the string if there are no - more characters. - - <li> - <p>If <var title="">position</var> points to beyond the end of <var - title="">input</var>, return <var title="">numbers</var> and abort. - - <li> - <p>If the character in the string <var title="">input</var> at position - <var title="">position</var> is a U+002C COMMA character or a U+0020 - SPACE character, return to step 4. - - <li> - <p>Let <var title="">negated</var> be false. - - <li> - <p>Let <var title="">value</var> be 0. - - <li> - <p>Let <var title="">multiple</var> be 1. - - <li> - <p>Let <var title="">started</var> be false. - - <li> - <p>Let <var title="">finished</var> be false. - - <li> - <p>Let <var title="">bogus</var> be false. - - <li> - <p><em>Parser:</em> If the character in the string <var - title="">input</var> at position <var title="">position</var> is:</p> - - <dl - class=switch><!-- XXX this doesn't quite match what IE does: http://www.hixie.ch/tests/adhoc/html/flow/image-maps/004-demo.html - I couldn't work out a pattern to IE's results. Let me know if you can see one. --> - - <dt>A U+002D HYPHEN-MINUS character - - <dd> - <p>Follow these substeps:</p> - - <ol> - <li>If <var title="">finished</var> is true, skip to the next step in - the overall set of steps. - - <li>If <var title="">started</var> is true or if <var - title="">bogus</var> is true, let <var title="">negated</var> be - false. - - <li>Otherwise, if <var title="">started</var> is false and if <var - title="">bogus</var> is false, let <var title="">negated</var> be - true. - - <li>Let <var title="">started</var> be true. - </ol> - - <dt>A character in the range U+0030 DIGIT ZERO .. U+0039 DIGIT NINE - - <dd> - <p>Follow these substeps:</p> - - <ol> - <li>If <var title="">finished</var> is true, skip to the next step in - the overall set of steps. - - <li>Let <var title="">n</var> be the value of the digit, interpreted - in base ten, multiplied by <var title="">multiple</var>. - - <li>Add <var title="">n</var> to <var title="">value</var>. - - <li>If <var title="">value</var> is greater than zero, multiply <var - title="">multiple</var> by ten. - - <li>Let <var title="">started</var> be true. - </ol> - - <dt>A U+002C COMMA character - - <dt>A U+0020 SPACE character - - <dd> - <p>Follow these substeps:</p> - - <ol> - <li>If <var title="">started</var> is false, return the <var - title="">numbers</var> list and abort. - - <li>If <var title="">negated</var> is true, then negate <var - title="">value</var>. - - <li>Append <var title="">value</var> to the <var - title="">numbers</var> list. - - <li>Jump to step 4 in the overall set of steps. - </ol> - - <dt>A U+002E FULL STOP character - - <dd> - <p>Follow these substeps:</p> - - <ol> - <li>Let <var title="">finished</var> be true. - </ol> - - <dt>Any other character - - <dd> - <p>Follow these substeps:</p> - - <ol> - <li>If <var title="">finished</var> is true, skip to the next step in - the overall set of steps. - - <li>Let <var title="">negated</var> be false. - - <li>Let <var title="">bogus</var> be true. - - <li>If <var title="">started</var> is true, then return the <var - title="">numbers</var> list, and abort. (The value in <var - title="">value</var> is not appended to the list first; it is - dropped.) - </ol> - </dl> - - <li> - <p>Advance <var title="">position</var> to the next character in <var - title="">input</var>, or to beyond the end of the string if there are no - more characters. - - <li> - <p>If <var title="">position</var> points to a character (and not to - beyond the end of <var title="">input</var>), jump to the big - <em>Parser</em> step above. - - <li> - <p>If <var title="">negated</var> is true, then negate <var - title="">value</var>. - - <li> - <p>If <var title="">started</var> is true, then append <var - title="">value</var> to the <var title="">numbers</var> list, return - that list, and abort. - - <li> - <p>Return the <var title="">numbers</var> list and abort. - </ol> - - <h4 id=dates><span class=secno>3.2.4. </span>Dates and times</h4> - - <p>In the algorithms below, the <dfn id=number>number of days in month <var - title="">month</var> of year <var title="">year</var></dfn> is: - <em>31</em> if <var title="">month</var> is 1, 3, 5, 7, 8, 10, or 12; - <em>30</em> if <var title="">month</var> is 4, 6, 9, or 11; <em>29</em> if - <var title="">month</var> is 2 and <var title="">year</var> is a number - divisible by 400, or if <var title="">year</var> is a number divisible by - 4 but not by 100; and <em>28</em> otherwise. This takes into account leap - years in the Gregorian calendar. <a href="#refsGREGORIAN">[GREGORIAN]</a> - - <h5 id=specific><span class=secno>3.2.4.1. </span>Specific moments in time</h5> - - <p>A string is a <dfn id=valid5>valid datetime</dfn> if it has four digits - (representing the year), a literal hyphen, two digits (representing the - month), a literal hyphen, two digits (representing the day), optionally - some spaces, either a literal T or a space, optionally some more spaces, - two digits (for the hour), a colon, two digits (the minutes), optionally - the seconds (which, if included, must consist of another colon, two digits - (the integer part of the seconds), and optionally a decimal point followed - by one or more digits (for the fractional part of the seconds)), - optionally some spaces, and finally either a literal Z (indicating the - time zone is UTC), or, a plus sign or a minus sign followed by two digits, - a colon, and two digits (for the sign, the hours and minutes of the - timezone offset respectively); with the month-day combination being a - valid date in the given year according to the Gregorian calendar, the hour - values (<var title="">h</var>) being in the range 0 ≤ <var - title="">h</var> ≤ 23, the minute values (<var - title="">m</var>) in the range 0 ≤ <var - title="">m</var> ≤ 59, and the second value (<var - title="">s</var>) being in the range 0 ≤ <var - title="">h</var> < 60. <a - href="#refsGREGORIAN">[GREGORIAN]</a></p> - <!--XXX [GREGORIAN] should point to - <dd id="refsGREGORIAN">[GREGORIAN]</dd> - <dd>(Non-normative) <cite>Inter Gravissimas</cite>, A. Lilius, C. Clavius. Gregory XIII Papal Bulls, February 1582.</dd> - --> - - <p>The digits must be characters in the range U+0030 DIGIT ZERO (0) to - U+0039 DIGIT NINE (9), the hyphens must be a U+002D HYPHEN-MINUS - characters, the T must be a U+0054 LATIN CAPITAL LETTER T, the colons must - be U+003A COLON characters, the decimal point must be a U+002E FULL STOP, - the Z must be a U+005A LATIN CAPITAL LETTER Z, the plus sign must be a - U+002B PLUS SIGN, and the minus U+002D (same as the hyphen). - - <div class=example> - <p>The following are some examples of dates written as <a href="#valid5" - title="valid datetime">valid datetimes</a>.</p> - - <dl> - <dt>"<code>0037-12-13 00:00 Z</code>" - - <dd>Midnight UTC on the birthday of Nero (the Roman Emperor). - - <dt>"<code>1979-10-14T12:00:00.001-04:00</code>" - - <dd>One millisecond after noon on October 14th 1979, in the time zone in - use on the east coast of North America during daylight saving time. - - <dt>"<code>8592-01-01 T 02:09 +02:09</code>" - - <dd>Midnight UTC on the 1st of January, 8592. The time zone associated - with that time is two hours and nine minutes ahead of UTC. - </dl> - - <p>Several things are notable about these dates:</p> - - <ul> - <li>Years with fewer than four digits have to be zero-padded. The date - "37-12-13" would not be a valid date. - - <li>To unambiguously identify a moment in time prior to the introduction - of the Gregorian calendar, the date has to be first converted to the - Gregorian calendar from the calendar in use at the time (e.g. from the - Julian calendar). The date of Nero's birth is the 15th of December 37, - in the Julian Calendar, which is the 13th of December 37 in the - Gregorian Calendar.</li> - <!-- - XXX this might not be true. I can't find a reference that gives - his birthday with an explicit statement about the calendar being - used. However, it seems unlikely that it would be given in the - Gregorian calendar, so I assume sites use the Julian one. --> - - <li>The time and timezone components are not optional. - - <li>Dates before the year 0 or after the year 9999 can't be represented - as a datetime in this version of HTML. - - <li>Time zones differ based on daylight savings time. - </ul> - </div> - - <p class=note>Conformance checkers can use the algorithm below to determine - if a datetime is a valid datetime or not. - - <p>To <dfn id=datetime-parser>parse a string as a datetime value</dfn>, a - user agent must apply the following algorithm to the string. This will - either return a time in UTC, with associated timezone information for - round tripping or display purposes, or nothing, indicating the value is - not a <a href="#valid5">valid datetime</a>. If at any point the algorithm - says that it "fails", this means that it returns nothing. - - <ol> - <li> - <p>Let <var title="">input</var> be the string being parsed. - - <li> - <p>Let <var title="">position</var> be a pointer into <var - title="">input</var>, initially pointing at the start of the string. - - <li> - <p><a href="#collect">Collect a sequence of characters</a> in the range - U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the collected - sequence is not exactly four characters long, then fail. Otherwise, - interpret the resulting sequence as a base ten integer. Let that number - be the <var title="">year</var>. - - <li> - <p>If <var title="">position</var> is beyond the end of <var - title="">input</var> or if the character at <var title="">position</var> - is not a U+002D HYPHEN-MINUS character, then fail. Otherwise, move <var - title="">position</var> forwards one character. - - <li> - <p><a href="#collect">Collect a sequence of characters</a> in the range - U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the collected - sequence is not exactly two characters long, then fail. Otherwise, - interpret the resulting sequence as a base ten integer. Let that number - be the <var title="">month</var>. - - <li>If <var title="">month</var> is not a number in the range - 1 ≤ <var title="">month</var> ≤ 12, then fail. - - <li> - <p>Let <var title="">maxday</var> be the <a href="#number">number of days - in month <var title="">month</var> of year <var title="">year</var></a>. - - <li> - <p>If <var title="">position</var> is beyond the end of <var - title="">input</var> or if the character at <var title="">position</var> - is not a U+002D HYPHEN-MINUS character, then fail. Otherwise, move <var - title="">position</var> forwards one character. - - <li> - <p><a href="#collect">Collect a sequence of characters</a> in the range - U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the collected - sequence is not exactly two characters long, then fail. Otherwise, - interpret the resulting sequence as a base ten integer. Let that number - be the <var title="">day</var>. - - <li> - <p>If <var title="">day</var> is not a number in the range - 1 ≤ <var title="">month</var> ≤ <var - title="">maxday</var>, then fail. - - <li> - <p><a href="#collect">Collect a sequence of characters</a> that are - either U+0054 LATIN CAPITAL LETTER T characters or <a href="#space" - title="space character">space characters</a>. If the collected sequence - is zero characters long, or if it contains more than one U+0054 LATIN - CAPITAL LETTER T character, then fail. - - <li> - <p><a href="#collect">Collect a sequence of characters</a> in the range - U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the collected - sequence is not exactly two characters long, then fail. Otherwise, - interpret the resulting sequence as a base ten integer. Let that number - be the <var title="">hour</var>. - - <li>If <var title="">hour</var> is not a number in the range - 0 ≤ <var title="">hour</var> ≤ 23, then fail. - - <li> - <p>If <var title="">position</var> is beyond the end of <var - title="">input</var> or if the character at <var title="">position</var> - is not a U+003A COLON character, then fail. Otherwise, move <var - title="">position</var> forwards one character. - - <li> - <p><a href="#collect">Collect a sequence of characters</a> in the range - U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the collected - sequence is not exactly two characters long, then fail. Otherwise, - interpret the resulting sequence as a base ten integer. Let that number - be the <var title="">minute</var>. - - <li>If <var title="">minute</var> is not a number in the range - 0 ≤ <var title="">minute</var> ≤ 59, then fail. - - <li> - <p>Let <var title="">second</var> be a string with the value "0". - - <li> - <p>If <var title="">position</var> is beyond the end of <var - title="">input</var>, then fail. - - <li> - <p>If the character at <var title="">position</var> is a U+003A COLON, - then:</p> - - <ol> - <li> - <p>Advance <var title="">position</var> to the next character in <var - title="">input</var>. - - <li> - <p>If <var title="">position</var> is beyond the end of <var - title="">input</var>, or at the last character in <var - title="">input</var>, or if the next <em>two</em> characters in <var - title="">input</var> starting at <var title="">position</var> are not - two characters both in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT - NINE (9), then fail. - - <li> - <p><a href="#collect">Collect a sequence of characters</a> that are - either characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT - NINE (9) or U+002E FULL STOP characters. If the collected sequence has - more than one U+002E FULL STOP characters, or if the last character in - the sequence is a U+002E FULL STOP character, then fail. Otherwise, - let the collected string be <var title="">second</var> instead of its - previous value. - </ol> - - <li> - <p>Interpret <var title="">second</var> as a base ten number (possibly - with a fractional part). Let that number be <var title="">second</var> - instead of the string version. - - <li>If <var title="">second</var> is not a number in the range - 0 ≤ <var title="">hour</var> < 60, then fail. - (The values 60 and 61 are not allowed: leap seconds cannot be represented - by datetime values.) - - <li> - <p>If <var title="">position</var> is beyond the end of <var - title="">input</var>, then fail. - - <li> - <p><a href="#skip-whitespace">Skip whitespace.</a> - - <li> - <p>If the character at <var title="">position</var> is a U+005A LATIN - CAPITAL LETTER Z, then:</p> - - <ol> - <li> - <p>Let <var title="">timezone<sub title="">hours</sub></var> be 0. - - <li> - <p>Let <var title="">timezone<sub title="">minutes</sub></var> be 0. - - <li> - <p>Advance <var title="">position</var> to the next character in <var - title="">input</var>. - </ol> - - <li> - <p>Otherwise, if the character at <var title="">position</var> is either - a U+002B PLUS SIGN ("+") or a U+002D HYPHEN-MINUS ("-"), then:</p> - - <ol> - <li> - <p>If the character at <var title="">position</var> is a U+002B PLUS - SIGN ("+"), let <var title="">sign</var> be "positive". Otherwise, - it's a U+002D HYPHEN-MINUS ("-"); let <var title="">sign</var> be - "negative". - - <li> - <p>Advance <var title="">position</var> to the next character in <var - title="">input</var>. - - <li> - <p><a href="#collect">Collect a sequence of characters</a> in the range - U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the collected - sequence is not exactly two characters long, then fail. Otherwise, - interpret the resulting sequence as a base ten integer. Let that - number be the <var title="">timezone<sub title="">hours</sub></var>. - - <li>If <var title="">timezone<sub title="">hours</sub></var> is not a - number in the range 0 ≤ <var title="">timezone<sub - title="">hours</sub></var> ≤ 23, then fail. - - <li>If <var title="">sign</var> is "negative", then negate <var - title="">timezone<sub title="">hours</sub></var>. - - <li> - <p>If <var title="">position</var> is beyond the end of <var - title="">input</var> or if the character at <var - title="">position</var> is not a U+003A COLON character, then fail. - Otherwise, move <var title="">position</var> forwards one character. - - <li> - <p><a href="#collect">Collect a sequence of characters</a> in the range - U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the collected - sequence is not exactly two characters long, then fail. Otherwise, - interpret the resulting sequence as a base ten integer. Let that - number be the <var title="">timezone<sub title="">minutes</sub></var>. - - <li>If <var title="">timezone<sub title="">minutes</sub></var> is not a - number in the range 0 ≤ <var title="">timezone<sub - title="">minutes</sub></var> ≤ 59, then fail. - </ol> - - <li> - <p>If <var title="">position</var> is <em>not</em> beyond the end of <var - title="">input</var>, then fail. - - <li> - <p>Let <var title="">time</var> be the moment in time at year <var - title="">year</var>, month <var title="">month</var>, day <var - title="">day</var>, hours <var title="">hour</var>, minute <var - title="">minute</var>, second <var title="">second</var>, adding <var - title="">timezone<sub title="">hours</sub></var> hours and <var - title="">timezone<sub title="">minutes</sub></var> minutes. That moment - in time is a moment in the UTC timezone. - - <li> - <p>Let <var title="">timezone</var> be <var title="">timezone<sub - title="">hours</sub></var> hours and <var title="">timezone<sub - title="">minutes</sub></var> minutes from UTC. - - <li> - <p>Return <var title="">time</var> and <var title="">timezone</var>. - </ol> - - <h5 id=vaguer><span class=secno>3.2.4.2. </span>Vaguer moments in time</h5> - - <p>This section defines <dfn id=date-or title="date or time string">date or - time strings</dfn>. There are two kinds, <dfn id=date-or0 title="date or - time string in content">date or time strings in content</dfn>, and <dfn - id=date-or1 title="date or time string in attributes">date or time strings - in attributes</dfn>. The only difference is in the handling of whitespace - characters. - - <p>To parse a <a href="#date-or">date or time string</a>, user agents must - use the following algorithm. A <a href="#date-or">date or time string</a> - is a <em>valid</em> date or time string if the following algorithm, when - run on the string, doesn't say the string is invalid. - - <p>The algorithm may return nothing (in which case the string will be - invalid), or it may return a date, a time, a date and a time, or a date - and a time and and a timezone. Even if the algorithm returns one or more - values, the string can still be invalid. - - <ol><!-- INIT --> - - <li> - <p>Let <var title="">input</var> be the string being parsed. - - <li> - <p>Let <var title="">position</var> be a pointer into <var - title="">input</var>, initially pointing at the start of the string. - - <li> - <p>Let <var title="">results</var> be the collection of results that are - to be returned (one or more of a date, a time, and a timezone), - initially empty. If the algorithm aborts at any point, then whatever is - currently in <var title="">results</var> must be returned as the result - of the algorithm. - </li> - <!-- LEADING WHITESPACE --> - - <li> - <p>For the "in content" variant: <a href="#skip-">skip Zs characters</a>; - for the "in attributes" variant: <a href="#skip-whitespace">skip - whitespace</a>. - </li> - <!-- XXX skip whitespace in attribute? - really? --> - <!-- YEAR or HOUR --> - - <li> - <p><a href="#collect">Collect a sequence of characters</a> in the range - U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the collected - sequence is empty, then the string is invalid; abort these steps. - - <li> - <p>Let the sequence of characters collected in the last step be <var - title="">s</var>. - - <li> - <p>If <var title="">position</var> is past the end of <var - title="">input</var>, the string is invalid; abort these steps. - - <li> - <p>If the character at <var title="">position</var> is <em>not</em> a - U+003A COLON character, then:</p> - <!-- DATE --> - <ol> - <li> - <p>If the character at <var title="">position</var> is not a U+002D - HYPHEN-MINUS ("-") character either, then the string is invalid, abort - these steps. - </li> - <!-- YEAR --> - - <li> - <p>If the sequence <var title="">s</var> is not exactly four digits - long, then the string is invalid. (This does not stop the algorithm, - however.) - - <li> - <p>Interpret the sequence of characters collected in step 5 as a base - ten integer, and let that number be <var title="">year</var>. - - <li> - <p>Advance <var title="">position</var> past the U+002D HYPHEN-MINUS - ("-") character. - </li> - <!-- MONTH --> - - <li> - <p><a href="#collect">Collect a sequence of characters</a> in the range - U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the collected - sequence is empty, then the string is invalid; abort these steps. - - <li> - <p>If the sequence collected in the last step is not exactly two digits - long, then the string is invalid. - - <li> - <p>Interpret the sequence of characters collected two steps ago as a - base ten integer, and let that number be <var title="">month</var>. - - <li>If <var title="">month</var> is not a number in the range - 1 ≤ <var title="">month</var> ≤ 12, then the - string is invalid, abort these steps. - - <li> - <p>Let <var title="">maxday</var> be the <a href="#number">number of - days in month <var title="">month</var> of year <var - title="">year</var></a>. - - <li> - <p>If <var title="">position</var> is past the end of <var - title="">input</var>, or if the character at <var - title="">position</var> is <em>not</em> a U+002D HYPHEN-MINUS ("-") - character, then the string is invalid, abort these steps. Otherwise, - advance <var title="">position</var> to the next character. - </li> - <!-- DAY --> - - <li> - <p><a href="#collect">Collect a sequence of characters</a> in the range - U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the collected - sequence is empty, then the string is invalid; abort these steps. - - <li> - <p>If the sequence collected in the last step is not exactly two digits - long, then the string is invalid. - - <li> - <p>Interpret the sequence of characters collected two steps ago as a - base ten integer, and let that number be <var title="">day</var>. - - <li> - <p>If <var title="">day</var> is not a number in the range - 1 ≤ <var title="">day</var> ≤ <var - title="">maxday</var>, then the string is invalid, abort these steps. - - <li> - <p>Add the date represented by <var title="">year</var>, <var - title="">month</var>, and <var title="">day</var> to the <var - title="">results</var>. - </li> - <!-- WHITESPACE --> - - <li> - <p>For the "in content" variant: <a href="#skip-">skip Zs - characters</a>; for the "in attributes" variant: <a - href="#skip-whitespace">skip whitespace</a>. - - <li> - <p>If the character at <var title="">position</var> is a U+0054 LATIN - CAPITAL LETTER T, then move <var title="">position</var> forwards one - character. - - <li> - <p>For the "in content" variant: <a href="#skip-">skip Zs - characters</a>; for the "in attributes" variant: <a - href="#skip-whitespace">skip whitespace</a>. - </li> - <!-- at this point, if <var title="">position</var> points to a - number, we know that we passed at least one space or a T, because - otherwise the number would have been slurped up in the last - "collect" step. --> - <!-- HOUR --> - - <li> - <p><a href="#collect">Collect a sequence of characters</a> in the range - U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the collected - sequence is empty, then the string is invalid; abort these steps. - - <li> - <p>Let <var title="">s</var> be the sequence of characters collected in - the last step. - </ol> - </li> - <!-- TIME --> - - <li> - <p>If <var title="">s</var> is not exactly two digits long, then the - string is invalid. - - <li> - <p>Interpret the sequence of characters collected two steps ago as a base - ten integer, and let that number be <var title="">hour</var>. - - <li> - <p>If <var title="">hour</var> is not a number in the range - 0 ≤ <var title="">hour</var> ≤ 23, then the - string is invalid, abort these steps. - - <li> - <p>If <var title="">position</var> is past the end of <var - title="">input</var>, or if the character at <var - title="">position</var> is <em>not</em> a U+003A COLON character, then - the string is invalid, abort these steps. Otherwise, advance <var - title="">position</var> to the next character. - </li> - <!-- MINUTE --> - - <li> - <p><a href="#collect">Collect a sequence of characters</a> in the range - U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the collected - sequence is empty, then the string is invalid; abort these steps. - - <li> - <p>If the sequence collected in the last step is not exactly two digits - long, then the string is invalid. - - <li> - <p>Interpret the sequence of characters collected two steps ago as a base - ten integer, and let that number be <var title="">minute</var>. - - <li> - <p>If <var title="">minute</var> is not a number in the range - 0 ≤ <var title="">minute</var> ≤ 59, then the - string is invalid, abort these steps. - </li> - <!-- SECOND --> - - <li> - <p>Let <var title="">second</var> be 0. It may be changed to another - value in the next step. - - <li> - <p>If <var title="">position</var> is not past the end of <var - title="">input</var> and the character at <var title="">position</var> - is a U+003A COLON character, then:</p> - - <ol> - <li> - <p><a href="#collect">Collect a sequence of characters</a> that are - either characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT - NINE (9) or are U+002E FULL STOP. If the collected sequence is empty, - or contains more than one U+002E FULL STOP character, then the string - is invalid; abort these steps. - - <li> - <p>If the first character in the sequence collected in the last step is - not in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9), then - the string is invalid. - - <li> - <p>Interpret the sequence of characters collected two steps ago as a - base ten number (possibly with a fractional part), and let that number - be <var title="">second</var>. - - <li> - <p>If <var title="">second</var> is not a number in the range - 0 ≤ <var title="">minute</var> < 60, then - the string is invalid, abort these steps. - </ol> - - <li> - <p>Add the time represented by <var title="">hour</var>, <var - title="">minute</var>, and <var title="">second</var> to the <var - title="">results</var>. - </li> - <!-- TIME ZONE --> - - <li> - <p>If <var title="">results</var> has both a date and a time, then:</p> - - <ol> - <li> - <p>For the "in content" variant: <a href="#skip-">skip Zs - characters</a>; for the "in attributes" variant: <a - href="#skip-whitespace">skip whitespace</a>. - - <li> - <p>If <var title="">position</var> is past the end of <var - title="">input</var>, then skip to the next step in the overall set of - steps.</p> - <!-- UTC --> - - <li> - <p>Otherwise, if the character at <var title="">position</var> is a - U+005A LATIN CAPITAL LETTER Z, then:</p> - - <ol> - <li> - <p>Add the timezone corresponding to UTC (zero offset) to the <var - title="">results</var>. - - <li> - <p>Advance <var title="">position</var> to the next character in <var - title="">input</var>. - - <li> - <p>Skip to the next step in the overall set of steps. - </ol> - </li> - <!-- EXPLICIT TIMEZONE OFFSET --> - - <li> - <p>Otherwise, if the character at <var title="">position</var> is - either a U+002B PLUS SIGN ("+") or a U+002D HYPHEN-MINUS ("-"), then:</p> - - <ol><!-- SIGN --> - - <li> - <p>If the character at <var title="">position</var> is a U+002B PLUS - SIGN ("+"), let <var title="">sign</var> be "positive". Otherwise, - it's a U+002D HYPHEN-MINUS ("-"); let <var title="">sign</var> be - "negative". - </li> - <!-- HOURS --> - - <li> - <p>Advance <var title="">position</var> to the next character in <var - title="">input</var>. - - <li> - <p><a href="#collect">Collect a sequence of characters</a> in the - range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the - collected sequence is not exactly two characters long, then the - string is invalid. - - <li> - <p>Interpret the sequence collected in the last step as a base ten - number, and let that number be <var title="">timezone<sub - title="">hours</sub></var>. - - <li>If <var title="">timezone<sub title="">hours</sub></var> is not a - number in the range 0 ≤ <var title="">timezone<sub - title="">hours</sub></var> ≤ 23, then the string is - invalid; abort these steps. - - <li>If <var title="">sign</var> is "negative", then negate <var - title="">timezone<sub title="">hours</sub></var>. - - <li> - <p>If <var title="">position</var> is beyond the end of <var - title="">input</var> or if the character at <var - title="">position</var> is not a U+003A COLON character, then the - string is invalid; abort these steps. Otherwise, move <var - title="">position</var> forwards one character. - </li> - <!-- MINUTES --> - - <li> - <p><a href="#collect">Collect a sequence of characters</a> in the - range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9). If the - collected sequence is not exactly two characters long, then the - string is invalid. - - <li> - <p>Interpret the sequence collected in the last step as a base ten - number, and let that number be <var title="">timezone<sub - title="">minutes</sub></var>. - - <li>If <var title="">timezone<sub title="">minutes</sub></var> is not - a number in the range 0 ≤ <var title="">timezone<sub - title="">minutes</sub></var> ≤ 59, then the string is - invalid; abort these steps. - - <li> - <p>Add the timezone corresponding to an offset of <var - title="">timezone<sub title="">hours</sub></var> hours and <var - title="">timezone<sub title="">minutes</sub></var> minutes to the - <var title="">results</var>. - - <li> - <p>Skip to the next step in the overall set of steps. - </ol> - - <li> - <p>Otherwise, the string is invalid; abort these steps. - </ol> - - <li> - <p>For the "in content" variant: <a href="#skip-">skip Zs characters</a>; - for the "in attributes" variant: <a href="#skip-whitespace">skip - whitespace</a>. - - <li> - <p>If <var title="">position</var> is <em>not</em> past the end of <var - title="">input</var>, then the string is invalid.</p> - - <li> - <p>Abort these steps (the string is parsed). - </ol> - - <h4 id=time-offsets><span class=secno>3.2.5. </span>Time offsets</h4> - - <p class=big-issue><dfn id=valid6>valid time offset</dfn>, <dfn - id=rules4>rules for parsing time offsets</dfn>, <dfn id=time-offset>time - offset serialisation rules</dfn>; in the format "5d4h3m2s1ms" or "3m 9.2s" - or "00:00:00.00" or similar. - - <h4 id=tokens><span class=secno>3.2.6. </span>Tokens</h4> - - <p>A <dfn id=set-of>set of space-separated tokens</dfn> is a set of zero or - more words separated by one or more <a href="#space" title="space - character">space characters</a>, where words consist of any string of one - or more characters, none of which are <a href="#space" title="space - character">space characters</a>. - - <p>A string containing a <a href="#set-of">set of space-separated - tokens</a> may have leading or trailing <a href="#space" title="space - character">space characters</a>. - - <p>An <dfn id=unordered>unordered set of space-separated tokens</dfn> is a - <a href="#set-of">set of space-separated tokens</a> where none of the - words are duplicated. - - <p>An <dfn id=ordered>ordered set of unique space-separated tokens</dfn> is - a <a href="#set-of">set of space-separated tokens</a> where none of the - words are duplicated but where the order of the tokens is meaningful. - - <p>When a user agent has to <dfn id=split>split a string on spaces</dfn>, - it must use the following algorithm: - - <ol> - <li> - <p>Let <var title="">input</var> be the string being parsed. - - <li> - <p>Let <var title="">position</var> be a pointer into <var - title="">input</var>, initially pointing at the start of the string. - - <li> - <p>Let <var title="">tokens</var> be a list of tokens, initially empty. - - <li> - <p><a href="#skip-whitespace">Skip whitespace</a> - - <li> - <p>While <var title="">position</var> is not past the end of <var - title="">input</var>:</p> - - <ol> - <li> - <p><a href="#collect">Collect a sequence of characters</a> that are not - <a href="#space" title="space character">space characters</a>. - - <li> - <p>Add the string collected in the previous step to <var - title="">tokens</var>. - - <li> - <p><a href="#skip-whitespace">Skip whitespace</a> - </ol> - - <li> - <p>Return <var title="">tokens</var>. - </ol> - - <p>When a user agent has to <dfn id=remove0>remove a token from a - string</dfn>, it must use the following algorithm: - - <ol> - <li> - <p>Let <var title="">input</var> be the string being modified. - - <li> - <p>Let <var title="">token</var> be the token being removed. It will not - contain any <a href="#space" title="space character">space - characters</a>. - - <li> - <p>Let <var title="">output</var> be the output string, initially empty. - - <li> - <p>Let <var title="">position</var> be a pointer into <var - title="">input</var>, initially pointing at the start of the string. - - <li> - <p>If <var title="">position</var> is beyond the end of <var - title="">input</var>, set the string being modified to <var - title="">output</var>, and abort these steps. - - <li> - <p>If the character at <var title="">position</var> is a <a - href="#space">space character</a>: - - <ol> - <li> - <p>Append the character at <var title="">position</var> to the end of - <var title="">output</var>. - - <li> - <p>Increment <var title="">position</var> so it points at the next - character in <var title="">input</var>. - - <li> - <p>Return to step 5 in the overall set of steps. - </ol> - - <li> - <p>Otherwise, the character at <var title="">position</var> is the first - character of a token. <a href="#collect">Collect a sequence of - characters</a> that are not <a href="#space" title="space - character">space characters</a>, and let that be <var title="">s</var>. - - <li> - <p>If <var title="">s</var> is exactly equal to <var - title="">token</var>, then:</p> - - <ol> - <li> - <p><a href="#skip-whitespace">Skip whitespace</a> (in <var - title="">input</var>). - - <li> - <p>Remove any <a href="#space" title="space character">space - characters</a> currently at the end of <var title="">output</var>. - - <li> - <p>If <var title="">position</var> is not past the end of <var - title="">input</var>, and <var title="">output</var> is not the empty - string, append a single U+0020 SPACE character at the end of <var - title="">output</var>. - </ol> - - <li> - <p>Otherwise, append <var title="">s</var> to the end of <var - title="">output</var>. - - <li> - <p>Return to step 6 in the overall set of steps. - </ol> - - <p class=note>This causes any occurrences of the token to be removed from - the string, and any spaces that were surrounding the token to be collapsed - to a single space, except at the start and end of the string, where such - spaces are removed. - - <h4 id=keywords><span class=secno>3.2.7. </span>Keywords and enumerated - attributes</h4> - - <p>Some attributes are defined as taking one of a finite set of keywords. - Such attributes are called <dfn id=enumerated title="enumerated - attribute">enumerated attributes</dfn>. The keywords are each defined to - map to a particular <em>state</em> (several keywords might map to the same - state, in which case some of the keywords are synonyms of each other; - additionally, some of the keywords can be said to be non-conforming, and - are only in the specification for historical reasons). In addition, two - default states can be given. The first is the <em>invalid value - default</em>, the second is the <em>missing value default</em>. - - <p>If an enumerated attribute is specified, the attribute's value must be - one of the given keywords that are not said to be non-conforming, with no - leading or trailing whitespace. The keyword may use any mix of uppercase - and lowercase letters.<!-- XXX should - say "uppercase and lowercase ASCII letters" or some such --> - - <p>When the attribute is specified, if its value - <span>case-insensitively</span><!-- XXX ascii case folding --> matches one - of the given keywords then that keyword's state is the state that the - attribute represents. If the attribute value matches none of the given - keywords, but the attribute has an <em>invalid value default</em>, then - the attribute represents that state. Otherwise, if the attribute value - matches none of the keywords but there is a <em>missing value default</em> - state defined, then <em>that</em> is the state represented by the - attribute. Otherwise, there is no default, and invalid values must simply - be ignored. - - <p>When the attribute is <em>not</em> specified, if there is a <em>missing - value default</em> state defined, then that is the state represented by - the (missing) attribute. Otherwise, the absence of the attribute means - that there is no state represented. - - <p class=note>The empty string can be one of the keywords in some cases. - For example the <code title=attr-contenteditable><a - href="#contenteditable0">contenteditable</a></code> attribute has two - states: <em>true</em>, matching the <code title="">true</code> keyword and - the empty string, <em>false</em>, matching <code title="">false</code> and - all other keywords (it's the <em>invalid value default</em>). It could - further be thought of as having a third state <em>inherit</em>, which - would be the default when the attribute is not specified at all (the - <em>missing value default</em>), but for various reasons that isn't the - way this specification actually defines it. - - <h4 id=syntax-references><span class=secno>3.2.8. </span>References</h4> - - <p>A <dfn id=valid7>valid hashed ID reference</dfn> to an element of type - <var title="">type</var> is a string consisting of a U+0023 NUMBER SIGN - (<code title="">#</code>) character followed by a string which exactly - matches the value of the <code title=attr-id><a href="#id">id</a></code> - attribute of an element in the document with type <var - title="">type</var>. - - <p>The <dfn id=rules5>rules for parsing a hashed ID reference</dfn> to an - element of type <var title="">type</var> are as follows: - - <ol> - <li> - <p>If the string being parsed does not contain a U+0023 NUMBER SIGN - character, or if the first such character in the string is the last - character in the string, then return null and abort these steps. - - <li> - <p>Let <var title="">s</var> be the string from the character immediately - after the first U+0023 NUMBER SIGN character in the string being parsed - up to the end of that string. - - <li> - <p>Return the first element of type <var title="">type</var> that has an - <code title=attr-id><a href="#id">id</a></code> or <code - title="">name</code> attribute whose value case-insensitively matches - <var title="">s</var>. - </ol> - - <h3 id=documents0><span class=secno>3.3. </span>Documents and document - fragments</h3> - - <h4 id=semantics0><span class=secno>3.3.1. </span>Semantics</h4> - - <p>Elements, attributes, and attribute values in HTML are defined (by this - specification) to have certain meanings (semantics). For example, the - <code><a href="#ol">ol</a></code> element represents an ordered list, and - the <code title=lang>lang</code> attribute represents the language of the - content. - - <p>Authors must only use elements, attributes, and attribute values for - their appropriate semantic purposes. - - <div class=example> - <p>For example, the following document is non-conforming, despite being - syntactically correct:</p> - - <pre><!DOCTYPE html> -<html lang="en-GB"> - <head> <title> Demonstration </title> </head> - <body> - <table> - <tr> <td> My favourite animal is the cat. </td> </tr> - <tr> - <td> - —<a href="http://example.org/~ernest/"><cite>Ernest</cite></a>, - in an essay from 1992 - </td> - </tr> - </table> - </body> -</html></pre> - - <p>...because the data placed in the cells is clearly not tabular data. A - corrected version of this document might be:</p> - - <pre><!DOCTYPE html> -<html lang="en-GB"> - <head> <title> Demonstration </title> </head> - <body> - <blockquote> - <p> My favourite animal is the cat. </p> - </blockquote> - <p> - —<a href="http://example.org/~ernest/"><cite>Ernest</cite></a>, - in an essay from 1992 - </p> - </body> -</html></pre> - - <p>This next document fragment, intended to represent the heading of a - corporate site, is similarly non-conforming because the second line is - not intended to be a heading of a subsection, but merely a subheading or - subtitle (a subordinate heading for the same section).</p> - - <pre><body> - <h1>ABC Company</h1> - <h2>Leading the way in widget design since 1432</h2> - ...</pre> - - <p>The <code><a href="#header">header</a></code> element should be used in - these kinds of situations:</p> - - <pre><body> - <header> - <h1>ABC Company</h1> - <h2>Leading the way in widget design since 1432</h2> - </header> - ...</pre> - </div> - - <p>Through scripting and using other mechanisms, the values of attributes, - text, and indeed the entire structure of the document may change - dynamically while a user agent is processing it. The semantics of a - document at an instant in time are those represented by the state of the - document at that instant in time, and the semantics of a document can - therefore change over time. User agents must update their presentation of - the document as this occurs. - - <p class=example>HTML has a <code><a href="#progress">progress</a></code> - element that describes a progress bar. If its "value" attribute is - dynamically updated by a script, the UA would update the rendering to show - the progress changing. - - <h4 id=structure0><span class=secno>3.3.2. </span>Structure</h4> - - <p>All the elements in this specification have a defined content model, - which describes what nodes are allowed inside the elements, and thus what - the structure of an HTML document or fragment must look like. Authors must - only put elements inside an element if that element allows them to be - there according to its content model. - - <p class=note>As noted in the conformance and terminology sections, for the - purposes of determining if an element matches its content model or not, <a - href="#text-node" title="text node"><code>CDATASection</code> nodes in the - DOM are treated as equivalent to <code>Text</code> nodes</a>, and <a - href="#entity-references">entity reference nodes are treated as if they - were expanded in place</a>. - - <p>The <a href="#space" title="space character">space characters</a> are - always allowed between elements. User agents represent these characters - between elements in the source markup as text nodes in the - DOM.<!-- not a conf criteria since the parser now requires this - --> - Empty <a href="#text-node" title="text node">text nodes</a> and <a - href="#text-node" title="text node">text nodes</a> consisting of just - sequences of those characters are considered <dfn - id=inter-element>inter-element whitespace</dfn>. - - <p><a href="#inter-element">Inter-element whitespace</a>, comment nodes, - and processing instruction nodes must be ignored when establishing whether - an element matches its content model or not, and must be ignored when - following algorithms that define document and element semantics. - - <p>An element <var title="">A</var> is said to be <dfn - id=preceeded>preceeded or followed</dfn> by a second element <var - title="">B</var> if <var title="">A</var> and <var title="">B</var> have - the same parent node and there are no other element nodes or text nodes - (other than <a href="#inter-element">inter-element whitespace</a>) between - them. - - <p>Authors must only use <a href="#elements1">elements in the HTML - namespace</a> in the contexts where they are allowed, as defined for each - element. For XML compound documents, these contexts could be inside - elements from other namespaces, if those elements are defined as providing - the relevant contexts. - - <div class=example> - <p>The SVG specification defines the SVG <code>foreignObject</code> - element as allowing foreign namespaces to be included, thus allowing - compound documents to be created by inserting subdocument content under - that element. <em>This</em> specification defines the XHTML <code><a - href="#html">html</a></code> element as being allowed where subdocument - fragments are allowed in a compound document. Together, these two - definitions mean that placing an XHTML <code><a - href="#html">html</a></code> element as a child of an SVG - <code>foreignObject</code> element is conforming.</p> - </div> - - <h4 id=kinds><span class=secno>3.3.3. </span>Kinds of elements</h4> - - <p>Each element in HTML falls into zero or more categories that group - elements with similar characteristics together. This specification uses - the following categories: - - <ul class=brief> - <li><a href="#metadata">Metadata elements</a> - - <li><a href="#sectioning">Sectioning elements</a> - - <li><a href="#block-level0">Block-level elements</a> - - <li><a href="#strictly">Strictly inline-level content</a> - - <li><a href="#structured">Structured inline-level elements</a> - - <li><a href="#interactive1">Interactive elements</a> - - <li><span>Form control elements</span> - </ul> - <!-- XXX check that all the above got a section defining them, - however briefly --> - <!-- XXX check that the element definitions also link to those - sections --> - - <p>Some elements have unique requirements and do not fit into any - particular category. - - <p>In addition, some elements represent various common concepts; for - example, some elements represent <span>paragraphs</span>. - - <h5 id=block-level><span class=secno>3.3.3.1. </span><dfn - id=block-level0>Block-level elements</dfn></h5> - - <p>Block-level elements are used for structural grouping of page content. - - <p>There are several kinds of block-level elements: - - <ul> - <li>Some can only contain other block-level elements: <code><a - href="#blockquote">blockquote</a></code>, <code><a - href="#section">section</a></code>, <code><a - href="#article">article</a></code>, <code><a - href="#header">header</a></code>. - - <li>Some can only contain <a href="#inline-level0">inline-level - content</a>: <code><a href="#p">p</a></code>, <code><a - href="#h1">h1</a></code>-<code><a href="#h6">h6</a></code>, <code><a - href="#address">address</a></code>. - - <li>Some can contain either block-level elements or <a - href="#inline-level0">inline-level content</a> (but not both): <code><a - href="#nav">nav</a></code>, <code><a href="#aside">aside</a></code>, - <code><a href="#footer">footer</a></code>, <code><a - href="#div">div</a></code>. - - <li>Finally, some have very specific content models: <code><a - href="#ul">ul</a></code>, <code><a href="#ol">ol</a></code>, <code><a - href="#dl">dl</a></code>, <code><a href="#table">table</a></code>, - <code><a href="#script0">script</a></code>. - </ul> - - <p>There are also elements that seem to be block-level but aren't, such as - <code><a href="#body0">body</a></code>, <code><a href="#li">li</a></code>, - <code><a href="#dt">dt</a></code>, <code><a href="#dd">dd</a></code>, and - <code><a href="#td">td</a></code>. These elements are allowed only in - specific places, not simply anywhere that block-level elements are - allowed. - - <p>Some block-level elements play multiple roles. For instance, the - <code><a href="#script0">script</a></code> elements is allowed inside - <code><a href="#head">head</a></code> elements and can also be used as <a - href="#inline-level0">inline-level content</a>. Similarly, the <code><a - href="#ul">ul</a></code>, <code><a href="#ol">ol</a></code>, <code><a - href="#dl">dl</a></code>, <code><a href="#table">table</a></code>, and - <code><a href="#blockquote">blockquote</a></code> elements play dual roles - as both block-level and inline-level elements. - - <h5 id=inline-level><span class=secno>3.3.3.2. </span><dfn - id=inline-level0>Inline-level content</dfn></h5> - - <p>Inline-level content consists of text and various elements to annotate - the text, as well as some <a href="#embedded0">embedded content</a> (such - as images or sound clips). - - <p>Inline-level content comes in various types: - - <dl> - <dt><dfn id=strictly>Strictly inline-level content</dfn> - - <dd>Text, <a href="#embedded0">embedded content</a>, and elements that - annotate the text without introducing structural grouping. For example: - <code><a href="#a">a</a></code>, <code><a href="#meter">meter</a></code>, - <code><a href="#img">img</a></code>. Elements used in contexts allowing - only strictly inline-level content must not have any descendants that are - anything other than strictly inline-level content. - - <dt><dfn id=structured>Structured inline-level elements</dfn> - - <dd>Block-level elements that can also be used as inline-level content. - For example: <code><a href="#ol">ol</a></code>, <code><a - href="#blockquote">blockquote</a></code>, <code><a - href="#table">table</a></code>. - </dl> - - <p>Some elements are defined to have as a content model <dfn - id=significant>significant inline content</dfn>. This means that at least - one descendant of the element must be <a href="#significant0">significant - text</a> or <a href="#embedded0">embedded content</a>. - - <p>Unless an element's content model explicitly states that it must contain - <a href="#significant">significant inline content</a>, simply having no <a - href="#text-node" title="text node">text nodes</a> and no elements - satisfies an element whose content model is some kind of inline content. - - <p><dfn id=significant0>Significant text</dfn>, for the purposes of - determining the presence of <a href="#significant">significant inline - content</a>, consists of any character other than those falling in the <a - href="http://unicode.org/Public/UNIDATA/UCD.html#General_Category_Values">Unicode - categories</a> Zs, Zl, Zp, Cc, and Cf. <a - href="#refsUNICODE">[UNICODE]</a> - - <div class=example> - <p>The following three paragraphs are non-conforming because their content - model is not satisfied (they all count as empty).</p> - - <pre> -<p></p> -<p><em>&#x00A0;</em></p> -<p> - <ol> - <li></li> - </ol> -</p> -</pre> - </div> - - <p><dfn id=embedded0>Embedded content</dfn> consists of elements that - introduce content from other resources into the document, for example - <code><a href="#img">img</a></code>. Embedded content elements can have - <dfn id=fallback>fallback content</dfn>: content that is to be used when - the external resource cannot be used (e.g. because it is of an unsupported - format). The element definitions state what the fallback is, if any. - - <h5 id=transparent><span class=secno>3.3.3.3. </span>Transparent content - models</h5> - - <p>Some elements are described as <dfn id=transparent0>transparent</dfn>; - they have "transparent" as their content model. Some elements are - described as <dfn id=semi-transparent>semi-transparent</dfn>; this means - that part of their content model is "transparent" but that is not the only - part of the content model that must be satisfied. - - <p>When a content model includes a part that is "transparent", those parts - must only contain content that would still be conformant if all - transparent and semi-transparent elements in the tree were replaced, in - their parent element, by the children in the "transparent" part of their - content model, retaining order. - - <p>When a transparent or semi-transparent element has no parent, then the - part of its content model that is "transparent" must instead be treated as - zero or more <a href="#block-level0">block-level elements</a>, or <a - href="#inline-level0">inline-level content</a> (but not both). - - <h5 id=determining><span class=secno>3.3.3.4. </span><dfn - id=determining0>Determining if a particular element contains block-level - elements or inline-level content</dfn></h5> - - <p>Some elements are defined to have content models that allow either <a - href="#block-level0">block-level elements</a> or <a - href="#inline-level0">inline-level content</a>, but not both. For example, - the <code><a href="#aside">aside</a></code> and <code><a - href="#li">li</a></code> elements. - - <p>To establish whether such an element is being used as a block-level - container or as an inline-level container, for example in order to - determine if a document conforms to these requirements, user agents must - look at the element's child nodes. If any of the child nodes are not - allowed in block-level contexts, then the element is being used for <a - href="#inline-level0">inline-level content</a>. If all the child nodes are - allowed in a block-level context, then the element is being used for <a - href="#block-level0">block-level elements</a>. - - <p>Whenever this search would examine a <a - href="#transparent0">transparent</a> element, the element's own child - nodes must be examined instead, potentially recursing further if any of - those are themselves transparent. - - <div class=example> - <p>For instance, in the following (non-conforming) XML fragment, the - <code><a href="#li">li</a></code> element is being used as an - inline-level element container, because the <code><a - href="#meta0">meta</a></code> element is not allowed in a block-level - context. (It doesn't matter, for the purposes of determining whether it - is an inline-level or block-level context, that the <code><a - href="#meta0">meta</a></code> element is not allowed in inline-level - contexts either.)</p> - - <pre><ol> - <li> - <p> Hello World </p> - <meta title="this is an invalid example"/> - </li> -</ol> -</pre> - - <p>In the following fragment, the <code><a href="#aside">aside</a></code> - element is being used as a block-level container, because even though all - the elements it contains could be considered inline-level elements, there - are no nodes that can only be considered inline-level.</p> - - <pre><aside> - <ol> - <li> ... </li> - </ol> - <ul> - <li> ... </li> - </ul> -</aside></pre> - - <p>On the other hand, in the following similar fragment, the <code><a - href="#aside">aside</a></code> element is an inline-level container, - because the text ("Foo") can only be considered inline-level.</p> - - <pre><aside> - <ol> - <li> ... </li> - </ol> - Foo -</aside></pre> - </div> - - <h5 id=interactive0><span class=secno>3.3.3.5. </span><dfn - id=interactive1>Interactive elements</dfn></h5> - <!-- Don't change the above <dfn> or the text below without checking - all cross-references. Some of them refer specifically to the - activation behavior stuff. --> - - <p class=big-issue>Parts of this section should eventually be moved to DOM3 - Events.</p> - <!-- but see comment above --> - <!-- -TESTS: -http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E%0A%3Cp%20tabindex%3D1%3Etest%20%3Ca%20href%3D%22%22%3E%20%3Cem%3Etest%3C/em%3E%20%3C/a%3E%0A%3Cscript%3E%0A%20function%20test%20%28e%29%20%7B%20w%28e.type%20+%20%27%20on%20%27%20+%20e.target.tagName%20+%20%27%20through%20%27%20+%20e.currentTarget.tagName%29%3B%20%7D%0A%20document.getElementsByTagName%28%27a%27%29%5B0%5D.addEventListener%28%27click%27%2C%20test%2C%20false%29%3B%0A%20document.getElementsByTagName%28%27a%27%29%5B0%5D.addEventListener%28%27DOMActivate%27%2C%20test%2C%20false%29%3B%0A%20document.getElementsByTagName%28%27p%27%29%5B0%5D.addEventListener%28%27click%27%2C%20test%2C%20false%29%3B%0A%20document.getElementsByTagName%28%27p%27%29%5B0%5D.addEventListener%28%27DOMActivate%27%2C%20test%2C%20false%29%3B%0A%3C/script%3E%0A -http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20HTML%3E%0A%3Ca%20href%3Dhttp%3A//google.com/%20target%3Da%3EA%3C/a%3E%3Ca%20href%3Dhttp%3A//yahoo.com/%20target%3Db%3EB%3C/a%3E%3Cbr%3E%0A%3Ciframe%20name%3Da%3E%3C/iframe%3E%3Ciframe%20name%3Db%3E%3C/iframe%3E%0A%3Cscript%3E%0A%20var%20a%20%3D%20document.getElementsByTagName%28%27a%27%29%5B0%5D%3B%0A%20var%20b%20%3D%20document.getElementsByTagName%28%27a%27%29%5B1%5D%3B%0A%20a.appendChild%28b%29%3B%0A%3C/script%3E -http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20HTML%3E%0A%3Cform%20action%3D%22http%3A//google.com/%22%20onsubmit%3D%22w%28%27onsubmit%27%29%22%3E%3Cem%3EA%3C/em%3E%3C/form%3E%0A%3Cscript%3E%0Adocument.getElementsByTagName%28%27form%27%29%5B0%5D.attachEvent%28%27onsubmit%27%2C%20function%20%28%29%20%7B%20w%28%27submit%20fired%27%29%20%7D%29%3B%0Adocument.getElementsByTagName%28%27form%27%29%5B0%5D.fireEvent%28%27onsubmit%27%29%3B%0A%3C/script%3E -http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20HTML%3E%0A%3Cform%20action%3D%22http%3A//google.com/%22%3EX%3C/form%3E%0A%3Cscript%3E%0Avar%20evt%20%3D%20document.createEvent%28%22Events%22%29%3B%0Aevt.initEvent%28%22submit%22%2C%20true%2C%20true%29%3B%0Adocument.getElementsByTagName%28%27form%27%29%5B0%5D.dispatchEvent%28evt%29%3B%0A%3C/script%3E ---> - - <p>Certain elements in HTML can be activated, for instance <code><a - href="#a">a</a></code> elements, <code>button</code> elements, or - <code>input</code> elements when their <code>type</code> attribute is set - to <code>radio</code>. Activation of those elements can happen in various - (UA-defined) ways, for instance via the mouse or keyboard. - - <p>When activation is performed via some method other than clicking the - pointing device, the default action of the event that triggers the - activation must, instead of being activating the element directly, be to - <a href="#firing">fire a <code title="">click</code> event</a> on the same - element. - - <p>The default action of this <code title=event-click>click</code> event, - or of the real <code title=event-click>click</code> event if the element - was activated by clicking a pointing device, must be to <span title="fire - a DOMActivate event">fire a further <code - title=event-DOMActivate>DOMActivate</code> event</span> at the same - element, whose own default action is to go through all the elements the - <code title=event-DOMActivate>DOMActivate</code> event bubbled through - (starting at the target node and going towards the <code>Document</code> - node), looking for an element with an <a href="#activation0">activation - behavior</a>; the first element, in reverse tree order, to have one, must - have its activation behavior executed. - - <p class=note>The above doesn't happen for arbitrary synthetic events - dispatched by author script. However, the <code title=dom-click><a - href="#click">click()</a></code> method can be used to make it happen - programmatically. - - <p>For certain form controls, this process is complicated further by <a - href="http://www.whatwg.org/specs/web-forms/current-work/#the-click">changes - that must happen around the click event</a>. <a href="#refsWF2">[WF2]</a></p> - <!-- XXX WF2: when this is merged into - this spec, update xrefs --> - - <p class=note>Most interactive elements have content models that disallow - nesting interactive elements.</p> - <!-- - <li><span>Form control elements</span></li> XXX ---> - - <h5 id=paragraphs><span class=secno>3.3.3.6. </span>Paragraphs</h5> - - <p>A <dfn id=paragraph>paragraph</dfn> is typically a block of text with - one or more sentences that discuss a particular topic, as in typography, - but can also be used for more general thematic grouping. For instance, an - address is also a paragraph, as is a part of a form, a byline, or a stanza - in a poem. - - <p>Paragraphs can be represented by several elements. The <code><a - href="#address">address</a></code> element always represents a paragraph - of contact information for its section, the <code><a - href="#aside">aside</a></code>, <code><a href="#nav">nav</a></code>, - <code><a href="#footer">footer</a></code>, <code><a - href="#li">li</a></code>, and <code><a href="#dd">dd</a></code> elements - represent paragraphs with various specific semantics when they are <a - href="#determining0" title="Determining if a particular element contains - block-level elements or inline-level content">used as inline-level content - containers</a>, the <code><a href="#figure">figure</a></code> element - represents a paragraph in the form of <a href="#embedded0">embedded - content</a>, and the <code><a href="#p">p</a></code> element represents - all the other kinds of paragraphs, for which there are no dedicated - elements. - - <h3 id=global><span class=secno>3.4. </span>Global attributes</h3> - - <p>The following attributes are common to and may be specified on all <a - href="#html-elements">HTML elements</a> (even those not defined in this - specification): - - <dl class=element> - <dt>Global attributes: - - <dd><code title=attr-class><a href="#class">class</a></code> - - <dd><code title=attr-contenteditable><a - href="#contenteditable0">contenteditable</a></code> - - <dd><code title=attr-contextmenu><a - href="#contextmenu">contextmenu</a></code> - - <dd><code title=attr-dir><a href="#dir">dir</a></code> - - <dd><code title=attr-draggable><a href="#draggable">draggable</a></code> - - <dd><code title=attr-id><a href="#id">id</a></code> - - <dd><code title=attr-irrelevant><a - href="#irrelevant">irrelevant</a></code> - - <dd><code title=attr-lang><a href="#lang">lang</a></code> - - <dd><code title=attr-tabindex><a href="#tabindex">tabindex</a></code> - - <dd><code title=attr-title><a href="#title">title</a></code> - </dl> - - <p>In addition, the following <a href="#event2">event handler content - attributes</a> may be specified on any <span>HTML element</span>: - - <ul class=brief> - <li><code title=handler-onabort><a href="#onabort">onabort</a></code> - - <li><code title=handler-onbeforeunload><a - href="#onbeforeunload">onbeforeunload</a></code> - - <li><code title=handler-onblur><a href="#onblur">onblur</a></code> - - <li><code title=handler-onchange><a href="#onchange">onchange</a></code> - - <li><code title=handler-onclick><a href="#onclick">onclick</a></code> - - <li><code title=handler-oncontextmenu><a - href="#oncontextmenu">oncontextmenu</a></code> - - <li><code title=handler-ondblclick><a - href="#ondblclick">ondblclick</a></code> - - <li><code title=handler-ondrag><a href="#ondrag">ondrag</a></code> - - <li><code title=handler-ondragend><a - href="#ondragend">ondragend</a></code> - - <li><code title=handler-ondragenter><a - href="#ondragenter">ondragenter</a></code> - - <li><code title=handler-ondragleave><a - href="#ondragleave">ondragleave</a></code> - - <li><code title=handler-ondragover><a - href="#ondragover">ondragover</a></code> - - <li><code title=handler-ondragstart><a - href="#ondragstart">ondragstart</a></code> - - <li><code title=handler-ondrop><a href="#ondrop">ondrop</a></code> - - <li><code title=handler-onerror><a href="#onerror">onerror</a></code> - - <li><code title=handler-onfocus><a href="#onfocus">onfocus</a></code> - - <li><code title=handler-onkeydown><a - href="#onkeydown">onkeydown</a></code> - - <li><code title=handler-onkeypress><a - href="#onkeypress">onkeypress</a></code> - - <li><code title=handler-onkeyup><a href="#onkeyup">onkeyup</a></code> - - <li><code title=handler-onload><a href="#onload">onload</a></code> - - <li><code title=handler-onmessage><a - href="#onmessage">onmessage</a></code> - - <li><code title=handler-onmousedown><a - href="#onmousedown">onmousedown</a></code> - - <li><code title=handler-onmousemove><a - href="#onmousemove">onmousemove</a></code> - - <li><code title=handler-onmouseout><a - href="#onmouseout">onmouseout</a></code> - - <li><code title=handler-onmouseover><a - href="#onmouseover">onmouseover</a></code> - - <li><code title=handler-onmouseup><a - href="#onmouseup">onmouseup</a></code> - - <li><code title=handler-onmousewheel><a - href="#onmousewheel">onmousewheel</a></code> - - <li><code title=handler-onresize><a href="#onresize">onresize</a></code> - - <li><code title=handler-onscroll><a href="#onscroll">onscroll</a></code> - - <li><code title=handler-onselect><a href="#onselect">onselect</a></code> - - <li><code title=handler-onsubmit><a href="#onsubmit">onsubmit</a></code> - - <li><code title=handler-onunload><a href="#onunload">onunload</a></code> - </ul> - - <h4 id=the-id><span class=secno>3.4.1. </span>The <dfn id=id - title=attr-id><code>id</code></dfn> attribute</h4> - - <p>The <code title=attr-id><a href="#id">id</a></code> attribute represents - its element's unique identifier. The value must be unique in the subtree - within which the element finds itself and must contain at least one - character. The value must not contain any <a href="#space" title="space - character">space characters</a>.</p> - <!-- space characters are disallowed because space-separated lists - of IDs otherwise would not be able to reach all valid IDs --> - - <p>If the value is not the empty string, user agents must associate the - element with the given value (exactly, including any space characters) for - the purposes of ID matching within the subtree the element finds itself - (e.g. for selectors in CSS or for the <code>getElementById()</code> method - in the DOM). - - <p>Identifiers are opaque strings. Particular meanings should not be - derived from the value of the <code title=attr-id><a - href="#id">id</a></code> attribute. - - <p>This specification doesn't preclude an element having multiple IDs, if - other mechanisms (e.g. DOM Core methods) can set an element's ID in a way - that doesn't conflict with the <code title=attr-id><a - href="#id">id</a></code> attribute. - - <p>The <dfn id=id0 title=dom-id><code>id</code></dfn> DOM attribute must <a - href="#reflect">reflect</a> the <code title=attr-id><a - href="#id">id</a></code> content attribute. - - <h4 id=the-title><span class=secno>3.4.2. </span>The <dfn id=title - title=attr-title><code>title</code></dfn> attribute</h4> - - <p>The <code title=attr-title><a href="#title">title</a></code> attribute - represents advisory information for the element, such as would be - appropriate for a tooltip. On a link, this could be the title or a - description of the target resource; on an image, it could be the image - credit or a description of the image; on a paragraph, it could be a - footnote or commentary on the text; on a citation, it could be further - information about the source; and so forth. The value is text. - - <p>If this attribute is omitted from an element, then it implies that the - <code title=attr-title><a href="#title">title</a></code> attribute of the - nearest ancestor with a <code title=attr-title><a - href="#title">title</a></code> attribute set is also relevant to this - element. Setting the attribute overrides this, explicitly stating that the - advisory information of any ancestors is not relevant to this element. - Setting the attribute to the empty string indicates that the element has - no advisory information. - - <p>If the <code title=attr-title><a href="#title">title</a></code> - attribute's value contains U+000A LINE FEED (LF) characters, the content - is split into multiple lines. Each U+000A LINE FEED (LF) character - represents a line break. - - <p>Some elements, such as <code><a href="#link">link</a></code> and - <code><a href="#dfn">dfn</a></code>, define additional semantics for the - <code title=attr-title><a href="#title">title</a></code> attribute beyond - the semantics described above. - - <p>The <dfn id=title0 title=dom-title><code>title</code></dfn> DOM - attribute must <a href="#reflect">reflect</a> the <code - title=attr-title><a href="#title">title</a></code> content attribute. - - <h4 id=the-lang><span class=secno>3.4.3. </span>The <dfn id=lang - title=attr-lang><code>lang</code></dfn> (HTML only) and <dfn id=xmllang - title=attr-xml-lang><code>xml:lang</code></dfn> (XML only) attributes</h4> - - <p>The <code title=attr-lang><a href="#lang">lang</a></code> attribute - specifies the primary <dfn id=language>language</dfn> for the element's - contents and for any of the element's attributes that contain text. Its - value must be a valid RFC 3066 language code, or the empty string. <a - href="#refsRFC3066">[RFC3066]</a> - - <p>The <code title=attr-xml-lang><a href="#xmllang">xml:lang</a></code> - attribute is defined in XML. <a href="#refsXML">[XML]</a> - - <p>If these attributes are omitted from an element, then it implies that - the language of this element is the same as the language of the parent - element. Setting the attribute to the empty string indicates that the - primary language is unknown. - - <p>The <code title=attr-lang><a href="#lang">lang</a></code> attribute may - only be used on elements of <a href="#html-">HTML documents</a>. Authors - must not use the <code title=attr-lang><a href="#lang">lang</a></code> - attribute in <a href="#xml-documents">XML documents</a>. - - <p>The <code title=attr-xml-lang><a href="#xmllang">xml:lang</a></code> - attribute may only be used on elements of <a href="#xml-documents">XML - documents</a>. Authors must not use the <code title=attr-xml-lang><a - href="#xmllang">xml:lang</a></code> attribute in <a href="#html-">HTML - documents</a>.</p> - <!-- technically this - is redundant with the XML spec --> - - <p>To determine the language of a node, user agents must look at the - nearest ancestor element (including the element itself if the node is an - element) that has a <code title=attr-lang><a href="#lang">lang</a></code> - or <code title=attr-xml-lang><a href="#xmllang">xml:lang</a></code> - attribute set. That specifies the language of the node. - - <p>If both the <code title=attr-xml-lang><a - href="#xmllang">xml:lang</a></code> attribute and the <code - title=attr-lang><a href="#lang">lang</a></code> attribute are set on an - element, user agents must use the <code title=attr-xml-lang><a - href="#xmllang">xml:lang</a></code> attribute, and the <code - title=attr-lang><a href="#lang">lang</a></code> attribute must be <a - href="#ignored" title=ignore>ignored</a> for the purposes of determining - the element's language. - - <p>If no explicit language is given for the <a href="#root-element">root - element</a>, then language information from a higher-level protocol (such - as HTTP), if any, must be used as the final fallback language. In the - absence of any language information, the default value is unknown (the - empty string). - - <p>User agents may use the element's language to determine proper - processing or rendering (e.g. in the selection of appropriate fonts or - pronounciations, or for dictionary selection). <!--User - agents must not use the element's language to determine text - directionality. (commented out because text directionality is a - rendering-level concern.)--> - - <p>The <dfn id=lang0 title=dom-lang><code>lang</code></dfn> DOM attribute - must <a href="#reflect">reflect</a> the <code title=attr-lang><a - href="#lang">lang</a></code> content attribute. - - <h4 id=the-dir><span class=secno>3.4.4. </span>The <dfn id=dir - title=attr-dir><code>dir</code></dfn> attribute</h4> - - <p>The <code title=attr-dir><a href="#dir">dir</a></code> attribute - specifies the element's text directionality. The attribute is an <a - href="#enumerated">enumerated attribute</a> with the keyword <code - title="">ltr</code> mapping to the state <em>ltr</em>, and the keyword - <code title="">rtl</code> mapping to the state <em>rtl</em>. The attribute - has no defaults. - - <p>If the attribute has the state <em>ltr</em>, the element's - directionality is left-to-right. If the attribute has the state - <em>rtl</em>, the element's directionality is right-to-left. Otherwise, - the element's directionality is the same as its parent. - - <p>The processing of this attribute depends on the presentation layer. For - example, CSS 2.1 defines a mapping from this attribute to the CSS - 'direction' and 'unicode-bidi' properties, and defines rendering in terms - of those properties. - - <p>The <dfn id=dir0 title=dom-dir><code>dir</code></dfn> DOM attribute on - an element must <a href="#reflect">reflect</a> the <code title=attr-dir><a - href="#dir">dir</a></code> content attribute of that element, <a - href="#limited">limited to only known values</a>. - - <p>The <dfn id=dir1 title=dom-document-dir><code>dir</code></dfn> DOM - attribute on <code><a href="#htmldocument">HTMLDocument</a></code> objects - must <a href="#reflect">reflect</a> the <code title=attr-dir><a - href="#dir">dir</a></code> content attribute of <a href="#the-html0">the - <code>html</code> element</a>, if any, <a href="#limited">limited to only - known values</a>. If there is no such element, then the attribute must - return the empty string and do nothing on setting. - - <h4 id=classes><span class=secno>3.4.5. </span>The <dfn id=class - title=attr-class><code>class</code></dfn> attribute</h4> - - <p>Every <span>HTML element</span> may have a <code title=attr-class><a - href="#class">class</a></code> attribute specified. - - <p>The attribute, if specified, must have a value that is an <a - href="#unordered">unordered set of space-separated tokens</a> representing - the various classes that the element belongs to. - - <p>The classes that an HTML element has assigned to it consists of all the - classes returned when the value of the <code title=attr-class><a - href="#class">class</a></code> attribute is <a href="#split" title="split - a string on spaces">split on spaces</a>. - - <p class=note>Assigning classes to an element affects class matching in - selectors in CSS, the <code title=dom-document-getElementsByClassName><a - href="#getelementsbyclassname">getElementsByClassName()</a></code> method - in the DOM, and other such features. - - <p>Authors may use any value in the <code title=attr-class><a - href="#class">class</a></code> attribute, but are encouraged to use the - values that describe the nature of the content, rather than values that - describe the desired presentation of the content. - - <p>The <dfn id=classname title=dom-className><code>className</code></dfn> - and <dfn id=classlist title=dom-classList><code>classList</code></dfn> DOM - attributes must both <a href="#reflect">reflect</a> the <code - title=attr-class><a href="#class">class</a></code> content attribute. - - <h4 id=the-irrelevant><span class=secno>3.4.6. </span>The <dfn - id=irrelevant title=attr-irrelevant><code>irrelevant</code></dfn> - attribute</h4> - - <p>All elements may have the <code title=attr-irrelevant><a - href="#irrelevant">irrelevant</a></code> content attribute set. The <code - title=attr-irrelevant><a href="#irrelevant">irrelevant</a></code> - attribute is a <a href="#boolean0">boolean attribute</a>. When specified - on an element, it indicates that the element is not yet, or is no longer, - relevant. User agents should not render elements that have the <code - title=attr-irrelevant><a href="#irrelevant">irrelevant</a></code> - attribute specified. - - <div class=example> - <p>In the following skeletal example, the attribute is used to hide the a - Web game until the user logs in:</p> - - <pre> <h1>The Example Game</h1> - <section id="login"> - <h2>Login</h2> - <form> - ... - <!-- calls login() once the user's credentials have been checked --> - </form> - <script> - function login() { - // switch screens - document.getElementById('login').irrelevant = true; - document.getElementById('game').irrelevant = false; - } - </script> - </section> - <section id="game"> - ... - </section></pre> - - <p>In the following example, an image acts as a surrogate for an video. - When the image is clicked, it tries to load the video (and disables the - playback button). If the load succeeds enough that a frame of data has - been downloaded, the <code><a href="#video1">video</a></code> element - hides the surrogate image and shows the video instead, along with its - controls, and turns on autoplay (so that the video will commence playback - as soon as enough of it is loaded). If the load fails for any reason, the - video and the surrogate frame are both hidden (by hiding the paragraph - element containing them both), and the following paragraph is shown - instead, with its unhelpful error message and potentially helpful link to - download the video directly.</p> - - <p>In legacy user agents, the surrogate image would show (though clicking - it would have no effect) and the link to the video would be present - (allowing the video to be viewed in another application).</p> - - <pre> <p> - <input type="image" src="frame.png" alt="Play Video" - onclick=" nextSibling.load(); - disabled = true; - return false;" - ><video src="video.ogg" controls="" irrelevant="" - onloadedfirstframe=" - irrelevant = false; - previousSibling.irrelevant = true; - autoplay = true" - onerror=" parentNode.irrelevant = true; - parentNode.nextSibling.irrelevant = false"> - </video> - </p><p irrelevant=""> - Playback unavailable. - <a href="video.ogg">Download Video</a> - </p></pre> - </div> - - <p>The <code title=attr-irrelevant><a - href="#irrelevant">irrelevant</a></code> attribute must not be used to - hide content that could legitimately be shown in another presentation. For - example, it is incorrect to use <code title=attr-irrelevant><a - href="#irrelevant">irrelevant</a></code> to hide panels in a tabbed - dialog, because the tabbed interface is merely a kind of overflow - presentation — showing all the form controls in one big page with a - scrollbar would be equivalent, and no less correct. - - <p>Elements in a section hidden by the <code title=attr-irrelevant><a - href="#irrelevant">irrelevant</a></code> attribute are still active, e.g. - scripts and form controls in such sections still render execute and submit - respectively. Only their presentation to the user changes. - - <p>The <dfn id=irrelevant0 - title=dom-irrelevant><code>irrelevant</code></dfn> DOM attribute must <a - href="#reflect">reflect</a> the content attribute of the same name. - - <h3 id=interaction><span class=secno>3.5. </span><dfn - id=interaction0>Interaction</dfn></h3> - <!-- -ELEMENT - attribute long <span title="dom-tabindex">tabIndex</span>; - void <span title="dom-click">click</span>(); - void <span title="dom-focus">focus</span>(); - void <span title="dom-blur">blur</span>(); - void <span title="dom-scrollIntoView">scrollIntoView</span>(); - void <span title="dom-scrollIntoView">scrollIntoView</span>(in boolean top); - -DOCUMENT - readonly attribute <span>Element</span> <span title="dom-document-activeElement">activeElement</span>; - readonly attribute boolean <span title="dom-document-hasFocus">hasFocus</span>; ---> - - <h4 id=activation><span class=secno>3.5.1. </span>Activation</h4> - - <p>The <dfn id=click title=dom-click>click()</dfn> method must <a - href="#firing">fire a <code>click</code> event</a> at the element, whose - default action is the <span title="fire a DOMActivate event">firing of a - further <code title=event-DOMActivate>DOMActivate</code> event</span> at - the same element, whose own default action is to go through all the - elements the <code title=event-DOMActivate>DOMActivate</code> event - bubbled through (starting at the target node and going towards the - <code>Document</code> node), looking for an element with an <a - href="#activation0">activation behavior</a>; the first element, in reverse - tree order, to have one, must have its activation behavior executed. - - <h4 id=focus><span class=secno>3.5.2. </span>Focus</h4> - - <p>When an element is <em>focused</em>, key events received by the document - must be targeted at that element. There is always an element focused; in - the absence of other elements being focused, the document's root element - is it. - - <p>Which element within a document currently has focus is independent of - whether or not the document itself has the <em>system focus</em>. - - <p>Some focusable elements might take part in <em>sequential focus - navigation</em>. - - <h5 id=focus-management><span class=secno>3.5.2.1. </span>Focus management</h5> - - <p>The <dfn id=focus0 title=dom-focus><code>focus()</code></dfn> and <dfn - id=blur title=dom-blur><code>blur()</code></dfn> methods must focus and - unfocus the element respectively, if the element is focusable. - - <p>Some elements, most notably <code><a href="#area">area</a></code>, can - correspond to more than one distinct focusable area. When such an element - is focused using the <code title=dom-focus><a - href="#focus0">focus()</a></code> method, the first such region in tree - order is the one that must be focused. - - <p class=big-issue>Well that clearly needs more.</p> - <!-- XXX e.g. should the click, focus, blur methods be recursible? --> - - <p>The <dfn id=activeelement - title=dom-document-activeElement><code>activeElement</code></dfn> - attribute must return the element in the document that has focus. If no - element specifically has focus, this must return <a href="#the-body0">the - <code>body</code> element</a>. - - <p>The <dfn id=hasfocus - title=dom-document-hasFocus><code>hasFocus</code></dfn> attribute must - return true if the document, one of its nested <a href="#browsing0" - title="browsing context">browsing contexts</a>, or any element in the - document or its browsing contexts currently has the system focus. - - <h5 id=sequential><span class=secno>3.5.2.2. </span>Sequential focus - navigation</h5> - - <p class=issue>This section on the <code>tabindex</code> attribute needs to - be checked for backwards-compatibility. - - <p>The <dfn id=tabindex title=attr-tabindex><code>tabindex</code></dfn> - attribute specifies the relative order of elements for the purposes of - sequential focus navigation. The name "tab index" comes from the common - use of the "tab" key to navigate through the focusable elements. The term - "tabbing" refers to moving forward through the focusable elements. - - <p>The <code title=attr-tabindex><a href="#tabindex">tabindex</a></code> - attribute, if specified, must have a value that is a <a - href="#valid0">valid integer</a>. - - <p>If the attribute is specified, it must be parsed using the <a - href="#rules0">rules for parsing integers</a>. If parsing the value - returns an error, the attribute is ignored for the purposes of focus - management (as if it wasn't specified). - - <p>A positive integer or zero specifies the index of the element in the - current scope's tab order. Elements with the same index are sorted in <a - href="#tree-order">tree order</a> for the purposes of tabbing. - - <p id=negative-tabindex>A negative integer specifies that the element - should be removed from the tab order. If the element does normally take - focus, it may still be focused using other means (e.g. it could be focused - by a click). - - <p>If the attribute is absent (or invalid), then the user agent must treat - the element as if it had the value 0 or the value -1, based on platform - conventions. - - <p class=example>For example, a user agent might default - <code>textarea</code> elements to 0, and <code>button</code> elements to - -1, making text fields part of the tabbing cycle but buttons not. - - <p>When an element that does not normally take focus (i.e. whose default - value would be -1) has the <code title=attr-tabindex><a - href="#tabindex">tabindex</a></code> attribute specified with a positive - value, then it should be added to the tab order and should be made - focusable. When focused, the element matches the CSS <code>:focus</code> - pseudo-class and key events are dispatched on that element in response to - keyboard input. - - <p>The <dfn id=tabindex0 title=dom-tabIndex><code>tabIndex</code></dfn> DOM - attribute reflects the value of the <code title=attr-tabIndex><a - href="#tabindex">tabIndex</a></code> content attribute. If the attribute - is not present (or has an invalid value) then the DOM attribute must - return the UA's default value for that element, which will be either 0 - (for elements in the tab order) or -1 (for elements not in the tab order).</p> - <!--XXX - <h5>The <dfn><code>DocumentFocus</code></dfn> interface</h5> - - <p>The <code>DocumentFocus</code> interface contains methods for - moving focus around the document. It can be obtained from objects - that implement the <code>Document</code> interface using - binding-specific casting methods.</p> - - <pre class="idl">interface <dfn>DocumentFocus</dfn> { - void moveFocusForward(); - void moveFocusBackward(); - void moveFocusUp(); - void moveFocusRight(); - void moveFocusDown(); - void moveFocusLeft(); -};</pre> - - <p>The <dfn><code>currentFocus</code></dfn> attribute returns the - element to which key events will be sent when the document receives - key events.</p> - - <p>The <dfn><code>moveFocusForward</code></dfn> method uses the - <code>'nav-index'</code> property and the <code>tabindex</code> - attribute to find the next focusable element and focuses it.</p> - - <p>The <dfn><code>moveFocusBackward</code></dfn> method uses the - <code>'nav-index'</code> property and the <code>tabindex</code> - attribute to find the previous focusable element and focuses - it.</p> - - <p>The <dfn><code>moveFocusUp</code></dfn> method uses the - <code>'nav-up'</code> property and the <code>tabindex</code> - attribute to find an appropriate focusable element and focuses - it.</p> - - <p>In a similar manner, the <dfn><code>moveFocusRight</code></dfn>, - <dfn><code>moveFocusDown</code></dfn>, and - <dfn><code>moveFocusLeft</code></dfn> methods use the - <code>'nav-right'</code>, <code>'nav-down'</code>, and - <code>'nav-left'</code> properties (respectively), and the - <code>tabindex</code> attribute, to find an appropriate focusable - element and focus it.</p> - - <p>The <code>'nav-index'</code>, <code>'nav-up'</code>, - <code>'nav-right'</code>, <code>'nav-down'</code>, and - <code>'nav-left'</code> properties are defined in <a - href="#refsCSS3UI">[CSS3UI]</a>.</p> - -Other things to look at are IE's focus APIs (document.activeElement, -document.hasFocus, HTMLElement.setActive(), onBeforeActivate, -onActivate, onBeforeDeactivate, onDeactivate, document.hasFocus): - https://bugzilla.mozilla.org/show_bug.cgi?id=296471 - https://bugzilla.mozilla.org/show_bug.cgi?id=296469 - http://msdn.microsoft.com/workshop/author/dhtml/reference/properties/activeelement.asp - http://msdn.microsoft.com/workshop/author/dhtml/reference/methods/setactive.asp - http://msdn.microsoft.com/workshop/author/dhtml/reference/events/onbeforeactivate.asp - http://msdn.microsoft.com/workshop/author/dhtml/reference/methods/focus.asp ---> - - <h4 id=scrolling><span class=secno>3.5.3. </span>Scrolling elements into - view</h4> - - <p>The <dfn id=scrollintoview - title=dom-scrollIntoView><code>scrollIntoView([<var - title="">top</var>])</code></dfn> method, when called, must cause the - element on which the method was called to have the attention of the user - called to it. - - <p class=note>In a speech browser, this could happen by having the current - playback position move to the start of the given element. - - <p>In visual user agents, if the argument is present and has the value - false, the user agent should scroll the element into view such that both - the bottom and the top of the element are in the viewport, with the bottom - of the element aligned with the bottom of the viewport. If it isn't - possible to show the entire element in that way, or if the argument is - omitted or is true, then the user agent must instead simply align the top - of the element with the top of the viewport. - - <p>Non-visual user agents may ignore the argument, or may treat it in some - media-specific manner most useful to the user.</p> - <!-- XXX maybe this should move to CSSOM --> - - <h3 id=the-root><span class=secno>3.6. </span>The root element</h3> - - <h4 id=the-html><span class=secno>3.6.1. </span>The <dfn - id=html><code>html</code></dfn> element</h4> - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>As the root element of a document. - - <dd>Wherever a subdocument fragment is allowed in a compound document. - - <dt>Content model: - - <dd>A <code><a href="#head">head</a></code> element followed by a <code><a - href="#body0">body</a></code> element.</dd> - <!--XXX -Steven Pemberton was as always, a remarkable speaker, but his answer -to my question leaves me a very bad taste. Basically, I asked him why -XHTML2 preserves the useless head and body element. The answer was in -substance "because this is a compromise". Ah. So XHTML2 preserves two -useless elements that add potential dangers to the interpretation and -styling of documents because it's a compromise. Getting rid of head -would allow to attach directly the document's metadata to the root -element of the document, making much more sense than a head element. -Having a head element also preserves the ridiculous -engraved-in-the-marble "head contents are not rendered". Body is -dangerous because it's another box between the document and the -contents; you all have written a blog template with a <div -class="main"> or <div class="content">. Why do we also need a body? - - http://www.glazman.org/weblog/dotclear/index.php?2005/05/27/1055-adam-2 ---> - - <dt>Element-specific attributes: - - <dd>None (but see prose). - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#html">html</a></code> element represents the root of - an HTML document. - - <p>Though it has absolutely no effect and no meaning, the <code><a - href="#html">html</a></code> element, in <a href="#html-">HTML - documents</a>, may have an <code title="">xmlns</code> attribute - specified, if, and only if, it has the exact value - "<code>http://www.w3.org/1999/xhtml</code>". This does not apply to <a - href="#xml-documents">XML documents</a>. - - <p class=note>In HTML, the <code title="">xmlns</code> attribute has - absolutely no effect. It is basically a talisman. It is allowed merely to - make migration to and from XHTML mildly easier. When parsed by an <a - href="#html-0">HTML parser</a>, the attribute ends up in the null - namespace, not the "<code>http://www.w3.org/2000/xmlns/</code>" namespace - like namespace declaration attributes in XML do. - - <p class=note>In XML, an <code title="">xmlns</code> attribute is part of - the namespace declaration mechanism, and an element cannot actually have - an <code title="">xmlns</code> attribute in the null namespace specified. - - <h3 id=document><span class=secno>3.7. </span>Document metadata</h3> - - <p>Document metadata is represented by <dfn id=metadata>metadata - elements</dfn> in the document's <code><a href="#head">head</a></code> - element. - - <h4 id=the-head><span class=secno>3.7.1. </span>The <dfn - id=head><code>head</code></dfn> element</h4> - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>As the first element in an <code><a href="#html">html</a></code> - element. - - <dt>Content model: - - <dd>In any order unless otherwise specified: optionally one <code><a - href="#meta0">meta</a></code> element with a <code - title=attr-meta-charset><a href="#charset0">charset</a></code> attribute, - exactly one <code><a href="#title1">title</a></code> element, optionally - one <code><a href="#base">base</a></code> element, and zero or more other - <a href="#metadata">metadata elements</a> (in particular, <code><a - href="#link">link</a></code>, <code><a href="#meta0">meta</a></code>, - <code><a href="#style">style</a></code>, and <code><a - href="#script0">script</a></code>). - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#head">head</a></code> element collects the - document's metadata. - - <h4 id=the-title0><span class=secno>3.7.2. </span>The <dfn - id=title1><code>title</code></dfn> element</h4> - - <p><a href="#metadata" title="metadata elements">Metadata element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>In a <code><a href="#head">head</a></code> element containing no other - <code><a href="#title1">title</a></code> elements. - - <dt>Content model: - - <dd>Text (for details, see prose). - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#title1">title</a></code> element represents the - document's title or name. Authors should use titles that identify their - documents even when they are used out of context, for example in a user's - history or bookmarks, or in search results. The document's title is often - different from its first header, since the first header does not have to - stand alone when taken out of context. - - <div class=example> - <p>Here are some examples of appropriate titles, contrasted with the - top-level headers that might be used on those same pages.</p> - - <pre> <title>Introduction to The Mating Rituals of Bees</title> - ... - <h1>Introduction</h1> - <p>This companion guide to the highly successful - <cite>Introduction to Medieval Bee-Keeping</cite> book is... -</pre> - - <p>The next page might be a part of the same site. Note how the title - describes the subject matter unambiguously, while the first header - assumes the reader knowns what the context is and therefore won't wonder - if the dances are Salsa or Waltz:</p> - - <pre> <title>Dances used during bee mating rituals</title> - ... - <h1>The Dances</h1></pre> - </div> - - <p>The <code><a href="#title1">title</a></code> element must not contain - any elements. - - <p>The string to use as the document's title is given by the <code - title=dom-document-title><a - href="#document.title">document.title</a></code> DOM attribute. User - agents should use the document's title when referring to the document in - their user interface. - - <h4 id=the-base><span class=secno>3.7.3. </span>The <dfn - id=base><code>base</code></dfn> element</h4> - - <p><a href="#metadata" title="metadata elements">Metadata element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>In a <code><a href="#head">head</a></code> element, after the <code><a - href="#meta0">meta</a></code> element with the <code - title=attr-meta-charset><a href="#charset0">charset</a></code> attribute, - if any, but before any other elements. - - <dt>Content model: - - <dd>Empty. - - <dt>Element-specific attributes: - - <dd><code title=attr-base-href><a href="#href">href</a></code> - - <dd><code title=attr-base-target><a href="#target">target</a></code> - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmlbaseelement>HTMLBaseElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute DOMString <a href="#href0" title=dom-base-href>href</a>; - attribute DOMString <a href="#target0" title=dom-base-target>target</a>; -};</pre> - </dl> - - <p>The <code><a href="#base">base</a></code> element allows authors to - specify the document's base URI for the purposes of resolving relative - URIs, and the name of the default <a href="#browsing0">browsing - context</a> for the purposes of <a href="#following0">following - hyperlinks</a>. - - <p>There must be no more than one <code><a href="#base">base</a></code> - element per document. - - <p>The <dfn id=href title=attr-base-href><code>href</code></dfn> content - attribute, if specified, must contain a URI (or IRI). - - <p>User agents must use the value of the <code - title=att-base-href>href</code> attribute of the first <code><a - href="#base">base</a></code> element that is both a child of <a - href="#the-head0">the <code>head</code> element</a> and has an <code - title=att-base-href>href</code> attribute, if there is such an element, as - the document entity's base URI for the purposes of section 5.1.1 of RFC - 2396 ("Establishing a Base URI": "Base URI within Document Content"). This - base URI from RFC 2396 is referred to by the algorithm given in XML Base, - which <a href="#xmlBase">is a normative part of this specification</a>. <a - href="#refsRFC2396">[RFC2396]</a> - - <p>If the base URI given by this attribute is a relative URI, it must be - resolved relative to the higher-level base URIs (i.e. the base URI from - the encapsulating entity or the URI used to retrieve the entity) to obtain - an absolute base URI. All <code title=attr-xml-base>xml:base</code> - attributes must be ignored when resolving relative URIs in this <code - title=attr-base-href><a href="#href">href</a></code> attribute. - - <p class=note>If there are multiple <code><a href="#base">base</a></code> - elements with <code title=att-base-href>href</code> attributes, all but - the first are ignored. - - <p>The <dfn id=target title=attr-base-target><code>target</code></dfn> - attribute, if specified, must contain a <a href="#valid8">valid browsing - context name</a>. User agents use this name when <a - href="#following0">following hyperlinks</a>. - - <p>The <dfn id=href0 title=dom-base-href><code>href</code></dfn> and <dfn - id=target0 title=dom-base-target><code>target</code></dfn> DOM attributes - must <a href="#reflect">reflect</a> the content attributes of the same - name. - - <p class=note>Pages with multiple <code><a href="#base">base</a></code> - elements have all but their first <code><a href="#base">base</a></code> - element with an <code title=attr-base-href><a href="#href">href</a></code> - attribute ignored for the purposes of URI resolution, and all but their - first <code><a href="#base">base</a></code> element with a <code - title=attr-base-target><a href="#target">target</a></code> attribute - ignored for the purposes of default browsing context name resolution.</p> - <!-- XXX the former is for compat with IE7. The latter is not - actually exactly compatible with anything. We'll see if it breaks - anything. --> - - <h4 id=the-link><span class=secno>3.7.4. </span>The <dfn - id=link><code>link</code></dfn> element</h4> - - <p><a href="#metadata" title="metadata elements">Metadata element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>In a <code><a href="#head">head</a></code> element. - - <dt>Content model: - - <dd>Empty. - - <dt>Element-specific attributes: - - <dd><code title=attr-link-href><a href="#href1">href</a></code> (required) - - <dd><code title=attr-link-rel><a href="#rel">rel</a></code> (required) - - <dd><code title=attr-link-media><a href="#media0">media</a></code> - - <dd><code title=attr-link-hreflang><a href="#hreflang">hreflang</a></code> - - <dd><code title=attr-link-type><a href="#type">type</a></code> - - <dd>Also, the <code title=attr-link-title><a - href="#title2">title</a></code> attribute has special semantics on this - element. - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmllinkelement>HTMLLinkElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute boolean <a href="#disabled" title=dom-link-disabled>disabled</a>; - attribute DOMString <a href="#href2" title=dom-link-href>href</a>; - attribute DOMString <a href="#rel0" title=dom-link-rel>rel</a>; - readonly attribute DOMTokenList <a href="#rellist" title=dom-link-relList>relList</a>; - attribute DOMString <a href="#media1" title=dom-link-media>media</a>; - attribute DOMString <a href="#hreflang0" title=dom-link-hreflang>hreflang</a>; - attribute DOMString <a href="#type0" title=dom-link-type>type</a>; -};</pre> - - <p>The <code>LinkStyle</code> interface must also be implemented by this - element, the <a href="#styling0">styling processing model</a> defines - how. <a href="#refsCSSOM">[CSSOM]</a></p> - </dl> - - <p>The <code><a href="#link">link</a></code> element allows authors to - indicate explicit relationships between their document and other - resources. - - <p>The destination of the link is given by the <dfn id=href1 - title=attr-link-href><code>href</code></dfn> attribute, which must be - present and must contain a URI (or IRI). If the <code - title=attr-link-href><a href="#href1">href</a></code> attribute is absent, - then the element does not define a link. - - <p>The type of link indicated (the relationship) is given by the value of - the <dfn id=rel title=attr-link-rel><code>rel</code></dfn> attribute, - which must be present, and must have a value that is an <a - href="#unordered">unordered set of space-separated tokens</a>. The <a - href="#linkTypes">allowed values and their meanings</a> are defined in a - later section. If the <code title=attr-link-rel><a - href="#rel">rel</a></code> attribute is absent, or if the value used is - not allowed according to the definitions in this specification, then the - element does not define a link. - - <p>Two categories of links can be created using the <code><a - href="#link">link</a></code> element. <dfn id=links1 title="external - resource link">Links to external resources</dfn> are links to resources - that are to be used to augment the current document, and <dfn - id=hyperlink1 title="hyperlink link">hyperlink links</dfn> are <a - href="#hyperlinks" title=hyperlink>links to other documents</a>. The <a - href="#linkTypes">link types section</a> defines whether a particular link - type is an external resource or a hyperlink. One element can create - multiple links (of which some might be external resource links and some - might be hyperlinks). User agents should process the links on a per-link - basis, not a per-element basis. - - <p>The exact behaviour for links to external resources depends on the exact - relationship, as defined for the relevant link type. Some of the - attributes control whether or not the external resource is to be applied - (as defined below). For external resources that are represented in the DOM - (for example, style sheets), the DOM representation must be made available - even if the resource is not applied. (However, user agents may opt to only - fetch such resources when they are needed, instead of pro-actively - downloading all the external resources that are not applied.) - - <p>Interactive user agents should provide users with a means to <a - href="#following0" title="following hyperlinks">follow the hyperlinks</a> - created using the <code><a href="#link">link</a></code> element, somewhere - within their user interface. The exact interface is not defined by this - specification, but it should include the following information (obtained - from the element's attributes, again as defined below), in some form or - another (possibly simplified), for each hyperlink created with each - <code><a href="#link">link</a></code> element in the document: - - <ul><!-- the order here is the order that makes most sense for a UI --> - - <li>The relationship between this document and the resource (given by the - <code title=attr-link-rel><a href="#rel">rel</a></code> attribute) - - <li>The title of the resource (given by the <code title=attr-link-title><a - href="#title2">title</a></code> attribute). - - <li>The URI of the resource (given by the <code title=attr-link-href><a - href="#href1">href</a></code> attribute). - - <li>The language of the resource (given by the <code - title=attr-link-hreflang><a href="#hreflang">hreflang</a></code> - attribute). - - <li>The optimum media for the resource (given by the <code - title=attr-link-media><a href="#media0">media</a></code> attribute). - </ul> - - <p>User agents may also include other information, such as the type of the - resource (as given by the <code title=attr-link-type><a - href="#type">type</a></code> attribute). - - <p>The <dfn id=media0 title=attr-link-media><code>media</code></dfn> - attribute says which media the resource applies to. The value must be a - valid media query. <a href="#refsMQ">[MQ]</a> - - <p>If the link is a <a href="#hyperlink1" title="hyperlink - link">hyperlink</a> then the <code title=attr-link-media><a - href="#media0">media</a></code> attribute is purely advisory, and - describes for which media the document in question was designed. - - <p>However, if the link is an <a href="#links1">external resource link</a>, - then the <code title=attr-link-media><a href="#media0">media</a></code> - attribute is prescriptive. The user agent must only apply the external - resource to <span>views</span><!-- XXX xref --> while their state match - the listed media. - - <p id=default-media>The default, if the <code title=attr-link-media><a - href="#media0">media</a></code> attribute is omitted, is <code>all</code>, - meaning that by default links apply to all media. - - <p>The <dfn id=hreflang - title=attr-link-hreflang><code>hreflang</code></dfn> attribute on the - <code><a href="#link">link</a></code> element has the same semantics as - the <a href="#hreflang3" - title=attr-hyperlink-hreflang><code>hreflang</code> attribute on hyperlink - elements</a>. - - <p>The <dfn id=type title=attr-link-type><code>type</code></dfn> attribute - gives the MIME type of the linked resource. It is purely advisory. The - value must be a valid MIME type, optionally with parameters. <a - href="#refsRFC2046">[RFC2046]</a> - - <p>For <a href="#links1" title="external resource link">external resource - links</a>, user agents may use the type given in this attribute to decide - whether or not to consider using the resource at all. If the UA does not - support the given MIME type for the given link relationship, then the UA - may opt not to download and apply the resource. - - <p>User agents must not consider the <code title=attr-link-type><a - href="#type">type</a></code> attribute authoritative — upon fetching - the resource, user agents must not use metadata included in the link to - the resource to determine its type. - - <p>If the attribute is omitted, then the UA must fetch the resource to - determine its type and thus determine if it supports (and can apply) that - external resource. - - <div class=example> - <p>If a document contains three style sheet links labelled as follows:</p> - - <pre><link rel="stylesheet" href="A" type="text/css"> -<link rel="stylesheet" href="B" type="text/plain"> -<link rel="stylesheet" href="C"></pre> - - <p>...then a compliant UA that supported only CSS style sheets would fetch - the A and C files, and skip the B file (since <code>text/plain</code> is - not the MIME type for CSS style sheets). For these two files, it would - then check the actual types returned by the UA. For those that are sent - as <code>text/css</code>, it would apply the styles, but for those - labelled as <code>text/plain</code>, or any other type, it would not.</p> - </div> - <!--(to be deleted) (charset dropped) - <p>The <dfn title="attr-link-charset"><code>charset</code></dfn> - attribute gives the character encoding of the linked resource. It is - purely advisory. The value must be a valid character encoding name. - <a href="#refsIANACHARSET">[IANACHARSET]</a></p> - - <p>For <span title="external resource link">external resource - links</span>, user agents may use the character encoding given in - this attribute to decide whether or not to consider using the - resource at all. If the UA does not support the given encoding for - the given link relationship, then the UA may opt not to download and - apply the resource.</p> - - <p>However, once the resource has been fetched, user agents must - follow the rules for that resource type when determining the actual - character encoding.</p> ---> - - <p>The <dfn id=title2 title=attr-link-title><code>title</code></dfn> - attribute gives the title of the link. With one exception, it is purely - advisory. The value is text. The exception is for style sheet links, where - the <code title=attr-link-title><a href="#title2">title</a></code> - attribute defines <a href="#alternative">alternative style sheet sets</a>. - - <p class=note>The <code title=attr-link-title><a - href="#title2">title</a></code> attribute on <code><a - href="#link">link</a></code> elements differs from the global <code - title=attr-title><a href="#title">title</a></code> attribute of most other - elements in that a link without a title does not inherit the title of the - parent element: it merely has no title. - - <p>Some versions of HTTP defined a <code title="">Link:</code> header, to - be processed like a series of <code><a href="#link">link</a></code> - elements. When processing links, those must be taken into consideration as - well. For the purposes of ordering, links defined by HTTP headers must be - assumed to come before any links in the document, in the order that they - were given in the HTTP entity header. Relative URIs in these headers must - be resolved according to the rules given in HTTP, not relative to base - URIs set by the document (e.g. using a <code><a - href="#base">base</a></code> element or <code - title=attr-xml-base>xml:base</code> attributes). <a - href="#refsRFC2616">[RFC2616]</a> <a href="#refsRFC2068">[RFC2068]</a> - - <p>The DOM attributes <dfn id=href2 - title=dom-link-href><code>href</code></dfn>, <dfn id=rel0 - title=dom-link-rel><code>rel</code></dfn>, <dfn id=media1 - title=dom-link-media><code>media</code></dfn>, <dfn id=hreflang0 - title=dom-link-hreflang><code>hreflang</code></dfn>, and <dfn id=type0 - title=dom-link-type><code>type</code></dfn> each must <a - href="#reflect">reflect</a> the respective content attributes of the same - name. - - <p>The DOM attribute <dfn id=rellist - title=dom-link-rellist><code>relList</code></dfn> must <a - href="#reflect">reflect</a> the <code title=attr-link-rel><a - href="#rel">rel</a></code> content attribute. - - <p>The DOM attribute <dfn id=disabled - title=dom-link-disabled><code>disabled</code></dfn> only applies to style - sheet links. When the <code><a href="#link">link</a></code> element - defines a style sheet link, then the <code title=dom-link-disabled><a - href="#disabled">disabled</a></code> attribute behaves as defined <a - href="#disabled1" title=dom-linkstyle-disabled>for the alternative style - sheets DOM</a>. For all other <code><a href="#link">link</a></code> - elements it always return false and does nothing on setting. - - <h4 id=meta><span class=secno>3.7.5. </span>The <dfn - id=meta0><code>meta</code></dfn> element</h4> - - <p><a href="#metadata" title="metadata elements">Metadata element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>In a <code><a href="#head">head</a></code> element. - - <dt>Content model: - - <dd>Empty. - - <dt>Element-specific attributes: - - <dd><code title=attr-meta-name><a href="#name">name</a></code> - - <dd><code title=attr-meta-http-equiv><a - href="#http-equiv0">http-equiv</a></code> - - <dd><code title=attr-meta-content><a href="#content0">content</a></code> - - <dd><code title=attr-meta-charset><a href="#charset0">charset</a></code> - (<a href="#html-" title="HTML documents">HTML</a> only) - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmlmetaelement>HTMLMetaElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute DOMString <a href="#content1" title=dom-meta-content>content</a>; - attribute DOMString <a href="#name0" title=dom-meta-name>name</a>; - attribute DOMString <a href="#httpequiv" title=dom-meta-httpEquiv>httpEquiv</a>; -};</pre> - </dl> - - <p>The <code><a href="#meta0">meta</a></code> element represents various - kinds of metadata that cannot be expressed using the <code><a - href="#title1">title</a></code>, <code><a href="#base">base</a></code>, - <code><a href="#link">link</a></code>, <code><a - href="#style">style</a></code>, and <code><a - href="#script0">script</a></code> elements. - - <p>The <code><a href="#meta0">meta</a></code> element can represent - document-level metadata with the <code title=attr-meta-name><a - href="#name">name</a></code> attribute, pragma directives with the <code - title=attr-meta-http-equiv><a href="#http-equiv0">http-equiv</a></code> - attribute, and the file's character encoding declaration when an HTML - document is serialised to string form (e.g. for transmission over the - network or for disk storage) with the <code title=attr-meta-charset><a - href="#charset0">charset</a></code> attribute. - - <p>Exactly one of the <code title=attr-meta-name><a - href="#name">name</a></code>, <code title=attr-meta-http-equiv><a - href="#http-equiv0">http-equiv</a></code>, and <code - title=attr-meta-charset><a href="#charset0">charset</a></code> attributes - must be specified. - - <p>If either <code title=attr-meta-name><a href="#name">name</a></code> or - <code title=attr-meta-http-equiv><a - href="#http-equiv0">http-equiv</a></code> is specified, then the <code - title=attr-meta-content><a href="#content0">content</a></code> attribute - must also be specified. Otherwise, it must be omitted. - - <p>The <code title=attr-meta-charset><a href="#charset0">charset</a></code> - attribute may only be specified in <a href="#html5" title=HTML5>HTML - documents</a>, it must not be used in <a href="#xhtml5" title=XHTML>XML - documents</a>. If the <code title=attr-meta-charset><a - href="#charset0">charset</a></code> attribute is specified, the element - must be the first element in <a href="#the-head0">the <code>head</code> - element</a> of the file. - - <p>The <dfn id=content0 title=attr-meta-content><code>content</code></dfn> - attribute gives the value of the document metadata or pragma directive - when the element is used for those purposes. The allowed values depend on - the exact context, as described in subsequent sections of this - specification. - - <p>If a <code><a href="#meta0">meta</a></code> element has a <dfn id=name - title=attr-meta-name><code>name</code></dfn> attribute, it sets document - metadata. Document metadata is expressed in terms of name/value pairs, the - <code title=attr-meta-name><a href="#name">name</a></code> attribute on - the <code><a href="#meta0">meta</a></code> element giving the name, and - the <code title=attr-meta-content><a href="#content0">content</a></code> - attribute on the same element giving the value. The name specifies what - aspect of metadata is being set; valid names and the meaning of their - values are described in the following sections. If a <code><a - href="#meta0">meta</a></code> element has no <code - title=attr-meta-content><a href="#content0">content</a></code> attribute, - then the value part of the metadata name/value pair is the empty string. - - <p>The DOM attributes <dfn id=name0 - title=dom-meta-name><code>name</code></dfn> and <dfn id=content1 - title=dom-meta-content><code>content</code></dfn> must <a - href="#reflect">reflect</a> the respective content attributes of the same - name. The DOM attribute <dfn id=httpequiv - title=dom-meta-httpEquiv><code>httpEquiv</code></dfn> must reflect the - content attribute <code title=attr-meta-http-equiv><a - href="#http-equiv0">http-equiv</a></code>. - - <h5 id=standard><span class=secno>3.7.5.1. </span>Standard metadata names</h5> - - <p>This specification defines a few names for the <code - title=attr-meta-name><a href="#name">name</a></code> attribute of the - <code><a href="#meta0">meta</a></code> element. - - <dl> - <dt><dfn id=generator title=meta-generator>generator</dfn> - - <dd> - <p>The value must be a free-form string that identifies the software used - to generate the document. This value must not be used on hand-authored - pages. WYSIWYG editors have <a href="#wysiwyg2" title="WYSIWYG - signature">additional constraints</a> on the value used with this - metadata name. - - <dt><dfn id=dns title=meta-dns>dns</dfn> - - <dd> - <p>The value must be an <a href="#ordered">ordered set of unique - space-separated tokens</a>, each word of which is a host name. The list - allows authors to provide a list of host names that the user is expected - to subsequently need. User agents may, according to user preferences and - prevailing network conditions, pre-emptively resolve the given DNS names - (extracting the names from the value using the <a href="#split" - title="split a string on spaces">rules for splitting a string on - spaces</a>), thus precaching the DNS information for those hosts and - potentially reducing the time between page loads for subsequent user - interactions. Higher priority should be given to host names given - earlier in the list. - </dl> - - <h5 id=other><span class=secno>3.7.5.2. </span>Other metadata names</h5> - - <p><dfn id=extensions title=concept-meta-extensions>Extensions to the - predefined set of metadata names</dfn> may be registered in the <a - href="http://wiki.whatwg.org/wiki/MetaExtensions">WHATWG Wiki - MetaExtensions page</a>. - - <p>Anyone is free to edit the WHATWG Wiki MetaExtensions page at any time - to add a type. These new names must be specified with the following - information: - - <dl> - <dt>Keyword - - <dd> - <p>The actual name being defined. The name should not be confusingly - similar to any other defined name (e.g. differing only in case). - - <dt>Brief description - - <dd> - <p>A short description of what the metadata name's meaning is, including - the format the value is required to be in. - - <dt>Link to more details - - <dd>A link to a more detailed description of the metadata name's semantics - and requirements. It could be another page on the Wiki, or a link to an - external page. - - <dt>Synonyms - - <dd> - <p>A list of other names that have exactly the same processing - requirements. Authors should not use the names defined to be synonyms, - they are only intended to allow user agents to support legacy content. - - <dt>Status - - <dd> - <p>One of the following:</p> - - <dl> - <dt>Proposal - - <dd>The name has not received wide peer review and approval. Someone has - proposed it and is using it. - - <dt>Accepted - - <dd>The name has received wide peer review and approval. It has a - specification that unambiguously defines how to handle pages that use - the name, including when they use it in incorrect ways. - - <dt>Unendorsed - - <dd>The metadata name has received wide peer review and it has been - found wanting. Existing pages are using this keyword, but new pages - should avoid it. The "brief description" and "link to more details" - entries will give details of what authors should use instead, if - anything. - </dl> - - <p>If a metadata name is added with the "proposal" status and found to be - redundant with existing values, it should be removed and listed as a - synonym for the existing value.</p> - </dl> - - <p>Conformance checkers must use the information given on the WHATWG Wiki - MetaExtensions page to establish if a value not explicitly defined in this - specification is allowed or not. When an author uses a new type not - defined by either this specification or the Wiki page, conformance - checkers should offer to add the value to the Wiki, with the details - described above, with the "proposal" status. - - <p>This specification does not define how new values will get approved. It - is expected that the Wiki will have a community that addresses this. - - <p>Metadata names whose values are to be URIs must not be proposed or - accepted. Links must be represented using the <code><a - href="#link">link</a></code> element, not the <code><a - href="#meta0">meta</a></code> element. - - <h5 id=pragma><span class=secno>3.7.5.3. </span>Pragma directives</h5> - - <p>When the <dfn id=http-equiv - title=attr-meta-http-equiv><code>http-equiv</code></dfn> attribute is - specified on a <code><a href="#meta0">meta</a></code> element, the element - is a pragma directive. - - <p>The <dfn id=http-equiv0 - title=attr-meta-http-equiv><code>http-equiv</code></dfn> attribute is an - <a href="#enumerated">enumerated attribute</a>. The following table lists - the keywords defined for this attribute. The states given in the first - cell of the the rows with keywords give the states to which those keywords - map.<!-- Some of the keywords are non-conforming, as - noted in the last column.--> - - <table> - <thead> - <tr> - <th>State - - <th>Keywords <!-- <th>Notes--> - - <tbody><!-- things that are neither conforming nor do anything are commented out - <tr> - <td><span title="attr-meta-http-equiv-content-language">Content-Language</span> - <td><code title="">Content-Language</code> - <td>Non-conforming - <tr> - <td><span title="attr-meta-http-equiv-content-type">Content-Type</span> - <td><code title="">Content-Type</code> - <td>Non-conforming - <tr> - <td><span title="attr-meta-http-equiv-content-script-type">Content-Script-Type</span> - <td><code title="">Content-Script-Type</code> - <td>Non-conforming - <tr> - <td><span title="attr-meta-http-equiv-content-style-type">Content-Style-Type</span> - <td><code title="">Content-Style-Type</code> - <td>Non-conforming ---> - - <tr> - <td><a href="#refresh" title=attr-meta-http-equiv-refresh>Refresh</a> - - <td><code title="">refresh</code> <!-- <td>--> - - <tr> - <td><a href="#default" title=attr-meta-http-equiv-default-style>Default - style</a> - - <td><code title="">default-style</code> <!-- <td>--> - </table> - - <p>When a <code><a href="#meta0">meta</a></code> element is inserted into - the document, if its <code title=attr-meta-http-equiv><a - href="#http-equiv0">http-equiv</a></code> attribute is present and - represents one of the above states, then the user agent must run the - algorithm appropriate for that state, as described in the following list: - - <dl> - <dt><dfn id=refresh title=attr-meta-http-equiv-refresh>Refresh state</dfn> - - - <dd> - <ol><!-- TESTS: http://www.hixie.ch/tests/adhoc/html/meta/refresh/ --> - - <li> - <p>If another <code><a href="#meta0">meta</a></code> element in the <a - href="#refresh" title=attr-meta-http-equiv-refresh>Refresh state</a> - has already been successfully processed (i.e. when it was inserted the - user agent processed it and reached the last step of this list of - steps), then abort these steps. - - <li> - <p>If the <code><a href="#meta0">meta</a></code> element has no <code - title=attr-meta-content><a href="#content0">content</a></code> - attribute, or if that attribute's value is the empty string, then - abort these steps. - - <li> - <p>Let <var title="">input</var> be the value of the element's <code - title=attr-meta-content><a href="#content0">content</a></code> - attribute. - - <li> - <p>Let <var title="">position</var> point at the first character of - <var title="">input</var>. - - <li> - <p><a href="#skip-whitespace">Skip whitespace</a>. - - <li> - <p><a href="#collect" title="collect a sequence of characters">Collect - a sequence of characters</a> in the range U+0030 DIGIT ZERO to U+0039 - DIGIT NINE, and parse the resulting string using the <a - href="#rules">rules for parsing non-negative integers</a>. If the - sequence of characters collected is the empty string, then no number - will have been parsed; abort these steps. Otherwise, let <var - title="">time</var> be the parsed number. - - <li> - <p><a href="#collect" title="collect a sequence of characters">Collect - a sequence of characters</a> in the range U+0030 DIGIT ZERO to U+0039 - DIGIT NINE and U+002E FULL STOP ("<code title="">.</code>"). Ignore - any collected characters. - - <li> - <p><a href="#skip-whitespace">Skip whitespace</a>. - - <li> - <p>Let <var title="">url</var> be the address of the current page. - - <li> - <p>If the character in <var title="">input</var> pointed to by <var - title="">position</var> is a U+003B SEMICOLON ("<code - title="">;</code>"), then advance <var title="">position</var> to the - next character. Otherwise, jump to the last step. - - <li> - <p><a href="#skip-whitespace">Skip whitespace</a>. - - <li> - <p>If the character in <var title="">input</var> pointed to by <var - title="">position</var> is one of U+0055 LATIN CAPITAL LETTER U or - U+0075 LATIN SMALL LETTER U, then advance <var title="">position</var> - to the next character. Otherwise, jump to the last step. - - <li> - <p>If the character in <var title="">input</var> pointed to by <var - title="">position</var> is one of U+0052 LATIN CAPITAL LETTER R or - U+0072 LATIN SMALL LETTER R, then advance <var title="">position</var> - to the next character. Otherwise, jump to the last step. - - <li> - <p>If the character in <var title="">input</var> pointed to by <var - title="">position</var> is one of U+004C LATIN CAPITAL LETTER L or - U+006C LATIN SMALL LETTER L, then advance <var title="">position</var> - to the next character. Otherwise, jump to the last step. - - <li> - <p><a href="#skip-whitespace">Skip whitespace</a>. - - <li> - <p>If the character in <var title="">input</var> pointed to by <var - title="">position</var> is a U+003D EQUALS SIGN ("<code - title="">=</code>"), then advance <var title="">position</var> to the - next character. Otherwise, jump to the last step. - - <li> - <p><a href="#skip-whitespace">Skip whitespace</a>. - - <li> - <p>Let <var title="">url</var> be equal to the substring of <var - title="">input</var> from the character at <var - title="">position</var> to the end of the string. - - <li> - <p>Strip any trailing <a href="#space" title="space character">space - characters</a> from the end of <var title="">url</var>. - - <li> - <p>Strip any U+0009 CHARACTER TABULATION, U+000A LINE FEED (LF), and - U+000D CARRIAGE RETURN (CR) characters from <var title="">url</var>. - - <li> - <p>Resolve the <var title="">url</var> value to an absolute URI using - the base URI of the <code><a href="#meta0">meta</a></code> element. - - <li> - <p>Set a timer so that in <var title="">time</var> seconds, if the user - has not canceled the redirect, the user agent <a href="#navigate" - title=navigate>navigates</a> to <var title="">url</var>, with <a - href="#replacement">replacement enabled</a>. - </ol> - - <p>For <code><a href="#meta0">meta</a></code> elements in the <a - href="#refresh" title=attr-meta-http-equiv-refresh>Refresh state</a>, - the <code title=attr-meta-content><a href="#content0">content</a></code> - attribute must have a value consisting either of: - - <ul> - <li> just a <a href="#valid">valid non-negative integer</a>, or - - <li> a <a href="#valid">valid non-negative integer</a>, followed by a - U+003B SEMICOLON (<code title="">;</code>), followed by one or more <a - href="#space" title="space character">space characters</a>, followed by - either a U+0055 LATIN CAPITAL LETTER U or a U+0075 LATIN SMALL LETTER - U, a U+0052 LATIN CAPITAL LETTER R or a U+0072 LATIN SMALL LETTER R, a - U+004C LATIN CAPITAL LETTER L or a U+006C LATIN SMALL LETTER L, a - U+003D EQUALS SIGN (<code title="">=</code>), and then a valid URI (or - IRI). - </ul> - - <p>In the former case, the integer represents a number of seconds before - the page is to be reloaded; in the latter case the integer represents a - number of seconds before the page is to be replaced by the page at the - given URI.</p> - - <dd> - - <dt><dfn id=default title=attr-meta-http-equiv-default-style>Default style - state</dfn> - - <dd> - <ol> - <li class=big-issue>... - </ol> - - <dd> - </dl> - - <h5 id=charset><span class=secno>3.7.5.4. </span>Specifying and - establishing the document's character encoding</h5> - - <p>The <code><a href="#meta0">meta</a></code> element may also be used to - provide UAs with character encoding information for <a href="#html5" - title=HTML5>HTML</a> files, by setting the <dfn id=charset0 - title=attr-meta-charset><code>charset</code></dfn> attribute to the name - of a character encoding. This is called a character encoding declaration. - - <p>The following restrictions apply to character encoding declarations: - - <ul> - <li>When <a href="#syntax">serialised</a>, the <code - title=attr-meta-charset><a href="#charset0">charset</a></code> attribute - and its value must be contained completely in the first 512 bytes of the - file. - - <li>The attribute value must be serialised without the use of character - entity references of any kind. - - <li>The value must be a valid character encoding name. <a - href="#refsIANACHARSET">[IANACHARSET]</a> <!-- XXX - http://www.iana.org/assignments/character-sets --> - - <li>The character encoding name given must be the name of the character - encoding used to serialise the file. - - <li>The character encoding used must be a superset of US-ASCII - (specifically, ANSI_X3.4-1968) for bytes in the range 0x09 - 0x0D, 0x20, - 0x21, 0x22, 0x26, 0x27, 0x2C - 0x3F, 0x41 - 0x5A, and 0x61 - 0x7A.</li> - <!-- XXX #refs RFC1345 ? --> - <!-- is that list ok? do - any character sets we want to support do things outside that range? - --> - </ul> - - <p>If the encoding is one of UTF-8, UTF-16BE, UTF-16LE, UTF-32BE, or - UTF-32LE, then authors can use a BOM at the start of the file to indicate - the character encoding.</p> - <!-- UTF-EBCDIC, too! --> - - <p>In XHTML, the XML declaration should be used for inline character - encoding information, if necessary. - - <h4 id=the-style><span class=secno>3.7.6. </span>The <dfn - id=style><code>style</code></dfn> element</h4> - - <p><a href="#metadata" title="metadata elements">Metadata element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>In a <code><a href="#head">head</a></code> element. - - <dd>At the start of <code><a href="#article">article</a></code>, <code><a - href="#aside">aside</a></code>, <code><a href="#div">div</a></code>, and - <code><a href="#section">section</a></code> elements. - - <dt>Content model: - - <dd>Depends on the value of the <code title=attr-style-type><a - href="#type1">type</a></code> attribute. - - <dt>Element-specific attributes: - - <dd><code title=attr-style-media><a href="#media2">media</a></code> - - <dd><code title=attr-style-type><a href="#type1">type</a></code> - - <dd><code title=attr-style-scoped><a href="#scoped">scoped</a></code> - - <dd>Also, the <code title=attr-style-title><a - href="#title3">title</a></code> attribute has special semantics on this - element. - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmlstyleelement>HTMLStyleElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute boolean <code title=dom-style-disabled><a href="#disabled0">disabled</a></code>; - attribute DOMString <code title=dom-style-media><a href="#media3">media</a></code>; - attribute DOMString <code title=dom-style-type><a href="#type2">type</a></code>; - attribute boolean <code title=dom-style-scoped><a href="#scoped0">scoped</a></code>; -};</pre> - - <p>The <code>LinkStyle</code> interface must also be implemented by this - element, the <a href="#styling0">styling processing model</a> defines - how. <a href="#refsCSSOM">[CSSOM]</a></p> - </dl> - - <p>The <code><a href="#style">style</a></code> element allows authors to - embed style information in their documents. The <code><a - href="#style">style</a></code> element is one of several inputs to the <a - href="#styling0">styling processing model</a>. - - <p>If the <dfn id=type1 title=attr-style-type><code>type</code></dfn> - attribute is given, it must contain a valid MIME type, optionally with - parameters, that designates a styling language. <a - href="#refsRFC2046">[RFC2046]</a> If the attribute is absent, the type - defaults to <code>text/css</code>. <a href="#refsRFC2318">[RFC2138]</a></p> - <!-- XXX this is the second time we have this paragraph here... --> - - <p>When examining types to determine if they support the language, user - agents must not ignore unknown MIME parameters — types with unknown - parameters must be assumed to be unsupported. - - <p>The <dfn id=media2 title=attr-style-media><code>media</code></dfn> - attribute says which media the styles apply to. The value must be a valid - media query. <a href="#refsMQ">[MQ]</a> User agents must only apply the - styles to <span>views</span> while their state match the listed media. <a - href="#refsDOM3VIEWS">[DOM3VIEWS]</a> - - <p id=style-default-media>The default, if the <code - title=attr-style-media><a href="#media2">media</a></code> attribute is - omitted, is <code>all</code>, meaning that by default styles apply to all - media. - - <p>The <dfn id=scoped title=attr-style-scoped><code>scoped</code></dfn> - attribute is a <a href="#boolean0">boolean attribute</a>. If the attribute - is present, then the user agent must only apply the specified style - information to the <code><a href="#style">style</a></code> element's - parent element (if any), and that element's child nodes. Otherwise, the - specified styles must, if applied, be applied to the entire document. - - <p id=title-on-style>The <dfn id=title3 - title=attr-style-title><code>title</code></dfn> attribute on <code><a - href="#style">style</a></code> elements defines <a - href="#alternative">alternative style sheet sets</a>. If the <code><a - href="#style">style</a></code> element has no <code - title=attr-style-title><a href="#title3">title</a></code> attribute, then - it has no title; the <code title=attr-title><a - href="#title">title</a></code> attribute of ancestors does not apply to - the <code><a href="#style">style</a></code> element.</p> - <!-- - XXX xref --> - - <p class=note>The <code title=attr-style-title><a - href="#title3">title</a></code> attribute on <code><a - href="#style">style</a></code> elements, like the <code - title=attr-link-title><a href="#title2">title</a></code> attribute on - <code><a href="#link">link</a></code> elements, differs from the global - <code title=attr-title><a href="#title">title</a></code> attribute in that - a <code><a href="#style">style</a></code> block without a title does not - inherit the title of the parent element: it merely has no title. - - <p>All descendant elements must be processed, according to their semantics, - before the <code><a href="#style">style</a></code> element itself is - evaluated. For styling languages that consist of pure text, user agents - must evaluate <code><a href="#style">style</a></code> elements by passing - the concatenation of the contents of all the <a href="#text-node" - title="text node">text nodes</a> that are direct children of the <code><a - href="#style">style</a></code> element (not any other nodes such as - comments or elements), in <a href="#tree-order">tree order</a>, to the - style system. For XML-based styling languages, user agents must pass all - the children nodes of the <code><a href="#style">style</a></code> element - to the style system. - - <p class=note>This specification does not specify a style system, but CSS - is expected to be supported by most Web browsers. <a - href="#refsCSS21">[CSS21]</a> - - <p>The <dfn id=media3 title=dom-style-media><code>media</code></dfn>, <dfn - id=type2 title=dom-style-type><code>type</code></dfn> and <dfn id=scoped0 - title=dom-style-scoped><code>scoped</code></dfn> DOM attributes must <a - href="#reflect">reflect</a> the respective content attributes of the same - name. - - <p>The DOM <dfn id=disabled0 - title=dom-style-disabled><code>disabled</code></dfn> attribute behaves as - defined <a href="#disabled1" title=dom-linkstyle-disabled>for the - alternative style sheets DOM</a>. - - <h4 id=styling><span class=secno>3.7.7. </span><dfn id=styling0 - title="styling processing model">Styling</dfn></h4> - - <p>The <code><a href="#link">link</a></code> and <code><a - href="#style">style</a></code> elements can provide styling information - for the user agent to use when rendering the document. The DOM Styling - specification specifies what styling information is to be used by the user - agent and how it is to be used. <a href="#refsCSSOM">[CSSOM]</a> - - <p>The <code><a href="#style">style</a></code> and <code><a - href="#link">link</a></code> elements implement the <code>LinkStyle</code> - interface. <a href="#refsCSSOM">[CSSOM]</a> - - <p>For <code><a href="#style">style</a></code> elements, if the user agent - does not support the specified styling language, then the <code - title=dom-LinkStyle-sheet>sheet</code> attribute of the element's - <code>LinkStyle</code> interface must return null. Similarly, <code><a - href="#link">link</a></code> elements that do not represent <a - href="#stylesheet" title=rel-stylesheet>external resource links that - contribute to the styling processing model</a> (i.e. that do not have a - <code title=rel-stylesheet><a href="#stylesheet">stylesheet</a></code> - keyword in their <code title=attr-link-rel><a href="#rel">rel</a></code> - attribute), and <code><a href="#link">link</a></code> elements whose - specified resource has not yet been downloaded, or is not in a supported - styling language, must have their <code>LinkStyle</code> interface's <code - title=dom-LinkStyle-sheet>sheet</code> attribute return null. - - <p>Otherwise, the <code>LinkStyle</code> interface's <code - title=dom-LinkStyle-sheet>sheet</code> attribute must return a - <code>StyleSheet</code> object with the attributes implemented as follows: - <a href="#refsCSSOM">[CSSOM]</a> - - <dl> - <dt>The content type (<code title=dom-stylesheet-type>type</code> DOM - attribute) - - <dd> - <p>The content type must be the same as the style's specified type. For - <code><a href="#style">style</a></code> elements, this is the same as - the <code title=attr-style-type><a href="#type1">type</a></code> content - attribute's value, or <code title="">text/css</code> if that is omitted. - For <code><a href="#link">link</a></code> elements, this is the <a - href="#content-type8" title=Content-Type>Content-Type metadata of the - specified resource</a>. - - <dt>The location (<code title=dom-stylesheet-href>href</code> DOM - attribute) - - <dd> - <p>For <code><a href="#link">link</a></code> elements, the location must - be the URI given by the element's <code title=attr-link-href><a - href="#href1">href</a></code> content attribute. For <code><a - href="#style">style</a></code> elements, there is no location. - - <dt>The intended destination media for style information (<code - title=dom-stylesheet-media>media</code> DOM attribute) - - <dd> - <p>The media must be the same as the value of the element's <code - title="">media</code> content attribute. - - <dt>The style sheet title (<code title=dom-stylesheet-title>title</code> - DOM attribute) - - <dd> - <p>The title must be the same as the value of the element's <code - title="">title</code> content attribute. If the attribute is absent, - then the style sheet does not have a title. The title is used for - defining <dfn id=alternative>alternative style sheet sets</dfn>. - </dl> - - <p>The <dfn id=disabled1 - title=dom-LinkStyle-disabled><code>disabled</code></dfn> DOM attribute on - <code><a href="#link">link</a></code> and <code><a - href="#style">style</a></code> elements must return false and do nothing - on setting, if the <code title=dom-linkstyle-sheet>sheet</code> attribute - of their <code>LinkStyle</code> interface is null. Otherwise, it must - return the value of the <code>StyleSheet</code> interface's <code - title=dom-stylesheet-disabled>disabled</code> attribute on getting, and - forward the new value to that same attribute on setting.</p> - <!-- <p class="big-issue">Need more here - defining preferred - stylesheets, alternative stylesheets, persistent stylesheets, ordering - of stylesheets, dynamic additions/removals, how it maps to - .styleSheets, HTTP Link: headers, and the stuff about the alternative - stylesheet API.</p> XXX that will all be covered by Anne's spec --> - - <h3 id=sections><span class=secno>3.8. </span>Sections</h3> - - <p><dfn id=sectioning>Sectioning elements</dfn> are elements that divide - the page into, for lack of a better word, sections. This section describes - HTML's sectioning elements and elements that support them. - - <p id=applyToSection>Some elements are scoped to their nearest ancestor - sectioning element. For example, <code><a - href="#address">address</a></code> elements apply just to their section. - For such elements <var title="">x</var>, the elements that apply to a - sectioning element <var title="">e</var> are all the <var title="">x</var> - elements whose nearest sectioning element is <var title="">e</var>. - - <h4 id=the-body><span class=secno>3.8.1. </span>The <dfn - id=body0><code>body</code></dfn> element</h4> - - <p><a href="#sectioning" title="sectioning elements">Sectioning - element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>As the second element in an <code><a href="#html">html</a></code> - element. - - <dt>Content model: - - <dd>Zero or more <a href="#block-level0">block-level elements</a>. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#body0">body</a></code> element represents the main - content of the document. - - <p>The <code><a href="#body0">body</a></code> element potentially has a - heading. See the section on <a href="#headings0">headings and sections</a> - for further details. - - <p>In conforming documents, there is only one <code><a - href="#body0">body</a></code> element. The <code - title=dom-document-body><a href="#body">document.body</a></code> DOM - attribute provides scripts with easy access to a document's <code><a - href="#body0">body</a></code> element. - - <p class=note>Some DOM operations (for example, parts of the <a - href="#drag-and">drag and drop</a> model) are defined in terms of "<a - href="#the-body0">the body element</a>". This refers to a particular - element in the DOM, as per the definition of the term, and not any - arbitrary <code><a href="#body0">body</a></code> element. - - <h4 id=the-section><span class=secno>3.8.2. </span>The <dfn - id=section><code>section</code></dfn> element</h4> - - <p><a href="#sectioning" title="sectioning elements">Sectioning</a> <a - href="#block-level0" title="block-level elements">block-level element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> are expected. - - <dt>Content model: - - <dd>Zero or more <code><a href="#style">style</a></code> elements, - followed by zero or more <a href="#block-level0">block-level - elements</a>. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#section">section</a></code> element represents a - generic document or application section. A section, in this context, is a - thematic grouping of content, typically with a header, possibly with a - footer. - - <p class=example>Examples of sections would be chapters, the various tabbed - pages in a tabbed dialog box, or the numbered sections of a thesis. A Web - site's home page could be split into sections for an introduction, news - items, contact information. - - <p>Each <code><a href="#section">section</a></code> element potentially has - a heading. See the section on <a href="#headings0">headings and - sections</a> for further details. - - <h4 id=the-nav><span class=secno>3.8.3. </span>The <dfn - id=nav><code>nav</code></dfn> element</h4> - - <p><a href="#sectioning" title="sectioning elements">Sectioning</a> <a - href="#block-level0" title="block-level elements">block-level element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> are expected. - - <dt>Content model: - - <dd>Zero or more <a href="#block-level0">block-level elements</a>, or <a - href="#inline-level0">inline-level content</a> (but not both). - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#nav">nav</a></code> element represents a section of - a page that links to other pages or to parts within the page: a section - with navigation links. - - <p>When <a href="#determining0" title="Determining if a particular element - contains block-level elements or inline-level content">used as an - inline-level content</a> container, the element represents a <a - href="#paragraph">paragraph</a>. - - <p>Each <code><a href="#nav">nav</a></code> element potentially has a - heading. See the section on <a href="#headings0">headings and sections</a> - for further details. - - <h4 id=the-article><span class=secno>3.8.4. </span>The <dfn - id=article><code>article</code></dfn> element</h4> - - <p><a href="#sectioning" title="sectioning elements">Sectioning</a> <a - href="#block-level0" title="block-level elements">block-level element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> are expected. - - <dt>Content model: - - <dd>Zero or more <code><a href="#style">style</a></code> elements, - followed by zero or more <a href="#block-level0">block-level - elements</a>. - - <dt>Element-specific attributes: - - <dd>None.</dd> - <!-- -XXX attributes to give the date authored, date published ---> - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#article">article</a></code> element represents a - section of a page that consists of a composition that forms an independent - part of a document, page, or site. This could be a forum post, a magazine - or newspaper article, a Web log entry, a user-submitted comment, or any - other independent item of content. - - <p class=note>An <code><a href="#article">article</a></code> element is - "independent" in that its contents could stand alone, for example in - syndication. However, the element is still associated with its ancestors; - for instance, contact information that <a - href="#applyToSection">applies</a> to a parent <code><a - href="#body0">body</a></code> element still covers the <code><a - href="#article">article</a></code> as well. - - <p>When <code><a href="#article">article</a></code> elements are nested, - the inner <code><a href="#article">article</a></code> elements represent - articles that are in principle related to the contents of the outer - article. For instance, a Web log entry on a site that accepts - user-submitted comments could represent the comments as <code><a - href="#article">article</a></code> elements nested within the <code><a - href="#article">article</a></code> element for the Web log entry. - - <p>Author information associated with an <code><a - href="#article">article</a></code> element (q.v. the <code><a - href="#address">address</a></code> element) does not apply to nested - <code><a href="#article">article</a></code> elements. - - <p>Each <code><a href="#article">article</a></code> element potentially has - a heading. See the section on <a href="#headings0">headings and - sections</a> for further details. - - <h4 id=the-blockquote><span class=secno>3.8.5. </span>The <dfn - id=blockquote><code>blockquote</code></dfn> element</h4> - - <p><a href="#sectioning" title="sectioning elements">Sectioning</a> <a - href="#block-level0" title="block-level elements">block-level element</a>, - and <a href="#structured" title="structured inline-level - elements">structured inline-level element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> are expected. - - <dd>Where <a href="#structured">structured inline-level elements</a> are - allowed. - - <dt>Content model: - - <dd>Zero or more <a href="#block-level0">block-level elements</a>. - - <dt>Element-specific attributes: - - <dd><code title=attr-blockquote-cite><a href="#cite">cite</a></code> - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmlquoteelement>HTMLQuoteElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute DOMString <a href="#cite0" title=dom-quote-cite>cite</a>; -};</pre> - - <p class=note>The <code><a - href="#htmlquoteelement">HTMLQuoteElement</a></code> interface is also - used by the <code><a href="#q">q</a></code> element.</p> - </dl> - - <p>The <code><a href="#blockquote">blockquote</a></code> element represents - a section that is quoted from another source. - - <p>Content inside a <code><a href="#blockquote">blockquote</a></code> must - be quoted from another source, whose URI, if it has one, should be cited - in the <dfn id=cite title=attr-blockquote-cite><code>cite</code></dfn> - attribute. - - <p>If the <code title=attr-blockquote-cite><a href="#cite">cite</a></code> - attribute is present, it must be a URI (or IRI). User agents should allow - users to follow such citation links. - - <p>If a <code><a href="#blockquote">blockquote</a></code> element is <a - href="#preceeded">preceeded or followed</a> by a <code><a - href="#p">p</a></code> element that contains a single <code><a - href="#cite2">cite</a></code> element and is itself not <a - href="#preceeded">preceeded or followed</a> by another <code><a - href="#blockquote">blockquote</a></code> element and does not itself have - a <code><a href="#q">q</a></code> element descendant, then, the citation - given by that <code><a href="#cite2">cite</a></code> element gives the - source of the quotation contained in the <code><a - href="#blockquote">blockquote</a></code> element. - - <p>Each <code><a href="#blockquote">blockquote</a></code> element - potentially has a heading. See the section on <a - href="#headings0">headings and sections</a> for further details. - - <p>The <dfn id=cite0 title=dom-quote-cite><code>cite</code></dfn> DOM - attribute <code>reflects</code> the element's <code title="">cite</code> - content attribte. - - <p class=note>The best way to represent a conversation is not with the - <code><a href="#cite2">cite</a></code> and <code><a - href="#blockquote">blockquote</a></code> elements, but with the <code><a - href="#dialog">dialog</a></code> element. - - <h4 id=the-aside><span class=secno>3.8.6. </span>The <dfn - id=aside><code>aside</code></dfn> element</h4> - - <p><a href="#sectioning" title="sectioning elements">Sectioning</a> <a - href="#block-level0" title="block-level elements">block-level element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> are expected. - - <dt>Content model: - - <dd>Zero or more <code><a href="#style">style</a></code> elements, - followed by either zero or more <a href="#block-level0">block-level - elements</a>, or <a href="#inline-level0">inline-level content</a> (but - not both). - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#aside">aside</a></code> element represents a section - of a page that consists of content that is tangentially related to the - content around the <code><a href="#aside">aside</a></code> element, and - which could be considered separate from that content. Such sections are - often represented as sidebars in printed typography. - - <p>When <a href="#determining0" title="Determining if a particular element - contains block-level elements or inline-level content">used as an - inline-level content</a> container, the element represents a <a - href="#paragraph">paragraph</a>. - - <p>Each <code><a href="#aside">aside</a></code> element potentially has a - heading. See the section on <a href="#headings0">headings and sections</a> - for further details. - - <h4 id=the-h1><span class=secno>3.8.7. </span>The <dfn - id=h1><code>h1</code></dfn>, <dfn id=h2><code>h2</code></dfn>, <dfn - id=h3><code>h3</code></dfn>, <dfn id=h4><code>h4</code></dfn>, <dfn - id=h5><code>h5</code></dfn>, and <dfn id=h6><code>h6</code></dfn> elements</h4> - - <p><a href="#block-level0">Block-level elements</a>. - - <dl class=element> - <dt>Contexts in which these elements may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> are expected. - - <dt>Content model: - - <dd><a href="#significant" title="significant inline - content">Significant</a> <a href="#strictly">strictly inline-level - content</a>. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>These elements define headers for their sections. - - <p>The semantics and meaning of these elements are defined in the section - on <a href="#headings0">headings and sections</a>. - - <p>These elements have a <dfn id=rank>rank</dfn> given by the number in - their name. The <code><a href="#h1">h1</a></code> element is said to have - the highest rank, the <code><a href="#h6">h6</a></code> element has the - lowest rank, and two elements with the same name have equal rank. - - <p>These elements must not be <a href="#significant" title="significant - inline content">empty</a>. - - <h4 id=the-header><span class=secno>3.8.8. </span>The <dfn - id=header><code>header</code></dfn> element</h4> - - <p><a href="#block-level0" title="block-level elements">Block-level - element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> are expected - and there are no <code><a href="#header">header</a></code> ancestors. - - <dt>Content model: - - <dd>Zero or more <a href="#block-level0">block-level elements</a>, - including at least one descendant <code><a href="#h1">h1</a></code>, - <code><a href="#h2">h2</a></code>, <code><a href="#h3">h3</a></code>, - <code><a href="#h4">h4</a></code>, <code><a href="#h5">h5</a></code>, or - <code><a href="#h6">h6</a></code> element, but no <span>sectioning - element</span> descendants, no <code><a href="#header">header</a></code> - element descendants, and no <code><a href="#footer">footer</a></code> - element descendants. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#header">header</a></code> element represents the - header of a section. Headers may contain more than just the section's - heading — for example it would be reasonable for the header to - include version history information. - - <p><code><a href="#header">header</a></code> elements must not contain any - <code><a href="#header">header</a></code> elements, <code><a - href="#footer">footer</a></code> elements, or any sectioning elements - (such as <code><a href="#section">section</a></code>) as descendants. - - <p><code><a href="#header">header</a></code> elements must have at least - one <code><a href="#h1">h1</a></code>, <code><a href="#h2">h2</a></code>, - <code><a href="#h3">h3</a></code>, <code><a href="#h4">h4</a></code>, - <code><a href="#h5">h5</a></code>, or <code><a href="#h6">h6</a></code> - element as a descendant. - - <p>For the purposes of document summaries, outlines, and the like, <code><a - href="#header">header</a></code> elements are equivalent to the highest <a - href="#rank" title=rank>ranked</a> <code><a - href="#h1">h1</a></code>-<code><a href="#h6">h6</a></code> element - descendant (the first such element if there are multiple elements with - that <a href="#rank">rank</a>). - - <p>Other heading elements indicate subheadings or subtitles. - - <div class=example> - <p>Here are some examples of valid headers. In each case, the emphasised - text represents the text that would be used as the header in an - application extracting header data and ignoring subheadings.</p> - - <pre><header> - <h1><strong>The reality dysfunction</strong></h1> - <h2>Space is not the only void</h2> -</header></pre> - - <pre><header> - <p>Welcome to...</p> - <h1><strong>Voidwars!</strong></h1> -</header></pre> - - <pre><header> - <h1><strong>Scalable Vector Graphics (SVG) 1.2</strong></h1> - <h2>W3C Working Draft 27 October 2004</h2> - <dl> - <dt>This version:</dt> - <dd><a href="http://www.w3.org/TR/2004/WD-SVG12-20041027/">http://www.w3.org/TR/2004/WD-SVG12-20041027/</a></dd> - <dt>Previous version:</dt> - <dd><a href="http://www.w3.org/TR/2004/WD-SVG12-20040510/">http://www.w3.org/TR/2004/WD-SVG12-20040510/</a></dd> - <dt>Latest version of SVG 1.2:</dt> - <dd><a href="http://www.w3.org/TR/SVG12/">http://www.w3.org/TR/SVG12/</a></dd> - <dt>Latest SVG Recommendation:</dt> - <dd><a href="http://www.w3.org/TR/SVG/">http://www.w3.org/TR/SVG/</a></dd> - <dt>Editor:</dt> - <dd>Dean Jackson, W3C, <a href="mailto:dean@w3.org">dean@w3.org</a></dd> - <dt>Authors:</dt> - <dd>See <a href="#authors">Author List</a></dd> - </dl> - <p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notic <em>...</em> -</header></pre> - </div> - - <p>The section on <a href="#headings0">headings and sections</a> defines - how <code><a href="#header">header</a></code> elements are assigned to - individual sections. - - <p>The <a href="#rank">rank</a> of a <code><a - href="#header">header</a></code> element is the same as for an <code><a - href="#h1">h1</a></code> element (the highest rank). - - <h4 id=the-footer><span class=secno>3.8.9. </span>The <dfn - id=footer><code>footer</code></dfn> element</h4> - - <p><a href="#block-level0" title="block-level elements">Block-level - element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> are expected. - - <dt>Content model: - - <dd>Either zero or more <a href="#block-level0">block-level elements</a>, - but with no <code><a href="#h1">h1</a></code>, <code><a - href="#h2">h2</a></code>, <code><a href="#h3">h3</a></code>, <code><a - href="#h4">h4</a></code>, <code><a href="#h5">h5</a></code>, <code><a - href="#h6">h6</a></code>, <code><a href="#header">header</a></code>, or - <code><a href="#footer">footer</a></code> elements as descendants, and - with no <a href="#sectioning" title="sectioning elements">sectioning - elements</a> as descendants; or, <a href="#inline-level0">inline-level - content</a> (but not both). - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#footer">footer</a></code> element represents the - footer for the section it <a href="#applyToSection">applies</a> to. A - footer typically contains information about its section such as who wrote - it, links to related documents, copyright data, and the like. - - <p><code><a href="#footer">footer</a></code> elements must not contain any - <code><a href="#footer">footer</a></code>, <code><a - href="#header">header</a></code>, <code><a href="#h1">h1</a></code>, - <code><a href="#h2">h2</a></code>, <code><a href="#h3">h3</a></code>, - <code><a href="#h4">h4</a></code>, <code><a href="#h5">h5</a></code>, or - <code><a href="#h6">h6</a></code> elements, or any of the sectioning - elements (such as <code><a href="#section">section</a></code>), as - descendants. - - <p>When <a href="#determining0" title="Determining if a particular element - contains block-level elements or inline-level content">used as an - inline-level content</a> container, the element represents a <a - href="#paragraph">paragraph</a>. - - <p>Contact information for the section given in a <code><a - href="#footer">footer</a></code> should be marked up using the <code><a - href="#address">address</a></code> element.</p> - <!-- XXX examples needed --> - - <h4 id=the-address><span class=secno>3.8.10. </span>The <dfn - id=address><code>address</code></dfn> element</h4> - - <p><a href="#block-level0" title="block-level elements">Block-level - element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> are expected. - - <dt>Content model: - - <dd><a href="#inline-level0">Inline-level content</a>. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#address">address</a></code> element represents a <a - href="#paragraph">paragraph</a> of contact information for the section it - <a href="#applyToSection">applies</a> to. - - <div class=example> - <p>For example, a page at the W3C Web site related to HTML might include - the following contact information:</p> - - <pre><ADDRESS> - <A href="../People/Raggett/">Dave Raggett</A>, - <A href="../People/Arnaud/">Arnaud Le Hors</A>, - contact persons for the <A href="Activity">W3C HTML Activity</A> -</ADDRESS></pre> - </div> - - <p>The <code><a href="#address">address</a></code> element must not be used - to represent arbitrary addresses (e.g. postal addresses), unless those - addresses are contact information for the section. (The <code><a - href="#p">p</a></code> element is the appropriate element for marking up - such addresses.) - - <p>The <code><a href="#address">address</a></code> element must not contain - information other than contact information. - - <div class=example> - <p>For example, the following is non-conforming use of the <code><a - href="#address">address</a></code> element:</p> - - <pre><ADDRESS>Last Modified: 1999/12/24 23:37:50</ADDRESS></pre> - </div> - - <p>Typically, the <code><a href="#address">address</a></code> element would - be included with other information in a <code><a - href="#footer">footer</a></code> element. - - <p>To determine the contact information for a sectioning element (such as a - document's <code><a href="#body0">body</a></code> element, which would - give the contact information for the page), UAs must collect all the - <code><a href="#address">address</a></code> elements that <a - href="#applyToSection">apply</a> to that sectioning element and its - ancestor sectioning elements. The contact information is the collection of - all the information given by those elements. - - <p class=note>Contact information for one sectioning element, e.g. a - <code><a href="#aside">aside</a></code> element, does not apply to its - ancestor elements, e.g. the page's <code><a href="#body0">body</a></code>. - - <h4 id=headings><span class=secno>3.8.11. </span><dfn id=headings0>Headings - and sections</dfn></h4> - - <p>The <code><a href="#h1">h1</a></code>-<code><a href="#h6">h6</a></code> - elements and the <code><a href="#header">header</a></code> element are - headings. - - <p>The first heading in a sectioning element gives the header for that - section. Subsequent headers of equal or higher <a href="#rank">rank</a> - start new (implied) sections, headers of lower <a href="#rank">rank</a> - start subsections that are part of the previous one. - - <p>Sectioning elements other than <code><a - href="#blockquote">blockquote</a></code> are always considered subsections - of their nearest ancestor sectioning element, regardless of what implied - sections other headings may have created. However, <code><a - href="#blockquote">blockquote</a></code> elements <em>are</em> associated - with implied sections. Effectively, <code><a - href="#blockquote">blockquote</a></code> elements act like sections on the - inside, and act opaquely on the outside. - - <div class=example> - <p>For the following fragment:</p> - - <pre><body> - <h1>Foo</h1> - <h2>Bar</h2> - <blockquote> - <h3>Bla</h3> - </blockquote> - <p>Baz</p> - <h2>Quux</h2> - <section> - <h3>Thud</h3> - </section> - <p>Grunt</p> -</body></pre> - - <p>...the structure would be:</p> - - <ol> - <li> Foo (heading of explicit <code><a href="#body0">body</a></code> - section) - <ol> - <li> Bar (heading starting implied section) - <ol> - <li> Bla (heading of explicit <code><a - href="#blockquote">blockquote</a></code> section) - </ol> - Baz (paragraph) - - <li> Quux (heading starting implied section) - - <li> Thud (heading of explicit <code><a - href="#section">section</a></code> section) - </ol> - Grunt (paragraph) - </ol> - - <p>Notice how the <code><a href="#blockquote">blockquote</a></code> nests - inside an implicit section while the <code><a - href="#section">section</a></code> does not (and in fact, ends the - earlier implicit section so that a later paragraph is back at the top - level).</p> - </div> - - <p>Sections may contain headers of any <a href="#rank">rank</a>, but - authors are strongly encouraged to either use only <code><a - href="#h1">h1</a></code> elements, or to use elements of the appropriate - <a href="#rank">rank</a> for the section's nesting level. - - <p>Authors are also encouraged to explictly wrap sections in sectioning - elements, instead of relying on the implicit sections generated by having - multiple heading in one sectioning element. - - <div class=example> - <p>For example, the following is correct:</p> - - <pre><body> - <h4>Apples</h4> - <p>Apples are fruit.</p> - <section> - <h2>Taste</h2> - <p>They taste lovely.</p> - <h6>Sweet</h6> - <p>Red apples are sweeter than green ones.</p> - <h1>Color</h1> - <p>Apples come in various colors.</p> - </section> -</body></pre> - - <p>However, the same document would be more clearly expressed as:</p> - - <pre><body> - <h1>Apples</h1> - <p>Apples are fruit.</p> - <section> - <h2>Taste</h2> - <p>They taste lovely.</p> - <section> - <h3>Sweet</h3> - <p>Red apples are sweeter than green ones.</p> - </section> - </section> - <section> - <h2>Color</h2> - <p>Apples come in various colors.</p> - </section> -</body></pre> - - <p>Both of the documents above are semantically identical and would - produce the same outline in compliant user agents.</p> - </div> - - <h5 id=outlines><span class=secno>3.8.11.1. </span>Creating an outline</h5> - - <p>Documents can be viewed as a tree of sections, which defines how each - element in the tree is semantically related to the others, in terms of the - overall section structure. This tree is related to the document tree, but - there is not a one-to-one relationship between elements in the DOM and the - document's sections. - - <p>The tree of sections should be used when generating document outlines, - for example when generating tables of contents. - - <p>To derive the tree of sections from the document tree, a hypothetical - tree is used, consisting of a view of the document tree containing only - the <code><a href="#h1">h1</a></code>-<code><a href="#h6">h6</a></code> - and <code><a href="#header">header</a></code> elements, and the sectioning - elements other than <code><a href="#blockquote">blockquote</a></code>. - Descendants of <code><a href="#h1">h1</a></code>-<code><a - href="#h6">h6</a></code>, <code><a href="#header">header</a></code>, and - <code><a href="#blockquote">blockquote</a></code> elements must be removed - from this view. - - <p>The hypothetical tree must be rooted at the <a href="#root-element">root - element</a> or at a sectioning element. In particular, while the sections - inside <code><a href="#blockquote">blockquote</a></code>s do not - contribute to the document's tree of sections, <code><a - href="#blockquote">blockquote</a></code>s can have outlines of their own. - - <p>UAs must take this hypothetical tree (which will become the outline) and - mutate it by walking it depth first in <a href="#tree-order">tree - order</a> and, for each <code><a href="#h1">h1</a></code>-<code><a - href="#h6">h6</a></code> or <code><a href="#header">header</a></code> - element that is not the first element of its parent sectioning element, - inserting a new sectioning element, as follows: - - <dl class=switch> - <dt>If the element is a <code><a href="#header">header</a></code> element, - or if it is an <code><a href="#h1">h1</a></code>-<code><a - href="#h6">h6</a></code> node of <a href="#rank">rank</a> equal to or - higher than the first element in the parent sectioning element (assuming - that is also an <code><a href="#h1">h1</a></code>-<code><a - href="#h6">h6</a></code> node), or if the first element of the parent - sectioning element is a sectioning element: - - <dd>Insert the new sectioning element as the immediately following sibling - of the parent sectioning element, and move all the elements from the - current heading element up to the end of the parent sectioning element - into the new sectioning element. - - <dt>Otherwise: - - <dd>Move the current heading element, and all subsequent siblings up to - but excluding the next sectioning element, <code><a - href="#header">header</a></code> element, or <code><a - href="#h1">h1</a></code>-<code><a href="#h6">h6</a></code> of equal or - higher <a href="#rank">rank</a>, whichever comes first, into the new - sectioning element, then insert the new sectioning element where the - current header was. - </dl> - - <p>The outline is then the resulting hypothetical tree. The <a href="#rank" - title=rank>ranks</a> of the headers become irrelevant at this point: each - sectioning element in the hypothetical tree contains either no or one - heading element child. If there is one, then it gives the section's - heading, of there isn't, the section has no heading. - - <p>Sections are nested as in the hypothetical tree. If a sectioning element - is a child of another, that means it is a subsection of that other - section. - - <p>When creating an interactive table of contents, entries should jump the - user to the relevant section element, if it was a real element in the - original document, or to the heading, if the section element was one of - those created during the above process. - - <p class=example>Selecting the first section of the document therefore - always takes the user to the top of the document, regardless of where the - first header in the <code><a href="#body0">body</a></code> is to be found.</p> - <!-- XXX assuming there is a body, anyway --> - - <div class=note> - <p>The hypothetical tree (before mutations) could be generated by creating - a <code>TreeWalker</code> with the following <a - href="http://www.w3.org/TR/DOM-Level-2-Traversal-Range/traversal.html#Traversal-NodeFilter"><code>NodeFilter</code></a> - (described here as an anonymous ECMAScript function). <a - href="#refsDOMTR">[DOMTR]</a> <a href="#refsECMA262">[ECMA262]</a></p> - - <pre>function (n) { - // This implementation only knows about HTML elements. - // An implementation that supports other languages might be - // different. - - // Reject anything that isn't an element. - if (n.nodeType != Node.ELEMENT_NODE) - return NodeFilter.FILTER_REJECT; - - // Skip any descendants of headings. - if ((n.parentNode && n.parentNode.namespaceURI == 'http://www.w3.org/1999/xhtml') && - (n.parentNode.localName == 'h1' || n.parentNode.localName == 'h2' || - n.parentNode.localName == 'h3' || n.parentNode.localName == 'h4' || - n.parentNode.localName == 'h5' || n.parentNode.localName == 'h6' || - n.parentNode.localName == 'header')) - return NodeFilter.FILTER_REJECT; - - // Skip any blockquotes. - if ((n.namespaceURI == 'http://www.w3.org/1999/xhtml') && - (n.localName == 'blockquote')) - return NodeFilter.FILTER_REJECT; - - // Accept HTML elements in the list given in the prose above. - if ((n.namespaceURI == 'http://www.w3.org/1999/xhtml') && - (n.localName == 'body' || /*n.localName == 'blockquote' ||*/ - n.localName == 'section' || n.localName == 'nav' || - n.localName == 'article' || n.localName == 'aside' || - n.localName == 'h1' || n.localName == 'h2' || - n.localName == 'h3' || n.localName == 'h4' || - n.localName == 'h5' || n.localName == 'h6' || - n.localName == 'header')) - return NodeFilter.FILTER_ACCEPT; - - // Skip the rest. - return NodeFilter.FILTER_SKIP; -}</pre> - </div> - - <h5 id=associatedSection><span class=secno>3.8.11.2. </span>Determining - which heading and section applies to a particular node</h5> - - <p>Given a particular node, user agents must use the following algorithm, - <em>in the given order</em>, to determine which heading and section the - node is most closely associated with. The processing of this algorithm - must stop as soon as the associated section and heading are established - (even if they are established to be nothing). - - <ol> - <li>If the node has an ancestor that is a <code><a - href="#header">header</a></code> element, then the associated heading is - the most distant such ancestor. The associated section is that <code><a - href="#header">header</a></code>'s associated section (i.e. repeat this - algorithm for that <code><a href="#header">header</a></code>). - - <li>If the node has an ancestor that is an <code><a - href="#h1">h1</a></code>-<code><a href="#h6">h6</a></code> element, then - the associated heading is the most distant such ancestor. The associated - section is that heading's section (i.e. repeat this algorithm for that - heading element). - - <li>If the node is an <code><a href="#h1">h1</a></code>-<code><a - href="#h6">h6</a></code> element or a <code><a - href="#header">header</a></code> element, then the associated heading is - the element itself. The UA must then generate the <a - href="#outlines">hypothetical section tree</a> described in the previous - section, rooted at the nearest section ancestor (or the <a - href="#root-element">root element</a> if there is no such ancestor). If - the parent of the heading in that hypothetical tree is an element in the - real document tree, then that element is the associated section. - Otherwise, there is no associated section element. - - <li>If the node is a sectioning element, then the associated section is - itself. The UA must then generate the <a href="#outlines">hypothetical - section tree</a> described in the previous section, rooted at the section - itself. If the section element, in that hypothetical tree, has a child - element that is an <code><a href="#h1">h1</a></code>-<code><a - href="#h6">h6</a></code> element or a <code><a - href="#header">header</a></code> element, then that element is the - associated heading. Otherwise, there is no associated heading element. - - <li>If the node is a <code><a href="#footer">footer</a></code> or <code><a - href="#address">address</a></code> element, then the associated section - is the nearest ancestor sectioning element, if there is one. The node's - associated heading is the same as that sectioning element's associated - heading (i.e. repeat this algorithm for that sectioning element). If - there is no ancestor sectioning element, the element has no associated - section nor an associated heading. - - <li>Otherwise, the node is just a normal node, and the document has to be - examined more closely to determine its section and heading. Create a view - rooted at the nearest ancestor sectioning element (or the <a - href="#root-element">root element</a> if there is none) that has just - <code><a href="#h1">h1</a></code>-<code><a href="#h6">h6</a></code> - elements, <code><a href="#header">header</a></code> elements, the node - itself, and sectioning elements other than <code><a - href="#blockquote">blockquote</a></code> elements. (Descendants of any of - the nodes in this view can be ignored, as can any node later in the tree - than the node in question, as the algorithm below merely walks backwards - up this view.) - - <li>Let <var title="">n</var> be an iterator for this view, initialised at - the node in question. - - <li>Let <var title="">c</var> be the current best candidate heading, - initially null, and initially not used. It is used when top-level heading - candidates are to be searched for (see below). - - <li>Repeat these steps (which effectively goes backwards through the - node's previous siblings) until an answer is found: - <ol> - <li>If <var title="">n</var> points to a node with no previous sibling, - and <var title="">c</var> is null, then return the node's parent node - as the answer. If the node has no parent node, return null as the - answer. - - <li>Otherwise, if <var title="">n</var> points to a node with no - previous sibling, return <var title="">c</var> as the answer. - - <li>Adjust <var title="">n</var> so that it points to the previous - sibling of the current position. - - <li>If <var title="">n</var> is pointing at an <code><a - href="#h1">h1</a></code> or <code><a href="#header">header</a></code> - element, then return that element as the answer. - - <li>If <var title="">n</var> is pointing at an <code><a - href="#h2">h2</a></code>-<code><a href="#h6">h6</a></code> element, and - heading candidates are not being searched for, then return that element - as the answer. - - <li>Otherwise, if <var title="">n</var> is pointing at an <code><a - href="#h2">h2</a></code>-<code><a href="#h6">h6</a></code> element, and - either <var title="">c</var> is still null, or <var title="">c</var> is - a heading of lower <a href="#rank">rank</a> than this one, then set - <var title="">c</var> to be this element, and continue going backwards - through the previous siblings. - - <li>If <var title="">n</var> is pointing at a sectioning element, then - from this point on top-level heading candidates are being searched for. - (Specifically, we are looking for the nearest top-level header for the - current section.) Continue going backwards through the previous - siblings. - </ol> - - <li>If the answer from the previous step (the loop) is null, which can - only happen if the node has no preceeding headings and is not contained - in a sectioning element, then there is no associated heading and no - associated section. - - <li>Otherwise, if the answer from the earlier loop step is a sectioning - element, then the associated section is that element and the associated - heading is that sectioning element's associated heading (i.e. repeat this - algorithm for that section). - - <li>Otherwise, if the answer from that same earlier step is an <code><a - href="#h1">h1</a></code>-<code><a href="#h6">h6</a></code> element or a - <code><a href="#header">header</a></code> element, then the associated - heading is that element and the associated section is that heading - element's associated section (i.e. repeat this algorithm for that - heading). - </ol> - - <p class=note>Not all nodes have an associated header or section. For - example, if a section is implied, as when multiple headers are found in - one sectioning element, then a node in that section has an anonymous - associated section (its section is not represented by a real element), and - the algorithm above does not associate that node with any particular - sectioning element. - - <div class=example> - <p>For the following fragment:</p> - - <pre><body> - <h1>X</h1> - <h2>X</h2> - <blockquote> - <h3>X</h3> - </blockquote> - <p id="a">X</p> - <h4>Text Node A</h4> - <section> - <h5>X</h5> - </section> - <p>Text Node B</p> -</body></pre> - - <p>The associations are as follows (not all associations are shown):</p> - - <table> - <thead> - <tr> - <th>Node - - <th>Associated heading - - <th>Associated section - - <tbody> - <tr> - <td><code><body></code> - - <td><code><h1></code> - - <td><code><body></code> - - <tr> - <td><code><h1></code> - - <td><code><h1></code> - - <td><code><body></code> - - <tr> - <td><code><h2></code> - - <td><code><h2></code> - - <td>None. - - <tr> - <td><code><blockquote></code> - - <td><code><h2></code> - - <td>None. - - <tr> - <td><code><h3></code> - - <td><code><h3></code> - - <td><code><blockquote></code> - - <tr> - <td><code><p id="a"></code> - - <td><code><h2></code> - - <td>None. - - <tr> - <td><code>Text Node A</code> - - <td><code><h4></code> - - <td>None. - - <tr> - <td><code>Text Node B</code> - - <td><code><h1></code> - - <td><code><body></code> - </table> - </div> - - <h5 id=distinguishing><span class=secno>3.8.11.3. </span>Distinguishing - site-wide headers from page headers</h5> - - <p>Given the <a href="#outlines">hypothetical section tree</a>, but - ignoring any sections created for <code><a href="#nav">nav</a></code> and - <code><a href="#aside">aside</a></code> elements, and any of their - descendants, if the root of the tree is <a href="#the-body0">the - <code>body</code> element</a>'s section, and it has only a single - subsection which is created by an <code><a - href="#article">article</a></code> element, then the header of <a - href="#the-body0">the <code>body</code> element</a> should be assumed to - be a site-wide header, and the header of the <code><a - href="#article">article</a></code> element should be assumed to be the - page's header. - - <p>If a page starts with a heading that is common to the whole site, the - document must be authored such that, in the document's <a - href="#outlines">hypothetical section tree</a>, ignoring any sections - created for <code><a href="#nav">nav</a></code> and <code><a - href="#aside">aside</a></code> elements and any of their descendants, the - root of the tree is <a href="#the-body0">the <code>body</code> - element</a>'s section, its heading is the site-wide heading, <a - href="#the-body0">the <code>body</code> element</a> has just one - subsection, that subsection is created by an <code><a - href="#article">article</a></code> element, and that <code><a - href="#article">article</a></code>'s header is the page heading. - - <p>If a page does not contain a site-wide heading, then the page must be - authored such that, in the document's <a href="#outlines">hypothetical - section tree</a>, ignoring any sections created for <code><a - href="#nav">nav</a></code> and <code><a href="#aside">aside</a></code> - elements and any of their descendants, either <a href="#the-body0">the - <code>body</code> element</a> has no subsections, or it has more than one - subsection, or it has a single subsection but that subsection is not - created by an <code><a href="#article">article</a></code> element. - - <p class=note>Conceptually, a site is thus a document with many articles - — when those articles are split into many pages, the heading of the - original single page becomes the heading of the site, repeated on every - page. - - <h3 id=prose><span class=secno>3.9. </span>Prose</h3> - - <h4 id=the-p><span class=secno>3.9.1. </span>The <dfn - id=p><code>p</code></dfn> element</h4> - - <p><a href="#block-level0" title="block-level elements">Block-level - element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> are expected. - - <dt>Content model: - - <dd><a href="#significant" title="significant inline - content">Significant</a> <a href="#inline-level0">inline-level - content</a>. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#p">p</a></code> element represents a <a - href="#paragraph">paragraph</a>. - - <p><code><a href="#p">p</a></code> elements can contain a mixture of <a - href="#strictly">strictly inline-level content</a>, such as text, images, - hyperlinks, etc, and <a href="#structured">structured inline-level - elements</a>, such as lists, tables, and block quotes. <code><a - href="#p">p</a></code> elements must not be <a href="#significant" - title="significant inline content">empty</a>. - - <div class=example> - <p>The following examples are conforming HTML fragments:</p> - - <pre><p>The little kitten gently seated himself on a piece of -carpet. Later in his life, this would be referred to as the time the -cat sat on the mat.</p></pre> - - <pre><fieldset> - <legend>Personal information</legend> - <p> - <label>Name: <input name="n"></label> - <label><input name="anon" type="checkbox"> Hide from other users</label> - </p> - <p><label>Address: <textarea name="a"></textarea></label></p> -</fieldset></pre> - - <pre><p>There was once an example from Femley,<br> -Whose markup was of dubious quality.<br> -The validator complained,<br> -So the author was pained,<br> -To move the error from the markup to the rhyming.</p></pre> - </div> - - <p>The <code><a href="#p">p</a></code> element should not be used when a - more specific element is more appropriate. - - <div class=example> - <p>The following example is technically correct:</p> - - <pre><section> - <!-- ... --> - <p>Last modified: 2001-04-23</p> - <p>Author: fred@example.com</p> -</section></pre> - - <p>However, it would be better marked-up as:</p> - - <pre><section> - <!-- ... --> - <footer>Last modified: 2001-04-23</footer> - <address>Author: fred@example.com</address> -</section></pre> - - <p>Or:</p> - - <pre><section> - <!-- ... --> - <footer> - <p>Last modified: 2001-04-23</p> - <address>Author: fred@example.com</address> - </footer> -</section></pre> - </div> - - <h4 id=the-hr><span class=secno>3.9.2. </span>The <dfn - id=hr><code>hr</code></dfn> element</h4> - - <p><a href="#block-level0" title="block-level elements">Block-level - element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> are expected. - - <dt>Content model: - - <dd>Empty. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#hr">hr</a></code> element represents a <a - href="#paragraph">paragraph</a>-level thematic break, e.g. a scene change - in a story, or a transition to another topic within a section of a - reference book. - - <h4 id=the-br><span class=secno>3.9.3. </span>The <dfn - id=br><code>br</code></dfn> element</h4> - - <p><a href="#strictly">Strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd>Empty. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#br">br</a></code> element represents a line break. - - <p><code><a href="#br">br</a></code> elements must be empty. Any content - inside <code><a href="#br">br</a></code> elements must not be considered - part of the surrounding text. - - <p><code><a href="#br">br</a></code> elements must only be used for line - breaks that are actually part of the content, as in poems or addresses. - - <div class=example> - <p>The following example is correct usage of the <code><a - href="#br">br</a></code> element:</p> - - <pre><p>P. Sherman<br> -42 Wallaby Way<br> -Sydney</p></pre> - </div> - - <p><code><a href="#br">br</a></code> elements must not be used for - separating thematic groups in a paragraph. - - <div class=example> - <p>The following examples are non-conforming, as they abuse the <code><a - href="#br">br</a></code> element:</p> - - <pre><p><a ...>34 comments.</a><br> -<a ...>Add a comment.<a></p></pre> - - <pre><p>Name: <input name="name"><br> -Address: <input name="address"></p></pre> - - <p>Here are alternatives to the above, which are correct:</p> - - <pre><p><a ...>34 comments.</a></p> -<p><a ...>Add a comment.<a></p></pre> - - <pre><p>Name: <input name="name"></p> -<p>Address: <input name="address"></p></pre> - <!-- XXX should have labels in the examples above --></div> - - <h4 id=the-dialog><span class=secno>3.9.4. </span>The <dfn - id=dialog><code>dialog</code></dfn> element</h4> - - <p><a href="#block-level0" title="block-level elements">Block-level - element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> are expected. - - <dt>Content model: - - <dd>Zero or more pairs of <code><a href="#dt">dt</a></code> and <code><a - href="#dd">dd</a></code> elements. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#dialog">dialog</a></code> element represents a - conversation. - - <p>Each part of the conversation must have an explicit talker (or speaker) - given by a <code><a href="#dt">dt</a></code> element, and a discourse (or - quote) given by a <code><a href="#dd">dd</a></code> element. - - <div class=example> - <p>This example demonstrates this using an extract from Abbot and - Costello's famous sketch, <cite>Who's on first</cite>:</p> - - <pre><dialog> - <dt>Costello - <dd> Look, you gotta first baseman? - <dt> Abbott - <dd> Certainly. - <dt> Costello - <dd> Who's playing first? - <dt> Abbott - <dd> That's right. - <dt> Costello - <dd> When you pay off the first baseman every month, who gets the money? - <dt> Abbott - <dd> Every dollar of it. -</dialog></pre> - </div> - - <p class=note>Text in a <code><a href="#dt">dt</a></code> element in a - <code><a href="#dialog">dialog</a></code> element is implicitly the source - of the text given in the following <code><a href="#dd">dd</a></code> - element, and the contents of the <code><a href="#dd">dd</a></code> element - are implicitly a quote from that speaker. There is thus no need to include - <code><a href="#cite2">cite</a></code>, <code><a href="#q">q</a></code>, - or <code><a href="#blockquote">blockquote</a></code> elements in this - markup. Indeed, a <code><a href="#q">q</a></code> element inside a - <code><a href="#dd">dd</a></code> element in a conversation would actually - imply the person talking were themselves quoting someone else. See the - <code><a href="#cite2">cite</a></code>, <code><a href="#q">q</a></code>, - and <code><a href="#blockquote">blockquote</a></code> elements for other - ways to cite or quote. - - <h3 id=preformatted><span class=secno>3.10. </span>Preformatted text</h3> - - <h4 id=the-pre><span class=secno>3.10.1. </span>The <dfn - id=pre><code>pre</code></dfn> element</h4> - - <p><a href="#block-level0" title="block-level elements">Block-level - element</a>, and <a href="#structured" title="structured inline-level - elements">structured inline-level element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> are expected. - - <dd>Where <a href="#structured">structured inline-level elements</a> are - allowed. - - <dt>Content model: - - <dd><a href="#strictly">Strictly inline-level content</a>. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#pre">pre</a></code> element represents a block of - preformatted text, in which structure is represented by typographic - conventions rather than by elements. - - <p>Some examples of cases where the <code><a href="#pre">pre</a></code> - element could be used: - - <ul> - <li>Including an e-mail, with paragraphs indicated by blank lines, lists - indicated by lines prefixed with a bullet, and so on. - - <li>Including fragments of computer code, with structure indicated - according to the conventions of that language. - - <li>Displaying ASCII art.</li> - <!-- XXX need a note about non-visual UAs --> - </ul> - - <p>If, ignoring <a href="#text-node" title="text node">text nodes</a> - consisting only of <a href="#inter-element" title="inter-element - whitespace">whitespace</a>, the only child of a <code><a - href="#pre">pre</a></code> is a <code><a href="#code">code</a></code> - element, then the <code><a href="#pre">pre</a></code> element represents a - block of computer code. - - <p>If, ignoring <a href="#text-node" title="text node">text nodes</a> - consisting only of <a href="#inter-element" title="inter-element - whitespace">whitespace</a>, the only child of a <code><a - href="#pre">pre</a></code> is a <code><a href="#samp">samp</a></code> - element, then the <code><a href="#pre">pre</a></code> element represents a - block of computer output.</p> - <!-- XXX examples --> - - <h3 id=lists0><span class=secno>3.11. </span>Lists</h3> - - <h4 id=the-ol><span class=secno>3.11.1. </span>The <dfn - id=ol><code>ol</code></dfn> element</h4> - - <p><a href="#block-level0" title="block-level elements">Block-level - element</a>, and <a href="#structured" title="structured inline-level - elements">structured inline-level element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> are expected. - - <dd>Where <a href="#structured">structured inline-level elements</a> are - allowed. - - <dt>Content model: - - <dd>Zero or more <code><a href="#li">li</a></code> elements. - - <dt>Element-specific attributes: - - <dd><code title=attr-ol-start><a href="#start0">start</a></code> - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmlolistelement>HTMLOListElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute long <a href="#start1" title=dom-ol-start>start</a>; -};</pre> - </dl> - - <p>The <code><a href="#ol">ol</a></code> element represents an ordered list - of items (which are represented by <code><a href="#li">li</a></code> - elements). - - <p>The <dfn id=start0 title=attr-ol-start><code>start</code></dfn> - attribute, if present, must be a <a href="#valid0">valid integer</a> - giving the ordinal value of the first list item. - - <p>If the <code title=attr-ol-start><a href="#start0">start</a></code> - attribute is present, user agents must <a href="#rules0" title="rules for - parsing integers">parse it as an integer</a>, in order to determine the - attribute's value. The default value, used if the attribute is missing or - if the value cannot be converted to a number according to the referenced - algorithm, is 1. - - <p>The items of the list are the <code><a href="#li">li</a></code> element - child nodes of the <code><a href="#ol">ol</a></code> element, in <a - href="#tree-order">tree order</a>. - - <p>The first item in the list has the ordinal value given by the <code><a - href="#ol">ol</a></code> element's <code title=attr-ol-start><a - href="#start0">start</a></code> attribute, unless that <code><a - href="#li">li</a></code> element has a <code title=attr-li-value><a - href="#value">value</a></code> attribute with a value that can be - successfully parsed, in which case it has the ordinal value given by that - <code title=attr-li-value><a href="#value">value</a></code> attribute. - - <p>Each subsequent item in the list has the ordinal value given by its - <code title=attr-li-value><a href="#value">value</a></code> attribute, if - it has one, or, if it doesn't, the ordinal value of the previous item, - plus one. - - <p>The <dfn id=start1 title=dom-ol-start><code>start</code></dfn> DOM - attribute must <a href="#reflect">reflect</a> the value of the <code - title=attr-ol-start><a href="#start0">start</a></code> content attribute.</p> - <!-- XXX resuming numbering of lists from previous lists? --> - <!-- XXX counting up and down? --> - <!-- XXX reverse-counted lists? --> - - <h4 id=the-ul><span class=secno>3.11.2. </span>The <dfn - id=ul><code>ul</code></dfn> element</h4> - - <p><a href="#block-level0" title="block-level elements">Block-level - element</a>, and <a href="#structured" title="structured inline-level - elements">structured inline-level element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> are expected. - - <dd>Where <a href="#structured">structured inline-level elements</a> are - allowed. - - <dt>Content model: - - <dd>Zero or more <code><a href="#li">li</a></code> elements. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#ul">ul</a></code> element represents an unordered - list of items (which are represented by <code><a href="#li">li</a></code> - elements). - - <p>The items of the list are the <code><a href="#li">li</a></code> element - child nodes of the <code><a href="#ul">ul</a></code> element. - - <h4 id=the-li><span class=secno>3.11.3. </span>The <dfn - id=li><code>li</code></dfn> element</h4> - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Inside <code><a href="#ol">ol</a></code> elements. - - <dd>Inside <code><a href="#ul">ul</a></code> elements. - - <dd>Inside <code><a href="#menu">menu</a></code> elements. - - <dt>Content model: - - <dd>When the element is a child of an <code><a href="#ol">ol</a></code> or - <code><a href="#ul">ul</a></code> element and the grandchild of an - element that is <a href="#determining0" title="Determining if a - particular element contains block-level elements or inline-level - content">being used as an inline-level content container</a>, or, when - the element is a child of a <code><a href="#menu">menu</a></code> - element: <a href="#inline-level0">inline-level content</a>. - - <dd>Otherwise: zero or more <a href="#block-level0">block-level - elements</a>, or <a href="#inline-level0">inline-level content</a> (but - not both). - - <dt>Element-specific attributes: - - <dd>If the element is a child of an <code><a href="#ol">ol</a></code> - element: <code title=attr-li-value><a href="#value">value</a></code> - - <dd>If the element is not the child of an <code><a - href="#ol">ol</a></code> element: None. - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmllielement>HTMLLIElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute long <a href="#value0" title=dom-li-value>value</a>; -};</pre> - </dl> - - <p>The <code><a href="#li">li</a></code> element represents a list item. If - its parent element is an <code><a href="#ol">ol</a></code>, <code><a - href="#ul">ul</a></code>, or <code><a href="#menu">menu</a></code> - element, then the element is an item of the parent element's list, as - defined for those elements. Otherwise, the list item has no defined - list-related relationship to any other <code><a href="#li">li</a></code> - element. - - <p>When the list item is the child of an <code><a href="#ol">ol</a></code> - or <code><a href="#ul">ul</a></code> element, the content model of the - item depends on the way that parent element was used. If it was used as - structured inline content (i.e. if <em>that</em> element's parent was <a - href="#determining0" title="Determining if a particular element contains - block-level elements or inline-level content">used as an inline-level - content</a> container), then the <code><a href="#li">li</a></code> element - must only contain <a href="#inline-level0">inline-level content</a>. - Otherwise, the element may be used either for <a href="#inline-level0" - title="inline-level content">inline content</a> or <a - href="#block-level0">block-level elements</a>. - - <p>When the list item is the child of a <code><a - href="#menu">menu</a></code> element, the <code><a - href="#li">li</a></code> element must contain only <a - href="#inline-level0">inline-level content</a>. - - <p>When the list item is not the child of an <code><a - href="#ol">ol</a></code>, <code><a href="#ul">ul</a></code>, or <code><a - href="#menu">menu</a></code> element, e.g. because it is an orphaned node - not in the document, it may contain either for <a href="#inline-level0" - title="inline-level content">inline content</a> or <a - href="#block-level0">block-level elements</a>. - - <p>When <a href="#determining0" title="Determining if a particular element - contains block-level elements or inline-level content">used as an - inline-level content</a> container, the list item represents a single <a - href="#paragraph">paragraph</a>. - - <p>The <dfn id=value title=attr-li-value><code>value</code></dfn> - attribute, if present, must be a <a href="#valid0">valid integer</a> - giving the ordinal value of the first list item. - - <p>If the <code title=attr-li-value><a href="#value">value</a></code> - attribute is present, user agents must <a href="#rules0" title="rules for - parsing integers">parse it as an integer</a>, in order to determine the - attribute's value. If the attribute's value cannot be converted to a - number, it must be treated as if the attribute was absent. The attribute - has no default value. - - <p>The <code title=attr-li-value><a href="#value">value</a></code> - attribute is processed relative to the element's parent <code><a - href="#ol">ol</a></code> element (q.v.), if there is one. If there is not, - the attribute has no effect. - - <p>The <dfn id=value0 title=dom-li-value><code>value</code></dfn> DOM - attribute must <a href="#reflect">reflect</a> the value of the <code - title=dom-li-value><a href="#value0">value</a></code> content attribute. - - <h4 id=the-dl><span class=secno>3.11.4. </span>The <dfn - id=dl><code>dl</code></dfn> element</h4> - - <p><a href="#block-level0" title="block-level elements">Block-level - element</a>, and <a href="#structured" title="structured inline-level - elements">structured inline-level element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> are expected. - - <dd>Where <a href="#structured">structured inline-level elements</a> are - allowed. - - <dt>Content model: - - <dd>Zero or more groups each consisting of one or more <code><a - href="#dt">dt</a></code> elements followed by one or mode <code><a - href="#dd">dd</a></code> elements. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#dl">dl</a></code> element introduces an unordered - association list consisting of zero or more name-value groups (a - description list). Each group must consist of one or more names (<code><a - href="#dt">dt</a></code> elements) followed by one or more values - (<code><a href="#dd">dd</a></code> elements). - - <p>Name-value groups may be terms and definitions, metadata topics and - values, or any other groups of name-value data. - - <div class=example> - <p>The following are all conforming HTML fragments.</p> - - <p>In the following example, one entry ("Authors") is linked to two values - ("John" and "Luke").</p> - - <pre><dl> - <dt> Authors - <dd> John - <dd> Luke - <dt> Editor - <dd> Frank -</dl></pre> - - <p>In the following example, one definition is linked to two terms.</p> - - <pre><dl> - <dt lang="en-US"> <dfn>color</dfn> </dt> - <dt lang="en-GB"> <dfn>colour</dfn> </dt> - <dd> A sensation which (in humans) derives from the ability of - the fine structure of the eye to distinguish three differently - filtered analyses of a view. </dd> -</dl></pre> - - <p>The following example illustrates the use of the <code><a - href="#dl">dl</a></code> element to mark up metadata of sorts. At the end - of the example, one group has two metadata labels ("Authors" and - "Editors") and two values ("Robert Rothman" and "Daniel Jackson").</p> - - <pre><dl> - <dt> Last modified time </dt> - <dd> 2004-12-23T23:33Z </dd> - <dt> Recommended update interval </dt> - <dd> 60s </dd> - <dt> Authors </dt> - <dt> Editors </dt> - <dd> Robert Rothman </dd> - <dd> Daniel Jackson </dd> -</dl></pre> - </div> - - <p>If a <code><a href="#dl">dl</a></code> element is empty, it contains no - groups. - - <p>If a <code><a href="#dl">dl</a></code> element contains non-<a - href="#inter-element" title="inter-element whitespace">whitespace</a> <a - href="#text-node" title="text node">text nodes</a>, or elements other than - <code><a href="#dt">dt</a></code> and <code><a href="#dd">dd</a></code>, - then those elements or <a href="#text-node" title="text node">text - nodes</a> do not form part of any groups in that <code><a - href="#dl">dl</a></code>, and the document is non-conforming. - - <p>If a <code><a href="#dl">dl</a></code> element contains only <code><a - href="#dt">dt</a></code> elements, then it consists of one group with - names but no values, and the document is non-conforming. - - <p>If a <code><a href="#dl">dl</a></code> element contains only <code><a - href="#dd">dd</a></code> elements, then it consists of one group with - values but no names, and the document is non-conforming. - - <p class=note>The <code><a href="#dl">dl</a></code> element is - inappropriate for marking up dialogue, since dialogue is ordered (each - speaker/line pair comes after the next). For an example of how to mark up - dialogue, see the <code><a href="#dialog">dialog</a></code> element. - - <h4 id=the-dt><span class=secno>3.11.5. </span>The <dfn - id=dt><code>dt</code></dfn> element</h4> - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Before <code><a href="#dd">dd</a></code> or <code><a - href="#dt">dt</a></code> elements inside <code><a - href="#dl">dl</a></code> elements. - - <dd>Before a <code><a href="#dd">dd</a></code> element inside a <code><a - href="#dialog">dialog</a></code> element. - - <dt>Content model: - - <dd><a href="#strictly">Strictly inline-level content</a>. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#dt">dt</a></code> element represents the term, or - name, part of a term-description group in a description list (<code><a - href="#dl">dl</a></code> element), and the talker, or speaker, part of a - talker-discourse pair in a conversation (<code><a - href="#dialog">dialog</a></code> element). - - <p class=note>The <code><a href="#dt">dt</a></code> element itself, when - used in a <code><a href="#dl">dl</a></code> element, does not indicate - that its contents are a term being defined, but this can be indicated - using the <code><a href="#dfn">dfn</a></code> element. - - <h4 id=the-dd><span class=secno>3.11.6. </span>The <dfn - id=dd><code>dd</code></dfn> element</h4> - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>After <code><a href="#dt">dt</a></code> or <code><a - href="#dd">dd</a></code> elements inside <code><a - href="#dl">dl</a></code> elements. - - <dd>After a <code><a href="#dt">dt</a></code> element inside a <code><a - href="#dialog">dialog</a></code> element. - - <dt>Content model: - - <dd>When the element is a child of a <code><a href="#dl">dl</a></code> - element and the grandchild of an element that is <a href="#determining0" - title="Determining if a particular element contains block-level elements - or inline-level content">being used as an inline-level content - container</a>: <a href="#inline-level0">inline-level content</a>. - - <dd>Otherwise: zero or more <a href="#block-level0">block-level - elements</a>, or <a href="#inline-level0">inline-level content</a> (but - not both). - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#dd">dd</a></code> element represents the - description, definition, or value, part of a term-description group in a - description list (<code><a href="#dl">dl</a></code> element), and the - discourse, or quote, part in a conversation (<code><a - href="#dialog">dialog</a></code> element). - - <p>The content model of a <code><a href="#dd">dd</a></code> element depends - on the way its parent element is being used. If the parent element is a - <code><a href="#dl">dl</a></code> element that is being used as structured - inline content (i.e. if the <code><a href="#dl">dl</a></code> element's - parent element is being <a href="#determining0" title="Determining if a - particular element contains block-level elements or inline-level - content">used as an inline-level content</a> container), then the <code><a - href="#dd">dd</a></code> element must only contain <a - href="#inline-level0">inline-level content</a>. - - <p>Otherwise, the element may be used either for <a href="#inline-level0" - title="inline-level content">inline content</a> or <a - href="#block-level0">block-level elements</a>. - - <h3 id=phrase><span class=secno>3.12. </span>Phrase elements</h3> - <!-- XXX ruby (delayed until someone can define it with error handling rules) --> - - <h4 id=the-a><span class=secno>3.12.1. </span>The <dfn - id=a><code>a</code></dfn> element</h4> - - <p><a href="#interactive1" title="interactive elements">Interactive</a>, <a - href="#strictly">strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed, if there are no ancestor <a href="#interactive1">interactive - elements</a>. - - <dt>Content model: - - <dd>When used in an element whose content model is only <a - href="#strictly">strictly inline-level content</a>: only <a - href="#significant" title="significant inline content">significant</a> <a - href="#strictly">strictly inline-level content</a>, but there must be no - <a href="#interactive1" title="interactive elements">interactive</a> - descendants. - - <dd>Otherwise: any <a href="#significant" title="significant inline - content">significant</a> <a href="#inline-level0">inline-level - content</a>, but there must be no <a href="#interactive1" - title="interactive elements">interactive</a> descendants. - - <dt>Element-specific attributes: - - <dd><code title=attr-hyperlink-href><a href="#href6">href</a></code> - - <dd><code title=attr-hyperlink-target><a href="#target3">target</a></code> - - <dd><code title=attr-hyperlink-ping><a href="#ping">ping</a></code> - - <dd><code title=attr-hyperlink-rel><a href="#rel3">rel</a></code> - - <dd><code title=attr-hyperlink-media><a href="#media12">media</a></code> - - <dd><code title=attr-hyperlink-hreflang><a - href="#hreflang3">hreflang</a></code> - - <dd><code title=attr-hyperlink-type><a href="#type17">type</a></code> - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmlanchorelement>HTMLAnchorElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute DOMString <a href="#href3" title=dom-a-href>href</a>; - attribute DOMString <a href="#target1" title=dom-a-target>target</a>; - attribute DOMString <a href="#ping0" title=dom-a-ping>ping</a>; - attribute DOMString <a href="#rel1" title=dom-a-rel>rel</a>; - readonly attribute DOMTokenList <a href="#rellist0" title=dom-a-relList>relList</a>; - attribute DOMString <a href="#media4" title=dom-a-media>media</a>; - attribute DOMString <a href="#hreflang1" title=dom-a-hreflang>hreflang</a>; - attribute DOMString <a href="#type3" title=dom-a-type>type</a>; -};</pre> - - <p>The <code title=command-ro><a href="#command2">Command</a></code> - interface must also be implemented by this element.</p> - </dl> - - <p>If the <code><a href="#a">a</a></code> element has an <code - title=attr-hyperlink-href><a href="#href6">href</a></code> attribute, then - it represents a <a href="#hyperlinks">hyperlink</a>. - - <p>If the <code><a href="#a">a</a></code> element has no <code - title=attr-hyperlink-href><a href="#href6">href</a></code> attribute, then - the element is a placeholder for where a link might otherwise have been - placed, if it had been relevant. - - <p>The <code title=attr-hyperlink-target><a - href="#target3">target</a></code>, <code title=attr-hyperlink-ping><a - href="#ping">ping</a></code>, <code title=attr-hyperlink-rel><a - href="#rel3">rel</a></code>, <code title=attr-hyperlink-media><a - href="#media12">media</a></code>, <code title=attr-hyperlink-hreflang><a - href="#hreflang3">hreflang</a></code>, and <code - title=attr-hyperlink-type><a href="#type17">type</a></code> attributes - must be omitted if the <code title=attr-hyperlink-href><a - href="#href6">href</a></code> attribute is not present.</p> - <!-- XXX really? that makes it harder to use as a - placeholder. --> - - <div class=example> - <p>If a site uses a consistent navigation toolbar on every page, then the - link that would normally link to the page itself could be marked up using - an <code><a href="#a">a</a></code> element:</p> - - <pre><nav> - <ul> - <li> <a href="/">Home</a> </li> - <li> <a href="/news">News</a> </li> - <li> <a>Examples</a> </li> - <li> <a href="/legal">Legal</a> </li> - </ul> -</nav></pre> - </div> - - <p>Interactive user agents should allow users to <a href="#following0" - title="following hyperlinks">follow hyperlinks</a> created using the - <code><a href="#a">a</a></code> element. The <code - title=attr-hyperlink-href><a href="#href6">href</a></code>, <code - title=attr-hyperlink-target><a href="#target3">target</a></code> and <code - title=attr-hyperlink-ping><a href="#ping">ping</a></code> attributes - decide how the link is followed. The <code title=attr-hyperlink-rel><a - href="#rel3">rel</a></code>, <code title=attr-hyperlink-media><a - href="#media12">media</a></code>, <code title=attr-hyperlink-hreflang><a - href="#hreflang3">hreflang</a></code>, and <code - title=attr-hyperlink-type><a href="#type17">type</a></code> attributes may - be used to indicate to the user the likely nature of the target resource - before the user follows the link. - - <p>The <a href="#activation0">activation behavior</a> of <code><a - href="#a">a</a></code> elements that represent <span>hyperlinks</span> is - to run the following steps: - - <ol> - <li> - <p>If the <code title=event-DOMActivate>DOMActivate</code> event in - question is not <span title=concept-events-trusted>trusted</span> (i.e. - a <code title=dom-click><a href="#click">click()</a></code> method call - was the reason for the event being dispatched), and the <code><a - href="#a">a</a></code> element's <code title=attr-hyperlink-target><a - href="#target3">target</a></code> attribute is <span - class=big-issue>...</span> then raise an <code>INVALID_ACCESS_ERR</code> - exception and abort these steps. - - <li> - <p>If the target of the <code title=event-DOMActivate>DOMActivate</code> - event is an <code><a href="#img">img</a></code> element with an <code - title=attr-img-ismap><a href="#ismap">ismap</a></code> attribute - specified, then server-side image map processing must be performed, as - follows:</p> - - <ol><!-- http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E%0A...%3Ca%20href%3D%22%23%22%3E%3Cimg%20ismap%20usemap%3D%22%23a%22%20src%3D/resources/images/smallcats%3E%3C/a%3E%0A%3Cmap%20name%3Da%3E%3Carea%20shape%3Drect%20coords%3D0%2C0%2C50%2C50%20href%3Db%3E%3C/map%3E --> - - <li>If the <code title=event-DOMActivate>DOMActivate</code> event was - dispatched as the result of a real pointing-device-triggered <code - title=event-click>click</code> event on the <code><a - href="#img">img</a></code> element, then let <var title="">x</var> be - the distance in CSS pixels from the left edge of the image to the - location of the click, and let <var title="">y</var> be the distance in - CSS pixels from the top edge of the image to the location of the click. - Otherwise, let <var title="">x</var> and <var title="">y</var> be zero. - - <li>Let the <dfn id=hyperlink2><var>hyperlink suffix</var></dfn> be a - U+003F QUESTION MARK character, the value of <var title="">x</var> - expressed as a base-ten integer using ASCII digits (U+0030 DIGIT ZERO - to U+0039 DIGIT NINE), a U+002C COMMA character, and the value of <var - title="">y</var> expressed as a base-ten integer using ASCII digits. - </ol> - - <li> - <p>Finally, the user agent must <a href="#following0" title="following - hyperlinks">follow the hyperlink</a> defined by the <code><a - href="#a">a</a></code> element. If the steps above defined a <var><a - href="#hyperlink2">hyperlink suffix</a></var>, then take that into - account when following the hyperlink. - </ol> - - <p class=note>One way that a user agent can enable users to follow - hyperlinks is by allowing <code><a href="#a">a</a></code> elements to be - clicked, or focussed and activated by the keyboard. This <a - href="#interactive1" title="interactive elements">will cause</a> the - aforementioned <a href="#activation0">activation behavior</a> to be - invoked. - - <p>The <code><a href="#a">a</a></code> element must not be <a - href="#significant" title="significant inline content">empty</a>. - - <p>The DOM attributes <dfn id=href3 - title=dom-a-href><code>href</code></dfn>, <dfn id=ping0 - title=dom-a-ping><code>ping</code></dfn>, <dfn id=target1 - title=dom-a-target><code>target</code></dfn>, <dfn id=rel1 - title=dom-a-rel><code>rel</code></dfn>, <dfn id=media4 - title=dom-a-media><code>media</code></dfn>, <dfn id=hreflang1 - title=dom-a-hreflang><code>hreflang</code></dfn>, and <dfn id=type3 - title=dom-a-type><code>type</code></dfn>, must each <a - href="#reflect">reflect</a> the respective content attributes of the same - name. - - <p>The DOM attribute <dfn id=rellist0 - title=dom-a-rellist><code>relList</code></dfn> must <a - href="#reflect">reflect</a> the <code title=attr-hyperlink-rel><a - href="#rel3">rel</a></code> content attribute. - - <h4 id=the-q><span class=secno>3.12.2. </span>The <dfn - id=q><code>q</code></dfn> element</h4> - - <p><a href="#strictly">Strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd>When used in an element whose content model is only <a - href="#strictly">strictly inline-level content</a>: only <a - href="#strictly">strictly inline-level content</a>. - - <dd>Otherwise: any <a href="#inline-level0">inline-level content</a>. - - <dt>Element-specific attributes: - - <dd><code title=attr-q-cite><a href="#cite1">cite</a></code> - - <dt>DOM interface: - - <dd> The <code><a href="#q">q</a></code> element uses the <code><a - href="#htmlquoteelement">HTMLQuoteElement</a></code> interface. - </dl> - - <p>The <code><a href="#q">q</a></code> element represents a part of a - paragraph quoted from another source. - - <p>Content inside a <code><a href="#q">q</a></code> element must be quoted - from another source, whose URI, if it has one, should be cited in the <dfn - id=cite1 title=attr-q-cite><code>cite</code></dfn> attribute. - - <p>If the <code title=attr-q-cite><a href="#cite1">cite</a></code> - attribute is present, it must be a URI (or IRI). User agents should allow - users to follow such citation links. - - <p>If a <code><a href="#q">q</a></code> element is contained (directly or - indirectly) in a <a href="#paragraph">paragraph</a> that contains a single - <code><a href="#cite2">cite</a></code> element and has no other <code><a - href="#q">q</a></code> element descendants, then, the citation given by - that <code><a href="#cite2">cite</a></code> element gives the source of - the quotation contained in the <code><a href="#q">q</a></code> element.</p> - <!-- XXX need examples --> - - <h4 id=the-cite><span class=secno>3.12.3. </span>The <dfn - id=cite2><code>cite</code></dfn> element</h4> - - <p><a href="#strictly">Strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd><a href="#strictly">Strictly inline-level content</a>. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>.</dd> - <!-- XXX should the cite element have a cite attribute? --> - </dl> - - <p>The <code><a href="#cite2">cite</a></code> element represents a - citation: the source, or reference, for a quote or statement made in the - document. - - <p class=note>A <em>citation</em> is not a <em>quote</em> (for which the - <code><a href="#q">q</a></code> element is appropriate). - - <div class=example> - <p>This is incorrect usage:</p> - - <pre><p><cite>This is wrong!</cite>, said Ian.</p></pre> - - <p>This is the correct way to do it:</p> - - <pre><p><q>This is correct!</q>, said <cite>Ian</cite>.</p></pre> - - <p>This is also wrong, because the title and the name are not references - or citations:</p> - - <pre><p>My favourite book is <cite>The Reality Dysfunction</cite> -by <cite>Peter F. Hamilton</cite>.</p></pre> - - <p>This is correct, because even though the source is not quoted, it is - cited:</p> - - <pre><p>According to <cite>the Wikipedia article on -HTML</cite>, HTML is defined in formal specifications that were -developed and published throughout the 1990s.</p></pre> - </div> - - <p class=note>The <code><a href="#cite2">cite</a></code> element can apply - to <code><a href="#blockquote">blockquote</a></code> and <code><a - href="#q">q</a></code> elements in certain cases described in the - definitions of those elements. - - <h4 id=the-em><span class=secno>3.12.4. </span>The <dfn - id=em><code>em</code></dfn> element</h4> - - <p><a href="#strictly">Strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd>When used in an element whose content model is only <a - href="#strictly">strictly inline-level content</a>: only <a - href="#strictly">strictly inline-level content</a>. - - <dd>Otherwise: any <a href="#inline-level0">inline-level content</a>. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#em">em</a></code> element represents stress emphasis - of its contents. - - <p>The level of emphasis that a particlar piece of content has is given by - its number of ancestor <code><a href="#em">em</a></code> elements. - - <p>The placement of emphasis changes the meaning of the sentence. The - element thus forms an integral part of the content. The precise way in - which emphasis is used in this way depends on the language. - - <div class=example> - <p>These examples show how changing the emphasis changes the meaning. - First, a general statement of fact, with no emphasis:</p> - - <pre><p>Cats are cute animals.</p></pre> - - <p>By emphasising the first word, the statement implies that the kind of - animal under discussion is in question (maybe someone is asserting that - dogs are cute):</p> - - <pre><p><em>Cats</em> are cute animals.</p></pre> - - <p>Moving the emphasis to the verb, one highlights that the truth of the - entire sentence is in question (maybe someone is saying cats are not - cute):</p> - - <pre><p>Cats <em>are</em> cute animals.</p></pre> - - <p>By moving it to the adjective, the exact nature of the cats is - reasserted (maybe someone suggested cats were <em>mean</em> animals):</p> - - <pre><p>Cats are <em>cute</em> animals.</p></pre> - - <p>Similarly, if someone asserted that cats were vegetables, someone - correcting this might emphasise the last word:</p> - - <pre><p>Cats are cute <em>animals</em>.</p></pre> - - <p>By emphasising the entire sentence, it becomes clear that the speaker - is fighting hard to get the point across. This kind of emphasis also - typically affects the punctuation, hence the exclamation mark here.</p> - - <pre><p><em>Cats are cute animals!</em></p></pre> - - <p>Anger mixed with emphasising the cuteness could lead to markup such as:</p> - - <pre><p><em>Cats are <em>cute</em> animals!</em></p></pre> - </div> - <!-- XXX should say it is wrong to use as in: - - <p><em>Note</em>: ...</p> - - --> - - <h4 id=the-strong><span class=secno>3.12.5. </span>The <dfn - id=strong><code>strong</code></dfn> element</h4> - - <p><a href="#strictly">Strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd>When used in an element whose content model is only <a - href="#strictly">strictly inline-level content</a>: only <a - href="#strictly">strictly inline-level content</a>. - - <dd>Otherwise: any <a href="#inline-level0">inline-level content</a>. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#strong">strong</a></code> element represents strong - importance for its contents. - - <p>The relative level of importance of a piece of content is given by its - number of ancestor <code><a href="#strong">strong</a></code> elements; - each <code><a href="#strong">strong</a></code> element increases the - importance of its contents. - - <p>Changing the importance of a piece of text with the <code><a - href="#strong">strong</a></code> element does not change the meaning of - the sentence. - - <div class=example> - <p>Here is an example of a warning notice in a game, with the various - parts marked up according to how important they are:</p> - <!-- DO NOT REFLOW THIS EXAMPLE it has been carefully balanced --> - <pre><p><strong>Warning.</strong> This dungeon is dangerous. -<strong>Avoid the ducks.</strong> Take any gold you find. -<strong><strong>Do not take any of the diamonds</strong>, -they are explosive and <strong>will destroy anything within -ten meters.</strong></strong> You have been warned.</p></pre> - </div> - - <h4 id=the-small><span class=secno>3.12.6. </span>The <dfn - id=small><code>small</code></dfn> element</h4> - - <p><a href="#strictly">Strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd>When used in an element whose content model is only <a - href="#strictly">strictly inline-level content</a>: only <a - href="#strictly">strictly inline-level content</a>. - - <dd>Otherwise: any <a href="#inline-level0">inline-level content</a>. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#small">small</a></code> element represents small - print (part of a document often describing legal restrictions, such as - copyrights or other disadvantages), or other side comments. - - <p class=note>The <code><a href="#small">small</a></code> element does not - "de-emphasise" or lower the importance of text emphasised by the <code><a - href="#em">em</a></code> element or marked as important with the <code><a - href="#strong">strong</a></code> element. - - <div class=example> - <p>In this example the footer contains contact information and a - copyright.</p> - - <pre><footer> - <address> - For more details, contact - <a href="mailto:js@example.com">John Smith</a>. - </address> - <p><small>© copyright 2038 Example Corp.</small></p> -</footer></pre> - - <p>In this second example, the <code><a href="#small">small</a></code> - element is used for a side comment.</p> - - <pre><p>Example Corp today announced record profits for the -second quarter <small>(Full Disclosure: Foo News is a subsidiary of -Example Corp)</small>, leading to speculation about a third quarter -merger with Demo Group.</p></pre> - - <p>In this last example, the <code><a href="#small">small</a></code> - element is marked as being <em>important</em> small print.</p> - - <pre><p><strong><small>Continued use of this service will result in a kiss.</small></strong></p></pre> - </div> - - <h4 id=the-m><span class=secno>3.12.7. </span>The <dfn - id=m><code>m</code></dfn> element</h4> - - <p><a href="#strictly">Strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd>When used in an element whose content model is only <a - href="#strictly">strictly inline-level content</a>: only <a - href="#strictly">strictly inline-level content</a>. - - <dd>Otherwise: any <a href="#inline-level0">inline-level content</a>. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#m">m</a></code> element represents a run of text - marked or highlighted. - - <div class=example> - <p>In the following snippet, a paragraph of text refers to a specific part - of a code fragment.</p> - - <pre><p>The highlighted part below is where the error lies:</p> -<pre><code>var i: Integer; -begin - i := <m>1.1</m>; -end.</code></pre></pre> - - <p>Another example of the <code><a href="#m">m</a></code> element is - highlighting parts of a document that are matching some search string. If - someone looked at a document, and the server knew that the user was - searching for the word "kitten", then the server might return the - document with one paragraph modified as follows:</p> - - <pre><p>I also have some <m>kitten</m>s who are visiting me -these days. They're really cute. I think they like my garden!</p></pre> - </div> - - <h4 id=the-dfn><span class=secno>3.12.8. </span>The <dfn - id=dfn><code>dfn</code></dfn> element</h4> - - <p><a href="#strictly">Strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed, if there are no ancestor <code><a href="#dfn">dfn</a></code> - elements. - - <dt>Content model: - - <dd><a href="#strictly">Strictly inline-level content</a>, but there must - be no descendant <code><a href="#dfn">dfn</a></code> elements. - - <dt>Element-specific attributes: - - <dd>None, but the <code title=attr-dfn-title><a - href="#title4">title</a></code> attribute has special semantics on this - element. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#dfn">dfn</a></code> element represents the defining - instance of a term. The <a href="#paragraph">paragraph</a>, <a href="#dl" - title=dl>description list group</a>, or <a href="#sectioning" - title="sectioning elements">section</a> that contains the <code><a - href="#dfn">dfn</a></code> element contains the definition for the term - given by the contents of the <code><a href="#dfn">dfn</a></code> element. - - <p><code><a href="#dfn">dfn</a></code> elements must not be nested. - - <p><dfn id=defining>Defining term</dfn>: If the <code><a - href="#dfn">dfn</a></code> element has a <dfn id=title4 - title=attr-dfn-title><code>title</code></dfn> attribute, then the exact - value of that attribute is the term being defined. Otherwise, if it - contains exactly one element child node and no child <a href="#text-node" - title="text node">text nodes</a>, and that child element is an <code><a - href="#abbr">abbr</a></code> element with a <code title=attr-abbr-title><a - href="#title5">title</a></code> attribute, then the exact value of - <em>that</em> attribute is the term being defined. Otherwise, it is the - exact <code><a href="#textcontent">textContent</a></code> of the <code><a - href="#dfn">dfn</a></code> element that gives the term being defined.</p> - <!-- XXX that means <dfn>x \n x</dfn> won't match <span>x x</span> --> - - <p>If the <code title=attr-dfn-title><a href="#title4">title</a></code> - attribute of the <code><a href="#dfn">dfn</a></code> element is present, - then it must only contain the term being defined. - - <p>There must only be one <code><a href="#dfn">dfn</a></code> element per - document for each term defined (i.e. there must not be any duplicate <a - href="#defining" title="defining term">terms</a>). - - <p class=note>The <code title=attr-title><a href="#title">title</a></code> - attribute of ancestor elements does not affect <code><a - href="#dfn">dfn</a></code> elements. - - <p>The <code><a href="#dfn">dfn</a></code> element enables automatic - cross-references. Specifically, any <code><a href="#span">span</a></code>, - <code><a href="#abbr">abbr</a></code>, <code><a - href="#code">code</a></code>, <code><a href="#var">var</a></code>, - <code><a href="#samp">samp</a></code>, or <code><a href="#i">i</a></code> - element that has a non-empty <code title=attr-title><a - href="#title">title</a></code> attribute whose value exactly equals the <a - href="#defining" title="defining term">term</a> of a <code><a - href="#dfn">dfn</a></code> element in the same document, or which has no - <code title=attr-title><a href="#title">title</a></code> attribute but - whose <code><a href="#textcontent">textContent</a></code> exactly equals - the <a href="#defining" title="defining term">term</a> of a <code><a - href="#dfn">dfn</a></code> element in the document, and that has no <a - href="#interactive1">interactive elements</a> or <code><a - href="#dfn">dfn</a></code> elements either as ancestors or descendants, - and has no other elements as ancestors that are themselves matching these - conditions, should be presented in such a way that the user can jump from - the element to the first <code><a href="#dfn">dfn</a></code> element - giving the defining instance of that term.</p> - <!-- XXX that means <dfn>x x</dfn> won't match <span>x \n x</span> --> - <!-- need to mention that <span> is useful for cross-refs that don't - actually use the term itself --> - - <div class=example> - <p>In the following fragment, the term "GDO" is first defined in the first - paragraph, then used in the second. A compliant UA could provide a link - from the <code><a href="#abbr">abbr</a></code> element in the second - paragraph to the <code><a href="#dfn">dfn</a></code> element in the - first.</p> - - <pre><p>The <dfn><abbr title="Garage Door Opener">GDO</abbr></dfn> -is a device that allows off-world teams to open the iris.</p> -<!-- ... later in the document: --> -<p>Teal'c activated his <abbr title="Garage Door Opener">GDO</abbr> -and so Hammond ordered the iris to be opened.</p></pre> - <!-- XXX need some examples of nesting where the top element makes - a crossref but the inner ones don't despite also matching the - algorithm above --> - <!-- XXX need some examples of duplicates being bad, of title - attributes being bad, etc --> - </div> - - <h4 id=the-abbr><span class=secno>3.12.9. </span>The <dfn - id=abbr><code>abbr</code></dfn> element</h4> - - <p><a href="#strictly">Strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd><a href="#strictly">Strictly inline-level content</a>. - - <dt>Element-specific attributes: - - <dd>None, but the <code title=attr-abbr-title><a - href="#title5">title</a></code> attribute has special semantics on this - element. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#abbr">abbr</a></code> element represents an - abbreviation or acronym. The <dfn id=title5 - title=attr-abbr-title><code>title</code></dfn> attribute should be used to - provide an expansion of the abbreviation. If present, the attribute must - only contain an expansion of the abbreviation. - - <div class=example> - <p>The paragraph below contains an abbreviation marked up with the - <code><a href="#abbr">abbr</a></code> element.</p> - - <pre><p>The <abbr title="Web Hypertext Application Technology -Working Group">WHATWG</abbr> is a loose unofficial collaboration of -Web browser manufacturers and interested parties who wish to develop -new technologies designed to allow authors to write and deploy -Applications over the World Wide Web.</p></pre> - </div> - - <p>The <code title=attr-abbr-title><a href="#title5">title</a></code> - attribute may be omitted if there is a <code><a href="#dfn">dfn</a></code> - element in the document whose <a href="#defining">defining term</a> is the - abbreviation (the <code><a href="#textcontent">textContent</a></code> of - the <code><a href="#abbr">abbr</a></code> element). - - <div class=example> - <p>In the example below, the word "Zat" is used as an abbreviation in the - second paragraph. The abbreviation is defined in the first, so the - explanatory <code title=attr-abbr-title><a - href="#title5">title</a></code> attribute has been omitted. Because of - the way <code><a href="#dfn">dfn</a></code> elements are defined, the - second <code><a href="#abbr">abbr</a></code> element in this example - would be connected (in some UA-specific way) to the first.</p> - - <pre><p>The <dfn><abbr>Zat</abbr></dfn>, short for Zat'ni'catel, is a weapon.</p> -<p>Jack used a <abbr>Zat</abbr> to make the boxes of evidence disappear.</p></pre> - </div> - - <h4 id=the-time><span class=secno>3.12.10. </span>The <dfn - id=time><code>time</code></dfn> element</h4> - - <p><a href="#strictly">Strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd><a href="#strictly">Strictly inline-level content</a>. - - <dt>Element-specific attributes: - - <dd><code title=attr-time-datetime><a href="#datetime">datetime</a></code> - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmltimeelement>HTMLTimeElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute DOMString <a href="#datetime0" title=dom-time-datetime>dateTime</a>; - readonly attribute DOMTimeStamp <a href="#date0" title=dom-time-date>date</a>; - readonly attribute DOMTimeStamp <a href="#time1" title=dom-time-time>time</a>; - readonly attribute DOMTimeStamp <a href="#timezone0" title=dom-time-timezone>timezone</a>; -};</pre> - </dl> - - <p>The <code><a href="#time">time</a></code> element represents a date - and/or a time. - - <p>The <dfn id=datetime - title=attr-time-datetime><code>datetime</code></dfn> attribute, if - present, must contain a <a href="#date-or">date or time string</a> that - identifies the date or time being specified. - - <p>If the <code title=attr-time-datetime><a - href="#datetime">datetime</a></code> attribute is not present, then the - date or time must be specified in the content of the element, such that - parsing the element's <code><a href="#textcontent">textContent</a></code> - according to the rules for parsing <a href="#date-or0" title="date or time - string in content">date or time strings in content</a> successfully - extracts a date or time. - - <p>The <dfn id=datetime0 - title=dom-time-datetime><code>dateTime</code></dfn> DOM attribute must <a - href="#reflect">reflect</a> the <code title=attr-time-datetime><a - href="#datetime">datetime</a></code> content attribute. - - <p>User agents, to obtain the <dfn id=date - title=concept-time-date>date</dfn>, <dfn id=time0 - title=concept-time-time>time</dfn>, and <dfn id=timezone - title=concept-time-timezone>timezone</dfn> represented by a <code><a - href="#time">time</a></code> element, must follow the following steps: - - <ol> - <li>If the <code title=attr-time-datetime><a - href="#datetime">datetime</a></code> attribute is present, then parse it - according to the rules for parsing <a href="#date-or1" title="date or - time string in attributes">date or time strings in content</a>, and let - the result be <var title="">result</var>. - - <li>Otherwise, parse the element's <code><a - href="#textcontent">textContent</a></code> according to the rules for - parsing <a href="#date-or1" title="date or time string in - attributes">date or time strings in content</a>, and let the result be - <var title="">result</var>. - - <li>If <var title="">result</var> is empty (because the parsing failed), - then the <a href="#date" title=concept-time-date>date</a> is unknown, the - <a href="#time0" title=concept-time-time>time</a> is unknown, and the <a - href="#timezone" title=concept-time-timezone>timezone</a> is unknown. - - <li>Otherwise: if <var title="">result</var> contains a date, then that is - the <a href="#date" title=concept-time-date>date</a>; if <var - title="">result</var> contains a time, then that is the <a href="#time0" - title=concept-time-time>time</a>; and if <var title="">result</var> - contains a timezone, then the timezone is the element's <a - href="#timezone" title=concept-time-timezone>timezone</a>. (A timezone - can only be present if both a date and a time are also present.) - </ol> - - <p>The <dfn id=date0 title=dom-time-date><code>date</code></dfn> DOM - attribute must return null if the <a href="#date" - title=concept-time-date>date</a> is unknown, and otherwise must return the - time corresponding to midnight UTC (i.e. the first second) of the given <a - href="#date" title=concept-time-date>date</a>. - - <p>The <dfn id=time1 title=dom-time-time><code>time</code></dfn> DOM - attribute must return null if the <a href="#time0" - title=concept-time-time>time</a> is unknown, and otherwise must return the - time corresponding to the given <a href="#time0" - title=concept-time-time>time</a> of 1970-01-01, with the timezone UTC. - - <p>The <dfn id=timezone0 - title=dom-time-timezone><code>timezone</code></dfn> DOM attribute must - return null if the <a href="#timezone" - title=concept-time-timezone>timezone</a> is unknown, and otherwise must - return the time corresponding to 1970-01-01 00:00 UTC in the given <a - href="#timezone" title=concept-time-timezone>timezone</a>, with the - timezone set to UTC (i.e. the time corresponding to 1970-01-01 at 00:00 - UTC plus the offset corresponding to the timezone). - - <div class=example> - <p>In the following snippet:</p> - - <pre><p>Our first date was <time datetime="2006-09-23">a saturday</time>.</p></pre> - - <p>...the <code><a href="#time">time</a></code> element's <code - title=dom-time-date><a href="#date0">date</a></code> attribute would have - the value 1,158,969,600,000ms, and the <code title=dom-time-time><a - href="#time1">time</a></code> and <code title=dom-time-timezone><a - href="#timezone0">timezone</a></code> attributes would return null.</p> - - <p>In the following snippet:</p> - - <pre><p>We stopped talking at <time datetime="2006-09-24 05:00 -7">5am the next morning</time>.</p></pre> - - <p>...the <code><a href="#time">time</a></code> element's <code - title=dom-time-date><a href="#date0">date</a></code> attribute would have - the value 1,159,056,000,000ms, the <code title=dom-time-time><a - href="#time1">time</a></code> attribute would have the value - 18,000,000ms, and the <code title=dom-time-timezone><a - href="#timezone0">timezone</a></code> attribute would return - -25,200,000ms. To obtain the actual time, the three attributes can be - added together, obtaining 1,159,048,800,000, which is the specified date - and time in UTC.</p> - - <p>Finally, in the following snippet:</p> - - <pre><p>Many people get up at <time>08:00</time>.</p></pre> - - <p>...the <code><a href="#time">time</a></code> element's <code - title=dom-time-date><a href="#date0">date</a></code> attribute would have - the value null, the <code title=dom-time-time><a - href="#time1">time</a></code> attribute would have the value - 28,800,000ms, and the <code title=dom-time-timezone><a - href="#timezone0">timezone</a></code> attribute would return null.</p> - </div> - - <p class=big-issue>These APIs may be suboptimal. Comments on making them - more useful to JS authors are welcome. The primary use cases for these - elements are for marking up publication dates e.g. in blog entries, and - for marking event dates in hCalendar markup. Thus the DOM APIs are likely - to be used as ways to generate interactive calendar widgets or some such. - - <h4 id=the-meter><span class=secno>3.12.11. </span>The <dfn - id=meter><code>meter</code></dfn> element</h4> - - <p><a href="#strictly">Strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd><a href="#strictly">Strictly inline-level content</a>. - - <dt>Element-specific attributes: - - <dd><code title=attr-meter-value><a href="#value1">value</a></code> - - <dd><code title=attr-meter-min><a href="#min">min</a></code> - - <dd><code title=attr-meter-low><a href="#low">low</a></code> - - <dd><code title=attr-meter-high><a href="#high">high</a></code> - - <dd><code title=attr-meter-max><a href="#max">max</a></code> - - <dd><code title=attr-meter-optimum><a href="#optimum">optimum</a></code> - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmlmeterelement>HTMLMeterElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute long <a href="#value2" title=dom-meter-value>value</a>; - attribute long <a href="#min0" title=dom-meter-min>min</a>; - attribute long <a href="#max0" title=dom-meter-max>max</a>; - attribute long <a href="#low0" title=dom-meter-low>low</a>; - attribute long <a href="#high0" title=dom-meter-high>high</a>; - attribute long <a href="#optimum0" title=dom-meter-optimum>optimum</a>; -};</pre> - </dl> - - <p>The <code><a href="#meter">meter</a></code> element represents a scalar - measurement within a known range, or a fractional value; for example disk - usage, the relevance of a query result, or the fraction of a voting - population to have selected a particular candidate. - - <p>This is also known as a gauge. - - <p class=note>The <code><a href="#meter">meter</a></code> element should - not be used to indicate progress (as in a progress bar). For that role, - HTML provides a separate <code><a href="#progress">progress</a></code> - element. - - <p>There are six attributes that determine the semantics of the gauge - represented by the element. - - <p>The <dfn id=min title=attr-meter-min><code>min</code></dfn> attribute - specifies the lower bound of the range, and the <dfn id=max - title=attr-meter-max><code>max</code></dfn> attribute specifies the upper - bound. The <dfn id=value1 title=attr-meter-value><code>value</code></dfn> - attribute specifies the value to have the gauge indicate as the "measured" - value. - - <p>The other three attributes can be used to segment the gauge's range into - "low", "medium", and "high" parts, and to indicate which part of the gauge - is the "optimum" part. The <dfn id=low - title=attr-meter-low><code>low</code></dfn> attribute specifies the range - that is considered to be the "low" part, and the <dfn id=high - title=attr-meter-high><code>high</code></dfn> attribute specifies the - range that is considered to be the "high" part. The <dfn id=optimum - title=attr-meter-optimum><code>optimum</code></dfn> attribute gives the - position that is "optimum"; if that is higher than the "high" value then - this indicates that the higher the value, the better; if it's lower than - the "low" mark then it indicates that lower values are better, and - naturally if it is in between then it indicates that neither high nor low - values are good. - - <p><strong>Authoring requirements</strong>: The recommended way of giving - the value is to include it as contents of the element, either as two - numbers (the higher number represents the maximum, the other number the - current value), or as a percentage or similar (using one of the characters - such as "%"), or as a fraction. - - <p>The <code title=attr-meter-value><a href="#value1">value</a></code>, - <code title=attr-meter-min><a href="#min">min</a></code>, <code - title=attr-meter-low><a href="#low">low</a></code>, <code - title=attr-meter-high><a href="#high">high</a></code>, <code - title=attr-meter-max><a href="#max">max</a></code>, and <code - title=attr-meter-optimum><a href="#optimum">optimum</a></code> attributes - are all optional. When present, they must have values that are <a - href="#valid1" title="valid floating point number">valid floating point - numbers</a>. - - <div class=example> - <p>The following examples all represent a measurement of three quarters - (of the maximum of whatever is being measured):</p> - - <pre><meter>75%</meter> -<meter>750‰</meter> -<meter>3/4</meter> -<meter>6 blocks used (out of 8 total)</meter> -<meter>max: 100; current: 75</meter> -<meter><object data="graph75.png">0.75</object></meter> -<meter min="0" max="100" value="75"></meter></pre> - </div> - - <p><strong>User agent requirements</strong>: User agents must parse the - <code title=attr-meter-min><a href="#min">min</a></code>, <code - title=attr-meter-max><a href="#max">max</a></code>, <code - title=attr-meter-value><a href="#value1">value</a></code>, <code - title=attr-meter-low><a href="#low">low</a></code>, <code - title=attr-meter-high><a href="#high">high</a></code>, and <code - title=attr-meter-optimum><a href="#optimum">optimum</a></code> attributes - using the <a href="#rules1">rules for parsing floating point number - values</a>. - - <p>If the <code title=attr-meter-value><a href="#value1">value</a></code> - attribute has been omitted, the user agent must also process the <code><a - href="#textcontent">textContent</a></code> of the element according to the - <a href="#steps">steps for finding one or two numbers of a ratio in a - string</a>. These steps will return nothing, one number, one number with a - denominator punctuation character, or two numbers. - - <p>User agents must then use all these numbers to obtain values for six - points on the gauge, as follows. (The order in which these are evaluated - is important, as some of the values refer to earlier ones.) - - <dl> - <dt>The minimum value - - <dd> - <p>If the <code title=attr-meter-min><a href="#min">min</a></code> - attribute is specified and a value could be parsed out of it, then the - minimum value is that value. Otherwise, the minimum value is zero.</p> - - <dt>The maximum value - - <dd> - <p>If the <code title=attr-meter-max><a href="#max">max</a></code> - attribute is specified and a value could be parsed out of it, the - maximum value is that value.</p> - - <p>Otherwise, if the <code title=attr-meter-max><a - href="#max">max</a></code> attribute is specified but no value could be - parsed out of it, or if it was not specified, but either or both of the - <code title=attr-meter-min><a href="#min">min</a></code> or <code - title=attr-meter-value><a href="#value1">value</a></code> attributes - <em>were</em> specified, then the maximum value is 1.</p> - - <p>Otherwise, none of the <code title=attr-meter-max><a - href="#max">max</a></code>, <code title=attr-meter-min><a - href="#min">min</a></code>, and <code title=attr-meter-value><a - href="#value1">value</a></code> attributes were specified. If the result - of processing the <code><a href="#textcontent">textContent</a></code> of - the element was either nothing or just one number with no denominator - punctuation character, then the maximum value is 1; if the result was - one number but it had an associated denominator punctuation character, - then the maximum value is the <a href="#a-value" title="values - associated with denominator punctuation characters">value associated - with that denominator punctuation character</a>; and finally, if there - were two numbers parsed out of the <code><a - href="#textcontent">textContent</a></code>, then the maximum is the - higher of those two numbers.</p> - - <p>If the above machinations result in a maximum value less than the - minimum value, then the maximum value is actually the same as the - minimum value.</p> - - <dt>The actual value - - <dd> - <p>If the <code title=attr-meter-value><a href="#value1">value</a></code> - attribute is specified and a value could be parsed out of it, then that - value is the actual value.</p> - - <p>If the <code title=attr-meter-value><a href="#value1">value</a></code> - attribute is not specified but the <code title=attr-meter-max><a - href="#max">max</a></code> attribute <em>is</em> specified and the - result of processing the <code><a - href="#textcontent">textContent</a></code> of the element was one number - with no associated denominator punctuation character, then that number - is the actual value.</p> - - <p>If neither of the <code title=attr-meter-value><a - href="#value1">value</a></code> and <code title=attr-meter-max><a - href="#max">max</a></code> attributes are specified, then, if the result - of processing the <code><a href="#textcontent">textContent</a></code> of - the element was one number (with or without an associated denominator - punctuation character), then that is the actual value, and if the result - of processing the <code><a href="#textcontent">textContent</a></code> of - the element was two numbers, then the actual value is the lower of the - two numbers found.</p> - - <p>Otherwise, if none of the above apply, the actual value is zero.</p> - - <p>If the above procedure results in an actual value less than the - minimum value, then the actual value is actually the same as the minimum - value.</p> - - <p>If, on the other hand, the result is an actual value greater than the - maximum value, then the actual value is the maximum value.</p> - - <dt>The low boundary - - <dd> - <p>If the <code title=attr-meter-low><a href="#low">low</a></code> - attribute is specified and a value could be parsed out of it, then the - low boundary is that value. Otherwise, the low boundary is the same as - the minimum value.</p> - - <p>If the above results in a low boundary that is less than the minimum - value, the low boundary is the minimum value.</p> - - <dt>The high boundary - - <dd> - <p>If the <code title=attr-meter-high><a href="#high">high</a></code> - attribute is specified and a value could be parsed out of it, then the - high boundary is that value. Otherwise, the high boundary is the same as - the maximum value.</p> - - <p>If the above results in a high boundary that is higher than the - maximum value, the high boundary is the maximum value.</p> - - <dt>The optimum point - - <dd> - <p>If the <code title=attr-meter-optimum><a - href="#optimum">optimum</a></code> attribute is specified and a value - could be parsed out of it, then the optimum point is that value. - Otherwise, the optimum point is the midpoint between the minimum value - and the maximum value.</p> - - <p>If the optimum point is then less than the minimum value, then the - optimum point is actually the same as the minimum value. Similarly, if - the optimum point is greater than the maximum value, then it is actually - the maximum value instead.</p> - </dl> - - <p>All of which should result in the following inequalities all being true: - - <ul class=brief> - <li>minimum value ≤ actual value ≤ maximum value - - <li>minimum value ≤ low boundary ≤ high boundary ≤ maximum value - - <li>minimum value ≤ optimum point ≤ maximum value - </ul> - - <p><strong>UA requirements for regions of the gauge</strong>: If the - optimum point is equal to the low boundary or the high boundary, or - anywhere in between them, then the region between the low and high - boundaries of the gauge must be treated as the optimum region, and the low - and high parts, if any, must be treated as suboptimal. Otherwise, if the - optimum point is less than the low boundary, then the region between the - minimum value and the low boundary must be treated as the optimum region, - the region between the low boundary and the high boundary must be treated - as a suboptimal region, and the region between the high boundary and the - maximum value must be treated as an even less good region. Finally, if the - optimum point is higher than the high boundary, then the situation is - reversed; the region between the high boundary and the maximum value must - be treated as the optimum region, the region between the high boundary and - the low boundary must be treated as a suboptimal region, and the remaining - region between the low boundary and the minimum value must be treated as - an even less good region. - - <p><strong>UA requirements for showing the gauge</strong>: When - representing a <code><a href="#meter">meter</a></code> element to the - user, the UA should indicate the relative position of the actual value to - the minimum and maximum values, and the relationship between the actual - value and the three regions of the gauge. - - <div class=example> - <p>The following markup:</p> - - <pre> -<h3>Suggested groups</h3> -<menu type="toolbar"> - <a href="?cmd=hsg" onclick="hideSuggestedGroups()">Hide suggested groups</a> -</menu> -<ul> - <li> - <p><a href="/group/comp.infosystems.www.authoring.stylesheets/view">comp.infosystems.www.authoring.stylesheets</a> - - <a href="/group/comp.infosystems.www.authoring.stylesheets/subscribe">join</a></p> - <p>Group description: <strong>Layout/presentation on the WWW.</strong></p> - <p><strong><meter value="0.5">Moderate activity,</meter></strong> Usenet, 618 subscribers</p> - </li> - <li> - <p><a href="/group/netscape.public.mozilla.xpinstall/view">netscape.public.mozilla.xpinstall</a> - - <a href="/group/netscape.public.mozilla.xpinstall/subscribe">join</a></p> - <p>Group description: <strong>Mozilla XPInstall discussion.</strong></p> - <p><strong><meter value="0.25">Low activity,</meter></strong> Usenet, 22 subscribers</p> - </li> - <li> - <p><a href="/group/mozilla.dev.general/view">mozilla.dev.general</a> - - <a href="/group/mozilla.dev.general/subscribe">join</a></p> - <p><strong><meter value="0.25">Low activity,</meter></strong> Usenet, 66 subscribers</p> - </li> -</ul> -</pre> - - <p>Might be rendered as follows:</p> - - <p><img alt="With the <meter> elements rendered as inline green bars of - varying lengths." src="images/sample-meter.png"></p> - </div> - - <p>The <dfn id=min0 title=dom-meter-min><code>min</code></dfn>, <dfn - id=max0 title=dom-meter-max><code>max</code></dfn>, <dfn id=value2 - title=dom-meter-value><code>value</code></dfn>, <dfn id=low0 - title=dom-meter-low><code>low</code></dfn>, <dfn id=high0 - title=dom-meter-high><code>high</code></dfn>, and <dfn id=optimum0 - title=dom-meter-optimum><code>optimum</code></dfn> DOM attributes must - reflect the elements' content attributes of the same name. When the - relevant content attributes are absent, the DOM attributes must return - zero. The value parsed from the <code><a - href="#textcontent">textContent</a></code> never affects the DOM values. - - <p class=big-issue>Would be cool to have the <code title=dom-meter-value><a - href="#value2">value</a></code> DOM attribute update the <code><a - href="#textcontent">textContent</a></code> in-line...</p> - <!-- XXX -should we also look inside the title="" attribute? - Disk usage: <meter title="985MB of 986MB total" high="980">Full!</meter> -should we make the contents accessible in some way, e.g. as a tooltip? ---> - - <h4 id=the-progress><span class=secno>3.12.12. </span>The <dfn - id=progress><code>progress</code></dfn> element</h4> - - <p><a href="#strictly">Strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd><a href="#strictly">Strictly inline-level content</a>. - - <dt>Element-specific attributes: - - <dd><code title=attr-progress-value><a href="#value3">value</a></code> - - <dd><code title=attr-progress-max><a href="#max1">max</a></code> - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmlprogresselement>HTMLProgressElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute float <a href="#value4" title=dom-progress-value>value</a>; - attribute float <a href="#max2" title=dom-progress-max>max</a>; - readonly attribute float <a href="#position" title=dom-progress-position>position</a>; -};</pre> - </dl> - - <p>The <code><a href="#progress">progress</a></code> element represents the - completion progress of a task. The progress is either indeterminate, - indicating that progress is being made but that it is not clear how much - more work remains to be done before the task is complete (e.g. because the - task is waiting for a remote host to respond), or the progress is a number - in the range zero to a maximum, giving the fraction of work that has so - far been completed. - - <p>There are two attributes that determine the current task completion - represented by the element. - - <p>The <dfn id=value3 title=attr-progress-value><code>value</code></dfn> - attribute specifies how much of the task has been completed, and the <dfn - id=max1 title=attr-progress-max><code>max</code></dfn> attribute specifies - how much work the task requires in total. The units are arbitrary and not - specified. - - <p>Instead of using the attributes, authors are recommended to simply - include the current value and the maximum value inline as text inside the - element. - - <div class=example> - <p>Here is a snippet of a Web application that shows the progress of some - automated task:</p> - - <pre><section> - <h2>Task Progress</h2> - <p><label>Progress: <progress><span id="p">0</span>%</progress></p> - <script> - var progressBar = document.getElementById('p'); - function updateProgress(newValue) { - progressBar.textContent = newValue; - } - </script> -</section></pre> - - <p>(The <code>updateProgress()</code> method in this example would be - called by some other code on the page to update the actual progress bar - as the task progressed.)</p> - </div> - - <p><strong>Author requirements</strong>: The <code - title=attr-progress-max><a href="#max1">max</a></code> and <code - title=attr-progress-value><a href="#value3">value</a></code> attributes, - when present, must have values that are <a href="#valid1" title="valid - floating point number">valid floating point numbers</a>. The <code - title=attr-progress-max><a href="#max1">max</a></code> attribute, if - present, must have a value greater than zero. The <code - title=attr-progress-value><a href="#value3">value</a></code> attribute, if - present, must have a value equal to or greater than zero, and less than or - equal to the value of the <code title=attr-progress-max><a - href="#max1">max</a></code> attribute, if present. - - <p><strong>User agent requirements</strong>: User agents must parse the - <code title=attr-progress-max><a href="#max1">max</a></code> and <code - title=attr-progress-value><a href="#value3">value</a></code> attributes' - values according to the <a href="#rules1">rules for parsing floating point - number values</a>. - - <p>If the <code title=attr-progress-value><a - href="#value3">value</a></code> attribute is omitted, then user agents - must also parse the <code><a href="#textcontent">textContent</a></code> of - the <code><a href="#progress">progress</a></code> element in question - using the <a href="#steps">steps for finding one or two numbers of a ratio - in a string</a>. These steps will return nothing, one number, one number - with a denominator punctuation character, or two numbers. - - <p>Using the results of this processing, user agents must determine whether - the progress bar is an indeterminate progress bar, or whether it is a - determinate progress bar, and in the latter case, what its current and - maximum values are, all as follows: - - <ol> - <li>If the <code title=attr-progress-max><a href="#max1">max</a></code> - attribute is omitted, and the <code title=attr-progress-value><a - href="#value3">value</a></code> is omitted, and the results of parsing - the <code><a href="#textcontent">textContent</a></code> was nothing, then - the progress bar is an indeterminate progress bar. Abort these steps. - - <li>Otherwise, it is a determinate progress bar. - - <li>If the <code title=attr-progress-max><a href="#max1">max</a></code> - attribute is included, then, if a value could be parsed out of it, then - the maximum value is that value. - - <li>Otherwise, if the <code title=attr-progress-max><a - href="#max1">max</a></code> attribute is absent but the <code - title=attr-progress-value><a href="#value3">value</a></code> attribute is - present, or, if the <code title=attr-progress-max><a - href="#max1">max</a></code> attribute is present but no value could be - parsed from it, then the maximum is 1. - - <li>Otherwise, if neither attribute is included, then, if the <code><a - href="#textcontent">textContent</a></code> contained one number with an - associated denominator punctuation character, then the maximum value is - the <span>value associated with that denominator punctuation - character</span>; otherwise, if the <code><a - href="#textcontent">textContent</a></code> contained two numbers, the - maximum value is the higher of the two values; otherwise, the maximum - value is 1. - - <li>If the <code title=attr-progress-value><a - href="#value3">value</a></code> attribute is present on the element and a - value could be parsed out of it, that value is the current value of the - progress bar. Otherwise, if the attribute is present but no value could - be parsed from it, the current value is zero. - - <li>Otherwise if the <code title=attr-progress-value><a - href="#value3">value</a></code> attribute is absent and the <code - title=attr-progress-max><a href="#max1">max</a></code> attribute is - present, then, if the <code><a href="#textcontent">textContent</a></code> - was parsed and found to contain just one number, with no associated - denominator punctuation character, then the current value is that number. - Otherwise, if the <code title=attr-progress-value><a - href="#value3">value</a></code> attribute is absent and the <code - title=attr-progress-max><a href="#max1">max</a></code> attribute is - present then the current value is zero. - - <li>Otherwise, if neither attribute is present, then the current value is - the lower of the one or two numbers that were found in the <code><a - href="#textcontent">textContent</a></code> of the element. - - <li>If the maximum value is less than or equal to zero, then it is reset - to 1. - - <li>If the current value is less than zero, then it is reset to zero. - - <li>Finally, if the current value is greater than the maximum value, then - the current value is reset to the maximum value. - </ol> - - <p><strong>UA requirements for showing the progress bar</strong>: When - representing a <code><a href="#progress">progress</a></code> element to - the user, the UA should indicate whether it is a determinate or - indeterminate progress bar, and in the former case, should indicate the - relative position of the current value relative to the maximum value. - - <p>The <dfn id=max2 title=dom-progress-max><code>max</code></dfn> and <dfn - id=value4 title=dom-progress-value><code>value</code></dfn> DOM attributes - must reflect the elements' content attributes of the same name. When the - relevant content attributes are absent, the DOM attributes must return - zero. The value parsed from the <code><a - href="#textcontent">textContent</a></code> never affects the DOM values. - - <p class=big-issue>Would be cool to have the <code - title=dom-progress-value><a href="#value4">value</a></code> DOM attribute - update the <code><a href="#textcontent">textContent</a></code> in-line... - - <p>If the progress bar is an indeterminate progress bar, then the <dfn - id=position title=dom-progress-position><code>position</code></dfn> DOM - attribute must return -1. Otherwise, it must return the result of dividing - the current value by the maximum value. - - <h4 id=the-code><span class=secno>3.12.13. </span>The <dfn - id=code><code>code</code></dfn> element</h4> - - <p><a href="#strictly">Strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd>When used in an element whose content model is only <a - href="#strictly">strictly inline-level content</a>: only <a - href="#strictly">strictly inline-level content</a>. - - <dd>Otherwise: any <a href="#inline-level0">inline-level content</a>. - - <dt>Element-specific attributes: - - <dd>None, but the <code title=attr-title><a href="#title">title</a></code> - attribute has special semantics on this element when used with the - <code><a href="#dfn">dfn</a></code> element. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#code">code</a></code> element represents a fragment - of computer code. This could be an XML element name, a filename, a - computer program, or any other string that a computer would recognise. - - <p class=note>See the <code><a href="#pre">pre</a></code> element for more - detais. - - <div class=example> - <p>The following example shows how a block of code could be marked up - using the <code><a href="#pre">pre</a></code> and <code><a - href="#code">code</a></code> elements.</p> - - <pre><pre><code>var i: Integer; -begin - i := 1; -end.</code></pre></pre> - </div> - - <h4 id=the-var><span class=secno>3.12.14. </span>The <dfn - id=var><code>var</code></dfn> element</h4> - - <p><a href="#strictly">Strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd><a href="#strictly">Strictly inline-level content</a>. - - <dt>Element-specific attributes: - - <dd>None, but the <code title=attr-title><a href="#title">title</a></code> - attribute has special semantics on this element when used with the - <code><a href="#dfn">dfn</a></code> element. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#var">var</a></code> element represents a variable. - This could be an actual variable in a mathematical expression or - programming context, or it could just be a term used as a placeholder in - prose. - - <div class=example> - <p>In the paragraph below, the letter "n" is being used as a variable in - prose:</p> - - <pre><p>If there are <var>n</var> pipes leading to the ice -cream factory then I expect at <em>least</em> <var>n</var> -flavours of ice cream to be available for purchase!</p></pre> - </div> - - <h4 id=the-samp><span class=secno>3.12.15. </span>The <dfn - id=samp><code>samp</code></dfn> element</h4> - - <p><a href="#strictly">Strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd>When used in an element whose content model is only <a - href="#strictly">strictly inline-level content</a>: only <a - href="#strictly">strictly inline-level content</a>. - - <dd>Otherwise: any <a href="#inline-level0">inline-level content</a>. - - <dt>Element-specific attributes: - - <dd>None, but the <code title=attr-title><a href="#title">title</a></code> - attribute has special semantics on this element when used with the - <code><a href="#dfn">dfn</a></code> element. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#samp">samp</a></code> element represents (sample) - output from a program or computing system. - - <p class=note>See the <code><a href="#pre">pre</a></code> and <code><a - href="#kbd">kbd</a></code> elements for more detais. - - <div class=example> - <p>This example shows the <code><a href="#samp">samp</a></code> element - being used inline:</p> - - <pre><p>The computer said <samp>Too much cheese in tray -two</samp> but I didn't know what that meant.</p></pre> - - <p>This second example shows a block of sample output. Nested <code><a - href="#samp">samp</a></code> and <code><a href="#kbd">kbd</a></code> - elements allow for the styling of specific elements of the sample output - using a style sheet.</p> - <!-- XXX should those nested SAMPs be SPANs? --> - <pre><pre><samp><samp class="prompt">jdoe@mowmow:~$</samp> <kbd>ssh demo.example.com</kbd> -Last login: Tue Apr 12 09:10:17 2005 from mowmow.example.com on pts/1 -Linux demo 2.6.10-grsec+gg3+e+fhs6b+nfs+gr0501+++p3+c4a+gr2b-reslog-v6.189 #1 SMP Tue Feb 1 11:22:36 PST 2005 i686 unknown - -<samp class="prompt">jdoe@demo:~$</samp> <samp class="cursor">_</samp></samp></pre></pre> - </div> - - <h4 id=the-kbd><span class=secno>3.12.16. </span>The <dfn - id=kbd><code>kbd</code></dfn> element</h4> - - <p><a href="#strictly">Strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd><a href="#strictly">Strictly inline-level content</a>. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#kbd">kbd</a></code> element represents user input - (typically keyboard input, although it may also be used to represent other - input, such as voice commands). - - <p>When the <code><a href="#kbd">kbd</a></code> element is nested inside a - <code><a href="#samp">samp</a></code> element, it represents the input as - it was echoed by the system. - - <p>When the <code><a href="#kbd">kbd</a></code> element <em>contains</em> a - <code><a href="#samp">samp</a></code> element, it represents input based - on system output, for example invoking a menu item. - - <p>When the <code><a href="#kbd">kbd</a></code> element is nested inside - another <code><a href="#kbd">kbd</a></code> element, it represents an - actual key or other single unit of input as appropriate for the input - mechanism. - - <div class=example> - <p>Here the <code><a href="#kbd">kbd</a></code> element is used to - indicate keys to press:</p> - - <pre><p>To make George eat an apple, press <kbd><kbd>Shift</kbd>+<kbd>F3</kbd></kbd></p></pre> - - <p>In this second example, the user is told to pick a particular menu - item. The outer <code><a href="#kbd">kbd</a></code> element marks up a - block of input, with the inner <code><a href="#kbd">kbd</a></code> - elements representing each individual step of the input, and the <code><a - href="#samp">samp</a></code> elements inside them indicating that the - steps are input based on something being displayed by the system, in this - case menu labels:</p> - - <pre><p>To make George eat an apple, select - <kbd><kbd><samp>File</samp></kbd>|<kbd><samp>Eat Apple...</samp></kbd></kbd> -</p></pre> - </div> - - <h4 id=the-sup><span class=secno>3.12.17. </span>The <dfn - id=sup><code>sup</code></dfn> and <dfn id=sub><code>sub</code></dfn> - elements</h4> - - <p><a href="#strictly">Strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which these elements may be used: - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd><a href="#strictly">Strictly inline-level content</a>. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#sup">sup</a></code> element represents a superscript - and the <code><a href="#sub">sub</a></code> element represents a - subscript. - - <p>These elements must only be used to mark up typographical conventions - with specific meanings, not for typographical presentation for - presentation's sake. For example, it would be inappropriate for the - <code><a href="#sup">sup</a></code> and <code><a - href="#sub">sub</a></code> elements to be used in the name of the LaTeX - document preparation system. In general, authors should not use these - elements if the <em>absence</em> of those elements would not change the - meaning of the content. - - <p>When the <code><a href="#sub">sub</a></code> element is used inside a - <code><a href="#var">var</a></code> element, it represents the subscript - that identifies the variable in a family of variables. - - <div class=example> - <pre><p>The coordinate of the <var>i</var>th point is -(<var>x<sub><var>i</var></sub></var>, <var>y<sub><var>i</var></sub></var>). -For example, the 10th point has coordinate -(<var>x<sub>10</sub></var>, <var>y<sub>10</sub></var>).</p></pre> - </div> - - <p>In certain languages, superscripts are part of the typographical - conventions for some abbreviations. - - <div class=example> - <pre><p>The most beautiful women are -<span lang="fr"><abbr>M<sup>lle</sup></abbr> Gwendoline</span> and -<span lang="fr"><abbr>M<sup>me</sup></abbr> Denise</span>.</p></pre> - </div> - - <p>Mathematical expressions often use subscripts and superscripts. - <!--Authors are encouraged to use MathML for marking up mathematics, - but authors may opt to use <code>sub</code> and <code>sup</code> if - detailed mathematical markup is not desired. <a - href="#refsMathML">[MathML]</a>--></p> - <!-- XXX --> - - <div class=example> - <pre><var>E</var>=<var>m</var><var>c</var><sup>2</sup></pre> - - <pre>f(<var>x</var>, <var>n</var>) = log<sub>4</sub><var>x</var><sup><var>n</var></sup></pre> - </div> - - <h4 id=the-span><span class=secno>3.12.18. </span>The <dfn - id=span><code>span</code></dfn> element</h4> - - <p><a href="#strictly">Strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd>When used in an element whose content model is only <a - href="#strictly">strictly inline-level content</a>: only <a - href="#strictly">strictly inline-level content</a>. - - <dd>Otherwise: any <a href="#inline-level0">inline-level content</a>. - - <dt>Element-specific attributes: - - <dd>None, but the <code title=attr-title><a href="#title">title</a></code> - attribute has special semantics on this element when used with the - <code><a href="#dfn">dfn</a></code> element. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#span">span</a></code> element doesn't mean anything - on its own, but can be useful when used together with other attributes, - e.g. <code title=attr-class><a href="#class">class</a></code>, <code - title=attr-lang><a href="#lang">lang</a></code>, or <code - title=attr-dir><a href="#dir">dir</a></code>, or when used in conjunction - with the <code><a href="#dfn">dfn</a></code> element.</p> - <!-- XXX need examples --> - - <h4 id=the-i><span class=secno>3.12.19. </span>The <dfn - id=i><code>i</code></dfn> element</h4> - - <p><a href="#strictly">Strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd><a href="#strictly">Strictly inline-level content</a>. - - <dt>Element-specific attributes: - - <dd>None, but the <code title=attr-title><a href="#title">title</a></code> - attribute has special semantics on this element when used with the - <code><a href="#dfn">dfn</a></code> element. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#i">i</a></code> element represents a span of text in - an alternate voice or mood, or otherwise offset from the normal prose, - such as a taxonomic designation, a technical term, an idiomatic phrase - from another language, a thought, a ship name, or some other prose whose - typical typographic presentation is italicized. - - <p>Terms in languages different from the main text should be annotated with - <code title=attr-lang><a href="#lang">lang</a></code> attributes (<code - title=attr-xml-lang><a href="#xmllang">xml:lang</a></code> in XML). - - <div class=example> - <p>The examples below show uses of the <code><a href="#i">i</a></code> - element:</p> - - <pre><p>The <i>felis silvestris catus</i> is cute.</p> -<p>The <i>block-level elements</i> are defined above.</p> -<p>There is a certain <i lang="fr">je ne sais quoi</i> in the air.</p></pre> - - <p>In the following example, a dream sequence is marked up using <code><a - href="#i">i</a></code> elements.</p> - - <pre><p>Raymond tried to sleep.</p> -<p><i>The ship sailed away on Thursday</i>, he -dreamt. <i>The ship had many people aboard, including a beautiful -princess called Carey. He watched her, day-in, day-out, hoping she -would notice him, but she never did.</i></p> -<p><i>Finally one night he picked up the courage to speak with -her—</i></p> -<p>Raymond woke with a start as the fire alarm rang out.</p></pre> - </div> - - <p>The <code><a href="#i">i</a></code> element should be used as a last - resort when no other element is more appropriate. In particular, citations - should use the <code><a href="#cite2">cite</a></code> element, defining - instances of terms should use the <code><a href="#dfn">dfn</a></code> - element, stress emphasis should use the <code><a href="#em">em</a></code> - element, importance should be denoted with the <code><a - href="#strong">strong</a></code> element, quotes should be marked up with - the <code><a href="#q">q</a></code> element, and small print should use - the <code><a href="#small">small</a></code> element. - - <p class=note>Style sheets can be used to format <code><a - href="#i">i</a></code> elements, just like any other element can be - restyled. Thus, it is not the case that content in <code><a - href="#i">i</a></code> elements will necessarily be italicised. - - <h4 id=the-b><span class=secno>3.12.20. </span>The <dfn - id=b><code>b</code></dfn> element</h4> - - <p><a href="#strictly">Strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd><a href="#strictly">Strictly inline-level content</a>. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#b">b</a></code> element represents a span of text to - be stylistically offset from the normal prose without conveying any extra - importance, such as key words in a document abstract, product names in a - review, or other spans of text whose typical typographic presentation is - boldened. - - <div class=example> - <p>The following example shows a use of the <code><a - href="#b">b</a></code> element to highlight key words without marking - them up as important:</p> - - <pre><p>The <b>frobonitor</b> and <b>barbinator</b> components are fried.</p></pre> - - <p>The following would be <em>incorrect</em> usage:</p> - - <pre><p><b>WARNING!</b> Do not frob the barbinator!</p></pre> - - <p>In the previous example, the correct element to use would have been - <code><a href="#strong">strong</a></code>, not <code><a - href="#b">b</a></code>.</p> - - <p>In the following example, objects in a text adventure are highlighted - as being special by use of the <code><a href="#b">b</a></code> element.</p> - - <pre><p>You enter a small room. Your <b>sword</b> glows -brighter. A <b>rat</b> scurries past the corner wall.</p></pre> - </div> - - <p>The <code><a href="#b">b</a></code> element should be used as a last - resort when no other element is more appropriate. In particular, headers - should use the <code><a href="#h1">h1</a></code> to <code><a - href="#h6">h6</a></code> elements, stress emphasis should use the <code><a - href="#em">em</a></code> element, importance should be denoted with the - <code><a href="#strong">strong</a></code> element, and text marked or - highlighted should use the <code><a href="#m">m</a></code> element. - - <p class=note>Style sheets can be used to format <code><a - href="#b">b</a></code> elements, just like any other element can be - restyled. Thus, it is not the case that content in <code><a - href="#b">b</a></code> elements will necessarily be boldened. - - <h4 id=the-bdo><span class=secno>3.12.21. </span>The <dfn - id=bdo><code>bdo</code></dfn> element</h4> - - <p><a href="#strictly">Strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd><a href="#strictly">Strictly inline-level content</a>. - - <dt>Element-specific attributes: - - <dd>None, but the <code title=attr-dir><a href="#dir">dir</a></code> - global attribute is required on this element. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#bdo">bdo</a></code> element allows authors to - override the Unicode bidi algorithm by explicitly specifying a direction - override. <a href="#refsBIDI">[BIDI]</a> - - <p>Authors must specify the <code title=attr-dir><a - href="#dir">dir</a></code> attribute on this element, with the value - <code>ltr</code> to specify a left-to-right override and with the value - <code>rtl</code> to specify a right-to-left override. - - <p>If the element has the <code title=attr-dir><a - href="#dir">dir</a></code> attribute set to the exact value - <code>ltr</code>, then for the purposes of the bidi algorithm, the user - agent must act as if there was a U+202D LEFT-TO-RIGHT OVERRIDE character - at the start of the element, and a U+202C POP DIRECTIONAL FORMATTING at - the end of the element. - - <p>If the element has the <code title=attr-dir><a - href="#dir">dir</a></code> attribute set to the exact value - <code>rtl</code>, then for the purposes of the bidi algorithm, the user - agent must act as if there was a U+202E RIGHT-TO-LEFT OVERRIDE character - at the start of the element, and a U+202C POP DIRECTIONAL FORMATTING at - the end of the element. - - <p>The requirements on handling the <code><a href="#bdo">bdo</a></code> - element for the bidi algorithm may be implemented indirectly through the - style layer. For example, an HTML+CSS user agent should implement these - requirements by implementing the CSS <code>unicode-bidi</code> property. - <a href="#refsCSS21">[CSS21]</a></p> - <!-- XXX need examples --> - - <h3 id=edits><span class=secno>3.13. </span>Edits</h3> - - <p>The <code><a href="#ins">ins</a></code> and <code><a - href="#del">del</a></code> elements represent edits to the document. - - <h4 id=the-ins><span class=secno>3.13.1. </span>The <dfn - id=ins><code>ins</code></dfn> element</h4> - - <p><a href="#transparent0">Transparent</a> <a href="#block-level0" - title="block-level elements">block-level element</a>, and <a - href="#transparent0">transparent</a> <a href="#strictly">strictly - inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> is expected. - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd><a href="#transparent0">Transparent</a>. - - <dt>Element-specific attributes: - - <dd><code title=attr-mod-cite><a href="#cite3">cite</a></code> - - <dd><code title=attr-mod-datetime><a href="#datetime1">datetime</a></code> - - <dt>DOM interface: - - <dd>Uses the <code><a href="#htmlmodelement">HTMLModElement</a></code> - interface. - </dl> - - <p>The <code><a href="#ins">ins</a></code> element represents an addition - to the document. - - <p>The <code><a href="#ins">ins</a></code> element must be used only where - <a href="#block-level0">block-level elements</a> or <a - href="#strictly">strictly inline-level content</a> can be used. - - <p>An <code><a href="#ins">ins</a></code> element can only contain content - that would still be conformant if all elements with <a - href="#transparent0">transparent</a> content models were replaced by their - contents. - - <div class=example> - <p>The following would be syntactically legal:</p> - - <pre><aside> - <ins> - <p>...</p> - </ins> -</aside></pre> - - <p>As would this:</p> - - <pre><aside> - <ins> - <em>...</em> - </ins> -</aside></pre> - - <p>However, this last example would be illegal, as <code><a - href="#em">em</a></code> and <code><a href="#p">p</a></code> cannot both - be used inside an <code><a href="#aside">aside</a></code> element at the - same time:</p> - - <pre><aside> - <ins> - <p>...</p> - </ins> - <ins> - <em>...</em> - </ins> -</aside></pre> - </div> - - <h4 id=the-del><span class=secno>3.13.2. </span>The <dfn - id=del><code>del</code></dfn> element</h4> - - <p><a href="#block-level0" title="block-level elements">Block-level - element</a>, and <a href="#strictly">strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> is expected. - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd>When the element has a parent: same content model as the parent - element (without taking into account the other children of the parent - element). - - <dd>Otherwise: zero or more <a href="#block-level0">block-level - elements</a>, or <a href="#inline-level0">inline-level content</a> (but - not both). - - <dt>Element-specific attributes: - - <dd><code title=attr-mod-cite><a href="#cite3">cite</a></code> - - <dd><code title=attr-mod-datetime><a href="#datetime1">datetime</a></code> - - <dt>DOM interface: - - <dd>Uses the <code><a href="#htmlmodelement">HTMLModElement</a></code> - interface. - </dl> - - <p>The <code><a href="#del">del</a></code> element represents a removal - from the document. - - <p>The <code><a href="#del">del</a></code> element must only contain - content that would be allowed inside the parent element (regardless of - what the parent element actually contains). - - <div class=example> - <p>The following would be syntactically legal:</p> - - <pre><aside> - <del> - <p>...</p> - </del> - <ins> - <em>...</em> - </ins> -</aside></pre> - - <p>...even though the <code><a href="#p">p</a></code> and <code><a - href="#em">em</a></code> elements would never be allowed side by side in - the <code><a href="#aside">aside</a></code> element. This is allowed - because the <code><a href="#del">del</a></code> element represents - content that was removed, and it is quite possible that an edit could - cause an element to go from being an inline-level container to a - block-level container, or vice-versa.</p> - </div> - - <h4 id=attributes><span class=secno>3.13.3. </span>Attributes common to - <code><a href="#ins">ins</a></code> and <code><a - href="#del">del</a></code> elements</h4> - - <p>The <dfn id=cite3 title=attr-mod-cite><code>cite</code></dfn> attribute - may be used to specify a URI that explains the change. When that document - is long, for instance the minutes of a meeting, authors are encouraged to - include a fragment identifier pointing to the specific part of that - document that discusses the change. - - <p>If the <code title=attr-mod-cite><a href="#cite3">cite</a></code> - attribute is present, it must be a URI (or IRI) that explains the change. - User agents should allow users to follow such citation links. - - <p>The <dfn id=datetime1 - title=attr-mod-datetime><code>datetime</code></dfn> attribute may be used - to specify the time and date of the change. - - <p>If present, the <code title=attr-mod-datetime><a - href="#datetime1">datetime</a></code> attribute must be a <a - href="#valid5">valid datetime</a> value. - - <p>User agents must parse the <code title=attr-mod-datetime><a - href="#datetime1">datetime</a></code> attribute according to the <a - href="#datetime-parser">parse a string as a datetime value</a> algorithm. - If that doesn't return a time, then the modification has no associated - timestamp (the value is non-conforming; it is not a <a - href="#valid5">valid datetime</a>). Otherwise, the modification is marked - as having been made at the given datetime. User agents should use the - associated timezone information to determine which timezone to present the - given datetime in. - - <p>The <code><a href="#ins">ins</a></code> and <code><a - href="#del">del</a></code> elements must implement the <code><a - href="#htmlmodelement">HTMLModElement</a></code> interface: - - <pre - class=idl>interface <dfn id=htmlmodelement>HTMLModElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute DOMString <a href="#cite4" title=dom-mod-cite>cite</a>; - attribute DOMString <a href="#datetime2" title=dom-mod-datetime>dateTime</a>; -};</pre> - - <p>The <dfn id=cite4 title=dom-mod-cite><code>cite</code></dfn> DOM - attribute must reflect the element's ><code title=attr-mod-cite><a - href="#cite3">cite</a></code> content attribute. The <dfn id=datetime2 - title=dom-mod-datetime><code>dateTime</code></dfn> DOM attribute must - reflect the element's <code title="">datetime</code> content attribute. - - <h3 id=embedded><span class=secno>3.14. </span>Embedded content</h3> - - <h4 id=the-figure><span class=secno>3.14.1. </span>The <dfn - id=figure><code>figure</code></dfn> element</h4> - - <p><a href="#block-level0" title="block-level elements">Block-level - element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> are expected. - - <dt>Content model: - - <dd>In any order, exactly one <code><a href="#legend">legend</a></code> - element, and exactly one <a href="#embedded0">embedded content</a> - element. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#figure">figure</a></code> element represents a <a - href="#paragraph">paragraph</a> consisting of embedded content and a - caption. - - <p>The first <a href="#embedded0">embedded content</a> element child of the - <code><a href="#figure">figure</a></code> element, if any, is the - paragraph's content. - - <p>The first <code><a href="#legend">legend</a></code> element child of the - element, if any, represents the caption of the embedded content. If there - is no child <code><a href="#legend">legend</a></code> element, then there - is no caption. - - <p>If the embedded content cannot be used, then, for the purposes of - establishing what the <code><a href="#figure">figure</a></code> element - represents: - - <dl class=switch> - <dt>If the embedded content's <a href="#fallback">fallback content</a> is - a single <a href="#embedded0">embedded content</a> element - - <dd>The <code><a href="#figure">figure</a></code> element must be treated - as if that <a href="#embedded0">embedded content</a> element was the - <code><a href="#figure">figure</a></code> element's embedded content. (If - that embedded content can't be used either, then this processing must be - done again, with the new embedded content's <a href="#fallback">fallback - content</a>.) - - <dt>If the embedded content's fallback is nothing - - <dd>The entire <code><a href="#figure">figure</a></code> element - (including the caption, if any) must be ignored. - - <dt>If the embedded content's fallback is <a - href="#inline-level0">inline-level content</a> - - <dd>The entire <code><a href="#figure">figure</a></code> element - (including the caption, if any) must be treated as being a single <a - href="#paragraph">paragraph</a> with that <a - href="#inline-level0">inline-level content</a> as its content. - - <dt>Otherwise - - <dd>The entire <code><a href="#figure">figure</a></code> element - (including the caption, if any) must be treated as being replaced by that - fallback content. - </dl> - - <h4 id=the-img><span class=secno>3.14.2. </span>The <dfn - id=img><code>img</code></dfn> element</h4> - - <p><a href="#strictly" title="Strictly inline-level content">Strictly - inline-level</a> <a href="#embedded0">embedded content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>As the only <a href="#embedded0">embedded content</a> child of a - <code><a href="#figure">figure</a></code> element. - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd>Empty. - - <dt>Element-specific attributes: - - <dd><code title=attr-img-alt><a href="#alt">alt</a></code> (required) - - <dd><code title=attr-img-src><a href="#src">src</a></code> (required) - - <dd><code title=attr-hyperlink-usemap><a href="#usemap1">usemap</a></code> - - <dd><code title=attr-img-ismap><a href="#ismap">ismap</a></code> (but only - if one of the ancestor elements is an <code><a href="#a">a</a></code> - element) - - <dd><code title=attr-img-height><a href="#height">height</a></code> - - <dd><code title=attr-img-width><a href="#width">width</a></code> - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmlimageelement>HTMLImageElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute DOMString <a href="#alt0" title=dom-img-alt>alt</a>; - attribute DOMString <a href="#src0" title=dom-img-src>src</a>; - attribute DOMString <a href="#usemap" title=dom-img-useMap>useMap</a>; - attribute boolean <a href="#ismap0" title=dom-img-isMap>isMap</a>; - attribute long <a href="#height0" title=dom-img-height>height</a>; - attribute long <a href="#width0" title=dom-img-width>width</a>; - readonly attribute boolean <a href="#complete" title=dom-img-complete>complete</a>; -};</pre> - - <p class=note>An instance of <code><a - href="#htmlimageelement">HTMLImageElement</a></code> can be obtained - using the <code title=dom-image><a href="#image0">Image</a></code> - constructor.</p> - </dl> - - <p>The <code><a href="#img">img</a></code> element represents a piece of - text with an alternate graphical representation. The text is given by the - <dfn id=alt title=attr-img-alt><code>alt</code></dfn> attribute, which - must be present, and the URI to the graphical representation of that text - is given in the <dfn id=src title=attr-img-src><code>src</code></dfn> - attribute, which must also be present. - - <p>The image given by the <code title=attr-img-src><a - href="#src">src</a></code> attribute is the embedded content, and the - value of the <code title=attr-img-alt><a href="#alt">alt</a></code> - attribute is the <code><a href="#img">img</a></code> element's <a - href="#fallback">fallback content</a>. - - <p>When the <code title=attr-img-alt><a href="#alt">alt</a></code> - attribute's value is the empty string, the image supplements the - surrounding content. In such cases, the image could be omitted without - affecting the meaning of the document. - - <p>If the <code title=attr-img-alt><a href="#alt">alt</a></code> attribute - is omitted, user agents must treat the element as if it had an <code - title=attr-img-alt><a href="#alt">alt</a></code> attribute set to the - empty string. - - <p>The <code title=attr-img-alt><a href="#alt">alt</a></code> attribute - does not represent advisory information. User agents must not present the - contents of the <code title=attr-img-alt><a href="#alt">alt</a></code> - attribute in the same way as content of the <code title=attr-title><a - href="#title">title</a></code> attribute. - - <p class=big-issue>Guidelines on writing "alt" text here.</p> - <!-- http://www.cs.tut.fi/~jkorpela/html/alt.html --> - - <p>The <code title=attr-img-src><a href="#src">src</a></code> attribute - must contain a URI (or IRI). If the <code title=attr-img-src><a - href="#src">src</a></code> attribute is omitted, there is no alternative - image representation. - - <p>When the <code title=attr-img-src><a href="#src">src</a></code> - attribute is set, the user agent must immediately begin to download the - specified - resource<!-- XXX xref what fetching means, how to resolve URIs in - attributes (including those not in the DOM) -->, - unless the user agent cannot support images, or its support for images has - been disabled. - - <p>The download of the image must <a href="#delays">delay the <code - title=event-load>load</code> event</a>. - - <p>Once the download has completed, if the image is a valid image, the user - agent must <a href="#firing4">fire a <code title=event-load>load</code> - event</a> on the <code><a href="#img">img</a></code> element. If the - download fails or it completes but the image is not a valid or supported - image, the user agent must <a href="#firing5">fire an <code - title=event-error>error</code> event</a> on the <code><a - href="#img">img</a></code> element. - - <p>The remote server's response metadata (e.g. an HTTP 404 status code, or - <a href="#content-type8" title=Content-Type>associated Content-Type - headers</a>) must be ignored when determining whether the resource - obtained is a valid image or not. - - <p class=note>This allows servers to return images with error responses. - - <p>User agents must not support non-image resources with the <code><a - href="#img">img</a></code> element. - - <p>The <code title=attr-hyperlink-usemap><a - href="#usemap1">usemap</a></code> attribute, if present, can indicate that - the image has an associated <a href="#image">image map</a>. - - <p>The <dfn id=ismap title=attr-img-ismap><code>ismap</code></dfn> - attribute, when used on an element that is a descendant of an <code><a - href="#a">a</a></code> element with an <code title=attr-hyperlink-href><a - href="#href6">href</a></code> attribute, indicates by its presence that - the element provides access to a server-side image map. This affects how - events are handled on the corresponding <code><a href="#a">a</a></code> - element. - - <p>The <code title=attr-img-ismap><a href="#ismap">ismap</a></code> - attribute is a <a href="#boolean0">boolean attribute</a>. The attribute - must not be specified on an element that does not have an ancestor - <code><a href="#a">a</a></code> element. - - <p>The <dfn id=height title=attr-img-height><code>height</code></dfn> and - <dfn id=width title=attr-img-width><code>width</code></dfn> attributes - give the preferred rendered dimensions of the image if the image is to be - shown in a visual medium. - - <p class=big-issue>Should we require the dimensions to be correct? Should - we disallow percentages? - - <p>The values of the <code title=attr-img-height><a - href="#height">height</a></code> and <code title=attr-img-width><a - href="#width">width</a></code> attributes must be either <a href="#valid" - title="valid non-negative integer">valid non-negative integers</a> or <a - href="#valid3" title="valid non-negative percentage">valid non-negative - percentages</a>. - - <p>To parse the attributes, user agents must use the <a - href="#rules2">rules for parsing dimension values</a>. This will return - either an integer length, a percentage value, or nothing. When one of - these attributes has no value, it must be - <span>ignored</span><!-- XXX xref -->. - - <p>The user agent requirements for processing the values obtained from - parsing these attributes are described <a href="#sizing" title="sizing of - embedded content">in the rendering section</a><!-- XXX xref - -->. - - <p>The <code><a href="#img">img</a></code> element must be empty.</p> - <!-- contents - should be ignored for rendering but not for semantics, - e.g. <script>, <input>, etc. --> - - <p>The DOM attributes <dfn id=alt0 - title=dom-img-alt><code>alt</code></dfn>, <dfn id=src0 - title=dom-img-src><code>src</code></dfn>, <dfn id=usemap - title=dom-img-useMap><code>useMap</code></dfn>, and <dfn id=ismap0 - title=dom-img-isMap><code>isMap</code></dfn> each must <a - href="#reflect">reflect</a> the respective content attributes of the same - name. - - <p>The DOM attributes <dfn id=height0 - title=dom-img-height><code>height</code></dfn> and <dfn id=width0 - title=dom-img-width><code>width</code></dfn> must return the rendered - height and width of the image, in CSS pixels, if the image is being - rendered, and is being rendered to a visual medium, or 0 otherwise. <a - href="#refsCSS21">[CSS21]</a> - - <p>The DOM attribute <dfn id=complete - title=dom-img-complete><code>complete</code></dfn> must return true if the - user agent has downloaded the image specified in the <code - title=attr-img-src><a href="#src">src</a></code> attribute, and it is a - valid image, and false otherwise. - - <h4 id=the-iframe><span class=secno>3.14.3. </span>The <dfn - id=iframe><code>iframe</code></dfn> element</h4> - - <p><a href="#strictly" title="Strictly inline-level content">Strictly - inline-level</a> <a href="#embedded0">embedded content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>As the only <a href="#embedded0">embedded content</a> child of a - <code><a href="#figure">figure</a></code> element. - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd>Text (for details, see prose). - - <dt>Element-specific attributes: - - <dd><code title=attr-iframe-src><a href="#src1">src</a></code> - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmliframeelement>HTMLIFrameElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute DOMString <a href="#src2" title=dom-iframe-src>src</a>;<!-- - readonly attribute Document <span title="dom-iframe-contentDocument">contentDocument</span>; - readonly attribute <span>Window</span> <span title="dom-iframe-contentWindow">contentWindow</span>;--> -};</pre> - - <p>Objects implementing the <code><a - href="#htmliframeelement">HTMLIFrameElement</a></code> interface must - also implement the <code>EmbeddingElement</code> interface defined in - the Window Object specification. <a href="#refsWINDOW">[WINDOW]</a></p> - <!-- XXX --> - </dl> - - <p>The <code><a href="#iframe">iframe</a></code> element introduces a new - nested <a href="#browsing0">browsing context</a>. - - <p>The <dfn id=src1 title=attr-iframe-src><code>src</code></dfn> attribute, - if present, must be a URI (or IRI) to a page that the nested <a - href="#browsing0">browsing context</a> is to contain. When the browsing - context is created, if the attribute is present, the user agent must <a - href="#navigate">navigate</a> this browsing context to the given URI, with - <a href="#replacement">replacement enabled</a>. If the user <a - href="#navigate" title=navigate>navigates</a> away from this page, the - <code><a href="#iframe">iframe</a></code>'s corresponding <code><a - href="#window">Window</a></code> object will reference new - <code>Document</code> objects, but the <code title=attr-iframe-src><a - href="#src1">src</a></code> attribute will not change. - - <p>Whenever the <code title=attr-iframe-src><a href="#src1">src</a></code> - attribute is set, the nested <a href="#browsing0">browsing context</a> - must be <a href="#navigate" title=navigate>navigated</a> to the given URI. - - <p>If the <code title=attr-iframe-src><a href="#src1">src</a></code> - attribute is not set when the element is created, the browsing context - will remain at the initial <code>about:blank</code> page. - - <p>When content loads in an <code><a href="#iframe">iframe</a></code>, - after any <code title=event-load><a href="#load0">load</a></code> events - are fired within the content itself, the user agent must <a - href="#firing4">fire a <code title=event-load>load</code> event</a> at the - <code><a href="#iframe">iframe</a></code> element. When content fails to - load (e.g. due to a network error), then the user agent must <a - href="#firing5">fire an <code title=event-error>error</code> event</a> at - the element instead. - - <p>When there is an active parser in the <code><a - href="#iframe">iframe</a></code>, and when anything in the <code><a - href="#iframe">iframe</a></code> that is <a href="#delays" title="delay - the load event">delaying the <code title=event-load>load</code> event</a> - in the <code><a href="#iframe">iframe</a></code>'s <a - href="#browsing0">browsing context</a>, the <code><a - href="#iframe">iframe</a></code> must <a href="#delays">delay the <code - title=event-load>load</code> event</a>. - - <p class=note>If, during the handling of the <code title=event-load><a - href="#load0">load</a></code> event, the <a href="#browsing0">browsing - context</a> in the <code><a href="#iframe">iframe</a></code> is again <a - href="#navigate" title=navigate>navigated</a>, that will further <a - href="#delays">delay the <code title=event-load>load</code> event</a>. - - <p>An <code><a href="#iframe">iframe</a></code> element never has <a - href="#fallback">fallback content</a>, as it will always create a nested - <a href="#browsing0">browsing context</a>, regardless of whether the - specified initial contents are successfully used. - - <p><code><a href="#iframe">iframe</a></code> elements may contain any text. - <code><a href="#iframe">iframe</a></code> elements must not contain - element nodes. Descendants of <code><a href="#iframe">iframe</a></code> - elements represent nothing. (In legacy user agents that do not support - <code><a href="#iframe">iframe</a></code> elements, the contents would be - parsed as markup that could act as fallback content.) - - <p class=big-issue>restrictions for what that text must be? - - <p class=note>The <a href="#html-0">HTML parser</a> treats markup inside - <code><a href="#iframe">iframe</a></code> elements as text. - - <p>The DOM attribute <dfn id=src2 - title=dom-iframe-src><code>src</code></dfn> must <a - href="#reflect">reflect</a> the content attribute of the same name. - - <h4 id=the-embed><span class=secno>3.14.4. </span>The <dfn - id=embed><code>embed</code></dfn> element</h4> - - <p><a href="#strictly" title="Strictly inline-level content">Strictly - inline-level</a> <a href="#embedded0">embedded content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>As the only <a href="#embedded0">embedded content</a> child of a - <code><a href="#figure">figure</a></code> element. - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd>Empty. - - <dt>Element-specific attributes: - - <dd><code title=attr-embed-src><a href="#src3">src</a></code> (required) - - <dd><code title=attr-embed-type><a href="#type4">type</a></code> - - <dd><code title=attr-embed-height>height</code> - - <dd><code title=attr-embed-width>width</code> - - <dd>Any other attribute that has no namespace (see prose). - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmlembedelement>HTMLEmbedElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute DOMString <a href="#src4" title=dom-embed-src>src</a>; - attribute DOMString <a href="#type5" title=dom-embed-type>type</a>; - attribute long <a href="#height1" title=dom-embed-height>height</a>; - attribute long <a href="#width1" title=dom-embed-width>width</a>; -};</pre> - - <p>Depending on the type of content instantiated by the <code><a - href="#embed">embed</a></code> element, the node may also support other - interfaces.</p> - </dl> - - <p>The <code><a href="#embed">embed</a></code> element represents an - integration point for an external (typically non-HTML) application or - interactive content. - - <p>The <dfn id=src3 title=attr-embed-src><code>src</code></dfn> attribute - gives the address of the resource being embedded. The attribute must be - present and contain a URI (or IRI). - - <p>If the <code title=attr-embed-src><a href="#src3">src</a></code> - attribute is missing, then the <code><a href="#embed">embed</a></code> - element must be ignored. - - <p>When the <code title=attr-embed-src><a href="#src3">src</a></code> - attribute is set, user agents are expected to find an appropriate handler - for the specified resource, based on the <a href="#type-of" - title=concept-embed-type>content's type</a>, and hand that handler the - content of the resource. If the handler supports a scriptable interface, - the <code><a href="#htmlembedelement">HTMLEmbedElement</a></code> object - representing the element should expose that interfaces. - - <p>The download of the resource must <a href="#delays">delay the <code - title=event-load>load</code> event</a>. - - <p>The user agent should pass the names and values of all the attributes of - the <code><a href="#embed">embed</a></code> element that have no namespace - to the handler used. Any (namespace-less) attribute may be specified on - the <code><a href="#embed">embed</a></code> element.</p> - <!-- duplicates what's in <object> section below --> - - <p class=note>This specification does not define a mechanism for - interacting with third-party handlers, as it is expected to be - user-agent-specific. Some UAs might opt to support a plugin mechanism such - as the Netscape Plugin API; others may use remote content convertors or - have built-in support for certain types. <a href="#refsNPAPI">[NPAPI]</a> - - <p>The <code><a href="#embed">embed</a></code> element has no <a - href="#fallback">fallback content</a>. If the user agent can't display the - specified resource, e.g. because the given type is not supported, then the - user agent must use a default handler for the content. (This default could - be as simple as saying "Unsupported Format", of course.) - - <p>The <dfn id=type4 title=attr-embed-type><code>type</code></dfn> - attribute, if present, gives the MIME type of the linked resource. The - value must be a valid MIME type, optionally with parameters. <a - href="#refsRFC2046">[RFC2046]</a> - - <p>The <dfn id=type-of title=concept-embed-type>type of the content</dfn> - being embedded is defined as follows: - - <ol> - <li>If the element has a <code title=attr-embed-type><a - href="#type4">type</a></code> attribute, then the value of the <code - title=attr-embed-type><a href="#type4">type</a></code> attribute is the - <span>content's type</span>. - - <li>Otherwise, if the specified resource has <a href="#content-type8" - title=Content-Type>explicit Content-Type metadata</a>, then that is the - <span>content's type</span>. - - <li>Otherwise, the content has no type and there can be no appropriate - handler for it. - </ol> - - <p class=big-issue>Should we instead say that the content-sniffing that - we're going to define for top-level browsing contexts should apply here? - - <p class=big-issue>Should we require the type attribute to match the server - information? - - <p class=big-issue>We should say that 404s, etc, don't affect whether the - resource is used or not. Not sure how to say it here though. - - <p>Browsers should take extreme care when interacting with external content - intended for third-party renderers. When third-party software is run with - the same privileges as the user agent itself, vulnerabilities in the - third-party software become as dangerous as those in the user agent. - - <p class=big-issue>height/width - - <p>The DOM attributes <dfn id=src4 - title=dom-embed-src><code>src</code></dfn> and <dfn id=type5 - title=dom-embed-type><code>type</code></dfn> each must <a - href="#reflect">reflect</a> the respective content attributes of the same - name. - - <p>The DOM attributes <dfn id=height1 - title=dom-embed-height><code>height</code></dfn> and <dfn id=width1 - title=dom-embed-width><code>width</code></dfn> must return the rendered - height and width of the image, in CSS pixels, if the image is being - rendered, and is being rendered to a visual medium, or 0 otherwise. <a - href="#refsCSS21">[CSS21]</a> - - <h4 id=the-object><span class=secno>3.14.5. </span>The <dfn - id=object><code>object</code></dfn> element</h4> - - <p><a href="#strictly" title="Strictly inline-level content">Strictly - inline-level</a> <a href="#embedded0">embedded content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>As the only <a href="#embedded0">embedded content</a> child of a - <code><a href="#figure">figure</a></code> element. - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd>When used as the child of a <code><a href="#figure">figure</a></code> - element, or, when used as a <em><code><a href="#figure">figure</a></code> - fallback <code><a href="#object">object</a></code></em>: Zero or more - <code><a href="#param">param</a></code> elements, followed by either zero - or more <a href="#block-level0">block-level elements</a> or a single - <code><a href="#object">object</a></code> element, which is then - considered to be a <em><code><a href="#figure">figure</a></code> fallback - <code><a href="#object">object</a></code></em>. - - <dd>Otherwise: Zero or more <code><a href="#param">param</a></code> - elements, followed by <a href="#inline-level0">inline-level content</a>. - - <dt>Element-specific attributes: - - <dd><code title=attr-object-data><a href="#data">data</a></code> (required - if <code title=attr-object-type><a href="#type6">type</a></code> is not - given) - - <dd><code title=attr-object-type><a href="#type6">type</a></code> - (required if <code title=attr-object-data><a href="#data">data</a></code> - is not given) - - <dd><code title=attr-hyperlink-usemap><a href="#usemap1">usemap</a></code> - - <dd><code title=attr-object-height>height</code> - - <dd><code title=attr-object-width>width</code> - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmlobjectelement>HTMLObjectElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute DOMString <a href="#data0" title=dom-object-data>data</a>; - attribute DOMString <a href="#type7" title=dom-object-type>type</a>; - attribute DOMString <a href="#usemap0" title=dom-object-useMap>useMap</a>; - attribute long <a href="#height2" title=dom-object-height>height</a>; - attribute long <a href="#width2" title=dom-object-width>width</a>;<!-- - readonly attribute Document <span title="dom-object-contentDocument">contentDocument</span>; - readonly attribute <span>Window</span> <span title="dom-object-contentWindow">contentWindow</span>;--> -};</pre> - - <p>Objects implementing the <code><a - href="#htmlobjectelement">HTMLObjectElement</a></code> interface must - also implement the <code>EmbeddingElement</code> interface defined in - the Window Object specification. <a href="#refsWINDOW">[WINDOW]</a></p> - - <p>Depending on the type of content instantiated by the <code><a - href="#object">object</a></code> element, the node may also support - other interfaces.</p> - </dl> - - <p class=big-issue>Shouldn't allow inline-level content to be the content - model when the parent's content model is strictly inline only. - - <p>The <code><a href="#object">object</a></code> element can represent an - external resource, which, depending on the type of the resource, will - either be treated as an image, as a nested <a href="#browsing0">browsing - context</a>, or as an external resource to be processed by a third-party - software package. - - <p>The <dfn id=data title=attr-object-data><code>data</code></dfn> - attribute, if present, specifies the address of the resource. If present, - the attribute must be a URI (or IRI). - - <p>The <dfn id=type6 title=attr-object-type><code>type</code></dfn> - attribute, if present, specifies the type of the resource. If present, the - attribute must be a valid MIME type, optionally with parameters. <a - href="#refsRFC2046">[RFC2046]</a> - - <p>One or both of the <code title=attr-object-data><a - href="#data">data</a></code> and <code title=attr-object-type><a - href="#type6">type</a></code> attributes must be present. - - <p>Whenever the <code title=attr-object-data><a - href="#data">data</a></code> attribute changes, or, if the <code - title=attr-object-data><a href="#data">data</a></code> attribute is not - present, whenever the <code title=attr-object-type><a - href="#type6">type</a></code> attribute changes, the user agent must - follow the following steps to determine what the <code><a - href="#object">object</a></code> element represents: - - <ol> - <li> - <p>If the <code title=attr-object-data><a href="#data">data</a></code> - attribute is present, then:</p> - - <ol> - <li> - <p>Begin a load for the resource.</p> - <!-- XXX define that - --><!-- XXX xref --> - <p>The download of the resource must <a href="#delays">delay the <code - title=event-load>load</code> event</a>.</p> - - <li> - <p>If the resource is not yet available (e.g. because the resource was - not available in the cache, so that loading the resource required - making a request over the network), then jump to step 3 in the overall - set of steps (fallback). When the resource becomes available, or if - the load fails, restart this algorithm from this step. Resources can - load incrementally; user agents may opt to consider a resource - "available" whenever enough data has been obtained to begin processing - the resource. - - <li> - <p>If the load failed (e.g. DNS error), <a href="#firing5">fire an - <code title=event-error>error</code> event</a> at the element, then - jump to step 3 in the overall set of steps (fallback). - - <li> - <p>Determine the <em>resource type</em>, as follows:</p> - - <p class=big-issue>This says to trust the type. Should we instead use - the same mechanism as for browsing contexts?</p> - - <dl class=switch> - <dt>If the resource has <a href="#content-type8" - title=Content-Type>associated Content-Type metadata</a> - - <dd>The type is the type specified in <a href="#content-type8" - title=Content-Type>the resource's Content-Type metadata</a>. - - <dt>Otherwise, if the <code title=attr-object-type><a - href="#type6">type</a></code> attribute is present - - <dd>The type is the type specified in the <code - title=attr-object-type><a href="#type6">type</a></code> attribute. - - <dt>Otherwise, there is no explicit type information - - <dd>The type is the <span title="sniffed type of a resource">sniffed - type of the resource</span>. - </dl> - - <li> - <p>Handle the content as given by the first of the following cases that - matches:</p> - - <dl class=switch> - <dt>If the resource requires a special handler (e.g. a plugin) - - <dd> - <p>The user agent should find an appropriate handler for the - specified resource, based on the <em>resource type</em> found in the - previous step, and pass the content of the resource to that handler. - If the handler supports a scriptable interface, the <code><a - href="#htmlobjectelement">HTMLObjectElement</a></code> object - representing the element should expose that interface. The handler - is not a nested <a href="#browsing0">browsing context</a>. If no - appropriate handler can be found, then jump to step 3 in the overall - set of steps (fallback).</p> - - <p>The user agent should pass the names and values of all the <span - title=concept-param-parameter>parameters</span> given by <code><a - href="#param">param</a></code> elements that are children of the - <code><a href="#object">object</a></code> element to the handler - used.</p> - <!-- duplicates what's in <embed> section above --> - <p class=note>This specification does not define a mechanism for - interacting with third-party handlers, as it is expected to be - user-agent-specific. Some UAs might opt to support a plugin - mechanism such as the Netscape Plugin API; others may use remote - content convertors or have built-in support for certain types. <a - href="#refsNPAPI">[NPAPI]</a></p> - - <p class=big-issue>this doesn't completely duplicate the navigation - section, since it handles <param>, etc, but surely some work - should be done to work with it</p> - - <dt>If the type of the resource is an <span>XML MIME - type</span><!-- XXX xref --> - - <dt>If the type of the resource is HTML - - <dt>If the type of the resource does not start with - "<code>image/</code>" - - <dd> - <p>The <code><a href="#object">object</a></code> element must be - associated with a nested <a href="#browsing0">browsing context</a>, - if it does not already have one. The element's nested <a - href="#browsing0">browsing context</a> must then be <a - href="#navigate" title=navigate>navigated</a> to the given resource, - with <a href="#replacement">replacement enabled</a>. (The <code - title=attr-object-data><a href="#data">data</a></code> attribute of - the <code><a href="#object">object</a></code> element doesn't get - updated if the browsing context gets further navigated to other - locations.)</p> - - <p class=big-issue>navigation might end up treating it as something - else, because it can do sniffing. how should we handle that?</p> - - <dt>If the resource is a supported image format, and support for - images has not been disabled - - <dd> - <p>The <code><a href="#object">object</a></code> element represents - the specified image. The image is not a nested <a - href="#browsing0">browsing context</a>.</p> - - <p class=big-issue>shouldn't we use the image-sniffing stuff here?</p> - - <dt>Otherwise - - <dd> - <p>The <code><a href="#object">object</a></code> element represents - the specified image, but the image cannot be shown. Jump to step 3 - below in the overall set of steps (fallback).</p> - </dl> - - <li> - <p>The element's contents are not part of what the <code><a - href="#object">object</a></code> element represents.</p> - - <li> - <p>Once the resource is completely loaded, <a href="#firing4">fire a - <code title=event-load>load</code> event</a> at the element. - </li> - <!-- XXX ordering of events (like with iframe) - --> - </ol> - - <li> - <p>If the <code title=attr-object-data><a href="#data">data</a></code> - attribute is absent but the <code title=attr-object-type><a - href="#type6">type</a></code> attribute is present, and if the user - agent can find a handler suitable according to the value of the <code - title=attr-object-type><a href="#type6">type</a></code> attribute, then - that handler should be used. If the handler supports a scriptable - interface, the <code><a - href="#htmlobjectelement">HTMLObjectElement</a></code> object - representing the element should expose that interface. The handler is - not a nested <a href="#browsing0">browsing context</a>. If no suitable - handler can be found, jump to the next step (fallback). - - <li> - <p>(Fallback.) The <code><a href="#object">object</a></code> element - doesn't represent anything except what the element's contents represent, - ignoring any leading <code><a href="#param">param</a></code> element - children. This is the element's <a href="#fallback">fallback - content</a>. - </ol> - - <p>In the absence of other factors (such as style sheets), user agents must - show the user what the <code><a href="#object">object</a></code> element - represents. Thus, the contents of <code><a - href="#object">object</a></code> elements act as <a - href="#fallback">fallback content</a>, to be used only when referenced - resources can't be shown (e.g. because it returned a 404 error). This - allows multiple <code><a href="#object">object</a></code> elements to be - nested inside each other, targeting multiple user agents with different - capabilities, with the user agent picking the best one it supports. - - <p>The <code title=attr-hyperlink-usemap><a - href="#usemap1">usemap</a></code> attribute, if present while the <code><a - href="#object">object</a></code> element represents an image, can indicate - that the object has an associated <a href="#image">image map</a>. The - attribute must be ignored if the <code><a href="#object">object</a></code> - element doesn't represent an image. - - <p class=big-issue>height/width - - <p>The DOM attributes <dfn id=data0 - title=dom-object-data><code>data</code></dfn>, <dfn id=type7 - title=dom-object-type><code>type</code></dfn>, <dfn id=usemap0 - title=dom-object-useMap><code>useMap</code></dfn>, <dfn id=height2 - title=dom-object-height><code>height</code></dfn>, and <dfn id=width2 - title=dom-object-width><code>width</code></dfn> each must <a - href="#reflect">reflect</a> the respective content attributes of the same - name. - - <h4 id=the-param><span class=secno>3.14.6. </span>The <dfn - id=param><code>param</code></dfn> element</h4> - <!-- no type --> - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>As a child of an <code><a href="#object">object</a></code> element, - before any content other than <code><a href="#param">param</a></code> - elements. - - <dt>Content model: - - <dd>Empty. - - <dt>Element-specific attributes: - - <dd><code title=attr-param-name><a href="#name1">name</a></code> - (required) - - <dd><code title=attr-param-value><a href="#value5">value</a></code> - (required) - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmlparamelement>HTMLParamElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute DOMString <a href="#name2" title=dom-param-name>name</a>; - attribute DOMString <a href="#value6" title=dom-param-value>value</a>; -};</pre> - </dl> - - <p>The <code><a href="#param">param</a></code> element defines parameters - for handlers invoked by <code><a href="#object">object</a></code> - elements. - - <p>The <dfn id=name1 title=attr-param-name><code>name</code></dfn> - attribute gives the name of the parameter. - - <p>The <dfn id=value5 title=attr-param-value><code>value</code></dfn> - attribute gives the value of the parameter. - - <p>Both attributes must be present. They may have any value. - - <p>If both attributes are present, and if the parent element of the - <code><a href="#param">param</a></code> is an <code><a - href="#object">object</a></code> element, then the element defines a <dfn - id=parameter title=concept-param-parameters>parameter</dfn> with the given - name/value pair. - - <p>The DOM attributes <dfn id=name2 - title=dom-param-name><code>name</code></dfn> and <dfn id=value6 - title=dom-param-value><code>value</code></dfn> must both <a - href="#reflect">reflect</a> the respective content attributes of the same - name. - - <h4 id=video><span class=secno>3.14.7. </span>The <dfn - id=video1><code>video</code></dfn> element</h4> - - <p><a href="#semi-transparent">Semi-transparent</a> <a href="#strictly" - title="Strictly inline-level content">strictly inline-level</a> <a - href="#embedded0">embedded content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>As the only <a href="#embedded0">embedded content</a> child of a - <code><a href="#figure">figure</a></code> element. - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd>If the element has a <code title=attr-media-src><a - href="#src5">src</a></code> attribute: <a - href="#transparent0">transparent</a>. - - <dd>If the element does not have a <code title=attr-media-src><a - href="#src5">src</a></code> attribute: one or more <code><a - href="#source">source</a></code> elements, then, <a - href="#transparent0">transparent</a>. - - <dt>Element-specific attributes: - - <dd><code title=attr-media-src><a href="#src5">src</a></code> - - <dd><code title=attr-media-autoplay><a - href="#autoplay">autoplay</a></code> - - <dd><code title=attr-media-start><a href="#start2">start</a></code> - - <dd><code title=attr-media-loopstart><a - href="#loopstart">loopstart</a></code> - - <dd><code title=attr-media-loopend><a href="#loopend">loopend</a></code> - - <dd><code title=attr-media-end><a href="#end">end</a></code> - - <dd><code title=attr-media-loopcount><a - href="#loopcount">loopcount</a></code> - - <dd><code title=attr-media-controls><a - href="#controls">controls</a></code> - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmlvideoelement>HTMLVideoElement</dfn> : <a href="#htmlmediaelement">HTMLMediaElement</a> { - readonly attribute unsigned long <a href="#videowidth" title=dom-video-videoWidth>videoWidth</a>; - readonly attribute unsigned long <a href="#videoheight" title=dom-video-videoHeight>videoHeight</a>; -};</pre> - </dl> - <!-- XXX request: changing the playback aspect ratio --> - <!-- XXX request: applying CSS filters --> - - <p>A <code><a href="#video1">video</a></code> element represents a video or - movie. - - <p>Content may be provided inside the <code><a - href="#video1">video</a></code> element so that older Web browsers, which - do not support <code><a href="#video1">video</a></code>, can display text - to the user informing them of how to access the video contents. User - agents should not show this fallback content to the user. - - <p>The <code><a href="#video1">video</a></code> element is a <a - href="#media5">media element</a> whose <a href="#media7">media data</a> is - ostensibly video data, possibly with associated audio data. - - <p>The <code title=attr-media-src><a href="#src5">src</a></code>, <code - title=attr-media-autoplay><a href="#autoplay">autoplay</a></code>, <code - title=attr-media-start><a href="#start2">start</a></code>, <code - title=attr-media-loopstart><a href="#loopstart">loopstart</a></code>, - <code title=attr-media-loopend><a href="#loopend">loopend</a></code>, - <code title=attr-media-end><a href="#end">end</a></code>, <code - title=attr-media-loopcount><a href="#loopcount">loopcount</a></code>, and - <code title=attr-media-controls><a href="#controls">controls</a></code> - attributes are <a href="#media6" title="media element attributes">the - attributes common to all media elements</a>. - - <p>The <dfn id=videowidth - title=dom-video-videoWidth><code>videoWidth</code></dfn> DOM attribute - must return the native width of the video in CSS pixels. The <dfn - id=videoheight title=dom-video-videoHeight><code>videoHeight</code></dfn> - DOM attribute must return the native height of the video in CSS pixels. In - the absence of resolution information, user agents may assume that one - pixel in the video corresponds to one CSS pixel. If no video data is - available, then the attributes must return 0. - - <p>When no video data is available (the element's <code - title=dom-media-networkState><a - href="#networkstate">networkState</a></code> attribute is either <code - title=dom-media-EMPTY><a href="#empty">EMPTY</a></code>, <code - title=dom-media-LOADING><a href="#loading0">LOADING</a></code>, or <code - title=dom-media-LOADED_METADATA><a - href="#loadedmetadata">LOADED_METADATA</a></code>), <code><a - href="#video1">video</a></code> elements represent nothing. - - <p>When a <code><a href="#video1">video</a></code> element is <a - href="#actively">actively playing</a>, it represents the frame of video at - the continuously increasing <a href="#current" title="current playback - position">"current" position</a>. When the <a href="#current">current - playback position</a> changes such that the last frame rendered is no - longer the frame corresponding to the <a href="#current">current playback - position</a> in the video, the new frame must be rendered. Similarly, any - audio associated with the video must, if played, be played synchronised - with the <a href="#current">current playback position</a>, at the - specified <a href="#volume" title=dom-media-volume>volume</a> with the - specified <a href="#muted" title=dom-media-muted>mute state</a>. - - <p>When a <code><a href="#video1">video</a></code> element is <a - href="#paused" title=dom-media-paused>paused</a>, the element represents - the frame of video corresponding to the <a href="#current" title="current - playback position">current playback position</a>, or, if that is not - available yet (e.g. because the video is seeking or buffering), the last - rendered frame of video. - - <p>When a <code><a href="#video1">video</a></code> element is neither <a - href="#actively">actively playing</a> nor <a href="#paused" - title=dom-media-paused>paused</a>, the element represents the last frame - of the video to have been rendered. - - <p class=note>Which frame in a video stream corresponds to a particular - playback position is defined by the video stream's format. - - <p>Video content should be rendered inside the element's playback area such - that the video content is shown centered in the playback area at the - largest possible size that fits completely within it, with the video - content's aspect ratio being preserved. Thus, if the aspect ratio of the - playback area does not match the aspect ratio of the video, the video will - be shown letterboxed. Areas of the element's playback area that do not - contain the video represent nothing.</p> - <!-- XXX - make it an interactive element - default activation behaviour is to do the play() if paused, pause() - otherwise - --> - - <p>User agents should provide controls to enable or disable the display of - closed captions associated with the video stream, though such features - should, again, not interfere with the page's normal rendering. - - <p>User agents may allow users to view the video content in manners more - suitable to the user (e.g. full-screen or in an independent resizable - window). As for the other user interface features, controls to enable this - should not interfere with the page's normal rendering unless the user - agent is <a href="#expose" title="expose a user interface to the - user">exposing a user interface</a>. In such an independent context, - however, user agents may make full user interfaces visible, with, e.g., - play, pause, seeking, and volume controls, even if the <code - title=attr-media-controls><a href="#controls">controls</a></code> - attribute is absent. - - <p>User agents may allow video playback to affect system features that - could interfere with the user's experience; for example, user agents could - disable screensavers while video playback is in progress.</p> - <!-- XXX rendering section should mention that resizing a video - should in no way interrupt playback --> - - <h5 id=video0><span class=secno>3.14.7.1. </span>Video and audio codecs for - <code><a href="#video1">video</a></code> elements</h5> - - <p>User agents may support any video and audio codecs and container - formats. - - <p>User agents should support Ogg Theora video and Ogg Vorbis audio, as - well as the Ogg container format. <a href="#refsOggTheora">[THEORA]</a> <a - href="#refsOggVorbis">[VORBIS]</a> <a href="#refsOgg">[OGG]</a></p> - <!-- (it's not a MUST because some vendors may have legal reasons - why they can't or won't support it, and there's no point making them - non-conforming when they have no choice in the matter) --> - <!-- XXX mention that this spec doesn't require native support or - plugin support, either is fine --> - - <h4 id=audio><span class=secno>3.14.8. </span>The <dfn - id=audio1><code>audio</code></dfn> element</h4> - - <p><a href="#semi-transparent">Semi-transparent</a> <a href="#strictly" - title="Strictly inline-level content">strictly inline-level</a> <a - href="#embedded0">embedded content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>As the only <a href="#embedded0">embedded content</a> child of a - <code><a href="#figure">figure</a></code> element. - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd>If the element has a <code title=attr-media-src><a - href="#src5">src</a></code> attribute: <a - href="#transparent0">transparent</a>. - - <dd>If the element does not have a <code title=attr-media-src><a - href="#src5">src</a></code> attribute: one or more <code><a - href="#source">source</a></code> elements, then, <a - href="#transparent0">transparent</a>. - - <dt>Element-specific attributes: - - <dd><code title=attr-media-src><a href="#src5">src</a></code> - - <dd><code title=attr-media-autoplay><a - href="#autoplay">autoplay</a></code> - - <dd><code title=attr-media-start><a href="#start2">start</a></code> - - <dd><code title=attr-media-loopstart><a - href="#loopstart">loopstart</a></code> - - <dd><code title=attr-media-loopend><a href="#loopend">loopend</a></code> - - <dd><code title=attr-media-end><a href="#end">end</a></code> - - <dd><code title=attr-media-loopcount><a - href="#loopcount">loopcount</a></code> - - <dd><code title=attr-media-controls><a - href="#controls">controls</a></code> - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmlaudioelement>HTMLAudioElement</dfn> : <a href="#htmlmediaelement">HTMLMediaElement</a> { - // no members -};</pre> - </dl> - - <p>An <code><a href="#audio1">audio</a></code> element represents a sound - or audio stream. - - <p>Content may be provided inside the <code><a - href="#audio1">audio</a></code> element so that older Web browsers, which - do not support <code><a href="#audio1">audio</a></code>, can display text - to the user informing them of how to access the audio contents. User - agents should not show this fallback content to the user. - - <p>The <code><a href="#audio1">audio</a></code> element is a <a - href="#media5">media element</a> whose <a href="#media7">media data</a> is - ostensibly audio data. - - <p>The <code title=attr-media-src><a href="#src5">src</a></code>, <code - title=attr-media-autoplay><a href="#autoplay">autoplay</a></code>, <code - title=attr-media-start><a href="#start2">start</a></code>, <code - title=attr-media-loopstart><a href="#loopstart">loopstart</a></code>, - <code title=attr-media-loopend><a href="#loopend">loopend</a></code>, - <code title=attr-media-end><a href="#end">end</a></code>, <code - title=attr-media-loopcount><a href="#loopcount">loopcount</a></code>, and - <code title=attr-media-controls><a href="#controls">controls</a></code> - attributes are <a href="#media6" title="media element attributes">the - attributes common to all media elements</a>. - - <p>When an <code><a href="#audio1">audio</a></code> element is <a - href="#actively">actively playing</a>, it must have its audio data played - synchronised with the <a href="#current">current playback position</a>, at - the specified <a href="#volume" title=dom-media-volume>volume</a> with the - specified <a href="#muted" title=dom-media-muted>mute state</a>. - - <p>When an <code><a href="#audio1">audio</a></code> element is not <a - href="#actively">actively playing</a>, audio must not play for the - element. - - <h5 id=audio0><span class=secno>3.14.8.1. </span>Audio codecs for <code><a - href="#audio1">audio</a></code> elements</h5> - - <p>User agents may support any audio codecs and container formats. - - <p>User agents must support the WAVE container format with audio encoded - using the PCM format. <!-- XXX references? #refs --></p> - <!-- XXX mention that this spec doesn't require native support or - plugin support, either is fine --> - - <h4 id=media><span class=secno>3.14.9. </span>Media elements</h4> - - <p><dfn id=media5 title="media element">Media elements</dfn> implement the - following interface: - - <pre - class=idl>interface <dfn id=htmlmediaelement>HTMLMediaElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - - // error state - readonly attribute <a href="#mediaerror">MediaError</a> <a href="#error0" title=dom-media-error>error</a>; - - // network state - attribute DOMString <a href="#src6" title=dom-media-src>src</a>; - readonly attribute DOMString <a href="#currentsrc" title=dom-media-currentSrc>currentSrc</a>; - const unsigned short <a href="#empty" title=dom-media-EMPTY>EMPTY</a> = 0; - const unsigned short <a href="#loading0" title=dom-media-LOADING>LOADING</a> = 1; - const unsigned short <a href="#loadedmetadata" title=dom-media-LOADED_METADATA>LOADED_METADATA</a> = 2; - const unsigned short <a href="#loadedfirstframe" title=dom-media-LOADED_FIRST_FRAME>LOADED_FIRST_FRAME</a> = 3; - const unsigned short <a href="#loaded" title=dom-media-LOADED>LOADED</a> = 4; - readonly attribute unsigned short <a href="#networkstate" title=dom-media-networkState>networkState</a>; - readonly attribute float <a href="#bufferingrate" title=dom-media-bufferingRate>bufferingRate</a>; - readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#buffered" title=dom-media-buffered>buffered</a>; - void <a href="#load" title=dom-media-load>load</a>(); - - // ready state - const unsigned short <a href="#dataunavailable" title=dom-media-DATA_UNAVAILABLE>DATA_UNAVAILABLE</a> = 0; - const unsigned short <a href="#canshowcurrentframe" title=dom-media-CAN_SHOW_CURRENT_FRAME>CAN_SHOW_CURRENT_FRAME</a> = 1; - const unsigned short <a href="#canplay" title=dom-media-CAN_PLAY>CAN_PLAY</a> = 2; - const unsigned short <a href="#canplaythrough" title=dom-media-CAN_PLAY_THROUGH>CAN_PLAY_THROUGH</a> = 3; - readonly attribute unsigned short <a href="#readystate" title=dom-media-readyState>readyState</a>; - readonly attribute boolean <a href="#seeking0" title=dom-media-seeking>seeking</a>; - - // playback state - attribute float <a href="#currenttime" title=dom-media-currentTime>currentTime</a>; - readonly attribute float <a href="#duration" title=dom-media-duration>duration</a>; - readonly attribute unsigned short <a href="#paused" title=dom-media-paused>paused</a>; - attribute float <a href="#defaultplaybackrate" title=dom-media-defaultPlaybackRate>defaultPlaybackRate</a>; - attribute float <a href="#playbackrate" title=dom-media-playbackRate>playbackRate</a>; - readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#played" title=dom-media-played>played</a>; - readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#seekable" title=dom-media-seekable>seekable</a>; - readonly attribute boolean <a href="#ended0" title=dom-media-ended>ended</a>; - attribute boolean <a href="#autoplay0" title=dom-media-autoplay>autoplay</a>; - void <a href="#play" title=dom-media-play>play</a>(); - void <a href="#pause0" title=dom-media-pause>pause</a>(); - - // looping - attribute float <a href="#start3" title=dom-media-start>start</a>; - attribute float <a href="#end0" title=dom-media-end>end</a>; - attribute float <a href="#loopstart0" title=dom-media-loopStart>loopStart</a>; - attribute float <a href="#loopend0" title=dom-media-loopEnd>loopEnd</a>; - attribute unsigned long <a href="#loopcount0" title=dom-media-loopCount>loopCount</a>; - attribute unsigned long <a href="#currentloop" title=dom-media-currentLoop>currentLoop</a>; - - // cue points - void <a href="#addcuepoint" title=dom-media-addCuePoint>addCuePoint</a>(in float time, in <a href="#voidcallback">VoidCallback</a> callback, in bool pause); - void <a href="#removecuepoint" title=dom-media-removeCuePoint>removeCuePoint</a>(in float time, in <a href="#voidcallback">VoidCallback</a> callback); - - // controls - attribute boolean <a href="#controls0" title=dom-media-controls>controls</a>; - attribute float <a href="#volume" title=dom-media-volume>volume</a>; - attribute boolean <a href="#muted" title=dom-media-muted>muted</a>; -};</pre> - - <p>The <dfn id=media6>media element attributes</dfn>, <code - title=attr-media-src><a href="#src5">src</a></code>, <code - title=attr-media-autoplay><a href="#autoplay">autoplay</a></code>, <code - title=attr-media-start><a href="#start2">start</a></code>, <code - title=attr-media-loopstart><a href="#loopstart">loopstart</a></code>, - <code title=attr-media-loopend><a href="#loopend">loopend</a></code>, - <code title=attr-media-end><a href="#end">end</a></code>, <code - title=attr-media-loopcount><a href="#loopcount">loopcount</a></code>, and - <code title=attr-media-controls><a href="#controls">controls</a></code>, - apply to all <a href="#media5" title="media element">media elements</a>. - They are defined in this section.</p> - <!-- XXX v3 features: - * frame forward / backwards / step(n) while paused - * hasAudio, hasVideo, hasCaptions, etc - * per-frame control: get current frame; set current frame - * queue of content - - pause current stream and insert content at front of queue to play immediately - - pre-download another stream - - add stream(s) to play at end of current stream - - pause playback upon reaching a certain time - - playlists, with the ability to get metadata out of them (e.g. xspf) - * control over closed captions: enable, disable, select language - * get byte ranges as well as time ranges for buffered data - * in-band metadata and cue points to allow: - - Chapter markers that synchronize to playback (without having to poll - the playhead position) - - Annotations on video content (i.e., pop-up video) - - General custom metadata store (ratings, etc.) - * notification of chapter labels changing on the fly: - - onchapterlabelupdate, which has a time and a label - * general meta data, implemented as getters (don't expose the whole thing) - - getMetadata(key: string, language: string) => HTMLImageElement or string - - onmetadatachanged (no context info) - --> - - <p><a href="#media5" title="media element">Media elements</a> are used to - present audio data, or video and audio data, to the user. This is referred - to as <dfn id=media7>media data</dfn> in this section, since this section - applies equally to <a href="#media5" title="media element">media - elements</a> for audio or for video. The term <dfn id=media8>media - resource</dfn> is used to refer to the complete set of media data, e.g. - the complete video file, or complete audio file. - - <h5 id=error><span class=secno>3.14.9.1. </span>Error codes</h5> - - <p>All <a href="#media5" title="media element">media elements</a> have an - associated error status, which records the last error the element - encountered since the <code title=dom-media-load><a - href="#load">load()</a></code> method was last invoked. The <dfn id=error0 - title=dom-media-error><code>error</code></dfn> attribute, on getting, must - return the <code><a href="#mediaerror">MediaError</a></code> object - created for this last error, or null if there has not been an error. - - <pre class=idl>interface <dfn id=mediaerror>MediaError</dfn> { - const unsigned short <a href="#mediaerraborted" title=dom-MediaError-MEDIA_ERR_ABORTED>MEDIA_ERR_ABORTED</a> = 1; - const unsigned short <a href="#mediaerrnetwork" title=dom-MediaError-MEDIA_ERR_NETWORK>MEDIA_ERR_NETWORK</a> = 2; - const unsigned short <a href="#mediaerrdecode" title=dom-MediaError-MEDIA_ERR_DECODE>MEDIA_ERR_DECODE</a> = 3; - readonly attribute unsigned short <a href="#code0" title=dom-MediaError-code>code</a>; -};</pre> - - <p>The <dfn id=code0 title=dom-MediaError-code><code>code</code></dfn> - attribute of a <code><a href="#mediaerror">MediaError</a></code> object - must return the code for the error, which must be one of the following: - - <dl> - <dt><dfn id=mediaerraborted - title=dom-MediaError-MEDIA_ERR_ABORTED><code>MEDIA_ERR_ABORTED</code></dfn> - (numeric value 1) - - <dd>The download of the <a href="#media8">media resource</a> was aborted - by the user agent at the user's request. - - <dt><dfn id=mediaerrnetwork - title=dom-MediaError-MEDIA_ERR_NETWORK><code>MEDIA_ERR_NETWORK</code></dfn> - (numeric value 2) - - <dd>A network error of some description caused the user agent to stop - downloading the <a href="#media8">media resource</a>. - - <dt><dfn id=mediaerrdecode - title=dom-MediaError-MEDIA_ERR_DECODE><code>MEDIA_ERR_DECODE</code></dfn> - (numeric value 3) - - <dd>An error of some description occurred while decoding the <a - href="#media8">media resource</a>. - </dl> - - <h5 id=location><span class=secno>3.14.9.2. </span>Location of the media - resource</h5> - - <p>The <dfn id=src5 title=attr-media-src><code>src</code></dfn> content - attribute on <a href="#media5" title="media element">media elements</a> - gives the address of the video to show. The attribute, if present, must - contain a URI (or IRI). - - <p class=note>If a <code title=attr-media-src><a - href="#src5">src</a></code> attribute is specified, the resource it - specifies is the <a href="#media8">media resource</a> that will be used. - Otherwise, the resource specified by the first suitable <code><a - href="#source">source</a></code> element child of the <a - href="#media5">media element</a> is the one used. - - <p>The <dfn id=src6 title=dom-media-src><code>src</code></dfn> DOM - attribute on <a href="#media5" title="media element">media elements</a> - must <a href="#reflect">reflect</a> the content attribute of the same - name. - - <p>To <dfn id=pick-a>pick a media resource</dfn> for a <a - href="#media5">media element</a>, a user agent must follow the following - steps: - - <ol> - <li> - <p>If the <a href="#media5">media element</a> has a <code - title=attr-media-src><a href="#src5">src</a></code>, then the address - given in that attribute is the address of the <a href="#media8">media - resource</a>; jump to the last step. - - <li> - <p>Otherwise, let <var title="">candidate</var> be the first <code><a - href="#source">source</a></code> element child in the <a - href="#media5">media element</a>, or null if there is no such child. - - <li> - <p>If either:</p> - - <ul> - <li><var title="">candidate</var> is null, or - - <li>the <var title="">candidate</var> element has no <code - title=attr-source-src><a href="#src7">src</a></code> attribute, or - - <li>the <var title="">candidate</var> element has a <code - title=attr-source-type><a href="#type8">type</a></code> attribute and - that attribute's value, when parsed as a MIME type, does not represent - a type that the user agent can render (including any codecs described - by the <code title="">codec</code> parameter), or <a - href="#refsRFC2046">[RFC2046]</a> <a href="#refsRFC4281">[RFC4281]</a> - - <li>the <var title="">candidate</var> element has a <code - title=attr-source-media><a href="#media9">media</a></code> attribute - and that attribute's value, when processed according to the rules for - media queries, does not match the current environment, <a - href="#refsMQ">[MQ]</a> - </ul> - - <p>...then the <var title="">candidate</var> is not suitable; go to the - next step.</p> - - <p>Otherwise, the address given in that <var title="">candidate</var> - element's <code title=attr-source-src><a href="#src7">src</a></code> - attribute is the address of the <a href="#media8">media resource</a>; - jump to the last step.</p> - - <li> - <p>Let <var title="">candidate</var> be the next <code><a - href="#source">source</a></code> element child in the <a - href="#media5">media element</a>, or null if there are no more such - children. - - <li> - <p>If <var title="">candidate</var> is not null, return to step 3. - - <li> - <p>There is no <a href="#media8">media resource</a>. Abort these steps. - - <li> - <p>Let the address of the <dfn id=chosen>chosen media resource</dfn> be - the one that was found before jumping to this step. - </ol> - - <p>The <dfn id=currentsrc - title=dom-media-currentSrc><code>currentSrc</code></dfn> DOM attribute - must return the empty string if the <a href="#media5">media element</a>'s - <code title=dom-media-networkState><a - href="#networkstate">networkState</a></code> has the value <a - href="#empty" title=dom-media-EMPTY>EMPTY</a>, and the absolute URL of the - <a href="#chosen">chosen media resource</a> otherwise. - - <h5 id=network0><span class=secno>3.14.9.3. </span>Network states</h5> - - <p>As <a href="#media5" title="media element">media elements</a> interact - with the network, they go through several states. The <dfn id=networkstate - title=dom-media-networkState><code>networkState</code></dfn> attribute, on - getting, must return the current network state of the element, which must - be one of the following values: - - <dl> - <dt><dfn id=empty title=dom-media-EMPTY><code>EMPTY</code></dfn> (numeric - value 0) - - <dd>The element has not yet been initialised. All attributes are in their - initial states. - - <dt><dfn id=loading0 title=dom-media-LOADING><code>LOADING</code></dfn> - (numeric value 1) - - <dd>The element has <a href="#pick-a" title="pick a media resource">picked - a media resource</a> (the <a href="#chosen">chosen media resource</a> is - available from the <code title=dom-media-currentSrc><a - href="#currentsrc">currentSrc</a></code> attribute), but none of the - metadata has yet been obtained and therefore all the other attributes are - still in their initial states. - - <dt><dfn id=loadedmetadata - title=dom-media-LOADED_METADATA><code>LOADED_METADATA</code></dfn> - (numeric value 2) - - <dd>Enough of the resource has been obtained that the metadata attributes - are initialized (e.g. the length is known). The API will no longer raise - exceptions when used. - - <dt><dfn id=loadedfirstframe - title=dom-media-LOADED_FIRST_FRAME><code>LOADED_FIRST_FRAME</code></dfn> - (numeric value 3) - - <dd>Actual <a href="#media7">media data</a> has been obtained. In the case - of video, this specifically means that a frame of video is available and - can be shown. - - <dt><dfn id=loaded title=dom-media-LOADED><code>LOADED</code></dfn> - (numeric value 4) - - <dd>The entire <a href="#media8">media resource</a> has been obtained and - is available to the user agent locally. Network connectivity could be - lost without affecting the media playback. - </dl> - - <p>The algorithm for the <code title=dom-media-load><a - href="#load">load()</a></code> method defined below describes exactly when - the <code title=dom-media-networkState><a - href="#networkstate">networkState</a></code> attribute changes value. - - <h5 id=loading><span class=secno>3.14.9.4. </span>Loading the media - resource</h5> - - <p>All <a href="#media5" title="media element">media elements</a> have a - <dfn id=begun>begun flag</dfn>, which must begin in the false state, a - <dfn id=loaded-first-frame>loaded-first-frame flag</dfn>, which must begin - in the false state, and an <dfn id=autoplaying>autoplaying flag</dfn>, - which must begin in the true state. - - <p>When the <dfn id=load title=dom-media-load><code>load()</code></dfn> - method on a <a href="#media5">media element</a> is invoked, the user agent - must run the following steps. Note that this algorithm might get aborted, - e.g. if the <code title=dom-media-load><a href="#load">load()</a></code> - method itself is invoked again. - - <ol> - <li> - <p>Any already-running instance of this algorithm for this element must - be aborted. If those method calls have not yet returned, they must - finish the step they are on, and then immediately return. - - <li> - <p>If the element's <a href="#begun">begun flag</a> is true, then the <a - href="#begun">begun flag</a> must be set to false, the <code - title=dom-media-error><a href="#error0">error</a></code> attribute must - be set to a new <code><a href="#mediaerror">MediaError</a></code> object - whose <code title=dom-MediaError-code><a href="#code0">code</a></code> - attribute is set to <code title=dom-MediaError-MEDIA_ERR_ABORTED><a - href="#mediaerraborted">MEDIA_ERR_ABORTED</a></code>, and the user agent - must synchronously <a href="#firing6">fire a progress event</a> called - <code title=event-abort><a href="#abort">abort</a></code> at the <a - href="#media5">media element</a>. - - <li> - <p>The <code title=dom-media-error><a href="#error0">error</a></code> - attribute must be set to null, and the <a - href="#loaded-first-frame">loaded-first-frame flag</a> and - <span>loaded-enough-to-play-through flag</span> must be both set to - false. - - <li> - <p>The <code title=dom-media-playbackRate><a - href="#playbackrate">playbackRate</a></code> attribute must be set to - the value of the <code title=dom-media-defaultPlaybackRate><a - href="#defaultplaybackrate">defaultPlaybackRate</a></code> attribute. - - <li> - <p>If the <a href="#media5">media element</a>'s <code - title=dom-media-networkState><a - href="#networkstate">networkState</a></code> is not set to <a - href="#empty" title=dom-media-EMPTY>EMPTY</a>, then the following - substeps must be followed: - - <ol><!--<li>Let <var title="">events</var> be a list of event names, - initially empty.</li>--> - - <li>The <code title=dom-media-networkState><a - href="#networkstate">networkState</a></code> attribute must be set to - <a href="#empty" - title=dom-media-EMPTY>EMPTY</a><!--, and the user agent must - add <code title="event-emptied">emptied</code> to the <var - title="">events</var> list-->. - - <li>If <code title=dom-media-readyState><a - href="#readystate">readyState</a></code> is not set to <code - title=dom-media-DATA_UNAVAILABLE><a - href="#dataunavailable">DATA_UNAVAILABLE</a></code>, it must be set to - that state<!-- and the user agent must add <code - title="event-dataunavailable">dataunavailable</code> to the - <var title="">events</var> list-->. - - <li>If the <code title=dom-media-paused><a - href="#paused">paused</a></code> attribute is false, it must be set to - true<!--, and the user agent must add - <code title="event-pause">pause</code> to the <var - title="">events</var> list-->. - - <li>If <code title=dom-media-seeking><a - href="#seeking0">seeking</a></code> is true, it must be set to false. - - <li>The <a href="#current">current playback position</a> must be set to - 0. - - <li>The <code title=dom-media-currentLoop><a - href="#currentloop">currentLoop</a></code> DOM attribute must be set to - 0.</li> - <!--<li>The user agent must synchronously <span>fire a simple - event</span> at the <span>media element</span> for each event - name in <var title="">events</var>, in the same order that they - were added to that list.</li>--> - - <li>The user agent must synchronously <a href="#firing2">fire a simple - event</a> called <code title=event-emptied><a - href="#emptied">emptied</a></code> at the <a href="#media5">media - element</a>. - </ol> - - <li> - <p>The user agent must <a href="#pick-a">pick a media resource</a> for - the <a href="#media5">media element</a>. If that fails, the method must - raise an <code>INVALID_STATE_ERR</code> exception, and abort these - steps. - - <li> - <p>The <code title=dom-media-networkState><a - href="#networkstate">networkState</a></code> attribute must be set to <a - href="#loading0" title=dom-media-LOADING>LOADING</a>. - - <li> - <p class=note>The <code title=dom-media-currentSrc><a - href="#currentsrc">currentSrc</a></code> attribute starts returning the - new value. - - <li> - <p>The user agent must then set the <a href="#begun">begun flag</a> to - true and <a href="#firing6">fire a progress event</a> called - <code>begin</code> at the <a href="#media5">media element</a>. - - <li> - <p>The method must return, but these steps must continue. - - <li> - <p class=note>Playback of any previously playing <a href="#media8">media - resource</a> for this element stops. - - <li> - <p>If a download is in progress for the <a href="#media5">media - element</a>, the user agent should stop the download. - - <li> - <p>The user agent must then begin to download the <a - href="#chosen">chosen media resource</a>. The rate of the download may - be throttled, however, in response to user preferences (including - throttling it to zero until the user indicates that the download can - start), or to balance the download with other connections sharing the - same bandwidth. - - <li> - <p>While the download is progressing, the user agent must <a - href="#firing6">fire a progress event</a> called <code - title=event-progress><a href="#progress0">progress</a></code> at the - element every 350ms (±200ms) or for every byte received, whichever - is <em>least</em> frequent.</p> - - <p>If at any point the user agent has received no data for more than - about three seconds, the user agent must <a href="#firing6">fire a - progress event</a> called <code title=event-stalled><a - href="#stalled">stalled</a></code> at the element.</p> - - <p>User agents may allow users to selectively block or slow <a - href="#media7">media data</a> downloads. When a <a href="#media5">media - element</a>'s download has been blocked, the user agent must act as if - it was stalled (as opposed to acting as if the connection was closed).</p> - - <p>The user agent may use whatever means necessary to download the - resource (within the constraints put forward by this and other - specifications); for example, reconnecting to the server in the face of - network errors, using HTTP partial range requests, or switching to a - streaming protocol. The user agent must only consider a resource - erroneous if it has given up trying to download it.</p> - - <dl class=switch> - <dt>If the <a href="#media7">media data</a> cannot be downloaded at all, - due to network errors, causing the user agent to give up trying to - download the resource - - <dd> - <p>DNS errors and HTTP 4xx and 5xx errors (and equivalents in other - protocols) must cause the user agent to follow the following steps. - User agents may also follow these steps in response to other network - errors of similar severity.</p> - - <ol> - <li>The user agent should cancel the download. - - <li>The <code title=dom-media-error><a href="#error0">error</a></code> - attribute must be set to a new <code><a - href="#mediaerror">MediaError</a></code> object whose <code - title=dom-MediaError-code><a href="#code0">code</a></code> attribute - is set to <code title=dom-MediaError-MEDIA_ERR_NETWORK><a - href="#mediaerrnetwork">MEDIA_ERR_NETWORK</a></code>. - - <li>The <a href="#begun">begun flag</a> must be set to false and the - user agent must <a href="#firing6">fire a progress event</a> called - <code title=event-error><a href="#error1">error</a></code> at the <a - href="#media5">media element</a>. - - <li>The element's <code title=dom-media-networkState><a - href="#networkstate">networkState</a></code> attribute must be - switched to the <a href="#empty" title=dom-media-EMPTY>EMPTY</a> - value and the user agent must <a href="#firing2">fire a simple - event</a> called <code title=event-emptied><a - href="#emptied">emptied</a></code> at the element. - - <li>These steps must be aborted. - </ol> - - <dt id=fatal-decode-error>If the <a href="#media7">media data</a> can be - downloaded but is in an unsupported format, or can otherwise not be - properly rendered at all - - <dd> - <p>The server returning a file of the wrong kind (e.g. one that that - turns out to not be pure audio when the <a href="#media5">media - element</a> is a <code><a href="#audio1">audio</a></code> element), or - the file using unsupported codecs for all the data, must cause the - user agent to follow the following steps. User agents may also follow - these steps in response to other codec-related fatal errors, such as - the file requiring more resources to process than the user agent can - provide in real time.</p> - - <ol> - <li>The user agent should cancel the download. - - <li>The <code title=dom-media-error><a href="#error0">error</a></code> - attribute must be set to a new <code><a - href="#mediaerror">MediaError</a></code> object whose <code - title=dom-MediaError-code><a href="#code0">code</a></code> attribute - is set to <code title=dom-MediaError-MEDIA_ERR_DECODE><a - href="#mediaerrdecode">MEDIA_ERR_DECODE</a></code>. - - <li>The <a href="#begun">begun flag</a> must be set to false and the - user agent must <a href="#firing6">fire a progress event</a> called - <code title=event-error><a href="#error1">error</a></code> at the <a - href="#media5">media element</a>. - - <li>The element's <code title=dom-media-networkState><a - href="#networkstate">networkState</a></code> attribute must be - switched to the <a href="#empty" title=dom-media-EMPTY>EMPTY</a> - value and the user agent must <a href="#firing2">fire a simple - event</a> called <code title=event-emptied><a - href="#emptied">emptied</a></code> at the element. - - <li>These steps must be aborted. - </ol> - - <dt>If the <a href="#media7">media data</a> download is aborted by the - user - - <dd> - <p>The download is aborted by the user, e.g. because the user navigated - the browsing context to another page, the user agent must follow the - following steps. These steps are not followed if the <code - title=dom-media-load><a href="#load">load()</a></code> method itself - is reinvoked, as the steps above handle that particular kind of abort.</p> - - <ol> - <li>The user agent should cancel the download. - - <li>The <code title=dom-media-error><a href="#error0">error</a></code> - attribute must be set to a new <code><a - href="#mediaerror">MediaError</a></code> object whose <code - title=dom-MediaError-code><a href="#code0">code</a></code> attribute - is set to <code - title=dom-MediaError-MEDIA_ERR_ABORT>MEDIA_ERR_ABORT</code>. - - <li>The <a href="#begun">begun flag</a> must be set to false and the - user agent must <a href="#firing6">fire a progress event</a> called - <code title=event-abort><a href="#abort">abort</a></code> at the <a - href="#media5">media element</a>. - - <li>If the <a href="#media5">media element</a>'s <code - title=dom-media-networkState><a - href="#networkstate">networkState</a></code> attribute has the value - <code title=dom-media-LOADING><a href="#loading0">LOADING</a></code>, - the element's <code title=dom-media-networkState><a - href="#networkstate">networkState</a></code> attribute must be - switched to the <a href="#empty" title=dom-media-EMPTY>EMPTY</a> - value and the user agent must <a href="#firing2">fire a simple - event</a> called <code title=event-emptied><a - href="#emptied">emptied</a></code> at the element. - - <li>These steps must be aborted. - </ol> - - <dt id=non-fatal-media-error>If the <a href="#media7">media data</a> can - be downloaded but has non-fatal errors or uses, in part, codecs that - are unsupported, preventing the user agent from rendering the content - completely correctly but not preventing playback altogether - - <dd> - <p>The server returning data that is partially usable but cannot be - optimally rendered must cause the user agent to follow the following - steps.</p> - - <ol> - <li class=big-issue>Should we fire a 'warning' event? Set the 'error' - flag to 'MEDIA_ERR_SUBOPTIMAL' or something? - </ol> - - <dt>Once enough of the <a href="#media7">media data</a> has been - downloaded to determine the duration of the <a href="#media8">media - resource</a>, its dimensions, and other metadata - - <dd> - <p>The user agent must follow these substeps:</p> - - <ol> - <li> - <p>The <a href="#current">current playback position</a> must be set - to the <var><a href="#effective">effective start</a></var>. - - <li> - <p>The <code title=dom-media-networkState><a - href="#networkstate">networkState</a></code> attribute must be set - to <code title=dom-media-LOADED_METADATA><a - href="#loadedmetadata">LOADED_METADATA</a></code>. - - <li> - <p class=note>A number of attributes, including <code - title=dom-media-duration><a href="#duration">duration</a></code>, - <code title=dom-media-buffered><a - href="#buffered">buffered</a></code>, and <code - title=dom-media-played><a href="#played">played</a></code>, become - available. - - <li> - <p class=note>The user agent will <a href="#firing2">fire a simple - event</a> called <code title=event-durationchange><a - href="#durationchange">durationchange</a></code> at the element at - this point. - - <li> - <p>The user agent must <a href="#firing2">fire a simple event</a> - called <code title=event-loadedmetadata><a - href="#loadedmetadata0">loadedmetadata</a></code> at the element. - </ol> - - <dt id=handling-first-frame-available>Once enough of the <a - href="#media7">media data</a> has been downloaded to enable the user - agent to display the first frame of the <a href="#media8">media - resource</a> - - <dd> - <p>The user agent must follow these substeps:</p> - - <ol> - <li> - <p>The <code title=dom-media-networkState><a - href="#networkstate">networkState</a></code> attribute must be set - to <code title=dom-media-LOADED_FIRST_FRAME><a - href="#loadedfirstframe">LOADED_FIRST_FRAME</a></code>. - - <li> - <p>The <code title=dom-media-readyState><a - href="#readystate">readyState</a></code> attribute must change to - <code title=dom-media-CAN_SHOW_CURRENT_FRAME><a - href="#canshowcurrentframe">CAN_SHOW_CURRENT_FRAME</a></code>. - - <li> - <p>The <a href="#loaded-first-frame">loaded-first-frame flag</a> must - be set to true. - - <li> - <p>The user agent must <a href="#firing2">fire a simple event</a> - called <code title=event-loadedfirstfame>loadedfirstframe</code> at - the element. - - <li> - <p>The user agent must <a href="#firing2">fire a simple event</a> - called <code title=event-canshowcurrentframe><a - href="#canshowcurrentframe0">canshowcurrentframe</a></code> at the - element. - </ol> - </dl> - - <p>When the user agent has completed the download of the entire <a - href="#media8">media resource</a>, it must move on to the next step.</p> - - <li> - <p>If the download completes without errors, the <a href="#begun">begun - flag</a> must be set to false and the user agent must <a - href="#firing6">fire a progress event</a> called <code - title=event-load><a href="#load0">load</a></code> at the element. - </ol> - - <p>If a <a href="#media5">media element</a> whose <code - title=dom-media-networkState><a - href="#networkstate">networkState</a></code> has the value <code - title=dom-media-EMPTY><a href="#empty">EMPTY</a></code> is inserted into a - document, user agents must implicitly invoke the <code - title=dom-media-load><a href="#load">load()</a></code> method on the <a - href="#media5">media element</a> as soon as all other scripts have - finished executing<!-- XXX phrase that better? -->. Any exceptions raised - must be ignored. - - <p>The <dfn id=bufferingrate - title=dom-media-bufferingRate><code>bufferingRate</code></dfn> attribute - must return the average number of bits received per second for the current - download over the past few seconds. If there is no download in progress, - the attribute must return 0. - - <p>The <dfn id=buffered - title=dom-media-buffered><code>buffered</code></dfn> attribute must return - a static <a href="#normalised">normalised <code>TimeRanges</code> - object</a> that represents the ranges of the <a href="#media8">media - resource</a>, if any, that the user agent has downloaded, at the time the - attribute is evaluated. - - <p class=note>Typically this will be a single range anchored at the zero - point, but if, e.g. the user agent uses HTTP range requests in response to - seeking, then there could be multiple ranges. - - <h5 id=offsets><span class=secno>3.14.9.5. </span>Offsets into the media - resource</h5> - - <p>The <dfn id=duration - title=dom-media-duration><code>duration</code></dfn> attribute must return - the length of the <a href="#media8">media resource</a>, in seconds. If no - <a href="#media7">media data</a> is available, then the attributes must - return 0. If <a href="#media7">media data</a> is available but the length - is not known, the attribute must return the Not-a-Number (NaN) value. If - the <a href="#media8">media resource</a> is known to be unbounded (e.g. a - streaming radio), then the attribute must return the positive Infinity - value. - - <p>When the length of the <a href="#media8">media resource</a> changes - (e.g. from being unknown to known, or from indeterminate to known, or from - a previously established length to a new length) the user agent must, once - any running scripts have finished, <a href="#firing2">fire a simple - event</a> called <code title=event-durationchange><a - href="#durationchange">durationchange</a></code> at the <a - href="#media5">media element</a>. - - <p><a href="#media5" title="media element">Media elements</a> have a <dfn - id=current>current playback position</dfn>, which must initially be zero. - The current position is a time. - - <p>The <dfn id=currenttime - title=dom-media-currentTime><code>currentTime</code></dfn> attribute must, - on getting, return the <a href="#current">current playback position</a>, - expressed in seconds. On setting, the user agent must <a href="#seek" - title=dom-media-seek>seek</a> to the new value. - - <p>The <dfn id=start2 title=attr-media-start><code>start</code></dfn> - content attribute gives the offset into the <a href="#media8">media - resource</a> at which playback is to begin. The default value is 0. - - <p>The <dfn id=effective><var>effective start</var></dfn> is the smaller of - <code title=dom-media-start><a href="#start3">start</a></code> and the end - of the <a href="#media8">media resource</a>. - - <p> - - <p>The <dfn id=loopstart - title=attr-media-loopstart><code>loopstart</code></dfn> content attribute - gives the offset into the <a href="#media8">media resource</a> at which - playback is to begin when looping a clip. The default value is 0. - - <p>The <dfn id=effective0><var>effective loop start</var></dfn> is the - smaller of <code title=dom-media-loopStart><a - href="#loopstart0">loopStart</a></code> and the end of the <a - href="#media8">media resource</a>. - - <p> - - <p>The <dfn id=loopend title=attr-media-loopend><code>loopend</code></dfn> - content attribute gives an offset into the <a href="#media8">media - resource</a> at which playback is to jump back to the <code - title=attr-media-loopstart><a href="#loopstart">loopstart</a></code>, when - looping the clip. The default value is infinity. - - <p>The <dfn id=effective1><var>effective loop end</var></dfn> is the - greater of <code title=dom-media-start><a href="#start3">start</a></code>, - <code title=dom-media-loopStart><a - href="#loopstart0">loopStart</a></code>, and <code - title=dom-media-loopEnd><a href="#loopend0">loopEnd</a></code>, and the - end of the <a href="#media8">media resource</a>. - - <p> - - <p>The <dfn id=end title=attr-media-end><code>end</code></dfn> content - attribute gives an offset into the <a href="#media8">media resource</a> at - which playback is to end. The default value is infinity. - - <p>The <dfn id=effective2><var>effective end</var></dfn> is the greater of - <code title=dom-media-start><a href="#start3">start</a></code>, <code - title=dom-media-loopStart><a href="#loopstart0">loopStart</a></code>, - <code title=dom-media-loopEnd><a href="#loopend0">end</a></code>, and the - end of the <a href="#media8">media resource</a>. - - <p> - - <p>The <code title=attr-media-start><a href="#start2">start</a></code>, - <code title=attr-media-loopstart><a - href="#loopstart">loopstart</a></code>, <code title=attr-media-loopend><a - href="#loopend">loopend</a></code>, and <code title=attr-media-end><a - href="#end">end</a></code> attributes must, if specified, contain <span - title="value time offset">value time offsets</span>. To get the time - values they represent, user agents must use the <a href="#rules4">rules - for parsing time offsets</a>. - - <p>The <dfn id=start3 title=dom-media-start><code>start</code></dfn>, <dfn - id=loopstart0 title=dom-media-loopStart><code>loopStart</code></dfn>, <dfn - id=loopend0 title=dom-media-loopEnd><code>loopEnd</code></dfn>, and <dfn - id=end0 title=dom-media-end><code>end</code></dfn> DOM attributes must <a - href="#reflect">reflect</a> the <code title=attr-media-start><a - href="#start2">start</a></code>, <code title=attr-media-loopstart><a - href="#loopstart">loopstart</a></code>, <code title=attr-media-loopend><a - href="#loopend">loopend</a></code>, and <code title=attr-media-end><a - href="#end">end</a></code> content attributes on the <a - href="#media5">media element</a> respectively. - - <p>The <dfn id=loopcount - title=attr-media-loopcount><code>loopcount</code></dfn> content attribute - gives the number of times to play the clip. The default value is 1. - - <p>The <dfn id=loopcount0 - title=dom-media-loopCount><code>loopCount</code></dfn> DOM attribute must - <a href="#reflect">reflect</a> the <code title=attr-media-loopcount><a - href="#loopcount">loopcount</a></code> content attribute on the <a - href="#media5">media element</a>. The value must be <a - href="#limited0">limited to only positive non-zero numbers</a>. - - <p>The <dfn id=currentloop - title=dom-media-currentLoop><code>currentLoop</code></dfn> attribute must - initially have the value 0. It gives the index of the current loop. It is - changed during playback as described below. - - <p>When any of the <code title=dom-media-start><a - href="#start3">start</a></code>, <code title=dom-media-loopStart><a - href="#loopstart0">loopStart</a></code>, <code title=dom-media-loopEnd><a - href="#loopend0">loopEnd</a></code>, <code title=dom-media-end><a - href="#end0">end</a></code>, and <code title=dom-media-loopCount><a - href="#loopcount0">loopCount</a></code> DOM attributes change value - (either through content attribute mutations reflecting into the DOM - attribute, or direct mutations of the DOM attribute), the user agent must - apply the following steps: - - <ol> - <li> - <p>If the <code title=dom-media-loopCount><a - href="#loopcount0">loopCount</a></code> DOM attribute's value is less - than the <code title=dom-media-currentLoop><a - href="#currentloop">currentLoop</a></code> DOM attribute's value, then - the <code title=dom-media-currentLoop><a - href="#currentloop">currentLoop</a></code> DOM attribute's value must be - set to the value of the <code title=dom-media-loopCount><a - href="#loopcount0">loopCount</a></code> DOM attribute's value (which - will make the current loop the last loop). - - <li> - <p>If the <a href="#media5">media element</a>'s <code - title=dom-media-networkState><a - href="#networkstate">networkState</a></code> is in the <code - title=dom-media-EMPTY><a href="#empty">EMPTY</a></code> state or the - <code title=dom-media-LOADING><a href="#loading0">LOADING</a></code> - state, then the user agent must at this point abort these steps. - - <li> - <p>If the <code title=dom-media-currentLoop><a - href="#currentloop">currentLoop</a></code> is zero, and the <a - href="#current">current playback position</a> is before the <var><a - href="#effective">effective start</a></var>, the user agent must <a - href="#seek" title=dom-media-seek>seek</a> to the <var><a - href="#effective">effective start</a></var>. - - <li> - <p>If the <code title=dom-media-currentLoop><a - href="#currentloop">currentLoop</a></code> is greater than zero, and the - <a href="#current">current playback position</a> is before the <var><a - href="#effective0">effective loop start</a></var>, the user agent must - <a href="#seek" title=dom-media-seek>seek</a> to the <var><a - href="#effective0">effective loop start</a></var>. - - <li> - <p>If the <code title=dom-media-currentLoop><a - href="#currentloop">currentLoop</a></code> is less than <code - title=dom-media-loopCount><a href="#loopcount0">loopCount</a></code>, - and the <a href="#current">current playback position</a> is after the - <var><a href="#effective1">effective loop end</a></var>, the user agent - must <a href="#seek" title=dom-media-seek>seek</a> to the <var><a - href="#effective0">effective loop start</a></var>, and increase <code - title=dom-media-loopCount><a href="#loopcount0">loopCount</a></code> by - 1. - - <li> - <p>If the <code title=dom-media-currentLoop><a - href="#currentloop">currentLoop</a></code> is equal to the <code - title=dom-media-loopCount><a href="#loopcount0">loopCount</a></code>, - and the <a href="#current">current playback position</a> is after the - <var><a href="#effective2">effective end</a></var>, the user agent must - <a href="#seek" title=dom-media-seek>seek</a> to the <var><a - href="#effective2">effective end</a></var> and then the looping will - end. - </ol> - - <h5 id=the-ready><span class=secno>3.14.9.6. </span>The ready states</h5> - - <p><a href="#media5" title="media element">Media elements</a> have a - <em>ready state</em>, which describes to what degree they are ready to be - rendered at the <a href="#current">current playback position</a>. The - possible values are as follows; the ready state of a media element at any - particular time is the greatest value describing the state of the element: - - <dl> - <dt><dfn id=dataunavailable - title=dom-media-DATA_UNAVAILABLE><code>DATA_UNAVAILABLE</code></dfn> - (numeric value 0) - - <dd>No data for the <a href="#current">current playback position</a> is - available. <a href="#media5" title="media element">Media elements</a> - whose <code title=dom-media-networkState><a - href="#networkstate">networkState</a></code> attribute is less than <code - title=dom-media-LOADED_FIRST_FRAME><a - href="#loadedfirstframe">LOADED_FIRST_FRAME</a></code> are always in the - <code title=dom-media-DATA_UNAVAILABLE><a - href="#dataunavailable">DATA_UNAVAILABLE</a></code> state. - - <dt><dfn id=canshowcurrentframe - title=dom-media-CAN_SHOW_CURRENT_FRAME><code>CAN_SHOW_CURRENT_FRAME</code></dfn> - (numeric value 1) - - <dd>Data for the immediate <a href="#current">current playback - position</a> is available, but not enough data is available that the user - agent could successfully advance the <a href="#current">current playback - position</a> at all without immediately reverting to the <code - title=dom-media-DATA_UNAVAILABLE><a - href="#dataunavailable">DATA_UNAVAILABLE</a></code> state. In video, this - corresponds to the user agent having data from the current frame, but not - the next frame. In audio, this corresponds to the user agent only having - audio up to the <a href="#current">current playback position</a>, but no - further. - - <dt><dfn id=canplay title=dom-media-CAN_PLAY><code>CAN_PLAY</code></dfn> - (numeric value 2) - - <dd>Data for the immediate <a href="#current">current playback - position</a> is available, as well as enough data for the user agent to - advance the <a href="#current">current playback position</a> at least a - little without immediately reverting to the <code - title=dom-media-DATA_UNAVAILABLE><a - href="#dataunavailable">DATA_UNAVAILABLE</a></code> state. In video, this - corresponds to the user agent having data for the current frame and the - next frame. In audio, this corresponds ot the user agent having data - beyond the <a href="#current">current playback position</a>. - - <dt><dfn id=canplaythrough - title=dom-media-CAN_PLAY_THROUGH><code>CAN_PLAY_THROUGH</code></dfn> - (numeric value 3) - - <dd>Data for the immediate <a href="#current">current playback - position</a> is available, as well as enough data for the user agent to - advance the <a href="#current">current playback position</a> at least a - little without immediately reverting to the <code - title=dom-media-DATA_UNAVAILABLE><a - href="#dataunavailable">DATA_UNAVAILABLE</a></code> state, and, in - addition, the user agent estimates that data is being downloaded at a - rate where the <a href="#current">current playback position</a>, if it - were to advance at the rate given by the <code - title=dom-media-defaultPlaybackRate><a - href="#defaultplaybackrate">defaultPlaybackRate</a></code> attribute, - would not overtake the available data before playback reaches the <a - href="#effective2">effective end</a> of the <a href="#media8">media - resource</a> on the last <a href="#loopcount0" - title=dom-media-loopCount>loop</a>. - </dl> - - <p>When the ready state of a <a href="#media5">media element</a> whose - <code title=dom-media-networkState><a - href="#networkstate">networkState</a></code> is not <code - title=dom-media-EMPTY><a href="#empty">EMPTY</a></code> changes, the user - agent must follow the steps given below: - - <dl class=switch> - <dt>If the new ready state is <code title=dom-media-DATA_UNAVAILABLE><a - href="#dataunavailable">DATA_UNAVAILABLE</a></code> - - <dd> - <p>The user agent must <a href="#firing2">fire a simple event</a> called - <code title=event-dataunavailable><a - href="#dataunavailable0">dataunavailable</a></code> at the element. - - <dt>If the new ready state is <code - title=dom-media-CAN_SHOW_CURRENT_FRAME><a - href="#canshowcurrentframe">CAN_SHOW_CURRENT_FRAME</a></code> - - <dd> - <p>If the element's <a href="#loaded-first-frame">loaded-first-frame - flag</a> is true, the user agent must <a href="#firing2">fire a simple - event</a> called <code title=event-canshowcurrentframe><a - href="#canshowcurrentframe0">canshowcurrentframe</a></code> event.</p> - - <p class=note>The first time the <code title=dom-media-networkState><a - href="#networkstate">networkState</a></code> attribute switches to this - value, the <a href="#loaded-first-frame">loaded-first-frame flag</a> is - false, and the event is fired <a - href="#handling-first-frame-available">by the algorithm described - above</a> for the <code title=dom-media-load><a - href="#load">load()</a></code> method, in conjunction with other steps.</p> - - <dt>If the new ready state is <code title=dom-media-CAN_PLAY><a - href="#canplay">CAN_PLAY</a></code> - - <dd> - <p>The user agent must <a href="#firing2">fire a simple event</a> called - <code title=event-canplay><a href="#canplay0">canplay</a></code>. - - <dt>If the new ready state is <code title=dom-media-CAN_PLAY_THROUGH><a - href="#canplaythrough">CAN_PLAY_THROUGH</a></code> - - <dd> - <p>The user agent must <a href="#firing2">fire a simple event</a> called - <code title=event-canplaythrough><a - href="#canplaythrough0">canplaythrough</a></code> event. If the <a - href="#autoplaying">autoplaying flag</a> is true, and the <code - title=dom-media-paused><a href="#paused">paused</a></code> attribute is - true, and the <a href="#media5">media element</a> has an <code - title=attr-media-autoplay><a href="#autoplay">autoplay</a></code> - attribute specified, then the user agent must also set the <code - title=dom-media-paused><a href="#paused">paused</a></code> attribute to - false and <a href="#firing2">fire a simple event</a> called <code - title=event-play><a href="#play0">play</a></code>. - </dl> - - <p>The <dfn id=readystate - title=dom-media-readyState><code>readyState</code></dfn> DOM attribute - must, on getting, return the value described above that describes the - current ready state of the <a href="#media5">media element</a>. - - <p>The <dfn id=autoplay - title=attr-media-autoplay><code>autoplay</code></dfn> attribute is a <a - href="#boolean0">boolean attribute</a>. When present, the algorithm - described herein will cause the user agent to automatically begin playback - of the <a href="#media8">media resource</a> as soon as it can do so - without stopping. - - <p>The <dfn id=autoplay0 - title=dom-media-autoplay><code>autoplay</code></dfn> DOM attribute must <a - href="#reflect">reflect</a> the content attribute of the same name. - - <h5 id=playing><span class=secno>3.14.9.7. </span>Playing the media - resource</h5> - - <p>The <dfn id=paused title=dom-media-paused><code>paused</code></dfn> - attribute represents whether the <a href="#media5">media element</a> is - paused or not. The attribute must initially be true. - - <p>A <a href="#media5">media element</a> is said to be <dfn - id=actively>actively playing</dfn> when its <code - title=dom-media-paused><a href="#paused">paused</a></code> attribute is - false, the <code title=dom-media-readyState><a - href="#readystate">readyState</a></code> attribute is either <code - title=dom-media-CAN_PLAY><a href="#canplay">CAN_PLAY</a></code> or <code - title=dom-media-CAN_PLAY_THROUGH><a - href="#canplaythrough">CAN_PLAY_THROUGH</a></code>, the element has not <a - href="#ended">ended playback</a>, playback has not <a - href="#stopped">stopped due to errors</a>, and the element has not <a - href="#paused0">paused for user interaction</a>. - - <p>A <a href="#media5">media element</a> is said to have <dfn - id=ended>ended playback</dfn> when the element's <code - title=dom-media-networkState><a - href="#networkstate">networkState</a></code> attribute is <code - title=dom-media-LOADED_METADATA><a - href="#loadedmetadata">LOADED_METADATA</a></code> or greater, the <a - href="#current">current playback position</a> is equal to the <var><a - href="#effective2">effective end</a></var> of the <a href="#media8">media - resource</a>, and the <code title=dom-media-currentLoop><a - href="#currentloop">currentLoop</a></code> attribute is equal to the <code - title=dom-media-loopCount><a href="#loopcount0">loopCount</a></code> DOM - attribute. - - <p>A <a href="#media5">media element</a> is said to have <dfn - id=stopped>stopped due to errors</dfn> when the element's <code - title=dom-media-networkState><a - href="#networkstate">networkState</a></code> attribute is <code - title=dom-media-LOADED_METADATA><a - href="#loadedmetadata">LOADED_METADATA</a></code> or greater, and the user - agent has <a href="#non-fatal-media-error">encounters a non-fatal - error</a> during the processing of the <a href="#media7">media data</a>, - and due to that error, is not able to play the content at the <a - href="#current">current playback position</a>. - - <p>A <a href="#media5">media element</a> is said to have <dfn - id=paused0>paused for user interaction</dfn> when its <code - title=dom-media-paused><a href="#paused">paused</a></code> attribute is - false, the <code title=dom-media-readyState><a - href="#readystate">readyState</a></code> attribute is either <code - title=dom-media-CAN_PLAY><a href="#canplay">CAN_PLAY</a></code> or <code - title=dom-media-CAN_PLAY_THROUGH><a - href="#canplaythrough">CAN_PLAY_THROUGH</a></code> and the user agent has - reached a point in the <a href="#media8">media resource</a> where the user - has to make a selection for the resource to continue. - - <p>It is possible for a <a href="#media5">media element</a> to have both <a - href="#ended">ended playback</a> and <a href="#paused0">paused for user - interaction</a> at the same time. - - <p>When a <a href="#media5">media element</a> is <a - href="#actively">actively playing</a>, its <a href="#current">current - playback position</a> must increase monotonically at <code - title=dom-media-playbackRate><a - href="#playbackrate">playbackRate</a></code> units of media time per unit - time of wall clock time. If this value is not 1, the user agent may apply - pitch adjustments to any audio component of the <a href="#media8">media - resource</a>. - - <p><a href="#media8" title="media resource">Media resources</a> might be - internally scripted or interactive. Thus, a <a href="#media5">media - element</a> could play in a non-linear fashion. If this happens, the user - agent must act as if the algorithm for <a href="#seek" - title=dom-media-seek>seeking</a> was used whenever the <a - href="#current">current playback position</a> changes in a discontinuous - fashion (so that the relevant events fire). - - <p>When a <a href="#media5">media element</a> that is <a - href="#actively">actively playing</a> stops playing because its <code - title=dom-media-readyState><a href="#readystate">readyState</a></code> - attribute changes to a value lower than <code title=dom-media-CAN_PLAY><a - href="#canplay">CAN_PLAY</a></code>, without the element having <a - href="#ended">ended playback</a>, or playback having <a - href="#stopped">stopped due to errors</a>, or playback having <a - href="#paused0">paused for user interaction</a>, the user agent must <a - href="#firing2">fire a simple event</a> called <code - title=event-timeupdate><a href="#timeupdate">timeupdate</a></code> at the - element, and then must <a href="#firing2">fire a simple event</a> called - <code title=event-waiting><a href="#waiting">waiting</a></code> at the - element. - - <p>When a <a href="#media5">media element</a> that is <a - href="#actively">actively playing</a> stops playing because it has <a - href="#paused0">paused for user interaction</a>, the user agent must <a - href="#firing2">fire a simple event</a> called <code - title=event-timeupdate><a href="#timeupdate">timeupdate</a></code> at the - element. - - <p>When <code title=dom-media-currentLoop><a - href="#currentloop">currentLoop</a></code> is less than <span><code - title=dom-media-loopCount><a - href="#loopcount0">loopCount</a></code>-1</span> and the <a - href="#current">current playback position</a> reaches the <var><a - href="#effective1">effective loop end</a></var>, then the user agent must - <a href="#seek" title=dom-media-seek>seek</a> to the <var><a - href="#effective0">effective loop start</a></var>, increase <code - title=dom-media-loopCount><a href="#loopcount0">loopCount</a></code> by 1, - and <a href="#firing2">fire a simple event</a> called <code - title=event-timeupdate><a href="#timeupdate">timeupdate</a></code>. - - <p>When <code title=dom-media-currentLoop><a - href="#currentloop">currentLoop</a></code> is equal to the <span><code - title=dom-media-loopCount><a - href="#loopcount0">loopCount</a></code>-1</span> and the <a - href="#current">current playback position</a> reaches the <var><a - href="#effective2">effective end</a></var>, then the user agent must - follow these steps: - - <ol> - <li> - <p>The user agent must stop playback. - - <li> - <p>The <code title=dom-media-ended><a href="#ended0">ended</a></code> - attribute becomes true, as described below. - - <li> - <p>The user agent must <a href="#firing2">fire a simple event</a> called - <code title=event-timeupdate><a href="#timeupdate">timeupdate</a></code> - at the element. - - <li> - <p>The user agent must <a href="#firing2">fire a simple event</a> called - <code title=event-ended><a href="#ended1">ended</a></code> at the - element. - </ol> - - <p>The <dfn id=defaultplaybackrate - title=dom-media-defaultPlaybackRate><code>defaultPlaybackRate</code></dfn> - attribute gives the desired speed at which the <a href="#media8">media - resource</a> is to play, as a multiple of its intrinsic speed. The - attribute is mutable, but on setting, if the new value is 0.0, a - <code>NOT_SUPPORTED_ERR</code> exception must be raised instead of the - value being changed. It must initially have the value 1.0. - - <p>The <dfn id=playbackrate - title=dom-media-playbackRate><code>playbackRate</code></dfn> attribute - gives the speed at which the <a href="#media8">media resource</a> plays, - as a multiple of its intrinsic speed. If it is not equal to the <code - title=dom-media-defaultPlaybackRate><a - href="#defaultplaybackrate">defaultPlaybackRate</a></code>, then the - implication is that the user is using a feature such as fast forward or - slow motion playback. The attribute is mutable, but on setting, if the new - value is 0.0, a <code>NOT_SUPPORTED_ERR</code> exception must be raised - instead of the value being changed. Otherwise, the playback must change - speed (if the element is <a href="#actively">actively playing</a>). It - must initially have the value 1.0. - - <p>When the <code title=dom-media-defaultPlaybackRate><a - href="#defaultplaybackrate">defaultPlaybackRate</a></code> or <code - title=dom-media-playbackRate><a - href="#playbackrate">playbackRate</a></code> attributes change value - (either by being set by script or by being changed directly by the user - agent, e.g. in response to user control) the user agent must, once any - running scripts have finished, <a href="#firing2">fire a simple event</a> - called <code title=event-ratechange>ratechange</code> at the <a - href="#media5">media element</a>. - - <p>When the <dfn id=play title=dom-media-play><code>play()</code></dfn> - method on a <a href="#media5">media element</a> is invoked, the user agent - must run the following steps. - - <ol> - <li> - <p>If the <a href="#media5">media element</a>'s <code - title=dom-media-networkState><a - href="#networkstate">networkState</a></code> attribute has the value <a - href="#empty" title=dom-media-EMPTY>EMPTY</a>, then the user agent must - sychronously invoke the <code title=dom-media-load><a - href="#load">load()</a></code> method. If that raises an exception, that - exception must be reraised by the <code title=dom-media-play><a - href="#play">play()</a></code> method. - - <li> - <p>If the <a href="#ended" title="ended playback">playback has ended</a>, - then the user agent must set <code title=dom-media-currentLoop><a - href="#currentloop">currentLoop</a></code> to zero and <a href="#seek" - title=dom-media-seek>seek</a> to the <var><a href="#effective">effective - start</a></var>.</p> - - <li> - <p>The <code title=dom-media-playbackRate><a - href="#playbackrate">playbackRate</a></code> attribute must be set to - the value of the <code title=dom-media-defaultPlaybackRate><a - href="#defaultplaybackrate">defaultPlaybackRate</a></code> attribute. - - <li> - <p>If the <a href="#media5">media element</a>'s <code - title=dom-media-paused><a href="#paused">paused</a></code> attribute is - true, it must be set to false. - - <li> - <p>The <a href="#media5">media element</a>'s <a - href="#autoplaying">autoplaying flag</a> must be set to false. - - <li> - <p>The method must then return. - </ol> - - <p class=note>If the second step above involved a seek, the user agent will - <a href="#firing2">fire a simple event</a> called <code - title=event-timeupdate><a href="#timeupdate">timeupdate</a></code> at the - <a href="#media5">media element</a>. - - <p class=note>If the third step above caused the <code - title=dom-media-playbackRate><a - href="#playbackrate">playbackRate</a></code> attribute to change value, - the user agent will <a href="#firing2">fire a simple event</a> called - <code title=event-ratechange>ratechange</code> at the <a - href="#media5">media element</a>. - - <ul> - <li> - <p>If the fourth step above changed the value of <code - title=dom-media-paused><a href="#paused">paused</a></code>, the user - agent must <a href="#firing2">fire a simple event</a> called <code - title=event-play><a href="#play0">play</a></code> at the <a - href="#media5">media element</a>. - </ul> - - <p>When the <dfn id=pause0 title=dom-media-pause><code>pause()</code></dfn> - method is invoked, the user agent must run the following steps: - - <ol> - <li> - <p>If the <a href="#media5">media element</a>'s <code - title=dom-media-networkState><a - href="#networkstate">networkState</a></code> attribute has the value <a - href="#empty" title=dom-media-EMPTY>EMPTY</a>, then the user agent must - sychronously invoke the <code title=dom-media-load><a - href="#load">load()</a></code> method. If that raises an exception, that - exception must be reraised by the <code title=dom-media-play><a - href="#play">play()</a></code> method. - - <li> - <p>If the <a href="#media5">media element</a>'s <code - title=dom-media-paused><a href="#paused">paused</a></code> attribute is - false, it must be set to true. - - <li> - <p>The <a href="#media5">media element</a>'s <a - href="#autoplaying">autoplaying flag</a> must be set to false. - - <li> - <p>The method must then return. - - <li> - <p>If the second step above changed the value of <code - title=dom-media-paused><a href="#paused">paused</a></code>, the user - agent must first <a href="#firing2">fire a simple event</a> called <code - title=event-timeupdate><a href="#timeupdate">timeupdate</a></code> at - the element, and then <a href="#firing2">fire a simple event</a> called - title="event-pause">pause at the element. - </ol> - - <p>The <dfn id=ended0 title=dom-media-ended><code>ended</code></dfn> - attribute must return true if the <a href="#media5">media element</a> has - <a href="#ended">ended playback</a>, and false otherwise. - - <p>The <dfn id=played title=dom-media-played><code>played</code></dfn> - attribute must return a static <a href="#normalised">normalised - <code>TimeRanges</code> object</a> that represents the ranges of the <a - href="#media8">media resource</a>, if any, that the user agent has so far - rendered, at the time the attribute is evaluated. - - <h5 id=seeking><span class=secno>3.14.9.8. </span>Seeking</h5> - - <p>The <dfn id=seeking0 title=dom-media-seeking><code>seeking</code></dfn> - attribute must initially have the value false. - - <p>When the user agent is required to <dfn id=seek - title=dom-media-seek>seek</dfn> to a particular <var title="">new playback - position</var> in the <a href="#media8">media resource</a>, it means that - the user agent must run the following steps: - - <ol> - <li> - <p>If the <a href="#media5">media element</a>'s <code - title=dom-media-networkState><a - href="#networkstate">networkState</a></code> is less than <code - title=dom-media-LOADED_METADATA><a - href="#loadedmetadata">LOADED_METADATA</a></code>, then the user agent - must raise an <code>INVALID_STATE_ERR</code> exception (if the seek was - in response to a DOM method call or setting of a DOM attribute), and - abort these steps. - - <li> - <p>If <code title=dom-media-currentLoop><a - href="#currentloop">currentLoop</a></code> is 0, let <var - title="">min</var> be the <var><a href="#effective">effective - start</a></var>. Otherwise, let it be the <var><a - href="#effective0">effective loop start</a></var>. - - <li> - <p>If <code title=dom-media-currentLoop><a - href="#currentloop">currentLoop</a></code> is equal to the value of - <code title=dom-media-loopCount><a - href="#loopcount0">loopCount</a></code>, let <var title="">max</var> be - the <var><a href="#effective2">effective end</a></var>. Otherwise, let - it be the <var><a href="#effective1">effective loop end</a></var>. - - <li> - <p>If the <var title="">new playback position</var> is more than <var - title="">max</var>, let it be <var title="">max</var>. - - <li> - <p>If the <var title="">new playback position</var> is less than <var - title="">min</var>, let it be <var title="">min</var>. - - <li> - <p>If the (possibly now changed) <var title="">new playback - position</var> is not in one of the ranges given in the <code - title=dom-media-seekable><a href="#seekable">seekable</a></code> - attribute, then the user agent must raise an <code>INDEX_SIZE_ERR</code> - exception (if the seek was in response to a DOM method call or setting - of a DOM attribute), and abort these steps. - - <li> - <p>The <a href="#current">current playback position</a> must be set to - the given <var title="">new playback position</var>. - - <li> - <p>The <code title=dom-media-seeking><a - href="#seeking0">seeking</a></code> DOM attribute must be set to true. - - <li> - <p>The user agent must <a href="#firing2">fire a simple event</a> called - <code title=event-timeupdate><a href="#timeupdate">timeupdate</a></code> - at the element. - - <li> - <p>As soon as the user agent has established whether or not the <a - href="#media7">media data</a> for the <var title="">new playback - position</var> is available, and, if it is, decoded enough data to play - back that position, the <code title=dom-media-seeking><a - href="#seeking0">seeking</a></code> DOM attribute must be set to false. - </ol> - - <p>The <dfn id=seekable - title=dom-media-seekable><code>seekable</code></dfn> attribute must return - a static <a href="#normalised">normalised <code>TimeRanges</code> - object</a> that represents the ranges of the <a href="#media8">media - resource</a>, if any, that the user agent is able to seek to, at the time - the attribute is evaluated, notwithstanding the looping attributes (i.e. - the <var><a href="#effective">effective start</a></var> and <var><a - href="#effective2">effective end</a></var>, etc, don't affect the <code - title=dom-media-seekable><a href="#seekable">seeking</a></code> - attribute). - - <p class=note>If the user agent can seek to anywhere in the <a - href="#media8">media resource</a>, e.g. because the user agent and the - server support HTTP Range requests, then the attribute would return an - object with one range, whose start is 0, and whose end is the same as the - <code title=dom-media-duration><a href="#duration">duration</a></code> - attribute's value. - - <h5 id=cue-points><span class=secno>3.14.9.9. </span>Cue points</h5> - - <p><a href="#media5" title="media element">Media elements</a> have an - ordered list of (<var title="">time</var>, <var title="">callback</var>) - tuples called the <dfn id=cue-point>cue point list</dfn>. Each entry in - the list also has a boolean <var title="">pause</var> associated with it. - - <p>The <dfn id=addcuepoint - title=dom-media-addCuePoint><code>addCuePoint(<var title="">time</var>, - <var title="">callback</var>, <var title="">pause</var>)</code></dfn> - method must, when called, add a tuple made of the given <var - title="">time</var> and <var title="">callback</var> to the element's <a - href="#cue-point">cue point list</a>, and associate with that entry the - value of the <var title="">pause</var> argument. - - <p>The <dfn id=removecuepoint - title=dom-media-removeCuePoint><code>removeCuePoint(<var - title="">time</var>, <var title="">callback</var>)</code></dfn> method - must, when called, remove the first tuple matching the given <var - title="">time</var> and <var title="">callback</var> from the element's <a - href="#cue-point">cue point list</a>. - - <p>When the <a href="#current">current playback position</a> of a <a - href="#media5">media element</a> reaches one of the times given in the - element's <a href="#cue-point">cue point list</a>, the user agent must - follow these steps: - - <ol> - <li> - <p>First, if any of the entries in the <a href="#cue-point">cue point - list</a> with that time have their associated <var title="">pause</var> - boolean set to true, then the user agent must immediately act as if the - element's <code title=dom-media-pause><a - href="#pause0">pause()</a></code> method had been invoked. - - <li> - <p>The user agent must then <a href="#firing2">fire a simple event</a> - called <code title=event-timeupdate><a - href="#timeupdate">timeupdate</a></code> at the element. - - <li> - <p>The user agent must then invoke all the non-null callbacks for all the - entries in the list that match the <a href="#current">current playback - position</a> time, in the order they were added to the list. - </ol> - - <p>Invoking a callback (an object implementing the <code><a - href="#voidcallback">VoidCallback</a></code> interface) means calling its - <code title=dom-VoidCallback-handleEvent><a - href="#handleevent">handleEvent()</a></code> method. - - <pre class=idl>interface <dfn id=voidcallback>VoidCallback</dfn> { - void <a href="#handleevent" title=dom-voidCallback-handleEvent>handleEvent</a>(); -};</pre> - - <p>The <dfn id=handleevent - title=dom-voidCallback-handleEvent><code>handleEvent</code></dfn> method - of objects implementing the <code><a - href="#voidcallback">VoidCallback</a></code> interface is the entrypoint - for the callback represented by the object. - - <p>In the ECMAScript DOM binding, the ECMAScript native - <code>Function</code> type must implement the <code><a - href="#voidcallback">VoidCallback</a></code> interface such that invoking - the <code>handleEvent()</code> method of that interface on the object from - another language binding invokes the function itself. In the ECMAScript - binding itself, however, the <code>handleEvent()</code> method of the - interface is not directly accessible on <code>Function</code> objects. - Such functions, when invoked, must be called at the scope of the <a - href="#browsing0">browsing context</a>.</p> - <!-- - XXX if you change this make sure to also look up the other mentions - of handleEvent() in this file --> - - <h5 id=user-interface><span class=secno>3.14.9.10. </span>User interface</h5> - - <p>The <dfn id=controls - title=attr-media-controls><code>controls</code></dfn> attribute is a <a - href="#boolean0">boolean attribute</a>. If the attribute is present, or if - <a href="#scripting1">scripting is disabled</a>, then the user agent - should <dfn id=expose>expose a user interface to the user</dfn>. This user - interface should include features to begin playback, pause playback, seek - to an arbitrary position in the content (if the content supports arbitrary - seeking), change the volume, and showe the media content in manners more - suitable to the user (e.g. full-screen video or in an independent - resizable window). Other controls may also be made available. - - <p>If the attribute is absent, then the user agent should avoid making a - user interface available that could conflict with an author-provided user - interface. User agents may make the following features available, however, - even when the attribute is absent: - - <p>User agents may provide controls to affect playback of the media - resource (e.g. play, pause, seeking, and volume controls), but such - features should not interfere with the page's normal rendering. For - example, such features could be exposed in the <a href="#media5">media - element</a>'s context menu. - - <p>Where possible (specifically, for starting, stopping, pausing, and - unpausing playback, for muting or changing the volume of the audio, and - for seeking), user interface features exposed by the user agent must be - implemented in terms of the DOM API described above, so that, e.g., all - the same events fire. - - <p>The <dfn id=controls0 - title=dom-media-controls><code>controls</code></dfn> DOM attribute must <a - href="#reflect">reflect</a> the content attribute of the same name. - - <p>The <dfn id=volume title=dom-media-volume><code>volume</code></dfn> - attribute must return the playback volume of any audio portions of the <a - href="#media5">media element</a>, in the range 0.0 (silent) to 1.0 - (loudest). Initially, the volume must be 0.5, but user agents may remember - the last set value across sessions, on a per-site basis or otherwise, so - the volume may start at other values. On setting, if the new value is in - the range 0.0 to 1.0 inclusive, the attribute must be set to the new value - and the playback volume must be correspondingly adjusted as soon as - possible after setting the attribute, with 0.0 being silent, and 1.0 being - the loudest setting, values in between increasing in loudness. The range - need not be linear. The loudest setting may be lower than the system's - loudest possible setting; for example the user could have set a maximum - volume. If the new value is outside the range 0.0 to 1.0 inclusive, then, - on setting, an <code>INDEX_SIZE_ERR</code> exception must be raised - instead. - - <p>The <dfn id=muted title=dom-media-muted><code>muted</code></dfn> - attribute must return true if the audio channels are muted and false - otherwise. On setting, the attribute must be set to the new value; if the - new value is true, audio playback for this <a href="#media8">media - resource</a> must then be muted, and if false, audio playback must then be - enabled. - - <p>Whenever either the <code title=dom-media-muted><a - href="#muted">muted</a></code> or <code title=dom-media-volume><a - href="#volume">volume</a></code> attributes are changed, after any running - scripts have finished executing, the user agent must <a - href="#firing2">fire a simple event</a> called <code - title=event-volumechange><a href="#volumechange">volumechange</a></code> - at the <a href="#media5">media element</a>. - - <h5 id=time-range><span class=secno>3.14.9.11. </span>Time range</h5> - - <p>Objects implementing the <code><a - href="#timeranges">TimeRanges</a></code> interface represent a list of - ranges (periods) of time. - - <pre class=idl>interface <dfn id=timeranges>TimeRanges</dfn> { - readonly attribute unsigned long <a href="#length3" title=dom-TimeRanges-length>length</a>; - float <a href="#start4" title=dom-TimeRanges-start>start</a>(in unsigned long index); - float <a href="#endindex" title=dom-TimeRanges-end>end</a>(in unsigned long index); -};</pre> - - <p>The <dfn id=length3 - title=dom-TimeRanges-length><code>length</code></dfn> DOM attribute must - return the number of ranges represented by the object. - - <p>The <dfn id=start4 title=dom-TimeRanges-start><code>start(<var - title="">index</var>)</code></dfn> method must return the position of the - start of the <var title="">index</var>th range represented by the object, - in seconds measured from the start of the timeline that the object covers. - - <p>The <dfn id=endindex title=dom-TimeRanges-end><code>end(<var - title="">index</var>)</code></dfn> method must return the position of the - end of the <var title="">index</var>th range represented by the object, in - seconds measured from the start of the timeline that the object covers. - - <p>When a <code><a href="#timeranges">TimeRanges</a></code> object is said - to be a <dfn id=normalised>normalised <code>TimeRanges</code> - object</dfn>, the ranges it represents must obey the following criteria: - - <ul> - <li>The start of a range must be greater than the end of all earlier - ranges. - - <li>The start of a range must be less than the end of that same range. - </ul> - - <p>In other words, the ranges in such an object are ordered, don't overlap, - and don't touch (adjacent ranges are folded into one bigger range). - - <p>The timelines used by the objects returned by the <code - title=dom-media-buffered><a href="#buffered">buffered</a></code>, <code - title=dom-media-seekable><a href="#seekable">seekable</a></code> and <code - title=dom-media-played><a href="#played">played</a></code> DOM attributes - of <a href="#media5" title="media element">media elements</a> must be the - same as that element's <a href="#media8">media resource</a>'s timeline. - - <h5 id=mediaevents><span class=secno>3.14.9.12. </span>Event summary</h5> - - <p>The following events fire on <a href="#media5" title="media - element">media elements</a> as part of the processing model described - above: - - <table> - <thead> - <tr> - <th>Event name - - <th>Interface - - <th>Dispatched when... - - <th>Preconditions - - <tbody> - <tr> - <td><dfn id=begin title=event-begin><code>begin</code></dfn> - - <td><code>ProgressEvent</code> <a href="#refsPROGRESS">[PROGRESS]</a> - - <td>The user agent begins fetching the <a href="#media7">media data</a>, - synchronously during the <code title=dom-media-load><a - href="#load">load()</a></code> method call. - - <td><code title=dom-media-networkState><a - href="#networkstate">networkState</a></code> equals <code - title=dom-media-LOADING><a href="#loading0">LOADING</a></code> - - <tr> - <td><dfn id=progress0 title=event-progress><code>progress</code></dfn> - - <td><code>ProgressEvent</code> <a href="#refsPROGRESS">[PROGRESS]</a> - - <td>The user agent is fetching <a href="#media7">media data</a>. - - <td><code title=dom-media-networkState><a - href="#networkstate">networkState</a></code> is more than <code - title=dom-media-EMPTY><a href="#empty">EMPTY</a></code> and less than - <code title=dom-media-LOADED><a href="#loaded">LOADED</a></code> - - <tr> - <td><dfn id=loadedmetadata0 - title=event-loadedmetadata><code>loadedmetadata</code></dfn> - - <td><code>Event</code> - - <td>The user agent is fetching <a href="#media7">media data</a>, and the - <a href="#media8">media resource</a>'s metadata has just been received. - - - <td><code title=dom-media-networkState><a - href="#networkstate">networkState</a></code> equals <code - title=dom-media-LOADED_METADATA><a - href="#loadedmetadata">LOADED_METADATA</a></code> - - <tr> - <td><dfn id=loadedfirstframe0 - title=event-loadedfirstframe><code>loadedfirstframe</code></dfn> - - <td><code>Event</code> - - <td>The user agent is fetching <a href="#media7">media data</a>, and the - <a href="#media8">media resource</a>'s metadata has just been received. - - - <td><code title=dom-media-networkState><a - href="#networkstate">networkState</a></code> equals <code - title=dom-media-LOADED_FIRST_FRAME><a - href="#loadedfirstframe">LOADED_FIRST_FRAME</a></code> - - <tr> - <td><dfn id=load0 title=event-load><code>load</code></dfn> - - <td><code>ProgressEvent</code> <a href="#refsPROGRESS">[PROGRESS]</a> - - <td>The user agent finishes downloading the entire <a - href="#media8">media resource</a>. - - <td><code title=dom-media-networkState><a - href="#networkstate">networkState</a></code> equals <code - title=dom-media-LOADED><a href="#loaded">LOADED</a></code> - - <tr> - <td><dfn id=abort title=event-abort><code>abort</code></dfn> - - <td><code>ProgressEvent</code> <a href="#refsPROGRESS">[PROGRESS]</a> - - <td>The user agent stops fetching the <a href="#media7">media data</a> - before it is completely downloaded. This can be fired synchronously - during the <code title=dom-media-load><a href="#load">load()</a></code> - method call. - - <td><code title=dom-media-error><a href="#error0">error</a></code> is an - object with the code <code title=dom-MediaError-MEDIA_ERR_ABORTED><a - href="#mediaerraborted">MEDIA_ERR_ABORTED</a></code>. <code - title=dom-media-networkState><a - href="#networkstate">networkState</a></code> equals either <code - title=dom-media-EMPTY><a href="#empty">EMPTY</a></code> or <code - title=dom-media-LOADED><a href="#loaded">LOADED</a></code>, depending - on when the download was aborted. - - <tr> - <td><dfn id=error1 title=event-error><code>error</code></dfn> - - <td><code>ProgressEvent</code> <a href="#refsPROGRESS">[PROGRESS]</a> - - <td>An error occurs while fetching the <a href="#media7">media data</a>. - - - <td><code title=dom-media-error><a href="#error0">error</a></code> is an - object with the code <code - title=dom-MediaError-MEDIA_ERR_NETWORK_ERROR>MEDIA_ERR_NETWORK_ERROR</code> - or higher. <code title=dom-media-networkState><a - href="#networkstate">networkState</a></code> equals either <code - title=dom-media-EMPTY><a href="#empty">EMPTY</a></code> or <code - title=dom-media-LOADED><a href="#loaded">LOADED</a></code>, depending - on when the download was aborted. - - <tr> - <td><dfn id=emptied title=event-emptied><code>emptied</code></dfn> - - <td><code>Event</code> - - <td>A <a href="#media5">media element</a> whose <code - title=dom-media-networkState><a - href="#networkstate">networkState</a></code> was previously not in the - <code title=dom-media-EMPTY><a href="#empty">EMPTY</a></code> state has - just switched to that state (either because of a fatal error during - load that's about to be reported, or because the <code - title=dom-media-load><a href="#load">load()</a></code> method was - reinvoked, in which case it is fired synchronously during the <code - title=dom-media-load><a href="#load">load()</a></code> method call). - - <td><code title=dom-media-networkState><a - href="#networkstate">networkState</a></code> is <code - title=dom-media-EMPTY><a href="#empty">EMPTY</a></code>; all the DOM - attributes are in their initial states. - - <tr> - <td><dfn id=stalled title=event-stalled><code>stalled</code></dfn> - - <td><code>ProgressEvent</code> - - <td>The user agent is trying to fetch <a href="#media7">media data</a>, - but data is unexpectedly not forthcoming. - - <td> - - <tr> - <td><dfn id=play0 title=event-play><code>play</code></dfn> - - <td><code>Event</code> - - <td>Playback has begun. Fired after the <code title=dom-media-play><a - href="#play">play</a></code> method has returned. - - <td><code title=dom-media-paused><a href="#paused">paused</a></code> is - newly false. - - <tr> - <td><dfn id=pause1 title=event-pause><code>pause</code></dfn> - - <td><code>Event</code> - - <td>Playback has been paused. Fired after the <code - title=dom-media-pause><a href="#pause0">pause</a></code> method has - returned. - - <td><code title=dom-media-paused><a href="#paused">paused</a></code> is - newly true. - - <tr> - <td><dfn id=waiting title=event-waiting><code>waiting</code></dfn> - - <td><code>Event</code> - - <td>Playback has stopped because the next frame is not available, but - the user agent expects that frame to become available in due course. - - <td><code title=dom-media-readyState><a - href="#readystate">readyState</a></code> is either <code - title=dom-media-DATA_UNAVAILABLE><a - href="#dataunavailable">DATA_UNAVAILABLE</a></code> or <code - title=dom-media-CAN_SHOW_CURRENT_FRAME><a - href="#canshowcurrentframe">CAN_SHOW_CURRENT_FRAME</a></code>, and - <code title=dom-media-paused><a href="#paused">paused</a></code> is - false. Either <code title=dom-media-seeking><a - href="#seeking0">seeking</a></code> is true, or the <a - href="#current">current playback position</a> is not contained in any - of the ranges in <code title=dom-media-buffered><a - href="#buffered">buffered</a></code>. It is possible for playback to - stop for two other reasons without <code title=dom-media-paused><a - href="#paused">paused</a></code> being false, but those two reasons do - not fire this event: maybe <a href="#ended" title="ended - playback">playback ended</a>, or playback <a href="#stopped">stopped - due to errors</a>. - - <tr> - <td><dfn id=timeupdate - title=event-timeupdate><code>timeupdate</code></dfn> - - <td><code>Event</code> - - <td>The <a href="#current">current playback position</a> changed in an - interesting way, for example discontinuously. - - <td> - - <tr> - <td><dfn id=ended1 title=event-ended><code>ended</code></dfn> - - <td><code>Event</code> - - <td>Playback has stopped because the end of the <a href="#media8">media - resource</a> was reached. - - <td><code title=dom-media-currentTime><a - href="#currenttime">currentTime</a></code> equals the <var><a - href="#effective2">effective end</a></var>; <code - title=dom-media-ended><a href="#ended0">ended</a></code> is true. - - <tr> - <td><dfn id=dataunavailable0 - title=event-dataunavailable><code>dataunavailable</code></dfn> - - <td><code>Event</code> - - <td>The user agent cannot render the data at the <a - href="#current">current playback position</a> because data for the - current frame is not immediately available. - - <td>The <code title=dom-media-readyState><a - href="#readystate">readyState</a></code> attribute is newly equal to - <code title=DATA_UNAVAILABLE>DATA_UNAVAILABLE</code>. - - <tr> - <td><dfn id=canshowcurrentframe0 - title=event-canshowcurrentframe><code>canshowcurrentframe</code></dfn> - - <td><code>Event</code> - - <td>The user agent cannot render the data after the <a - href="#current">current playback position</a> because data for the next - frame is not immediately available. - - <td>The <code title=dom-media-readyState><a - href="#readystate">readyState</a></code> attribute is newly equal to - <code title=CAN_SHOW_CURRENT_FRAME>CAN_SHOW_CURRENT_FRAME</code>. - - <tr> - <td><dfn id=canplay0 title=event-canplay><code>canplay</code></dfn> - - <td><code>Event</code> - - <td>The user agent can resume playback of the <a href="#media7">media - data</a>, but estimates that if playback were to be started now, the <a - href="#media8">media resource</a> could not be rendered at the current - playback rate up to its end without having to stop for further - buffering of content. - - <td>The <code title=dom-media-readyState><a - href="#readystate">readyState</a></code> attribute is newly equal to - <code title=CAN_PLAY>CAN_PLAY</code>. - - <tr> - <td><dfn id=canplaythrough0 - title=event-canplaythrough><code>canplaythrough</code></dfn> - - <td><code>Event</code> - - <td>The user agent estimates that if playback were to be started now, - the <a href="#media8">media resource</a> could be rendered at the - current playback rate all the way to its end without having to stop for - further buffering. - - <td>The <code title=dom-media-readyState><a - href="#readystate">readyState</a></code> attribute is newly equal to - <code title=CAN_PLAY_THROUGH>CAN_PLAY_THROUGH</code>. - - <tr> - <td><dfn id=ratechange - title=event-ratehange><code>ratechange</code></dfn> - - <td><code>Event</code> - - <td>Either the <code title=dom-media-defaultPlaybackRate><a - href="#defaultplaybackrate">defaultPlaybackRate</a></code> or the <code - title=dom-media-playbackRate><a - href="#playbackrate">playbackRate</a></code> attribute has just been - updated. - - <td> - - <tr> - <td><dfn id=durationchange - title=event-durationchange><code>durationchange</code></dfn> - - <td><code>Event</code> - - <td>The <code title=dom-media-duration><a - href="#duration">duration</a></code> attribute has just been updated. - - <td> - - <tr> - <td><dfn id=volumechange - title=event-volumechange><code>volumechange</code></dfn> - - <td><code>Event</code> - - <td>Either the <code title=dom-media-volume><a - href="#volume">volume</a></code> attribute or the <code - title=dom-media-muted><a href="#muted">muted</a></code> attribute has - changed. Fired after the relevant attribute's setter has returned. - - <td> - </table> - - <h5 id=security0><span class=secno>3.14.9.13. </span>Security and privacy - considerations</h5> - - <p class=big-issue>Talk about making sure interactive media files (e.g. - SVG) don't have access to the container DOM (XSS potential); talk about - not exposing any sensitive data like metadata from tracks in the media - files (intranet snooping risk) - - <h4 id=the-source><span class=secno>3.14.10. </span>The <dfn - id=source><code>source</code></dfn> element</h4> - <!-- no type --> - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>As a child of a <a href="#media5">media element</a>, before any - content other than <code><a href="#source">source</a></code> elements. - - <dt>Content model: - - <dd>Empty. - - <dt>Element-specific attributes: - - <dd><code title=attr-source-src><a href="#src7">src</a></code> (required) - - <dd><code title=attr-source-type><a href="#type8">type</a></code> - - <dd><code title=attr-source-media><a href="#media9">media</a></code> - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmlsourceelement>HTMLSourceElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute DOMString <a href="#src8" title=dom-source-src>src</a>; - attribute DOMString <a href="#type9" title=dom-source-type>type</a>; - attribute DOMString <a href="#media10" title=dom-source-media>media</a>; -};</pre> - </dl> - - <p>The <code><a href="#source">source</a></code> element allows authors to - specify multiple <a href="#media8" title="media resource">media - resources</a> for <a href="#media5" title="media element">media - elements</a>. - - <p>The <dfn id=src7 title=attr-source-src><code>src</code></dfn> attribute - gives the address of the <a href="#media8">media resource</a>. The value - must be a URI (or IRI). This attribute must be present. - - <p>The <dfn id=type8 title=attr-source-type><code>type</code></dfn> - attribute gives the type of the <a href="#media8">media resource</a>, to - help the user agent determine if it can play this <a href="#media8">media - resource</a> before downloading it. Its value must be a MIME type. The - <code title="">codec</code> parameter may be specified and might be - necessary to specify exactly how the resource is encoded. <a - href="#refsRFC2046">[RFC2046]</a> <a href="#refsRFC4281">[RFC4281]</a> - - <p>The <dfn id=media9 title=attr-source-media><code>media</code></dfn> - attribute gives the intended media type of the <a href="#media8">media - resource</a>, to help the user agent determine if this <a - href="#media8">media resource</a> is useful to the user before downloading - it. Its value must be a valid media query. <a href="#refsMQ">[MQ]</a> - - <p>Either the <code title=attr-source-type><a href="#type8">type</a></code> - attribute, the <code title=attr-source-media><a - href="#media9">media</a></code> attribute or both, must be specified, - unless this is the last <code><a href="#source">source</a></code> element - child of the parent element. - - <p>If a <code><a href="#source">source</a></code> element is inserted into - a <a href="#media5">media element</a> that is already in a document and - whose <code title=dom-media-networkState><a - href="#networkstate">networkState</a></code> is in the <code - title=dom-media-EMPTY><a href="#empty">EMPTY</a></code> state, the user - agent must implicitly invoke the <code title=dom-media-load><a - href="#load">load()</a></code> method on the <a href="#media5">media - element</a> as soon as all other scripts have finished executing. Any - exceptions raised must be ignored. - - <p>The DOM attributes <dfn id=src8 - title=dom-source-src><code>src</code></dfn>, <dfn id=type9 - title=dom-source-type><code>type</code></dfn>, and <dfn id=media10 - title=dom-source-media><code>media</code></dfn> must <a - href="#reflect">reflect</a> the respective content attributes of the same - name. - - <h4 id=the-canvas><span class=secno>3.14.11. </span>The <dfn - id=canvas><code>canvas</code></dfn> element</h4> - - <p><a href="#strictly" title="Strictly inline-level content">Strictly - inline-level</a> <a href="#embedded0">embedded content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>As the only <a href="#embedded0">embedded content</a> child of a - <code><a href="#figure">figure</a></code> element. - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd><a href="#inline-level0">Inline-level content</a>. - - <dt>Element-specific attributes: - - <dd><code title=attr-canvas-height><a href="#height3">height</a></code> - - <dd><code title=attr-canvas-width><a href="#width3">width</a></code> - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmlcanvaselement>HTMLCanvasElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute unsigned long <a href="#width4" title=dom-canvas-width>width</a>; - attribute unsigned long <a href="#height4" title=dom-canvas-height>height</a>; - - DOMString <a href="#todataurl" title=dom-canvas-toDataURL>toDataURL</a>(); - DOMString <a href="#todataurl0" title=dom-canvas-toDataURL-type>toDataURL</a>(in DOMString type); - - DOMObject <a href="#getcontext" title=dom-canvas-getContext>getContext</a>(in DOMString contextId); -};</pre> - </dl> - - <p class=big-issue>Shouldn't allow inline-level content to be the content - model when the parent's content model is strictly inline only. - - <p>The <code><a href="#canvas">canvas</a></code> element represents a - resolution-dependent bitmap canvas, which can be used for rendering - graphs, game graphics, or other visual images on the fly. - - <p>Authors should not use the <code><a href="#canvas">canvas</a></code> - element in a document when a more suitable element is available. For - example, it is inappropriate to use a <code><a - href="#canvas">canvas</a></code> element to render a page heading: if the - desired presentation of the heading is graphically intense, it should be - marked up using appropriate elements (typically <code><a - href="#h1">h1</a></code>) and then styled using CSS and supporting - technologies such as XBL. - - <p>When authors use the <code><a href="#canvas">canvas</a></code> element, - they should also provide content that, when presented to the user, conveys - essentially the same function or purpose as the bitmap canvas. This - content may be placed as content of the <code><a - href="#canvas">canvas</a></code> element. The contents of the <code><a - href="#canvas">canvas</a></code> element, if any, are the element's <a - href="#fallback">fallback content</a>. - - <p>In interactive visual media with <span>scripting enabled</span>, the - canvas element is an embedded element with a dynamically created image. - - <p>In non-interactive, static, visual media, if the <code><a - href="#canvas">canvas</a></code> element has been previously painted on - (e.g. if the page was viewed in an interactive visual medium and is now - being printed, or if some script that ran during the page layout process - painted on the element), then the <code><a - href="#canvas">canvas</a></code> element must be treated as embedded - content with the current image and size. Otherwise, the element's fallback - content must be used instead. - - <p>In non-visual media, and in visual media with <span>scripting - disabled</span>, the <code><a href="#canvas">canvas</a></code> element's - fallback content must be used instead. - - <p>The <code><a href="#canvas">canvas</a></code> element has two attributes - to control the size of the coordinate space: <dfn id=height3 - title=attr-canvas-height><code>height</code></dfn> and <dfn id=width3 - title=attr-canvas-width><code>width</code></dfn>. These attributes, when - specified, must have values that are <a href="#valid" title="valid - non-negative integer">valid non-negative integers</a>. The <a - href="#rules">rules for parsing non-negative integers</a> must be used to - obtain their numeric values. If an attribute is missing, or if parsing its - value returns an error, then the default value must be used instead. The - <code title=attr-canvas-width><a href="#width3">width</a></code> attribute - defaults to 300, and the <code title=attr-canvas-height><a - href="#height3">height</a></code> attribute defaults to 150. - - <p>The intrinsic dimensions of the <code><a - href="#canvas">canvas</a></code> element equal the size of the coordinate - space, with the numbers interpreted in CSS pixels. However, the element - can be sized arbitrarily by a style sheet. During rendering, the image is - scaled to fit this layout size. - - <p>The size of the coordinate space does not necessarily represent the size - of the actual bitmap that the user agent will use internally or during - rendering. On high-definition displays, for instance, the user agent may - internally use a bitmap with two device pixels per unit in the coordinate - space, so that the rendering remains at high quality throughout. - - <p>The canvas must initially be fully transparent black. - - <p>Whenever the <code title=attr-canvas-width><a - href="#width3">width</a></code> and <code title=attr-canvas-height><a - href="#height3">height</a></code> attributes are set (whether to a new - value or to the previous value), the bitmap and any associated contexts - must be cleared back to their initial state and reinitialised with the - newly specified coordinate space dimensions. - - <p>The <dfn id=width4 title=dom-canvas-width><code>width</code></dfn> and - <dfn id=height4 title=dom-canvas-height><code>height</code></dfn> DOM - attributes must <a href="#reflect">reflect</a> the content attributes of - the same name. - - <div class=example> - <p>Only one square appears to be drawn in the following example:</p> - - <pre> - // canvas is a reference to a <canvas> element - var context = canvas.getContext('2d'); - context.fillRect(0,0,50,50); - canvas.setAttribute('width', '300'); // clears the canvas - context.fillRect(0,100,50,50); - canvas.width = canvas.width; // clears the canvas - context.fillRect(100,0,50,50); // only this square remains</pre> - </div> - - <p>To draw on the canvas, authors must first obtain a reference to a <dfn - id=context0>context</dfn> using the <dfn id=getcontext - title=dom-canvas-getContext><code>getContext(<var - title="">contextId</var>)</code></dfn> method of the <code><a - href="#canvas">canvas</a></code> element. - - <p>This specification only defines one context, with the name "<code - title=canvas-context-2d><a href="#d">2d</a></code>". If <code - title=dom-canvas-getContext><a href="#getcontext">getContext()</a></code> - is called with that exact string for tis <var title="">contextId</var> - argument, then the UA must return a reference to an object implementing - <code><a - href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code>. - Other specifications may define their own contexts, which would return - different objects. - - <p>Vendors may also define experimental contexts using the syntax - <code><var title="">vendorname</var>-<var title="">context</var></code>, - for example, <code>moz-3d</code>. - - <p>When the UA is passed an empty string or a string specifying a context - that it does not support, then it must return null. String comparisons - must be literal and case-sensitive. - - <p class=note>A future version of this specification will probably define a - <code>3d</code> context (probably based on the OpenGL ES API). - - <p>The <dfn id=todataurl - title=dom-canvas-toDataURL><code>toDataURL()</code></dfn> method must, - when called with no arguments, return a <code title="">data:</code> URI - containing a representation of the image as a PNG file. <a - href="#refsPNG">[PNG]</a>. - - <p>The <dfn id=todataurl0 - title=dom-canvas-toDataURL-type><code>toDataURL(<var - title="">type</var>)</code></dfn> method (when called with one <em>or - more</em> arguments) must return a <code>data:</code> URI containing a - representation of the image in the format given by <var - title="">type</var>. The possible values are MIME types with no - parameters, for example <code>image/png</code>, <code>image/jpeg</code>, - or even maybe <code>image/svg+xml</code> if the implementation actually - keeps enough information to reliably render an SVG image from the canvas. - - <p>Only support for <code>image/png</code> is required. User agents may - support other types. If the user agent does not support the requested - type, it must return the image using the PNG format. - - <p>User agents must convert the provided type to lower case before - establishing if they support that type and before creating the - <code>data:</code> URI.</p> - <!-- XXX define "convert to lower case" - --> - - <p class=note>When trying to use types other than <code>image/png</code>, - authors can check if the image was really returned in the requested format - by checking to see if the returned string starts with one the exact - strings "<code title="">data:image/png,</code>" or "<code - title="">data:image/png;</code>". If it does, the image is PNG, and thus - the requested type was not supported. - - <p>Arguments other than the <var title="">type</var> must be ignored, and - must not cause the user agent to raise an exception (as would normally - occur if a method was called with the wrong number of arguments). A future - version of this specification will probably allow extra parameters to be - passed to <code title=dom-canvas-toDataURL><a - href="#todataurl">toDataURL()</a></code> to allow authors to more - carefully control compression settings, image metadata, etc. - - <p><strong>Security:</strong> To prevent <em>information leakage</em>, the - <code title=dom-canvas-toDataURL><a - href="#todataurl">toDataURL()</a></code> and <code - title=dom-context-2d-getImageData><a - href="#getimagedata">getImageData()</a></code> methods should raise a <a - href="#security8">security exception</a> if the canvas has ever had an - image painted on it whose <a href="#origin0">origin</a> is different from - that of the script calling the method. - - <h5 id=the-2d><span class=secno>3.14.11.1. </span>The 2D context</h5> - - <p>When the <code title=dom-canvas-getContext><a - href="#getcontext">getContext()</a></code> method of a <code><a - href="#canvas">canvas</a></code> element is invoked with <dfn id=d - title=canvas-context-2d><code>2d</code></dfn> as the argument, a <code><a - href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> - object is returned. - - <p>There is only one <code><a - href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> - object per canvas, so calling the <code title=dom-canvas-getContext><a - href="#getcontext">getContext()</a></code> method with the <code - title=canvas-context-2d><a href="#d">2d</a></code> argument a second time - must return the same object. - - <p>The 2D context represents a flat cartesian surface whose origin (0,0) is - at the top left corner, with the coordinate space having <var - title="">x</var> values increasing when going right, and <var - title="">y</var> values increasing when going down. - - <pre - class=idl>interface <dfn id=canvasrenderingcontext2d>CanvasRenderingContext2D</dfn> { - - // back-reference to the canvas - readonly attribute <a href="#htmlcanvaselement">HTMLCanvasElement</a> <a href="#canvas0" title=dom-context-2d-canvas>canvas</a>; - - // state - void <a href="#save" title=dom-context-2d-save>save</a>(); // push state on state stack - void <a href="#restore" title=dom-context-2d-restore>restore</a>(); // pop state stack and restore state - - // transformations (default transform is the identity matrix) - void <a href="#scale" title=dom-context-2d-scale>scale</a>(in float x, in float y); - void <a href="#rotate" title=dom-context-2d-rotate>rotate</a>(in float angle); - void <a href="#translate" title=dom-context-2d-translate>translate</a>(in float x, in float y); - void <a href="#transform" title=dom-context-2d-transform>transform</a>(in float m11, in float m12, in float m21, in float m22, in float dx, in float dy); - void <a href="#settransform" title=dom-context-2d-setTransform>setTransform</a>(in float m11, in float m12, in float m21, in float m22, in float dx, in float dy); -<!-- - // XXXv3 we've also received requests for: - void skew(...); - void reflect(...); // or mirror(...) ---> - // compositing - attribute float <a href="#globalalpha" title=dom-context-2d-globalAlpha>globalAlpha</a>; // (default 1.0) - attribute DOMString <a href="#globalcompositeoperation" title=dom-context-2d-globalCompositeOperation>globalCompositeOperation</a>; // (default source-over) - - // colors and styles - attribute DOMObject <a href="#strokestyle" title=dom-context-2d-strokeStyle>strokeStyle</a>; // (default black) - attribute DOMObject <a href="#fillstyle" title=dom-context-2d-fillStyle>fillStyle</a>; // (default black) - <a href="#canvasgradient0">CanvasGradient</a> <a href="#createlineargradient" title=dom-context-2d-createLinearGradient>createLinearGradient</a>(in float x0, in float y0, in float x1, in float y1); - <a href="#canvasgradient0">CanvasGradient</a> <a href="#createradialgradient" title=dom-context-2d-createRadialGradient>createRadialGradient</a>(in float x0, in float y0, in float r0, in float x1, in float y1, in float r1); - <a href="#canvaspattern0">CanvasPattern</a> <a href="#createpatternimage" title=dom-context-2d-createPattern>createPattern</a>(in <a href="#htmlimageelement">HTMLImageElement</a> image, DOMString repetition); - <a href="#canvaspattern0">CanvasPattern</a> <a href="#createpatternimage" title=dom-context-2d-createPattern>createPattern</a>(in <a href="#htmlcanvaselement">HTMLCanvasElement</a> image, DOMString repetition); - - // line caps/joins - attribute float <a href="#linewidth" title=dom-context-2d-lineWidth>lineWidth</a>; // (default 1) - attribute DOMString <a href="#linecap" title=dom-context-2d-lineCap>lineCap</a>; // "butt", "round", "square" (default "butt") - attribute DOMString <a href="#linejoin" title=dom-context-2d-lineJoin>lineJoin</a>; // "round", "bevel", "miter" (default "miter") - attribute float <a href="#miterlimit" title=dom-context-2d-miterLimit>miterLimit</a>; // (default 10) - - // shadows - attribute float <a href="#shadowoffsetx" title=dom-context-2d-shadowOffsetX>shadowOffsetX</a>; // (default 0) - attribute float <a href="#shadowoffsety" title=dom-context-2d-shadowOffsetY>shadowOffsetY</a>; // (default 0) - attribute float <a href="#shadowblur" title=dom-context-2d-shadowBlur>shadowBlur</a>; // (default 0) - attribute DOMString <a href="#shadowcolor" title=dom-context-2d-shadowColor>shadowColor</a>; // (default transparent black) - - // rects - void <a href="#clearrect" title=dom-context-2d-clearRect>clearRect</a>(in float x, in float y, in float w, in float h); - void <a href="#fillrect" title=dom-context-2d-fillRect>fillRect</a>(in float x, in float y, in float w, in float h); - void <a href="#strokerect" title=dom-context-2d-strokeRect>strokeRect</a>(in float x, in float y, in float w, in float h); - - // path API - void <a href="#beginpath" title=dom-context-2d-beginPath>beginPath</a>(); - void <a href="#closepath" title=dom-context-2d-closePath>closePath</a>(); - void <a href="#moveto" title=dom-context-2d-moveTo>moveTo</a>(in float x, in float y); - void <a href="#lineto" title=dom-context-2d-lineTo>lineTo</a>(in float x, in float y); - void <a href="#quadraticcurveto" title=dom-context-2d-quadraticCurveTo>quadraticCurveTo</a>(in float cpx, in float cpy, in float x, in float y); - void <a href="#beziercurveto" title=dom-context-2d-bezierCurveTo>bezierCurveTo</a>(in float cp1x, in float cp1y, in float cp2x, in float cp2y, in float x, in float y); - void <a href="#arcto" title=dom-context-2d-arcTo>arcTo</a>(in float x1, in float y1, in float x2, in float y2, in float radius); - void <a href="#rectx" title=dom-context-2d-rect>rect</a>(in float x, in float y, in float w, in float h); - void <a href="#arcx-" title=dom-context-2d-arc>arc</a>(in float x, in float y, in float radius, in float startAngle, in float endAngle, in boolean anticlockwise); - void <a href="#fill" title=dom-context-2d-fill>fill</a>(); - void <a href="#stroke" title=dom-context-2d-stroke>stroke</a>(); - void <a href="#clip" title=dom-context-2d-clip>clip</a>(); - boolean <a href="#ispointinpath" title=dom-context-2d-isPointInPath>isPointInPath</a>(in float x, in float y); - - // drawing images - void <a href="#drawimage" title=dom-context-2d-drawImage>drawImage</a>(in <a href="#htmlimageelement">HTMLImageElement</a> image, in float dx, in float dy); - void <a href="#drawimage" title=dom-context-2d-drawImage>drawImage</a>(in <a href="#htmlimageelement">HTMLImageElement</a> image, in float dx, in float dy, in float dw, in float dh); - void <a href="#drawimage" title=dom-context-2d-drawImage>drawImage</a>(in <a href="#htmlimageelement">HTMLImageElement</a> image, in float sx, in float sy, in float sw, in float sh, in float dx, in float dy, in float dw, in float dh); - void <a href="#drawimage" title=dom-context-2d-drawImage>drawImage</a>(in <a href="#htmlcanvaselement">HTMLCanvasElement</a> image, in float dx, in float dy); - void <a href="#drawimage" title=dom-context-2d-drawImage>drawImage</a>(in <a href="#htmlcanvaselement">HTMLCanvasElement</a> image, in float dx, in float dy, in float dw, in float dh); - void <a href="#drawimage" title=dom-context-2d-drawImage>drawImage</a>(in <a href="#htmlcanvaselement">HTMLCanvasElement</a> image, in float sx, in float sy, in float sw, in float sh, in float dx, in float dy, in float dw, in float dh); - - // pixel manipulation - <a href="#imagedata">ImageData</a> <a href="#getimagedata" title=dom-context-2d-getImageData>getImageData</a>(in float sx, in float sy, in float sw, in float sh); - void <a href="#putimagedata" title=dom-context-2d-putImageData>putImageData</a>(in <a href="#imagedata">ImageData</a> image, in float dx, in float dy); - - // drawing text is not supported in this version of the API - // (there is no way to predict what metrics the fonts will have, - // which makes fonts very hard to use for painting) - -}; - -interface <dfn id=canvasgradient>CanvasGradient</dfn> { - // opaque object - void <a href="#addcolorstop" title=dom-canvasgradient-addColorStop>addColorStop</a>(in float offset, in DOMString color); -}; - -interface <dfn id=canvaspattern>CanvasPattern</dfn> { - // opaque object -}; - -interface <dfn id=imagedata>ImageData</dfn> { - readonly attribute long int <a href="#width5" title=dom-imagedata-width>width</a>; - readonly attribute long int <a href="#height5" title=dom-imagedata-height>height</a>; - readonly attribute int[] <a href="#data1" title=dom-imagedata-data>data</a>; -};</pre> - - <p>The <dfn id=canvas0 - title=dom-context-2d-canvas><code>canvas</code></dfn> attribute must - return the <code><a href="#canvas">canvas</a></code> element that the - context paints on. - - <h6 id=the-canvas0><span class=secno>3.14.11.1.1. </span>The canvas state</h6> - - <p>Each context maintains a stack of drawing states. <dfn id=drawing0 - title="drawing state">Drawing states</dfn> consist of: - - <ul class=brief> - <li>The current transformation matrix. - - <li>The current clip region. - - <li>The current values of the following attributes: <code - title=dom-context-2d-strokeStyle><a - href="#strokestyle">strokeStyle</a></code>, <code - title=dom-context-2d-fillStyle><a href="#fillstyle">fillStyle</a></code>, - <code title=dom-context-2d-globalAlpha><a - href="#globalalpha">globalAlpha</a></code>, <code - title=dom-context-2d-lineWidth><a href="#linewidth">lineWidth</a></code>, - <code title=dom-context-2d-lineCap><a href="#linecap">lineCap</a></code>, - <code title=dom-context-2d-lineJoin><a - href="#linejoin">lineJoin</a></code>, <code - title=dom-context-2d-miterLimit><a - href="#miterlimit">miterLimit</a></code>, <code - title=dom-context-2d-shadowOffsetX><a - href="#shadowoffsetx">shadowOffsetX</a></code>, <code - title=dom-context-2d-shadowOffsetY><a - href="#shadowoffsety">shadowOffsetY</a></code>, <code - title=dom-context-2d-shadowBlur><a - href="#shadowblur">shadowBlur</a></code>, <code - title=dom-context-2d-shadowColor><a - href="#shadowcolor">shadowColor</a></code>, <code - title=dom-context-2d-globalCompositeOperation><a - href="#globalcompositeoperation">globalCompositeOperation</a></code>. - </ul> - - <p class=note>The current path and the current bitmap are not part of the - drawing state. The current path is persistent, and can only be reset using - the <code title=dom-context-2d-beginPath><a - href="#beginpath">beginPath()</a></code> method. The current bitmap is - <span title=concept-canvas-image>a property of the - canvas</span><!-- XXX xref -->, not the context. - - <p>The <dfn id=save title=dom-context-2d-save><code>save()</code></dfn> - method must push a copy of the current drawing state onto the drawing - state stack. - - <p>The <dfn id=restore - title=dom-context-2d-restore><code>restore()</code></dfn> method must pop - the top entry in the drawing state stack, and reset the drawing state it - describes. If there is no saved state, the method must do nothing. - - <h6 id=transformations><span class=secno>3.14.11.1.2. </span><dfn - id=transformations0>Transformations</dfn></h6> - - <p>The transformation matrix is applied to all drawing operations prior to - their being rendered. It is also applied when creating the clip region.</p> - <!-- conformance criteria for actual drawing are - described in "drawing model" below --> - - <p>When the context is created, the transformation matrix must initially be - the identity transform. It may then be adjusted using the transformation - methods. - - <p>The transformation matrix can become infinite, at which point nothing is - drawn anymore.</p> - <!-- - Philip Taylor wrote: - > My experience with some 3d canvas code is that infinities come up in - > naturally harmless places, e.g. having a function that scales by x then - > translates by 1/x and wanting it to work when x=0 (which ought to draw - > nothing, since anything it draws is zero pixels wide), and it's a bit - > annoying to track down and fix those issues, so I'd probably like it if - > they were harmless in canvas methods. Opera appears to silently not draw - > anything if the transformation matrix is not finite, but Firefox throws - > exceptions when passing in non-finite arguments. - --> - - <p>The transformations must be performed in reverse order. For instance, if - a scale transformation that doubles the width is applied, followed by a - rotation transformation that rotates drawing operations by a quarter turn, - and a rectangle twice as wide as it is tall is then drawn on the canvas, - the actual result will be a square. - - <p>The <dfn id=scale title=dom-context-2d-scale><code>scale(<var - title="">x</var>, <var title="">y</var>)</code></dfn> method must add the - scaling transformation described by the arguments to the transformation - matrix. The <var title="">x</var> argument represents the scale factor in - the horizontal direction and the <var title="">y</var> argument represents - the scale factor in the vertical direction. The factors are multiples. If - either argument is Infinity the transformation matrix must be marked as - infinite instead of the method throwing an exception. - - <p>The <dfn id=rotate title=dom-context-2d-rotate><code>rotate(<var - title="">angle</var>)</code></dfn> method must add the rotation - transformation described by the argument to the transformation matrix. The - <var title="">angle</var> argument represents a clockwise rotation angle - expressed in radians. - - <p>The <dfn id=translate - title=dom-context-2d-translate><code>translate(<var title="">x</var>, <var - title="">y</var>)</code></dfn> method must add the translation - transformation described by the arguments to the transformation matrix. - The <var title="">x</var> argument represents the translation distance in - the horizontal direction and the <var title="">y</var> argument represents - the translation distance in the vertical direction. The arguments are in - coordinate space units. If either argument is Infinity the transformation - matrix must be marked as infinite instead of the method throwing an - exception. - - <p>The <dfn id=transform - title=dom-context-2d-transform><code>transform(<var title="">m11</var>, - <var title="">m12</var>, <var title="">m21</var>, <var title="">m22</var>, - <var title="">dx</var>, <var title="">dy</var>)</code></dfn> method must - multiply the current transformation matrix with the matrix described by: - - <table class=matrix> - <tbody> - <tr> - <td><var title="">m11</var> - - <td><var title="">m21</var> - - <td><var title="">dx</var> - - <tr> - <td><var title="">m12</var> - - <td><var title="">m22</var> - - <td><var title="">dy</var> - - <tr> - <td>0 - - <td>0 - - <td>1 - </table> - - <p>If any of the arguments are Infinity the transformation matrix must be - marked as infinite instead of the method throwing an exception. - - <p>The <dfn id=settransform - title=dom-context-2d-setTransform><code>setTransform(<var - title="">m11</var>, <var title="">m12</var>, <var title="">m21</var>, <var - title="">m22</var>, <var title="">dx</var>, <var - title="">dy</var>)</code></dfn> method must reset the current transform to - the identity matrix, and then invoke the <code><a href="#transform" - title=dom-context-2d-transform>transform</a>(<var title="">m11</var>, <var - title="">m12</var>, <var title="">m21</var>, <var title="">m22</var>, <var - title="">dx</var>, <var title="">dy</var>)</code> method with the same - arguments. If any of the arguments are Infinity the transformation matrix - must be marked as infinite instead of the method throwing an exception. - - <h6 id=compositing><span class=secno>3.14.11.1.3. </span>Compositing</h6> - - <p>All drawing operations are affected by the global compositing - attributes, <code title=dom-context-2d-globalAlpha><a - href="#globalalpha">globalAlpha</a></code> and <code - title=dom-context-2d-globalCompositeOperation><a - href="#globalcompositeoperation">globalCompositeOperation</a></code>.</p> - <!-- conformance criteria for painting are described in the "drawing - model" section below --> - - <p>The <dfn id=globalalpha - title=dom-context-2d-globalAlpha><code>globalAlpha</code></dfn> attribute - gives an alpha value that is applied to shapes and images before they are - composited onto the canvas. The value must be in the range from 0.0 (fully - transparent) to 1.0 (no additional transparency). If an attempt is made to - set the attribute to a value outside this range, the attribute must retain - its previous value. When the context is created, the <code - title=dom-context-2d-globalAlpha><a - href="#globalalpha">globalAlpha</a></code> attribute must initially have - the value 1.0. - - <p>The <dfn id=globalcompositeoperation - title=dom-context-2d-globalCompositeOperation><code>globalCompositeOperation</code></dfn> - attribute sets how shapes and images are drawn onto the existing bitmap, - once they have had <code title=dom-context-2d-globalAlpha><a - href="#globalalpha">globalAlpha</a></code> and the current transformation - matrix applied. It must be set to a value from the following list. In the - descriptions below, the source image, <var title="">A</var>, is the shape - or image being rendered, and the destination image, <var title="">B</var>, - is the current state of the bitmap. - - <dl> - <dt><dfn id=source-atop - title=gcop-source-atop><code>source-atop</code></dfn> - - <dd><var title="">A</var> atop <var title="">B</var>. Display the source - image wherever both images are opaque. Display the destination image - wherever the destination image is opaque but the source image is - transparent. Display transparency elsewhere. - - <dt><dfn id=source-in title=gcop-source-in><code>source-in</code></dfn> - - <dd><var title="">A</var> in <var title="">B</var>. Display the source - image wherever both the source image and destination image are opaque. - Display transparency elsewhere. - - <dt><dfn id=source-out title=gcop-source-out><code>source-out</code></dfn> - - <dd><var title="">A</var> out <var title="">B</var>. Display the source - image wherever the source image is opaque and the destination image is - transparent. Display transparency elsewhere. - - <dt><dfn id=source-over - title=gcop-source-over><code>source-over</code></dfn> (default) - - <dd><var title="">A</var> over <var title="">B</var>. Display the source - image wherever the source image is opaque. Display the destination image - elsewhere. - - <dt><dfn id=destination-atop - title=gcop-destination-atop><code>destination-atop</code></dfn> - - <dd><var title="">B</var> atop <var title="">A</var>. Same as <code - title=gcop-source-atop><a href="#source-atop">source-atop</a></code> but - using the destination image instead of the source image and vice versa. - - <dt><dfn id=destination-in - title=gcop-destination-in><code>destination-in</code></dfn> - - <dd><var title="">B</var> in <var title="">A</var>. Same as <code - title=gcop-source-in><a href="#source-in">source-in</a></code> but using - the destination image instead of the source image and vice versa. - - <dt><dfn id=destination-out - title=gcop-destination-out><code>destination-out</code></dfn> - - <dd><var title="">B</var> out <var title="">A</var>. Same as <code - title=gcop-source-out><a href="#source-out">source-out</a></code> but - using the destination image instead of the source image and vice versa. - - <dt><dfn id=destination-over - title=gcop-destination-over><code>destination-over</code></dfn> - - <dd><var title="">B</var> over <var title="">A</var>. Same as <code - title=gcop-source-over><a href="#source-over">source-over</a></code> but - using the destination image instead of the source image and vice versa.</dd> - <!-- no clear definition of this operator (doesn't correspond to a PorterDuff operator) - <dt><dfn title="gcop-darker"><code>darker</code></dfn></dt> - - <dd>Display the sum of the source image and destination image, - with color values approaching 0 as a limit.</dd> ---> - - <dt><dfn id=lighter title=gcop-lighter><code>lighter</code></dfn> - - <dd><var title="">A</var> plus <var title="">B</var>. Display the sum of - the source image and destination image, with color values approaching 1 - as a limit. - - <dt><dfn id=copy title=gcop-copy><code>copy</code></dfn> - - <dd><var title="">A</var> (<var title="">B</var> is ignored). Display the - source image instead of the destination image. - - <dt><dfn id=xor title=gcop-xor><code>xor</code></dfn> - - <dd><var title="">A</var> xor <var title="">B</var>. Exclusive OR of the - source image and destination image. - - <dt><code><var title="">vendorName</var>-<var - title="">operationName</var></code> - - <dd>Vendor-specific extensions to the list of composition operators should - use this syntax. - </dl> - - <p>These values are all case-sensitive — they must be used exactly as - shown. User agents must only recognise values that exactly match the - values given above. - - <p>The operators in the above list must be treated as described by the - Porter-Duff operator given at the start of their description (e.g. <var - title="">A</var> over <var title="">B</var>). <a - href="#refsPORTERDUFF">[PORTERDUFF]</a></p> - <!-- - <dd id="refsPORTERDUFF">[PORTERDUFF]</dd> - <dd><cite>Compositing Digital Images</cite>, SIGGRAPH '84: Proceedings of the 11th annual conference on Computer graphics and interactive techniques, Volume 18, Number 3, T. Porter, T Duff. ACM Press, July 1984. ISBN 0-89791-138-5.</dd> - --> - - <p>On setting, if the user agent does not recognise the specified value, it - must be ignored, leaving the value of <code - title=dom-context-2d-globalCompositeOperation><a - href="#globalcompositeoperation">globalCompositeOperation</a></code> - unaffected. - - <p>When the context is created, the <code - title=dom-context-2d-globalCompositeOperation><a - href="#globalcompositeoperation">globalCompositeOperation</a></code> - attribute must initially have the value <code>source-over</code>. - - <h6 id=colors><span class=secno>3.14.11.1.4. </span>Colors and styles</h6> - - <p>The <dfn id=strokestyle - title=dom-context-2d-strokeStyle><code>strokeStyle</code></dfn> attribute - represents the color or style to use for the lines around shapes, and the - <dfn id=fillstyle - title=dom-context-2d-fillStyle><code>fillStyle</code></dfn> attribute - represents the color or style to use inside the shapes. - - <p>Both attributes can be either strings, <code><a - href="#canvasgradient0">CanvasGradient</a></code>s, or <code><a - href="#canvaspattern0">CanvasPattern</a></code>s. On setting, strings must - be parsed as CSS <color> values and the color assigned, and <code><a - href="#canvasgradient0">CanvasGradient</a></code> and <code><a - href="#canvaspattern0">CanvasPattern</a></code> objects must be assigned - themselves. <a href="#refsCSS3COLOR">[CSS3COLOR]</a> If the value is a - string but is not a valid color, or is neither a string, a <code><a - href="#canvasgradient0">CanvasGradient</a></code>, nor a <code><a - href="#canvaspattern0">CanvasPattern</a></code>, then it must be ignored, - and the attribute must retain its previous value. - - <p>On getting, if the value is a color, then: if it has alpha equal to 1.0, - then the color must be returned as a lowercase six-digit hex value, - prefixed with a "#" character (U+0023 NUMBER SIGN), with the first two - digits representing the red component, the next two digits representing - the green component, and the last two digits representing the blue - component, the digits being in the range 0-9 a-f (U+0030 to U+0039 and - U+0061 to U+0066). If the value has alpha less than 1.0, then the value - must instead be returned in the CSS <code title="">rgba()</code> - functional-notation format: the literal string <code title="">rgba</code> - (U+0072 U+0067 U+0062 U+0061) followed by a U+0028 LEFT PARENTHESIS, a - base-ten integer in the range 0-255 representing the red component (using - digits 0-9, U+0030 to U+0039, in the shortest form possible), a literal - U+002C COMMA and U+0020 SPACE, an integer for the green component, a comma - and a space, an integer for the blue component, another comma and space, a - U+0030 DIGIT ZERO, a U+002E FULL STOP (representing the decimal point), - one or more digits in the range 0-9 (U+0030 to U+0039) representing the - fractional part of the alpha value, and finally a U+0029 RIGHT - PARENTHESIS. - - <p>Otherwise, if it is not a color but a <code><a - href="#canvasgradient0">CanvasGradient</a></code> or <code><a - href="#canvaspattern0">CanvasPattern</a></code>, then the respective - object must be returned. (Such objects are opaque and therefore only - useful for assigning to other attributes or for comparison to other - gradients or patterns.) - - <p>When the context is created, the <code - title=dom-context-2d-strokeStyle><a - href="#strokestyle">strokeStyle</a></code> and <code - title=dom-context-2d-fillStyle><a href="#fillstyle">fillStyle</a></code> - attributes must initially have the string value <code - title="">#000000</code>. - - <p>There are two types of gradients, linear gradients and radial gradients, - both represented by objects implementing the opaque <dfn - id=canvasgradient0><code>CanvasGradient</code></dfn> interface. - - <p>Once a gradient has been created (see below), stops are placed along it - to define how the colors are distributed along the gradient. The color of - the gradient at each stop is the color specified for that stop. Between - each such stop, the colors and the alpha component must be linearly - interpolated over the RGBA space without premultiplying the alpha value to - find the color to use at that offset. Before the first stop, the color - must be the color of the first stop. After the last stop, the color must - be the color of the last stop. When there are no stops, the gradient is - transparent black. - - <p>The <dfn id=addcolorstop - title=dom-canvasgradient-addColorStop><code>addColorStop(<var - title="">offset</var>, <var title="">color</var>)</code></dfn> method on - the <code><a href="#canvasgradient0">CanvasGradient</a></code> interface - adds a new stop to a gradient. If the <var title="">offset</var> is less - than 0 or greater than 1 then an <code>INDEX_SIZE_ERR</code> exception - must be raised. If the <var title="">color</var> cannot be parsed as a CSS - color, then a <code>SYNTAX_ERR</code> exception must be raised. Otherwise, - the gradient must have a new stop placed, at offset <var - title="">offset</var> relative to the whole gradient, and with the color - obtained by parsing <var title="">color</var> as a CSS <color> - value. If multiple stops are added at the same offset on a gradient, they - must be placed in the order added, with the first one closest to the start - of the gradient, and each subsequent one infinitesimally further along - towards the end point (in effect causing all but the first and last stop - added at each point to be ignored). - - <p>The <dfn id=createlineargradient - title=dom-context-2d-createLinearGradient><code>createLinearGradient(<var - title="">x0</var>, <var title="">y0</var>, <var title="">x1</var>, <var - title="">y1</var>)</code></dfn> method takes four arguments, representing - the start point (<var title="">x0</var>, <var title="">y0</var>) and end - point (<var title="">x1</var>, <var title="">y1</var>) of the gradient, in - coordinate space units, and must return a linear <code><a - href="#canvasgradient0">CanvasGradient</a></code> initialised with that - line. - - <p>Linear gradients must be rendered such that at and before the starting - point on the canvas the color at offset 0 is used, that at and after the - ending point the color at offset 1 is used, and that all points on a line - perpendicular to the line that crosses the start and end points have the - color at the point where those two lines cross (with the colors coming - from the interpolation described above). - - <p>If <span><var title="">x<sub>0</sub></var> = <var - title="">x<sub>1</sub></var></span> and <span><var - title="">y<sub>0</sub></var> = <var - title="">y<sub>1</sub></var></span>, then the linear gradient must paint - nothing.</p> - <!-- XXX could make this paint the start colour, - or the end colour, or raise an exception --> - - <p>The <dfn id=createradialgradient - title=dom-context-2d-createRadialGradient><code>createRadialGradient(<var - title="">x0</var>, <var title="">y0</var>, <var title="">r0</var>, <var - title="">x1</var>, <var title="">y1</var>, <var - title="">r1</var>)</code></dfn> method takes six arguments, the first - three representing the start circle with origin (<var title="">x0</var>, - <var title="">y0</var>) and radius <var title="">r0</var>, and the last - three representing the end circle with origin (<var title="">x1</var>, - <var title="">y1</var>) and radius <var title="">r1</var>. The values are - in coordinate space units. The method must return a radial <code><a - href="#canvasgradient0">CanvasGradient</a></code> initialised with those - two circles. If either of <var title="">r0</var> or <var title="">r1</var> - are negative, an <code>INDEX_SIZE_ERR</code> exception must be raised. - - <p>Radial gradients must be rendered by following these steps: - - <ol> - <li> - <p>Let <span>x(<var title="">ω</var>) = (<var - title="">x<sub>1</sub></var>-<var title="">x<sub>0</sub></var>)<var - title="">ω</var> + <var - title="">x<sub>0</sub></var></span></p> - - <p>Let <span>y(<var title="">ω</var>) = (<var - title="">y<sub>1</sub></var>-<var title="">y<sub>0</sub></var>)<var - title="">ω</var> + <var - title="">y<sub>0</sub></var></span></p> - - <p>Let <span>r(<var title="">ω</var>) = (<var - title="">r<sub>1</sub></var>-<var title="">r<sub>0</sub></var>)<var - title="">ω</var> + <var - title="">r<sub>0</sub></var></span></p> - - <p>Let the color at <var title="">ω</var> be the color of the - gradient at offset 0.0 for all values of <var title="">ω</var> - less than 0.0, the color at offset 1.0 for all values of <var - title="">ω</var> greater than 1.0, and the color at the given - offset for values of <var title="">ω</var> in the range - <span>0.0 ≤ <var - title="">ω</var> ≤ 1.0</span> - - <li> - <p>For all values of <var title="">ω</var> where <span>r(<var - title="">ω</var>) > 0</span>, starting with the value - of <var title="">ω</var> nearest to positive infinity and ending - with the value of <var title="">ω</var> nearest to negative - infinity, draw the circumference of the circle with radius <span>r(<var - title="">ω</var>)</span> at position (<span>x(<var - title="">ω</var>)</span>, <span>y(<var - title="">ω</var>)</span>), with the color at <var - title="">ω</var>, but only painting on the parts of the canvas - that have not yet been painted on by earlier circles in this step for - this rendering of the gradient. - </ol> - - <p>If <span><var title="">x<sub>0</sub></var> = <var - title="">x<sub>1</sub></var></span> and <span><var - title="">y<sub>0</sub></var> = <var - title="">y<sub>1</sub></var></span> and <span><var - title="">r<sub>0</sub></var> = <var - title="">r<sub>1</sub></var></span>, then the radial gradient must paint - nothing.</p> - <!-- XXX could make this paint the start colour, - or the end colour, or a circle of one in the other, or raise an - exception --> - - <p class=note>This effectively creates a cone, touched by the two circles - defined in the creation of the gradient, with the part of the cone before - the start circle (0.0) using the color of the first offset, the part of - the cone after the end circle (1.0) using the color of the last offset, - and areas outside the cone untouched by the gradient (transparent black). - - <p>Gradients must only be painted where the relevant stroking or filling - effects requires that they be drawn. - - <p>Support for actually painting gradients is optional. Instead of painting - the gradients, user agents may instead just paint the first stop's color. - However, <code title=dom-context-2d-createLinearGradient><a - href="#createlineargradient">createLinearGradient()</a></code> and <code - title=dom-context-2d-createRadialGradient><a - href="#createradialgradient">createRadialGradient()</a></code> must always - return objects when passed valid arguments. - - <p>Patterns are represented by objects implementing the opaque <dfn - id=canvaspattern0><code>CanvasPattern</code></dfn> interface. - - <p>To create objects of this type, the <dfn id=createpatternimage - title=dom-context-2d-createPattern><code>createPattern(image, - repetition)</code></dfn> method is used. The first argument gives the - image to use as the pattern (either an <code><a - href="#htmlimageelement">HTMLImageElement</a></code> or an <code><a - href="#htmlcanvaselement">HTMLCanvasElement</a></code>). Modifying this - image after calling the <code title=dom-context-2d-createPattern><a - href="#createpatternimage">createPattern()</a></code> method must not - affect the pattern. The second argument must be a string with one of the - following values: <code title="">repeat</code>, <code - title="">repeat-x</code>, <code title="">repeat-y</code>, <code - title="">no-repeat</code>. If the empty string or null is specified, <code - title="">repeat</code> must be assumed. If an unrecognised value is given, - then the user agent must raise a <code>SYNTAX_ERR</code> exception. User - agents must recognise the four values described above exactly (e.g. they - must not do case folding). The method must return a <code><a - href="#canvaspattern0">CanvasPattern</a></code> object suitably - initialised. - - <p>The <var title="">image</var> argument must be an instance of an - <code><a href="#htmlimageelement">HTMLImageElement</a></code> or <code><a - href="#htmlcanvaselement">HTMLCanvasElement</a></code>. If the <var - title="">image</var> is of the wrong type, the implementation must raise a - <code>TYPE_MISMATCH_ERR</code> exception. If the <var title="">image</var> - argument is an <code><a - href="#htmlimageelement">HTMLImageElement</a></code> object whose <code - title=dom-attr-complete>complete</code> attribute is false, then the - implementation must raise an <code>INVALID_STATE_ERR</code> exception. - - <p>Patterns must be painted so that the top left of the first image is - anchored at the origin of the coordinate space, and images are then - repeated horizontally to the left and right (if the <code>repeat-x</code> - string was specified) or vertically up and down (if the - <code>repeat-y</code> string was specified) or in all four directions all - over the canvas (if the <code>repeat</code> string was specified). The - images are not be scaled by this process; one CSS pixel of the image must - be painted on one coordinate space unit. Of course, patterns must only - actually painted where the stroking or filling effect requires that they - be drawn, and are affected by the current transformation matrix. - - <p>Support for patterns is optional. If the user agent doesn't support - patterns, then <code title=dom-context-2d-createPattern><a - href="#createpatternimage">createPattern()</a></code> must return null.</p> - <!-- - XXXv3 Requests for v3 features: - * apply transforms to patterns, so you don't have to create - transformed patterns manually by rendering them to an off-screen - canvas then using that canvas as the pattern. - --> - - <h6 id=line-styles><span class=secno>3.14.11.1.5. </span>Line styles</h6> - - <p>The <dfn id=linewidth - title=dom-context-2d-lineWidth><code>lineWidth</code></dfn> attribute - gives the default width of lines, in coordinate space units. On setting, - zero and negative values must be ignored, leaving the value unchanged. - - <p>When the context is created, the <code title=dom-context-2d-lineWidth><a - href="#linewidth">lineWidth</a></code> attribute must initially have the - value <code>1.0</code>. - - <p>The <dfn id=linecap - title=dom-context-2d-lineCap><code>lineCap</code></dfn> attribute defines - the type of endings that UAs shall place on the end of lines. The three - valid values are <code>butt</code>, <code>round</code>, and - <code>square</code>. The <code>butt</code> value means that the end of - each line is a flat edge perpendicular to the direction of the line. The - <code>round</code> value means that a semi-circle with the diameter equal - to the width of the line is then added on to the end of the line. The - <code>square</code> value means that at the end of each line is a - rectangle with the length of the line width and the width of half the line - width, placed flat against the edge perpendicular to the direction of the - line. On setting, any other value than the literal strings - <code>butt</code>, <code>round</code>, and <code>square</code> must be - ignored, leaving the value unchanged. - - <p>When the context is created, the <code title=dom-context-2d-lineCap><a - href="#linecap">lineCap</a></code> attribute must initially have the value - <code>butt</code>. - - <p>The <dfn id=linejoin - title=dom-context-2d-lineJoin><code>lineJoin</code></dfn> attribute - defines the type of corners that that UAs will place where two lines meet. - The three valid values are <code>round</code>, <code>bevel</code>, and - <code>miter</code>. - - <p>On setting, any other value than the literal strings <code>round</code>, - <code>bevel</code> and <code>miter</code> must be ignored, leaving the - value unchanged. - - <p>When the context is created, the <code title=dom-context-2d-lineJoin><a - href="#linejoin">lineJoin</a></code> attribute must initially have the - value <code>miter</code>. - - <p>The <code>round</code> value means that a filled arc connecting the - corners on the outside of the join, with the diameter equal to the line - width, and the origin at the point where the inside edges of the lines - touch, must be rendered at joins. The <code>bevel</code> value means that - a filled triangle connecting those two corners with a straight line, the - third point of the triangle being the point where the lines touch on the - inside of the join, must be rendered at joins. The <code>miter</code> - value means that a filled four- or five-sided polygon must be placed at - the join, with two of the lines being the perpendicular edges of the - joining lines, and the other two being continuations of the outside edges - of the two joining lines, as long as required to intersect without going - over the miter limit. - - <p>The miter length is the distance from the point where the lines touch on - the inside of the join to the intersection of the line edges on the - outside of the join. The miter limit ratio is the maximum allowed ratio of - the miter length to the line width. If the miter limit would be exceeded, - then a fifth line must be added to the polygon, connecting the two outside - lines, such that the distance from the inside point of the join to the - point in the middle of this fifth line is the maximum allowed value for - the miter length. - - <p>The miter limit ratio can be explicitly set using the <dfn id=miterlimit - title=dom-context-2d-miterLimit><code>miterLimit</code></dfn> attribute. - On setting, zero and negative values must be ignored, leaving the value - unchanged. - - <p>When the context is created, the <code - title=dom-context-2d-miterLimit><a - href="#miterlimit">miterLimit</a></code> attribute must initially have the - value <code>10.0</code>.</p> - <!-- XXX this section doesn't say what these attributes return or - what they do on setting. not a big deal; it's pretty obvious. but if - anyone complains, we'll have to add it --> - <!-- -XXXv3 dashed lines have been requested. Philip Taylor provides these -notes on what would need to be defined for dashed lines: -> I don't think it's entirely trivial to add, to the detail that's -> necessary in a specification. The common graphics APIs (at least -> Cairo, Quartz and java.awt.Graphics, and any SVG implementation) all -> have dashes specified by passing an array of dash lengths (alternating -> on/off), so that should be alright as long as you define what units -> it's measured in and what happens when you specify an odd number of -> values and how errors are handled and what happens if you update the -> array later. But after that, what does it do when stroking multiple -> subpaths, in terms of offsetting the dashes? When you use strokeRect, -> where is offset 0? Does moveTo reset the offset? How does it interact -> with lineCap/lineJoin? All the potential issues need test cases too, -> and the implementations need to make sure they handle any edge cases -> that the underlying graphics library does differently. (SVG Tiny 1.2 -> appears to skip some of the problems by leaving things undefined and -> allowing whatever behaviour the graphics library has.) - --> - - <h6 id=shadows><span class=secno>3.14.11.1.6. </span><dfn - id=shadows0>Shadows</dfn></h6> - - <p>All drawing operations are affected by the four global shadow - attributes. Shadows form part of the source image during composition. - - <p>The <dfn id=shadowcolor - title=dom-context-2d-shadowColor><code>shadowColor</code></dfn> attribute - sets the color of the shadow.</p> - <!-- XXX this section doesn't say what this attributes returns or - what they do on setting. if anyone complains, we'll have to add - it. shadowColor is a CSS Color attribute. --> - - <p>When the context is created, the <code - title=dom-context-2d-shadowColor><a - href="#shadowcolor">shadowColor</a></code> attribute initially must be - fully-transparent black. - - <p>The <dfn id=shadowoffsetx - title=dom-context-2d-shadowOffsetX><code>shadowOffsetX</code></dfn> and - <dfn id=shadowoffsety - title=dom-context-2d-shadowOffsetY><code>shadowOffsetY</code></dfn> - attributes specify the distance that the shadow will be offset in the - positive horizontal and positive vertical distance respectively. Their - values are in coordinate space units.</p> - <!-- XXX we don't define getting/setting --> - - <p>When the context is created, the shadow offset attributes initially have - the value <code>0</code>. - - <p>The <dfn id=shadowblur - title=dom-context-2d-shadowBlur><code>shadowBlur</code></dfn> attribute - specifies the number of coordinate space units that the blurring is to - cover. On setting, negative numbers must be ignored, leaving the attribute - unmodified.</p> - <!-- XXX we don't define getting/setting --> - - <p>When the context is created, the <code - title=dom-context-2d-shadowBlur><a - href="#shadowblur">shadowBlur</a></code> attribute must initially have the - value <code>0</code>. - - <p>Support for shadows is optional. When they are supported, then, when - shadows are drawn, they must be rendered using the specified color, - offset, and blur radius.</p> - <!-- XXX we don't really define what that means --> - - <h6 id=simple><span class=secno>3.14.11.1.7. </span>Simple shapes - (rectangles)</h6> - - <p>There are three methods that immediately draw rectangles to the bitmap. - They each take four arguments; the first two give the <var - title="">x</var> and <var title="">y</var> coordinates of the top left of - the rectangle, and the second two give the width and height of the - rectangle, respectively. - - <p>Shapes are painted without affecting the current path, and are subject - to <span title=dom-context-2d->transformations</span>, <a href="#shadows0" - title=shadows>shadow effects</a>, <span title=globalAlpha>global - alpha</span>, <a href="#clipping" title="clipping path">clipping - paths</a>, and <span title=globalCompositeOperation>global composition - operators</span>. - - <p>Negative values for width and height must cause the implementation to - raise an <code>INDEX_SIZE_ERR</code> exception. - - <p>The <dfn id=clearrect - title=dom-context-2d-clearRect><code>clearRect()</code></dfn> method must - clear the pixels in the specified rectangle to a fully transparent black, - erasing any previous image. If either height or width are zero, this - method has no effect. - - <p>The <dfn id=fillrect - title=dom-context-2d-fillRect><code>fillRect()</code></dfn> method must - paint the specified rectangular area using the <code - title=dom-context-2d-fillStyle><a href="#fillstyle">fillStyle</a></code>. - If either height or width are zero, this method has no effect. - - <p>The <dfn id=strokerect - title=dom-context-2d-strokeRect><code>strokeRect()</code></dfn> method - must draw stroke the path that would be created for the outline of a - rectangle of the specified size using the <code - title=dom-context-2d-strokeStyle><a - href="#strokestyle">strokeStyle</a></code>, <code - title=dom-context-2d-lineWidth><a href="#linewidth">lineWidth</a></code>, - <code title=dom-context-2d-lineJoin><a - href="#linejoin">lineJoin</a></code>, and (if appropriate) <code - title=dom-context-2d-miterLimit><a - href="#miterlimit">miterLimit</a></code> attributes. If both height and - width are zero, this method has no effect, since there is no path to - stroke (it's a point). If only one of the two is zero, then the method - will draw a line instead (the path for the outline is just a straight line - along the non-zero dimension). - - <h6 id=complex><span class=secno>3.14.11.1.8. </span>Complex shapes (paths)</h6> - - <p>The context always has a current path. There is only one current path, - it is not part of the <span title=dom-context-2d->drawing state</span>. - - <p>A <dfn id=path>path</dfn> has a list of zero or more subpaths. Each - subpath consists of a list of one or more points, connected by straight or - curved lines, and a flag indicating whether the subpath is closed or not. - A closed subpath is one where the last point of the subpath is connected - to the first point of the subpath by a straight line. Subpaths with fewer - than two points are ignored when painting the path. - - <p>Initially, the context's path must have zero subpaths. - - <p>The <dfn id=beginpath - title=dom-context-2d-beginPath><code>beginPath()</code></dfn> method must - empty the list of subpaths so that the context once again has zero - subpaths. - - <p>The <dfn id=moveto title=dom-context-2d-moveTo><code>moveTo(<var - title="">x</var>, <var title="">y</var>)</code></dfn> method must create a - new subpath with the specified point as its first (and only) point. - - <p>The <dfn id=closepath - title=dom-context-2d-closePath><code>closePath()</code></dfn> method must - do nothing if the context has no subpaths. Otherwise, it must mark the - last subpath as closed, create a new subpath whose first point is the same - as the previous subpath's first point, and finally add this new subpath to - the path. (If the last subpath had more than one point in its list of - points, then this is equivalent to adding a straight line connecting the - last point back to the first point, thus "closing" the shape, and then - repeating the last <code title=dom-context-2d-moveTo><a - href="#moveto">moveTo()</a></code> call.) - - <p>New points and the lines connecting them are added to subpaths using the - methods described below. In all cases, the methods only modify the last - subpath in the context's paths. - - <p>The <dfn id=lineto title=dom-context-2d-lineTo><code>lineTo(<var - title="">x</var>, <var title="">y</var>)</code></dfn> method must do - nothing if the context has no subpaths. Otherwise, it must connect the - last point in the subpath to the given point (<var title="">x</var>, <var - title="">y</var>) using a straight line, and must then add the given point - (<var title="">x</var>, <var title="">y</var>) to the subpath. - - <p>The <dfn id=quadraticcurveto - title=dom-context-2d-quadraticCurveTo><code>quadraticCurveTo(<var - title="">cpx</var>, <var title="">cpy</var>, <var title="">x</var>, <var - title="">y</var>)</code></dfn> method must do nothing if the context has - no subpaths. Otherwise it must connect the last point in the subpath to - the given point (<var title="">x</var>, <var title="">y</var>) by a - quadratic curve with control point (<var title="">cpx</var>, <var - title="">cpy</var>), and must then add the given point (<var - title="">x</var>, <var title="">y</var>) to the subpath. - - <p>The <dfn id=beziercurveto - title=dom-context-2d-bezierCurveTo><code>bezierCurveTo(<var - title="">cp1x</var>, <var title="">cp1y</var>, <var title="">cp2x</var>, - <var title="">cp2y</var>, <var title="">x</var>, <var - title="">y</var>)</code></dfn> method must do nothing if the context has - no subpaths. Otherwise, it must connect the last point in the subpath to - the given point (<var title="">x</var>, <var title="">y</var>) using a - bezier curve with control points (<var title="">cp1x</var>, <var - title="">cp1y</var>) and (<var title="">cp2x</var>, <var - title="">cp2y</var>). Then, it must add the point (<var title="">x</var>, - <var title="">y</var>) to the subpath. - - <p>The <dfn id=arcto title=dom-context-2d-arcTo><code>arcTo(<var - title="">x1</var>, <var title="">y1</var>, <var title="">x2</var>, <var - title="">y2</var>, <var title="">radius</var>)</code></dfn> method must do - nothing if the context has no subpaths. If the context <em>does</em> have - a subpath, then the behaviour depends on the arguments and the last point - in the subpath. - - <p>Let the point (<var title="">x0</var>, <var title="">y0</var>) be the - last point in the subpath. Let <var title="">The Arc</var> be the shortest - arc given by circumference of the circle that has one point tangent to the - line defined by the points (<var title="">x0</var>, <var - title="">y0</var>) and (<var title="">x1</var>, <var title="">y1</var>), - another point tangent to the line defined by the points (<var - title="">x1</var>, <var title="">y1</var>) and (<var title="">x2</var>, - <var title="">y2</var>), and that has radius <var title="">radius</var>. - The points at which this circle touches these two lines are called the - start and end tangent points respectively. - - <p>If the point (<var title="">x2</var>, <var title="">y2</var>) is on the - line defined by the points (<var title="">x0</var>, <var - title="">y0</var>) and (<var title="">x1</var>, <var title="">y1</var>) - then the method must do nothing, as no arc would satisfy the above - constraints. - - <p>Otherwise, the method must connect the point (<var title="">x0</var>, - <var title="">y0</var>) to the start tangent point by a straight line, - then connect the start tangent point to the end tangent point by <var - title="">The Arc</var>, and finally add the start and end tangent points - to the subpath. - - <p>Negative or zero values for <var title="">radius</var> must cause the - implementation to raise an <code>INDEX_SIZE_ERR</code> exception. - - <p>The <dfn id=arcx- title=dom-context-2d-arc><code>arc(<var - title="">x</var>, <var title="">y</var>, <var title="">radius</var>, <var - title="">startAngle</var>, <var title="">endAngle</var>, <var - title="">anticlockwise</var>)</code></dfn> method draws an arc. If the - context has any subpaths, then the method must add a straight line from - the last point in the subpath to the start point of the arc. In any case, - it must draw the arc between the start point of the arc and the end point - of the arc, and add the start and end points of the arc to the subpath. - The arc and its start and end points are defined as follows: - - <p>Consider a circle that has its origin at (<var title="">x</var>, <var - title="">y</var>) and that has radius <var title="">radius</var>. The - points at <var title="">startAngle</var> and <var title="">endAngle</var> - along the circle's circumference, measured in radians clockwise from the - positive x-axis, are the start and end points respectively. The arc is the - path along the circumference of this circle from the start point to the - end point, going anti-clockwise if the <var title="">anticlockwise</var> - argument is true, and clockwise otherwise. - - <p>Negative or zero values for <var title="">radius</var> must cause the - implementation to raise an <code>INDEX_SIZE_ERR</code> exception. - - <p>The <dfn id=rectx title=dom-context-2d-rect><code>rect(<var - title="">x</var>, <var title="">y</var>, <var title="">w</var>, <var - title="">h</var>)</code></dfn> method must create a new subpath containing - just the four points (<var title="">x</var>, <var title="">y</var>), (<var - title="">x</var>+<var title="">w</var>, <var title="">y</var>), (<var - title="">x</var>+<var title="">w</var>, <var title="">y</var>+<var - title="">h</var>), (<var title="">x</var>, <var title="">y</var>+<var - title="">h</var>), with those four points connected by straight lines, and - must then mark the subpath as closed. It must then create a new subpath - with the point (<var title="">x</var>, <var title="">y</var>) as the only - point in the subpath. - - <p>Negative values for <var title="">w</var> and <var title="">h</var> must - cause the implementation to raise an <code>INDEX_SIZE_ERR</code> - exception. - - <p>The <dfn id=fill title=dom-context-2d-fill><code>fill()</code></dfn> - method must fill each subpath of the current path in turn, using <code - title=dom-context-2d-fillStyle><a href="#fillstyle">fillStyle</a></code>, - and using the non-zero winding number rule. Open subpaths must be - implicitly closed when being filled (without affecting the actual - subpaths). - - <p>The <dfn id=stroke - title=dom-context-2d-stroke><code>stroke()</code></dfn> method must stroke - each subpath of the current path in turn, using the <code - title=dom-context-2d-strokeStyle><a - href="#strokestyle">strokeStyle</a></code>, <code - title=dom-context-2d-lineWidth><a href="#linewidth">lineWidth</a></code>, - <code title=dom-context-2d-lineJoin><a - href="#linejoin">lineJoin</a></code>, and (if appropriate) <code - title=dom-context-2d-miterLimit><a - href="#miterlimit">miterLimit</a></code> attributes. - - <p>Paths, when filled or stroked, must be painted without affecting the - current path, and must be subject to <a - href="#transformations0">transformations</a>, <a href="#shadows0" - title=shadows>shadow effects</a>, <a href="#globalalpha" - title=dom-context-2d-globalAlpha>global alpha</a>, <a href="#clipping" - title="clipping path">clipping paths</a>, and <a - href="#globalcompositeoperation" - title=dom-context-2d-globalCompositeOperation>global composition - operators</a>. - - <p class=note>The transformation is applied to the path when it is drawn, - not when the path is constructed. Thus, a single path can be constructed - and then drawn according to different transformations without recreating - the path. - - <p>The <dfn id=clip title=dom-context-2d-clip><code>clip()</code></dfn> - method must create a new <dfn id=clipping>clipping path</dfn> by - calculating the intersection of the current clipping path and the area - described by the current path (after applying the <span>current - transformation</span>), using the non-zero winding number rule. Open - subpaths must be implicitly closed when computing the clipping path, - without affecting the actual subpaths. - - <p>When the context is created, the initial clipping path is the rectangle - with the top left corner at (0,0) and the width and height of the - coordinate space.</p> - <!-- XXXv3 - Jordan OSETE suggests: - * support ways of extending the clip region (union instead of intersection) - - also "add", "substract", "replace", "intersect" and "xor" - * support ways of resetting the clip region without save/restore - --> - - <p>The <dfn id=ispointinpath - title=dom-context-2d-isPointInPath><code>isPointInPath(<var - title="">x</var>, <var title="">y</var>)</code></dfn> method must return - true if the point given by the <var title="">x</var> and <var - title="">y</var> coordinates passed to the method, when treated as - coordinates in the canvas' coordinate space unaffected by the current - transformation, is within the area of the canvas that would be filled if - the current path was to be filled; and must return false otherwise. - - <h6 id=images><span class=secno>3.14.11.1.9. </span>Images</h6> - - <p>To draw images onto the canvas, the <dfn id=drawimage - title=dom-context-2d-drawImage><code>drawImage</code></dfn> method can be - used. - - <p>This method is overloaded with three variants: <code - title="">drawImage(<var title="">image</var>, <var title="">dx</var>, <var - title="">dy</var>)</code>, <code title="">drawImage(<var - title="">image</var>, <var title="">dx</var>, <var title="">dy</var>, <var - title="">dw</var>, <var title="">dh</var>)</code>, and <code - title="">drawImage(<var title="">image</var>, <var title="">sx</var>, <var - title="">sy</var>, <var title="">sw</var>, <var title="">sh</var>, <var - title="">dx</var>, <var title="">dy</var>, <var title="">dw</var>, <var - title="">dh</var>)</code>. (Actually it is overloaded with six; each of - those three can take either an <code><a - href="#htmlimageelement">HTMLImageElement</a></code> or an <code><a - href="#htmlcanvaselement">HTMLCanvasElement</a></code> for the <var - title="">image</var> argument.) If not specified, the <var - title="">dw</var> and <var title="">dh</var> arguments default to the - values of <var title="">sw</var> and <var title="">sh</var>, interpreted - such that one CSS pixel in the image is treated as one unit in the canvas - coordinate space. If the <var title="">sx</var>, <var title="">sy</var>, - <var title="">sw</var>, and <var title="">sh</var> arguments are omitted, - they default to 0, 0, the image's intrinsic width in image pixels, and the - image's intrinsic height in image pixels, respectively. - - <p>The <var title="">image</var> argument must be an instance of an - <code><a href="#htmlimageelement">HTMLImageElement</a></code> or <code><a - href="#htmlcanvaselement">HTMLCanvasElement</a></code>. If the <var - title="">image</var> is of the wrong type, the implementation must raise a - <code>TYPE_MISMATCH_ERR</code> exception. If one of the <var - title="">sy</var>, <var title="">sw</var>, <var title="">sw</var>, and - <var title="">sh</var> arguments is outside the size of the image, or if - one of the <var title="">dw</var> and <var title="">dh</var> arguments is - negative, the implementation must raise an <code>INDEX_SIZE_ERR</code> - exception. If the <var title="">image</var> argument is an <code><a - href="#htmlimageelement">HTMLImageElement</a></code> object whose <code - title=dom-attr-complete>complete</code> attribute is false, then the - implementation must raise an <code>INVALID_STATE_ERR</code> exception. - - <p>When <code title=dom-context-2d-drawImage><a - href="#drawimage">drawImage()</a></code> is invoked, the specified region - of the image specified by the source rectangle (<var title="">sx</var>, - <var title="">sy</var>, <var title="">sw</var>, <var title="">sh</var>) - must be painted on the region of the canvas specified by the destination - rectangle (<var title="">dx</var>, <var title="">dy</var>, <var - title="">dw</var>, <var title="">dh</var>). - - <p><img alt="" src="images/drawImage.png"></p> - <!-- no alt="" text - since the image is just repeating what was stated in the previous - paragraph. --> - - <p>Images are painted without affecting the current path, and are subject - to <a href="#transformations0">transformations</a>, <a href="#shadows0" - title=shadows>shadow effects</a>, <a href="#globalalpha" - title=dom-context-2d-globalAlpha>global alpha</a>, <a href="#clipping" - title="clipping path">clipping paths</a>, and <a - href="#globalcompositeoperation" - title=dom-context-2d-globalCompositeOperation>global composition - operators</a>.</p> - <!-- XXX should somehow say that the image used is the actual image - of the target element, not the rendered image (e.g. height/width - attributes don't affect it --> - - <h6 id=pixel><span class=secno>3.14.11.1.10. </span><dfn id=pixel0>Pixel - manipulation</dfn></h6> - - <p>The <dfn id=getimagedata - title=dom-context-2d-getImageData><code>getImageData(<var - title="">sx</var>, <var title="">sy</var>, <var title="">sw</var>, <var - title="">sh</var>)</code></dfn> method must return an <code><a - href="#imagedata">ImageData</a></code> object representing the underlying - pixel data for the area of the canvas denoted by the rectangle which has - one corner at the (<var title="">sx</var>, <var title="">sy</var>) - coordinate, and that has width <var title="">sw</var> and height <var - title="">sh</var>. Pixels outside the canvas must be returned as - transparent black. Pixels must be returned as non-premultiplied alpha - values. - - <p><code><a href="#imagedata">ImageData</a></code> objects must be - initialised so that their <dfn id=height5 - title=dom-imagedata-height><code>height</code></dfn> attribute is set to - <var title="">h</var>, the number of rows in the image data, their <dfn - id=width5 title=dom-imagedata-width><code>width</code></dfn> attribute is - set to <var title="">w</var>, the number of physical device pixels per row - in the image data, and the <dfn id=data1 - title=dom-imagedata-data><code>data</code></dfn> attribute is initialised - to an array of <var title="">h</var>×<var title="">w</var>×4 - integers. The pixels must be represented in this array in left-to-right - order, row by row, starting at the top left, with each pixel's red, green, - blue, and alpha components being given in that order. Each component of - each device pixel represented in this array must be in the range 0..255, - representing the 8 bit value for that component. At least one pixel must - be returned. - - <p class=note>The width and height (<var title="">w</var> and <var - title="">h</var>) might be different than the <var title="">sw</var> and - <var title="">sh</var> arguments to the function, e.g. if the canvas is - backed by a high-resolution bitmap. - - <p>If the <code title=dom-context-2d-getImageData><a - href="#getimagedata">getImageData(<var title="">sx</var>, <var - title="">sy</var>, <var title="">sw</var>, <var - title="">sh</var>)</a></code> method is called with either the <var - title="">sw</var> or <var title="">sh</var> arguments set to zero or - negative values, the method must raise an <code>INDEX_SIZE_ERR</code> - exception. - - <p>The <dfn id=putimagedata - title=dom-context-2d-putImageData><code>putImageData(<var - title="">image</var>, <var title="">dx</var>, <var - title="">dy</var>)</code></dfn> method must take the given <code><a - href="#imagedata">ImageData</a></code> structure, and draw it at the - specified location <var title="">dx</var>,<var title="">dy</var> in the - canvas coordinate space, mapping each pixel represented by the <code><a - href="#imagedata">ImageData</a></code> structure into one device pixel. - - <p>If the first argument to the method is not an object whose [[Class]] - property is <code><a href="#imagedata">ImageData</a></code>, but all of - the following conditions are true, then the method must treat the first - argument as if it was an <code><a href="#imagedata">ImageData</a></code> - object (and thus not raise the <code>TYPE_MISMATCH_ERR</code> exception): - - <ul> - <li>The method's first argument is an object with <code - title=dom-imagedata-width><a href="#width5">width</a></code> and <code - title=dom-imagedata-height><a href="#height5">height</a></code> - attributes with integer values and a <code title=dom-imagedata-data><a - href="#data1">data</a></code> attribute whose value is an integer array. - - <li>The <code><a href="#imagedata">ImageData</a></code> object's <code - title=dom-imagedata-width><a href="#width5">width</a></code> is greater - than zero. - - <li>The <code><a href="#imagedata">ImageData</a></code> object's <code - title=dom-imagedata-height><a href="#height5">height</a></code> is - greater than zero. - - <li>The <code><a href="#imagedata">ImageData</a></code> object's <code - title=dom-imagedata-width><a href="#width5">width</a></code> multiplied - by its <code title=dom-imagedata-height><a - href="#height5">height</a></code> multiplied by 4 is equal to the number - of entries in the <code><a href="#imagedata">ImageData</a></code> - object's <code title=dom-imagedata-data><a href="#data1">data</a></code> - array. - - <li>The <code><a href="#imagedata">ImageData</a></code> object's <code - title=dom-imagedata-data><a href="#data1">data</a></code> array only - contains entries that are in the range 0 to 255 inclusive. - </ul> - - <p>The handling of pixel rounding when the specified coordinates do not - exactly map to the device coordinate space is not defined by this - specification, except that the following must result in no visible changes - to the rendering: - - <pre>context.putImageData(context.getImageData(x, y, w, h), x, y);</pre> - - <p>...for any value of <var title="">x</var> and <var title="">y</var>. In - other words, while user agents may round the arguments of the two methods - so that they map to device pixel boundaries, any rounding performed must - be performed consistently for both the <code - title=dom-context-2d-getImageData><a - href="#getimagedata">getImageData()</a></code> and <code - title=dom-context-2d-putImageData><a - href="#putimagedata">putImageData()</a></code> operations. - - <p>The current transformation matrix must not affect the <code - title=dom-context-2d-getImageData><a - href="#getimagedata">getImageData()</a></code> and <code - title=dom-context-2d-putImageData><a - href="#putimagedata">putImageData()</a></code> methods. - - <div class=example> - <p>The data returned by <code title=dom-context-2d-getImageData><a - href="#getimagedata">getImageData()</a></code> is at the resolution of - the canvas backing store, which is likely to not be one device pixel to - each CSS pixel if the display used is a high resolution display. Thus, - while one could create an <code><a href="#imagedata">ImageData</a></code> - object, one would net necessarily know what resolution the canvas - expected (how many pixels the canvas wants to paint over one coordinate - space unit pixel).</p> - - <p>In the following example, the script first obtains the size of the - canvas backing store, and then generates a few new <code><a - href="#imagedata">ImageData</a></code> objects which can be used.</p> - - <pre> - // canvas is a reference to a <canvas> element - // (note: this example uses JavaScript 1.7 features) - var context = canvas.getContext('2d'); - var backingStore = context.getImageData(0, 0, canvas.width, canvas.height); - var actualWidth = backingStore.width; - var actualHeight = backingStore.height; - - function CreateImageData(w, h) { - return { - height: h, - width: w, - data: [i for (i in function (n) { for (let i = 0; i < n; i += 1) yield 0 }(w*h*4)) ] - }; - } - - // create some plasma - var plasma = CreateImageData(actualWidth, actualHeight); - FillPlasma(plasma, 'green'); // green plasma - - // create a cloud - var could = CreateImageData(actualWidth, actualHeight); - FillCloud(cloud, actualWidth/2, actualHeight/2); // put a cloud in the middle - - // paint them on top of each other - context.putImageData(plasma, 0, 0); - context.putImageData(cloud, 0, 0); - - function FillPlasma(data) { ... } - function FillCload(data, x, y) { ... } -</pre> - </div> - - <h6 id=drawing><span class=secno>3.14.11.1.11. </span>Drawing model</h6> - - <p>When a shape or image is painted, user agents must follow these steps, - in the order given (or act as if they do): - - <ol> - <li>If the current transformation matrix is infinite, then do nothing. - Abort these steps. - - <li>The coordinates are transformed by the current transformation matrix. - - <li>The shape or image is rendered, creating image <var title="">A</var>, - as described in the previous sections. For shapes, the current fill, - stroke, and line styles must be honoured. - - <li>The shadow is rendered from image <var title="">A</var>, using the - current shadow styles, creating image <var title="">B</var>. - - <li>Image <var title="">A</var> is composited over image <var - title="">B</var> creating the source image. - - <li>The source image has its alpha adjusted by <code - title=dom-context-2d-globalAlpha><a - href="#globalalpha">globalAlpha</a></code>. - - <li>Within the clip region (as affected by the current transformation - matrix), the source image is composited over the current canvas bitmap - using the current composition operator. - </ol> - <!-- - <h5 id="3d">The 3D context</h5> - - <p class="big-issue">Well, one day.</p> ---> - - <h4 id=the-map><span class=secno>3.14.12. </span>The <dfn - id=map><code>map</code></dfn> element</h4> - - <p><a href="#block-level0" title="block-level elements">Block-level - element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> are expected. - - <dt>Content model: - - <dd>Zero or more <a href="#block-level0">block-level elements</a>. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmlmapelement>HTMLMapElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - readonly attribute <a href="#htmlcollection0">HTMLCollection</a> <a href="#areas" title=dom-map-areas>areas</a>; -};</pre> - </dl> - - <p>The <code><a href="#map">map</a></code> element, in conjuction with any - <code><a href="#area">area</a></code> element descendants, defines an <a - href="#image">image map</a>. - - <p>The <dfn id=areas title=dom-map-areas><code>areas</code></dfn> attribute - must return an <code><a href="#htmlcollection0">HTMLCollection</a></code> - rooted at the <code><a href="#map">map</a></code> element, whose filter - matches only <code><a href="#area">area</a></code> elements. - - <h4 id=the-area><span class=secno>3.14.13. </span>The <dfn - id=area><code>area</code></dfn> element</h4> - - <p><a href="#strictly">Strictly inline-level content</a>.</p> - <!-- XXX as defined, the area element on its own isn't enough to - satisfy "significant inline-level content" model. should it be? --> - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed, but only as a descendant of a <code><a - href="#map">map</a></code> element. - - <dt>Content model: - - <dd>Empty. - - <dt>Element-specific attributes: - - <dd><code title=attr-area-alt><a href="#alt1">alt</a></code> - - <dd><code title=attr-area-coords><a href="#coords">coords</a></code> - - <dd><code title=attr-area-shape><a href="#shape">shape</a></code> - - <dd><code title=attr-hyperlink-href><a href="#href6">href</a></code> - - <dd><code title=attr-hyperlink-target><a href="#target3">target</a></code> - - <dd><code title=attr-hyperlink-ping><a href="#ping">ping</a></code> - - <dd><code title=attr-hyperlink-rel><a href="#rel3">rel</a></code> - - <dd><code title=attr-hyperlink-media><a href="#media12">media</a></code> - - <dd><code title=attr-hyperlink-hreflang><a - href="#hreflang3">hreflang</a></code> - - <dd><code title=attr-hyperlink-type><a href="#type17">type</a></code> - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmlareaelement>HTMLAreaElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute DOMString <a href="#alt2" title=dom-area-alt>alt</a>; - attribute DOMString <a href="#coords0" title=dom-area-coords>coords</a>; - attribute DOMString <a href="#shape0" title=dom-area-shape>shape</a>; - attribute DOMString <a href="#href4" title=dom-area-href>href</a>; - attribute DOMString <a href="#target2" title=dom-area-target>target</a>; - attribute DOMString <a href="#ping1" title=dom-area-ping>ping</a>; - attribute DOMString <a href="#rel2" title=dom-area-rel>rel</a>; - readonly attribute DOMTokenList <a href="#rellist1" title=dom-area-relList>relList</a>; - attribute DOMString <a href="#media11" title=dom-area-media>media</a>; - attribute DOMString <a href="#hreflang2" title=dom-area-hreflang>hreflang</a>; - attribute DOMString <a href="#type10" title=dom-area-type>type</a>; -};</pre> - </dl> - - <p>The <code><a href="#area">area</a></code> element represents either a - hyperlink with some text and a corresponding area on an <a - href="#image">image map</a>, or a dead area on an image map. - - <p>If the <code><a href="#area">area</a></code> element has an <code - title=attr-hyperlink-href><a href="#href6">href</a></code> attribute, then - the <code><a href="#area">area</a></code> element represents a <a - href="#hyperlinks">hyperlink</a>; the <dfn id=alt1 - title=attr-area-alt><code>alt</code></dfn> attribute, which must then be - present, specifies the text. - - <p>However, if the <code><a href="#area">area</a></code> element has no - <code title=attr-hyperlink-href><a href="#href6">href</a></code> - attribute, then the area represented by the element cannot be selected, - and the <code title=attr-area-alt><a href="#alt1">alt</a></code> attribute - must be omitted. - - <p>In both cases, the <code title=attr-area-shape><a - href="#shape">shape</a></code> and <code title=attr-area-coords><a - href="#coords">coords</a></code> attributes specify the area. - - <p>The <dfn id=shape title=attr-area-shape><code>shape</code></dfn> - attribute is an <a href="#enumerated">enumerated attribute</a>. The - following table lists the keywords defined for this attribute. The states - given in the first cell of the the rows with keywords give the states to - which those keywords map. Some of the keywords are non-conforming, as - noted in the last column. - - <table> - <thead> - <tr> - <th>State - - <th>Keywords - - <th>Notes - - <tbody> - <tr> - <td rowspan=2><dfn id=circle title=attr-area-shape-circle>Circle - state</dfn> - - <td><code title="">circ</code> - - <td>Non-conforming - - <tr> - <td><code title="">circle</code> - - <td> - - <tr> - <td><dfn id=default0 title=attr-area-shape-default>Default state</dfn> - - <td><code title="">default</code> - - <td> - - <tr> - <td rowspan=2><dfn id=polygon title=attr-area-shape-poly>Polygon - state</dfn> - - <td><code title="">poly</code> - - <td> - - <tr> - <td><code title="">polygon</code> - - <td>Non-conforming - - <tr> - <td rowspan=2><dfn id=rectangle title=attr-area-shape-rect>Rectangle - state</dfn> - - <td><code title="">rect</code> - - <td> - - <tr> - <td><code title="">rectangle</code> - - <td>Non-conforming - </table> - - <p>The attribute may be ommited. The <i>missing value default</i> is the <a - href="#rectangle" title=attr-area-shape-rect>rectangle</a> state. - - <p>The <dfn id=coords title=attr-area-coords><code>coords</code></dfn> - attribute must, if specified, contain a <a href="#valid4">valid list of - integers</a>. This attribute gives the coordinates for the shape described - by the <code title=attr-area-shape><a href="#shape">shape</a></code> - attribute. The processing for this attribute is described as part of the - <a href="#image">image map</a> processing model. - - <p>In the <a href="#circle" title=attr-area-shape-circle>circle state</a>, - <code><a href="#area">area</a></code> elements must have a <code - title=attr-area-coords><a href="#coords">coords</a></code> attribute - present, with three integers, the last of which must be non-negative. The - first integer must be the distance in CSS pixels from the left edge of the - image to the center of the circle, the second integer must be the distance - in CSS pixels from the top edge of the image to the center of the circle, - and the third integer must be the radius of the circle, again in CSS - pixels. - - <p>In the <a href="#default0" title=attr-area-shape-default>default - state</a> state, <code><a href="#area">area</a></code> elements must not - have a <code title=attr-area-coords><a href="#coords">coords</a></code> - attribute. - - <p>In the <a href="#polygon" title=attr-area-shape-poly>polygon state</a>, - <code><a href="#area">area</a></code> elements must have a <code - title=attr-area-coords><a href="#coords">coords</a></code> attribute with - at least six integers, and the number of integers must be even. Each pair - of integers must represent a coordinate given as the distances from the - left and the top of the image in CSS pixels respectively, and all the - coordinates together must represent the points of the polygon, in order. - - <p>In the <a href="#rectangle" title=attr-area-shape-rect>rectangle - state</a>, <code><a href="#area">area</a></code> elements must have a - <code title=attr-area-coords><a href="#coords">coords</a></code> attribute - with exactly four integers, the first of which must be less than the - third, and the second of which must be less than the fourth. The four - points must represent, respectively, the distance from the left edge of - the image to the top left side of the rectangle, the distance from the top - edge to the top side, the distance from the left edge to the right side, - and the distance from the top edge to the bottom side, all in CSS pixels. - - <p>When user agents allow users to <a href="#following0" title="following - hyperlinks">follow hyperlinks</a> created using the <code><a - href="#area">area</a></code> element, as described in the next section, - the <code title=attr-hyperlink-href><a href="#href6">href</a></code>, - <code title=attr-hyperlink-target><a href="#target3">target</a></code> and - <code title=attr-hyperlink-ping><a href="#ping">ping</a></code> attributes - decide how the link is followed. The <code title=attr-hyperlink-rel><a - href="#rel3">rel</a></code>, <code title=attr-hyperlink-media><a - href="#media12">media</a></code>, <code title=attr-hyperlink-hreflang><a - href="#hreflang3">hreflang</a></code>, and <code - title=attr-hyperlink-type><a href="#type17">type</a></code> attributes may - be used to indicate to the user the likely nature of the target resource - before the user follows the link. - - <p>The <code title=attr-hyperlink-target><a - href="#target3">target</a></code>, <code title=attr-hyperlink-ping><a - href="#ping">ping</a></code>, <code title=attr-hyperlink-rel><a - href="#rel3">rel</a></code>, <code title=attr-hyperlink-media><a - href="#media12">media</a></code>, <code title=attr-hyperlink-hreflang><a - href="#hreflang3">hreflang</a></code>, and <code - title=attr-hyperlink-type><a href="#type17">type</a></code> attributes - must be omitted if the <code title=attr-hyperlink-href><a - href="#href6">href</a></code> attribute is not present. - - <p>The <a href="#activation0">activation behavior</a> of <code><a - href="#area">area</a></code> elements is to run the following steps: - - <ol> - <li>If the <code title=event-DOMActivate>DOMActivate</code> event in - question is not <span title=concept-events-trusted>trusted</span> (i.e. a - <code title=dom-click><a href="#click">click()</a></code> method call was - the reason for the event being dispatched), and the <code><a - href="#area">area</a></code> element's <code - title=attr-area-target>target</code> attribute is <span - class=big-issue>...</span> then raise an <code>INVALID_ACCESS_ERR</code> - exception. - - <li>Otherwise, the user agent must <a href="#following0" title="following - hyperlinks">follow the hyperlink</a> defined by the <code><a - href="#area">area</a></code> element, if any. - </ol> - - <p class=note>One way that a user agent can enable users to follow - hyperlinks is by allowing <code><a href="#area">area</a></code> elements - to be clicked, or focussed and activated by the keyboard. This <a - href="#interactive1" title="interactive elements">will cause</a> the - aforementioned <a href="#activation0">activation behavior</a> to be - invoked. - - <p>The DOM attributes <dfn id=alt2 - title=dom-area-alt><code>alt</code></dfn>, <dfn id=coords0 - title=dom-area-coords><code>coords</code></dfn>, <dfn id=shape0 - title=dom-area-shape><code>shape</code></dfn>, <dfn id=href4 - title=dom-area-href><code>href</code></dfn>, <dfn id=target2 - title=dom-area-target><code>target</code></dfn>, <dfn id=ping1 - title=dom-area-ping><code>ping</code></dfn>, <dfn id=rel2 - title=dom-area-rel><code>rel</code></dfn>, <dfn id=media11 - title=dom-area-media><code>media</code></dfn>, <dfn id=hreflang2 - title=dom-area-hreflang><code>hreflang</code></dfn>, and <dfn id=type10 - title=dom-area-type><code>type</code></dfn>, each must <a - href="#reflect">reflect</a> the respective content attributes of the same - name. - - <p>The DOM attribute <dfn id=rellist1 - title=dom-area-rellist><code>relList</code></dfn> must <a - href="#reflect">reflect</a> the <code title=attr-hyperlink-rel><a - href="#rel3">rel</a></code> content attribute. - - <h4 id=image-maps><span class=secno>3.14.14. </span>Image maps</h4> - <!-- TESTS - http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E%0A%3Cimg%20src%3D%22http%3A//hixie.ch/resources/images/smallcats%22%20usemap%3D%23a%20onclick%3Dw%28%27img%27%29%3E%0A%3Cmap%20name%3Da%3E%0A%20%3Carea%20onclick%3Dw%28%271%27%29%20coords%3D%270%25%200%25%20100%25%20100%25%27%20href%3Djavascript%3A%3E%0A%3C/map%3E - http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E%0A%3Cbody%20onfocus%3D%22w%28document.activeElement.tagName%29%22%3E%0A%3Cimg%20src%3D%22http%3A//hixie.ch/resources/images/smallcats%22%20usemap%3D%23a%20onclick%3Dw%28%27img%27%29%20onfocus%3D%22w%28document.activeElement.tagName%29%22%3E%0A%3Cimg%20src%3D%22http%3A//hixie.ch/resources/images/sample%22%20usemap%3D%23a%20onclick%3Dw%28%27img%27%29%20onfocus%3D%22w%28document.activeElement.tagName%29%22%3E%0A%3Cmap%20name%3Da%20onfocus%3D%22w%28document.activeElement.tagName%29%22%3E%0A%20%3Carea%20onclick%3Dw%28%271%27%29%20coords%3D%270%200%2050%2050%27%20href%3Djavascript%3A%20onfocus%3D%22w%28document.activeElement.tagName%29%22%3E%0A%3C/map%3E%0A%3Cscript%3E%0A%20var%20x%20%3D%20document.getElementsByTagName%28%27img%27%29%5B0%5D%3B%0A%20x.parentNode.appendChild%28x%29%3B%0A%20document.getElementsByTagName%28%27area%27%29%5B0%5D.focus%28%29%3B%0A%3C/script%3E - http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3Ex%3Cmap%3E%3Carea%20shape%3Dpolyg%20coords%3D%221%2C2%203%22%3E%3C/map%3E%0A%3Cscript%3Ex%20%3D%20document.getElementsByTagName%28%27area%27%29%5B0%5D%3B%20w%28x.shape%20+%20%27%20%27%20+%20x.coords%29%3C/script%3E - http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E%0D%0A%3Cp%3E%3Cimg%20src%3D%22http%3A//hixie.ch/resources/images/astrophy/128%22%20usemap%3D%23a%3E%0D%0A%3Cmap%20name%3Da%3E%3Carea%20shape%3Dcirc%20coords%3D%2220%2C20%2C10%25%22%20href%3D%23%3E%3Carea%20shape%3Dcirc%20coords%3D%2220%2C20%2C10%22%20href%3D%23%3E%3C/map%3E%0D%0A%3Cscript%3Edocument.write%28document.getElementsByTagName%28%27area%27%29%5B0%5D.coords%29%3C/script%3E - --> - - <p>An <dfn id=image>image map</dfn> allows geometric areas on an image to - be associated with <a href="#hyperlinks" title=hyperlink>hyperlinks</a>. - - <p>An image, in the form of an <code><a href="#img">img</a></code> element - or an <code><a href="#object">object</a></code> element representing an - image, may be associated with an image map (in the form of a <code><a - href="#map">map</a></code> element) by specifying a <dfn id=usemap1 - title=attr-hyperlink-usemap><code>usemap</code></dfn> attribute on the - <code><a href="#img">img</a></code> or <code><a - href="#object">object</a></code> element. The <code - title=attr-area-usemap>usemap</code> attribute, if specified, must be a <a - href="#valid7">valid hashed ID reference</a> to a <code><a - href="#map">map</a></code> element. - - <p>If an <code><a href="#img">img</a></code> element or an <code><a - href="#object">object</a></code> element representing an image has a <code - title=attr-area-usemap>usemap</code> attribute specified, user agents must - process it as follows: - - <ol> - <li> - <p>First, <a href="#rules5">rules for parsing a hashed ID reference</a> - to a <code><a href="#map">map</a></code> element must be followed. This - will return either an element (the <var title="">map</var>) or null. - - <li> - <p>If that returned null, then abort these steps. The image is not - associated with an image map after all. - - <li> - <p>Otherwise, the user agent must collect all the <code><a - href="#area">area</a></code> elements that are descendants of the <var - title="">map</var>. Let those be the <var title="">areas</var>. - </ol> - - <p>Having obtained the list of <code><a href="#area">area</a></code> - elements that form the image map (the <var title="">areas</var>), - interactive user agents must process the list in one of two ways. - - <p>If the user agent intends to show the text that the <code><a - href="#img">img</a></code> element represents, then it must use the - following steps. - - <p class=note>In user agents that do not support images, or that have - images disabled, <code><a href="#object">object</a></code> elements cannot - represent images, and thus this section never applies (the fallback - content is shown instead). The following steps therefore only apply to - <code><a href="#img">img</a></code> elements. - - <ol> - <li> - <p>Remove all the <code><a href="#area">area</a></code> elements in <var - title="">areas</var> that have no <code title=attr-hyperlink-href><a - href="#href6">href</a></code> attribute. - - <li> - <p>Remove all the <code><a href="#area">area</a></code> elements in <var - title="">areas</var> that have no <code title=attr-area-alt><a - href="#alt1">alt</a></code> attribute, or whose <code - title=attr-area-alt><a href="#alt1">alt</a></code> attribute's value is - the empty string, <em>if</em> there is another <code><a - href="#area">area</a></code> element in <var title="">areas</var> with - the same value in the <code title=attr-hyperlink-href><a - href="#href6">href</a></code> attribute and with a non-empty <code - title=attr-area-alt><a href="#alt1">alt</a></code> attribute. - - <li> - <p>Each remaining <code><a href="#area">area</a></code> element in <var - title="">areas</var> represents a <a href="#hyperlinks">hyperlink</a>. - Those hyperlinks should all be made available to the user in a manner - associated with the text of the <code><a href="#img">img</a></code> - element.</p> - - <p>In this context, user agents may represent <code><a - href="#area">area</a></code> and <code><a href="#img">img</a></code> - elements with no specified <code title="">alt</code> attributes, or - whose <code title="">alt</code> attributes are the empty string or some - other non-visible text, in a user-agent-defined fashion intended to - indicate the lack of suitable author-provided text. - </ol> - - <p>If the user agent intends to show the image and allow interaction with - the image to select hyperlinks, then the image must be associated with a - set of layered shapes, taken from the <code><a - href="#area">area</a></code> elements in <var title="">areas</var>, in - reverse tree order (so the last specified <code><a - href="#area">area</a></code> element in the <var title="">map</var> is the - bottom-most shape, and the first element in the <var title="">map</var>, - in tree order, is the top-most shape). - - <p>Each <code><a href="#area">area</a></code> element in <var - title="">areas</var> must be processed as follows to obtain a shape to - layer onto the image: - - <ol> - <li> - <p>Find the state that the element's <code title=attr-area-shape><a - href="#shape">shape</a></code> attribute represents. - - <li> - <p>Use the <a href="#rules3">rules for parsing a list of integers</a> to - parse the element's <code title=attr-area-coords><a - href="#coords">coords</a></code> attribute, if it is present, and let - the result be the <var title="">coords</var> list. If the attribute is - absent, let the <var title="">coords</var> list be the empty list. - - <li> - <p>If the number of items in the <var title="">coords</var> list is less - than the minimum number given for the <code><a - href="#area">area</a></code> element's current state, as per the - following table, then the shape is empty; abort these steps.</p> - - <table> - <thead> - <tr> - <th>State - - <th>Minimum number of items - - <tbody> - <tr> - <td><a href="#circle" title=attr-area-shape-circle>Circle state</a> - - <td>3 - - <tr> - <td><a href="#default0" title=attr-area-shape-default>Default - state</a> - - <td>0 - - <tr> - <td><a href="#polygon" title=attr-area-shape-poly>Polygon state</a> - - <td>6 - - <tr> - <td><a href="#rectangle" title=attr-area-shape-rect>Rectangle - state</a> - - <td>4 - </table> - - <li> - <p>Check for excess items in the <var title="">coords</var> list as per - the entry in the following list corresponding to the <code - title=attr-area-shape><a href="#shape">shape</a></code> attribute's - state:</p> - - <dl class=switch> - <dt><a href="#circle" title=attr-area-shape-circle>Circle state</a> - - <dd>Drop any items in the list beyond the third. - - <dt><a href="#default0" title=attr-area-shape-default>Default state</a> - - <dd>Drop all items in the list. - - <dt><a href="#polygon" title=attr-area-shape-poly>Polygon state</a> - - <dd>Drop the last item if there's an odd number of items. - - <dt><a href="#rectangle" title=attr-area-shape-rect>Rectangle state</a> - - <dd>Drop any items in the list beyond the fourth. - </dl> - - <li> - <p>If the <code title=attr-area-shape><a href="#shape">shape</a></code> - attribute represents the <a href="#rectangle" - title=attr-area-shape-rect>rectangle state</a>, and the first number in - the list is numerically less than the third number in the list, then - swap those two numbers around. - - <li> - <p>If the <code title=attr-area-shape><a href="#shape">shape</a></code> - attribute represents the <a href="#rectangle" - title=attr-area-shape-rect>rectangle state</a>, and the second number in - the list is numerically less than the fourth number in the list, then - swap those two numbers around. - - <li> - <p>If the <code title=attr-area-shape><a href="#shape">shape</a></code> - attribute represents the <a href="#circle" - title=attr-area-shape-circle>circle state</a>, and the third number in - the list is less than or equal to zero, then the shape is empty; abort - these steps. - - <li> - <p>Now, the shape represented by the element is the one described for the - entry in the list below corresponding to the state of the <code - title=attr-area-shape><a href="#shape">shape</a></code> attribute:</p> - - <dl class=switch> - <dt><a href="#circle" title=attr-area-shape-circle>Circle state</a> - - <dd> - <p>Let <var title="">x</var> be the first number in <var - title="">coords</var>, <var title="">y</var> be the second number, and - <var title="">r</var> be the third number.</p> - - <p>The shape is a circle whose center is <var title="">x</var> CSS - pixels from the left edge of the image and <var title="">x</var> CSS - pixels from the top edge of the image, and whose radius is <var - title="">r</var> pixels.</p> - - <dt><a href="#default0" title=attr-area-shape-default>Default state</a> - - <dd> - <p>The shape is a rectangle that exactly covers the entire image.</p> - - <dt><a href="#polygon" title=attr-area-shape-poly>Polygon state</a> - - <dd> - <p>Let <var title="">x<sub title=""><var title="">i</var></sub></var> - be the <span>(2<var title="">i</var>)</span>th entry in <var - title="">coords</var>, and <var title="">y<sub title=""><var - title="">i</var></sub></var> be the <span>(2<var - title="">i</var>+1)</span>th entry in <var title="">coords</var> (the - first entry in <var title="">coords</var> being the one with index 0).</p> - - <p>Let <var title="">the coordinates</var> be (<var title="">x<sub - title=""><var title="">i</var></sub></var>, <var title="">y<sub - title=""><var title="">i</var></sub></var>), interpreted in CSS pixels - measured from the top left of the image, for all integer values of - <var title="">i</var> from 0 to <span>(<var - title="">N</var>/2)-1</span>, where <var title="">N</var> is the - number of items in <var title="">coords</var>.</p> - - <p>The shape is a polygon whose vertices are given by <var title="">the - coordinates</var>, and whose interior is established using the - even-odd rule. <a href="#refsGRAPHICS">[GRAPHICS]</a></p> - <!-- If anyone has this book ("Computer Graphics: Principles and - Practice in C"), please check page 34 or so and see if it - makes any references to literature in the bibliographic - section to define the "even-odd" rule for polygon filling - and hit testing. - <dd id="refsGRAPHICS">[GRAPHICS]</dd> - <dd>(Non-normative) <cite>Computer Graphics: Principles and Practice in C</cite>, Second Edition, J. Foley, A. van Dam, S. Feiner, J. Hughes. Addison-Wesley, July 1995. ISBN 0-201-84840-6.</dd> - --> - <!-- - browsers implement the even-odd rule / even winding rule: - http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20html%3E%0A%3Cimg%20usemap%3D%22%23x%22%20src%3D%22/resources/images/sample%22%3E%0A%3Cmap%20name%3D%22x%22%3E%0A%20%20%3Carea%20shape%3Dpolygon%20coords%3D%220%2C0%200%2C100%20100%2C100%20100%2C2%201%2C2%202%2C1%202%2C99%2099%2C99%2099%2C0%22%20href%3Da%3E%0A%3C/map%3E%0A - --> - - - <dt><a href="#rectangle" title=attr-area-shape-rect>Rectangle state</a> - - <dd> - <p>Let <var title="">x1</var> be the first number in <var - title="">coords</var>, <var title="">y1</var> be the second number, - <var title="">x2</var> be the third number, and <var title="">y2</var> - be the fourth number.</p> - - <p>The shape is a rectangle whose top-left corner is given by the - coordinate (<var title="">x1</var>, <var title="">y1</var>) and whose - bottom right corner is given by the coordinate (<var - title="">x2</var>, <var title="">y2</var>), those coordinates being - interpreted as CSS pixels from the top left corner of the image.</p> - </dl> - </ol> - - <p>Mouse clicks on an image associated with a set of layered shapes per the - above algorithm must be dispatched to the top-most shape covering the - point that the pointing device indicated (if any), and then, must be - dispatched again (with a new <code>Event</code> object) to the image - element itself. User agents may also allow individual <code><a - href="#area">area</a></code> elements representing <a href="#hyperlinks" - title=hyperlink>hyperlinks</a> to be selected and activated (e.g. using a - keyboard); events from this are not also propagated to the image. - - <p class=note>Because a <code><a href="#map">map</a></code> element (and - its <code><a href="#area">area</a></code> elements) can be associated with - multiple <code><a href="#img">img</a></code> elements, it is possible for - an <code><a href="#area">area</a></code> element to correspond to multiple - focusable areas of the document. - - <p>Image maps are <em><a href="#live">live</a></em>; if the DOM is mutated, - then the user agent must act as if it had rerun the algorithms for image - maps. - - <h3 id=tabular><span class=secno>3.15. </span>Tabular data</h3> - - <h4 id=the-table><span class=secno>3.15.1. </span>The <dfn - id=table><code>table</code></dfn> element</h4> - - <p><a href="#block-level0" title="block-level elements">Block-level - element</a>, and <a href="#structured" title="structured inline-level - elements">structured inline-level element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> are expected. - - <dd>Where <a href="#structured">structured inline-level elements</a> are - allowed. - - <dt>Content model: - - <dd>In this order: optionally a <code><a - href="#caption0">caption</a></code> element, followed by either zero or - more <code><a href="#colgroup">colgroup</a></code> elements, followed - optionally by a <code><a href="#thead0">thead</a></code> element, - followed optionally by a <code><a href="#tfoot0">tfoot</a></code> - element, followed by either zero or more <code><a - href="#tbody">tbody</a></code> elements <em>or</em> one or more <code><a - href="#tr">tr</a></code> elements, followed optionally by a <code><a - href="#tfoot0">tfoot</a></code> element (but there can only be one - <code><a href="#tfoot0">tfoot</a></code> element child in total). - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmltableelement>HTMLTableElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute <span>HTMLTableCaptionElement</span> <a href="#caption" title=dom-table-caption>caption</a>; - HTMLElement <a href="#createcaption" title=dom-table-createCaption>createCaption</a>(); - void <a href="#deletecaption" title=dom-table-deleteCaption>deleteCaption</a>(); - attribute <a href="#htmltablesectionelement">HTMLTableSectionElement</a> <a href="#thead" title=dom-table-tHead>tHead</a>; - HTMLElement <a href="#createthead" title=dom-table-createTHead>createTHead</a>(); - void <a href="#deletethead" title=dom-table-deleteTHead>deleteTHead</a>(); - attribute <a href="#htmltablesectionelement">HTMLTableSectionElement</a> <a href="#tfoot" title=dom-table-tFoot>tFoot</a>; - HTMLElement <a href="#createtfoot" title=dom-table-createTFoot>createTFoot</a>(); - void <a href="#deletetfoot" title=dom-table-deleteTFoot>deleteTFoot</a>(); - readonly attribute <a href="#htmlcollection0">HTMLCollection</a> <a href="#tbodies" title=dom-table-tBodies>tBodies</a>; - readonly attribute <a href="#htmlcollection0">HTMLCollection</a> <a href="#rows" title=dom-table-rows>rows</a>; - HTMLElement <a href="#insertrow" title=dom-table-insertRow>insertRow</a>(in long index); - void <a href="#deleterow" title=dom-table-deleteRow>deleteRow</a>(in long index); -};</pre> - </dl> - - <p>The <code><a href="#table">table</a></code> element represents data with - more than one dimension (a <a href="#table1" - title=concept-table>table</a>). - - <p>The children of a <code><a href="#table">table</a></code> element must - be, in order: - - <ol> - <li> - <p>Zero or one <code><a href="#caption0">caption</a></code> elements. - - <li> - <p>Zero or more <code><a href="#colgroup">colgroup</a></code> elements. - - <li> - <p>Zero or one <code><a href="#thead0">thead</a></code> elements. - - <li> - <p>Zero or one <code><a href="#tfoot0">tfoot</a></code> elements, if the - last element in the table is not a <code><a - href="#tfoot0">tfoot</a></code> element. - - <li> - <p>Either:</p> - - <ul> - <li>Zero or more <code><a href="#tbody">tbody</a></code> elements, or - - <li>One or more <code><a href="#tr">tr</a></code> elements. - </ul> - - <li> - <p>Zero or one <code><a href="#tfoot0">tfoot</a></code> element, if there - are no other <code><a href="#tfoot0">tfoot</a></code> elements in the - table. - </ol> - - <p>The <code><a href="#table">table</a></code> element takes part in the <a - href="#table0">table model</a>. - - <p>The <dfn id=caption title=dom-table-caption><code>caption</code></dfn> - DOM attribute must return, on getting, the first <code><a - href="#caption0">caption</a></code> element child of the <code><a - href="#table">table</a></code> element. On setting, if the new value is a - <code><a href="#caption0">caption</a></code> element, the first <code><a - href="#caption0">caption</a></code> element child of the <code><a - href="#table">table</a></code> element, if any, must be removed, and the - new value must be inserted as the first node of the <code><a - href="#table">table</a></code> element. If the new value is not a <code><a - href="#caption0">caption</a></code> element, then a - <code>HIERARCHY_REQUEST_ERR</code> DOM exception must be raised instead. - - <p>The <dfn id=createcaption - title=dom-table-createCaption><code>createCaption()</code></dfn> method - must return the first <code><a href="#caption0">caption</a></code> element - child of the <code><a href="#table">table</a></code> element, if any; - otherwise a new <code><a href="#caption0">caption</a></code> element must - be created, inserted as the first node of the <code><a - href="#table">table</a></code> element, and then returned. - - <p>The <dfn id=deletecaption - title=dom-table-deleteCaption><code>deleteCaption()</code></dfn> method - must remove the first <code><a href="#caption0">caption</a></code> element - child of the <code><a href="#table">table</a></code> element, if any. - - <p>The <dfn id=thead title=dom-table-tHead><code>tHead</code></dfn> DOM - attribute must return, on getting, the first <code><a - href="#thead0">thead</a></code> element child of the <code><a - href="#table">table</a></code> element. On setting, if the new value is a - <code><a href="#thead0">thead</a></code> element, the first <code><a - href="#thead0">thead</a></code> element child of the <code><a - href="#table">table</a></code> element, if any, must be removed, and the - new value must be inserted immediately before the first element in the - <code><a href="#table">table</a></code> element that is neither a <code><a - href="#caption0">caption</a></code> element nor a <code><a - href="#colgroup">colgroup</a></code> element, if any, or at the end of the - table otherwise. If the new value is not a <code><a - href="#thead0">thead</a></code> element, then a - <code>HIERARCHY_REQUEST_ERR</code> DOM exception must be raised instead. - - <p>The <dfn id=createthead - title=dom-table-createTHead><code>createTHead()</code></dfn> method must - return the first <code><a href="#thead0">thead</a></code> element child of - the <code><a href="#table">table</a></code> element, if any; otherwise a - new <code><a href="#thead0">thead</a></code> element must be created and - inserted immediately before the first element in the <code><a - href="#table">table</a></code> element that is neither a <code><a - href="#caption0">caption</a></code> element nor a <code><a - href="#colgroup">colgroup</a></code> element, if any, or at the end of the - table otherwise, and then that new element must be returned. - - <p>The <dfn id=deletethead - title=dom-table-deleteTHead><code>deleteTHead()</code></dfn> method must - remove the first <code><a href="#thead0">thead</a></code> element child of - the <code><a href="#table">table</a></code> element, if any. - - <p>The <dfn id=tfoot title=dom-table-tFoot><code>tFoot</code></dfn> DOM - attribute must return, on getting, the first <code><a - href="#tfoot0">tfoot</a></code> element child of the <code><a - href="#table">table</a></code> element. On setting, if the new value is a - <code><a href="#tfoot0">tfoot</a></code> element, the first <code><a - href="#tfoot0">tfoot</a></code> element child of the <code><a - href="#table">table</a></code> element, if any, must be removed, and the - new value must be inserted immediately before the first element in the - <code><a href="#table">table</a></code> element that is neither a <code><a - href="#caption0">caption</a></code> element, a <code><a - href="#colgroup">colgroup</a></code> element, nor a <code><a - href="#thead0">thead</a></code> element, if any, or at the end of the - table if there are no such elements. If the new value is not a <code><a - href="#tfoot0">tfoot</a></code> element, then a - <code>HIERARCHY_REQUEST_ERR</code> DOM exception must be raised instead. - - <p>The <dfn id=createtfoot - title=dom-table-createTFoot><code>createTFoot()</code></dfn> method must - return the first <code><a href="#tfoot0">tfoot</a></code> element child of - the <code><a href="#table">table</a></code> element, if any; otherwise a - new <code><a href="#tfoot0">tfoot</a></code> element must be created and - inserted immediately before the first element in the <code><a - href="#table">table</a></code> element that is neither a <code><a - href="#caption0">caption</a></code> element, a <code><a - href="#colgroup">colgroup</a></code> element, nor a <code><a - href="#thead0">thead</a></code> element, if any, or at the end of the - table if there are no such elements, and then that new element must be - returned. - - <p>The <dfn id=deletetfoot - title=dom-table-deleteTFoot><code>deleteTFoot()</code></dfn> method must - remove the first <code><a href="#tfoot0">tfoot</a></code> element child of - the <code><a href="#table">table</a></code> element, if any. - - <p>The <dfn id=tbodies title=dom-table-tBodies><code>tBodies</code></dfn> - attribute must return an <code><a - href="#htmlcollection0">HTMLCollection</a></code> rooted at the <code><a - href="#table">table</a></code> node, whose filter matches only <code><a - href="#tbody">tbody</a></code> elements that are children of the <code><a - href="#table">table</a></code> element. - - <p>The <dfn id=rows title=dom-table-rows><code>rows</code></dfn> attribute - must return an <code><a href="#htmlcollection0">HTMLCollection</a></code> - rooted at the <code><a href="#table">table</a></code> node, whose filter - matches only <code><a href="#tr">tr</a></code> elements that are either - children of the <code><a href="#table">table</a></code> element, or - children of <code><a href="#thead0">thead</a></code>, <code><a - href="#tbody">tbody</a></code>, or <code><a - href="#tfoot0">tfoot</a></code> elements that are themselves children of - the <code><a href="#table">table</a></code> element. The elements in the - collection must be ordered such that those elements whose parent is a - <code><a href="#thead0">thead</a></code> are included first, in tree - order, followed by those elements whose parent is either a <code><a - href="#table">table</a></code> or <code><a href="#tbody">tbody</a></code> - element, again in tree order, followed finally by those elements whose - parent is a <code><a href="#tfoot0">tfoot</a></code> element, still in - tree order. - - <p>The behaviour of the <dfn id=insertrow - title=dom-table-insertRow><code>insertRow(<var - title="">index</var>)</code></dfn> method depends on the state of the - table. When it is called, the method must act as required by the first - item in the following list of conditions that describes the state of the - table and the <var title="">index</var> argument: - - <dl class=switch> - <dt>If <var title="">index</var> is less than -1 or greater than the - number of elements in <code title=dom-table-rows><a - href="#rows">rows</a></code> collection: - - <dd>The method must raise an <code>INDEX_SIZE_ERR</code> exception. - - <dt>If the <code title=dom-table-rows><a href="#rows">rows</a></code> - collection has zero elements in it, and the <code><a - href="#table">table</a></code> has no <code><a - href="#tbody">tbody</a></code> elements in it: - - <dd>The method must create a <code><a href="#tbody">tbody</a></code> - element, then create a <code><a href="#tr">tr</a></code> element, then - append the <code><a href="#tr">tr</a></code> element to the <code><a - href="#tbody">tbody</a></code> element, then append the <code><a - href="#tbody">tbody</a></code> element to the <code><a - href="#table">table</a></code> element, and finally return the <code><a - href="#tr">tr</a></code> element. - - <dt>If the <code title=dom-table-rows><a href="#rows">rows</a></code> - collection has zero elements in it: - - <dd>The method must create a <code><a href="#tr">tr</a></code> element, - append it to the last <code><a href="#tbody">tbody</a></code> element in - the table, and return the <code><a href="#tr">tr</a></code> element. - - <dt>If <var title="">index</var> is equal to -1 or equal to the number of - items in <code title=dom-table-rows><a href="#rows">rows</a></code> - collection: - - <dd>The method must create a <code><a href="#tr">tr</a></code> element, - and append it to the parent of the last <code><a href="#tr">tr</a></code> - element in the <code title=dom-table-rows><a href="#rows">rows</a></code> - collection. Then, the newly created <code><a href="#tr">tr</a></code> - element must be returned. - - <dt>Otherwise: - - <dd>The method must create a <code><a href="#tr">tr</a></code> element, - insert it immediately before the <var title="">index</var>th <code><a - href="#tr">tr</a></code> element in the <code title=dom-table-rows><a - href="#rows">rows</a></code> collection, in the same parent, and finally - must return the newly created <code><a href="#tr">tr</a></code> element. - </dl> - - <p>The <dfn id=deleterow title=dom-table-deleteRow><code>deleteRow(<var - title="">index</var>)</code></dfn> method must remove the <var - title="">index</var>th element in the <code title=dom-table-rows><a - href="#rows">rows</a></code> collection from its parent. If <var - title="">index</var> is less than zero or greater than or equal to the - number of elements in the <code title=dom-table-rows><a - href="#rows">rows</a></code> collection, the method must instead raise an - <code>INDEX_SIZE_ERR</code> exception. - - <h4 id=the-caption><span class=secno>3.15.2. </span>The <dfn - id=caption0><code>caption</code></dfn> element</h4> - <!-- element has no special category --> - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>As the first element child of a <code><a - href="#table">table</a></code> element. - - <dt>Content model: - - <dd><a href="#significant" title="significant inline - content">Significant</a> <a href="#strictly">strictly inline-level - content</a>. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#caption0">caption</a></code> element represents the - title of the <code><a href="#table">table</a></code> that is its parent, - if it has a parent and that is a <code><a href="#table">table</a></code> - element. - - <p>The <code><a href="#caption0">caption</a></code> element takes part in - the <a href="#table0">table model</a>. - - <h4 id=the-colgroup><span class=secno>3.15.3. </span>The <dfn - id=colgroup><code>colgroup</code></dfn> element</h4> - <!-- element has no special category --> - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>As a child of a <code><a href="#table">table</a></code> element, after - any <code><a href="#caption0">caption</a></code> elements and before any - <code><a href="#thead0">thead</a></code>, <code><a - href="#tbody">tbody</a></code>, <code><a href="#tfoot0">tfoot</a></code>, - and <code><a href="#tr">tr</a></code> elements. - - <dt>Content model: - - <dd>Zero or more <code><a href="#col">col</a></code> elements. - - <dt>Element-specific attributes: - - <dd><code title=attr-colgroup-span><a href="#span0">span</a></code>, but - only if the element contains no <code><a href="#col">col</a></code> - elements - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmltablecolelement>HTMLTableColElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute unsigned long <a href="#span1" title=dom-colgroup-span>span</a>; -};</pre> - </dl> - - <p>The <code><a href="#colgroup">colgroup</a></code> element represents a - <a href="#column0" title=concept-column-group>group</a> of one or more <a - href="#column" title=concept-column>columns</a> in the <code><a - href="#table">table</a></code> that is its parent, if it has a parent and - that is a <code><a href="#table">table</a></code> element. - - <p>If the <code><a href="#colgroup">colgroup</a></code> element contains no - <code><a href="#col">col</a></code> elements, then the element may have a - <dfn id=span0 title=attr-colgroup-span><code>span</code></dfn> content - attribute specified, whose value must be a <a href="#valid">valid - non-negative integer</a> greater than zero. Its default value, which must - be used if <a href="#rules" title="rules for parsing non-negative - integers">parsing the attribute as a non-negative integer</a> returns - either an error or zero, is 1. - - <p>The <code><a href="#colgroup">colgroup</a></code> element and its <code - title=attr-colgroup-span><a href="#span0">span</a></code> attribute take - part in the <a href="#table0">table model</a>. - - <p>The <dfn id=span1 title=dom-colgroup-span><code>span</code></dfn> DOM - attribute must <a href="#reflect">reflect</a> the content attribute of the - same name, with the exception that on setting, if the new value is 0, then - an <code>INDEX_SIZE_ERR</code> exception must be raised. - - <h4 id=the-col><span class=secno>3.15.4. </span>The <dfn - id=col><code>col</code></dfn> element</h4> - <!-- element has no special category --> - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>As a child of a <code><a href="#colgroup">colgroup</a></code> element - that doesn't have a <code title=attr-col-span><a - href="#span2">span</a></code> attribute. - - <dt>Content model: - - <dd>Empty. - - <dt>Element-specific attributes: - - <dd><code title=attr-col-span><a href="#span2">span</a></code> - - <dt>DOM interface: - - <dd> - <p><code><a href="#htmltablecolelement">HTMLTableColElement</a></code>, - same as for <code><a href="#colgroup">colgroup</a></code> elements. This - interface defines one member, <code title=dom-col-span><a - href="#span3">span</a></code>.</p> - </dl> - - <p>If a <code><a href="#col">col</a></code> element has a parent and that - is a <code><a href="#colgroup">colgroup</a></code> element that itself has - a parent that is a <code><a href="#table">table</a></code> element, then - the <code><a href="#col">col</a></code> element represents one or more <a - href="#column" title=concept-column>columns</a> in the <a href="#column0" - title=concept-column-group>column group</a> represented by that <code><a - href="#colgroup">colgroup</a></code>. - - <p>The element may have a <dfn id=span2 - title=attr-col-span><code>span</code></dfn> content attribute specified, - whose value must be a <a href="#valid">valid non-negative integer</a> - greater than zero. Its default value, which must be used if <a - href="#rules" title="rules for parsing non-negative integers">parsing the - attribute as a non-negative integer</a> returns either an error or zero, - is 1. - - <p>The <code><a href="#col">col</a></code> element and its <code - title=attr-col-span><a href="#span2">span</a></code> attribute take part - in the <a href="#table0">table model</a>. - - <p>The <dfn id=span3 title=dom-col-span><code>span</code></dfn> DOM - attribute must <a href="#reflect">reflect</a> the content attribute of the - same name, with the exception that on setting, if the new value is 0, then - an <code>INDEX_SIZE_ERR</code> exception must be raised. - - <h4 id=the-tbody><span class=secno>3.15.5. </span>The <dfn - id=tbody><code>tbody</code></dfn> element</h4> - <!-- element has no special category --> - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>As a child of a <code><a href="#table">table</a></code> element, after - any <code><a href="#caption0">caption</a></code>, <code><a - href="#colgroup">colgroup</a></code>, and <code><a - href="#thead0">thead</a></code> elements, but only if there are no - <code><a href="#tr">tr</a></code> elements that are children of the - <code><a href="#table">table</a></code> element. - - <dt>Content model: - - <dd>One or more <code><a href="#tr">tr</a></code> elements - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmltablesectionelement>HTMLTableSectionElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - readonly attribute <a href="#htmlcollection0">HTMLCollection</a> <a href="#rows0" title=dom-tbody-rows>rows</a>; - <a href="#htmlelement">HTMLElement</a> <a href="#insertrow0" title=dom-tbody-insertRow>insertRow</a>(in long index); - void <a href="#deleterow0" title=dom-tbody-deleteRow>deleteRow</a>(in long index); -};</pre> - - <p>The <code><a - href="#htmltablesectionelement">HTMLTableSectionElement</a></code> - interface is also used for <code><a href="#thead0">thead</a></code> and - <code><a href="#tfoot0">tfoot</a></code> elements.</p> - </dl> - - <p>The <code><a href="#tbody">tbody</a></code> element represents a <a - href="#row-group" title=concept-row-group>block</a> of <a href="#row0" - title=concept-row>rows</a> that consist of a body of data for the parent - <code><a href="#table">table</a></code> element, if the <code><a - href="#tbody">tbody</a></code> element has a parent and it is a <code><a - href="#table">table</a></code>. - - <p>The <code><a href="#tbody">tbody</a></code> element takes part in the <a - href="#table0">table model</a>. - - <p>The <dfn id=rows0 title=dom-tbody-rows><code>rows</code></dfn> attribute - must return an <code><a href="#htmlcollection0">HTMLCollection</a></code> - rooted at the element, whose filter matches only <code><a - href="#tr">tr</a></code> elements that are children of the element. - - <p>The <dfn id=insertrow0 title=dom-tbody-insertRow><code>insertRow(<var - title="">index</var>)</code></dfn> method must, when invoked on an element - <var title="">table section</var>, act as follows: - - <p>If <var title="">index</var> is less than -1 or greater than the number - of elements in the <code title=dom-tbody-rows><a - href="#rows0">rows</a></code> collection, the method must raise an - <code>INDEX_SIZE_ERR</code> exception. - - <p>If <var title="">index</var> is equal to -1 or equal to the number of - items in the <code title=dom-tbody-rows><a href="#rows0">rows</a></code> - collection, the method must create a <code><a href="#tr">tr</a></code> - element, append it to the element <var title="">table section</var>, and - return the newly created <code><a href="#tr">tr</a></code> element. - - <p>Otherwise, the method must create a <code><a href="#tr">tr</a></code> - element, insert it as a child of the <var title="">table section</var> - element, immediately before the <var title="">index</var>th <code><a - href="#tr">tr</a></code> element in the <code title=dom-tbody-rows><a - href="#rows0">rows</a></code> collection, and finally must return the - newly created <code><a href="#tr">tr</a></code> element. - - <p>The <dfn id=deleterow0 title=dom-tbody-deleteRow><code>deleteRow(<var - title="">index</var>)</code></dfn> method must remove the <var - title="">index</var>th element in the <code title=dom-tbody-rows><a - href="#rows0">rows</a></code> collection from its parent. If <var - title="">index</var> is less than zero or greater than or equal to the - number of elements in the <code title=dom-tbody-rows><a - href="#rows0">rows</a></code> collection, the method must instead raise an - <code>INDEX_SIZE_ERR</code> exception. - - <h4 id=the-thead><span class=secno>3.15.6. </span>The <dfn - id=thead0><code>thead</code></dfn> element</h4> - <!-- element has no special category --> - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>As a child of a <code><a href="#table">table</a></code> element, after - any <code><a href="#caption0">caption</a></code>, and <code><a - href="#colgroup">colgroup</a></code> elements and before any <code><a - href="#tbody">tbody</a></code>, <code><a href="#tfoot0">tfoot</a></code>, - and <code><a href="#tr">tr</a></code> elements, but only if there are no - other <code><a href="#thead0">thead</a></code> elements that are children - of the <code><a href="#table">table</a></code> element. - - <dt>Content model: - - <dd>One or more <code><a href="#tr">tr</a></code> elements - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd><code><a - href="#htmltablesectionelement">HTMLTableSectionElement</a></code>, as - defined for <code><a href="#tbody">tbody</a></code> elements. - </dl> - - <p>The <code><a href="#thead0">thead</a></code> element represents the <a - href="#row-group" title=concept-row-group>block</a> of <a href="#row0" - title=concept-row>rows</a> that consist of the column labels (headers) for - the parent <code><a href="#table">table</a></code> element, if the - <code><a href="#thead0">thead</a></code> element has a parent and it is a - <code><a href="#table">table</a></code>. - - <p>The <code><a href="#thead0">thead</a></code> element takes part in the - <a href="#table0">table model</a>. - - <h4 id=the-tfoot><span class=secno>3.15.7. </span>The <dfn - id=tfoot0><code>tfoot</code></dfn> element</h4> - <!-- element has no special category --> - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>As a child of a <code><a href="#table">table</a></code> element, after - any <code><a href="#caption0">caption</a></code>, <code><a - href="#colgroup">colgroup</a></code>, and <code><a - href="#thead0">thead</a></code> elements and before any <code><a - href="#tbody">tbody</a></code> and <code><a href="#tr">tr</a></code> - elements, but only if there are no other <code><a - href="#tfoot0">tfoot</a></code> elements that are children of the - <code><a href="#table">table</a></code> element. - - <dd>As a child of a <code><a href="#table">table</a></code> element, after - any <code><a href="#caption0">caption</a></code>, <code><a - href="#colgroup">colgroup</a></code>, <code><a - href="#thead0">thead</a></code>, <code><a href="#tbody">tbody</a></code>, - and <code><a href="#tr">tr</a></code> elements, but only if there are no - other <code><a href="#tfoot0">tfoot</a></code> elements that are children - of the <code><a href="#table">table</a></code> element. - - <dt>Content model: - - <dd>One or more <code><a href="#tr">tr</a></code> elements - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd><code><a - href="#htmltablesectionelement">HTMLTableSectionElement</a></code>, as - defined for <code><a href="#tbody">tbody</a></code> elements. - </dl> - - <p>The <code><a href="#tfoot0">tfoot</a></code> element represents the <a - href="#row-group" title=concept-row-group>block</a> of <a href="#row0" - title=concept-row>rows</a> that consist of the column summaries (footers) - for the parent <code><a href="#table">table</a></code> element, if the - <code><a href="#tfoot0">tfoot</a></code> element has a parent and it is a - <code><a href="#table">table</a></code>. - - <p>The <code><a href="#tfoot0">tfoot</a></code> element takes part in the - <a href="#table0">table model</a>. - - <h4 id=the-tr><span class=secno>3.15.8. </span>The <dfn - id=tr><code>tr</code></dfn> element</h4> - <!-- element has no special category --> - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>As a child of a <code><a href="#thead0">thead</a></code> element. - - <dd>As a child of a <code><a href="#tbody">tbody</a></code> element. - - <dd>As a child of a <code><a href="#tfoot0">tfoot</a></code> element. - - <dd>As a child of a <code><a href="#table">table</a></code> element, after - any <code><a href="#caption0">caption</a></code>, <code><a - href="#colgroup">colgroup</a></code>, and <code><a - href="#thead0">thead</a></code> elements, but only if there are no - <code><a href="#tbody">tbody</a></code> elements that are children of the - <code><a href="#table">table</a></code> element. - - <dt>Content model: - - <dd>One or more <code><a href="#td">td</a></code> or <code><a - href="#th">th</a></code> elements - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmltablerowelement>HTMLTableRowElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - readonly attribute long <a href="#rowindex" title=dom-tr-rowIndex>rowIndex</a>; - readonly attribute long <a href="#rowindex0" title=dom-tr-sectionRowIndex>sectionRowIndex</a>; - readonly attribute <a href="#htmlcollection0">HTMLCollection</a> <a href="#cells" title=dom-tr-cells>cells</a>; - <a href="#htmlelement">HTMLElement</a> <a href="#insertcell" title=dom-tr-insertCell>insertCell</a>(in long index); - void <span>deleteCell</span>(in long index); -};</pre> - </dl> - - <p>The <code><a href="#tr">tr</a></code> element represents a <a - href="#row0" title=concept-row>row</a> of <a href="#cell" - title=concept-cell>cells</a> in a <a href="#table1" - title=concept-table>table</a>. - - <p>The <code><a href="#tr">tr</a></code> element takes part in the <a - href="#table0">table model</a>. - - <p>The <dfn id=rowindex title=dom-tr-rowIndex><code>rowIndex</code></dfn> - element must, if the element has a parent <code><a - href="#table">table</a></code> element, or a parent <code><a - href="#tbody">tbody</a></code>, <code><a href="#thead0">thead</a></code>, - or <code><a href="#tfoot0">tfoot</a></code> element and a - <em>grandparent</em> <code><a href="#table">table</a></code> element, - return the index of the <code><a href="#tr">tr</a></code> element in that - <code><a href="#table">table</a></code> element's <code - title=dom-table-rows><a href="#rows">rows</a></code> collection. If there - is no such <code><a href="#table">table</a></code> element, then the - attribute must return 0. - - <p>The <dfn id=rowindex0 - title=dom-tr-sectionRowIndex><code>rowIndex</code></dfn> DOM attribute - must, if the element has a parent <code><a href="#table">table</a></code>, - <code><a href="#tbody">tbody</a></code>, <code><a - href="#thead0">thead</a></code>, or <code><a - href="#tfoot0">tfoot</a></code> element, return the index of the <code><a - href="#tr">tr</a></code> element in the parent element's <code - title="">rows</code> collection (for tables, that's the <code - title=dom-table-rows><a href="#rows">rows</a></code> collection; for table - sections, that's the <code title=dom-tbody-rows><a - href="#rows0">rows</a></code> collection). If there is no such parent - element, then the attribute must return 0. - - <p>The <dfn id=cells title=dom-tr-cells><code>cells</code></dfn> attribute - must return an <code><a href="#htmlcollection0">HTMLCollection</a></code> - rooted at the <code><a href="#tr">tr</a></code> element, whose filter - matches only <code><a href="#td">td</a></code> and <code><a - href="#th">th</a></code> elements that are children of the <code><a - href="#tr">tr</a></code> element. - - <p>The <dfn id=insertcell title=dom-tr-insertCell><code>insertCell(<var - title="">index</var>)</code></dfn> method must act as follows: - - <p>If <var title="">index</var> is less than -1 or greater than the number - of elements in the <code title=dom-tr-cells><a - href="#cells">cells</a></code> collection, the method must raise an - <code>INDEX_SIZE_ERR</code> exception. - - <p>If <var title="">index</var> is equal to -1 or equal to the number of - items in <code title=dom-tr-cells><a href="#cells">cells</a></code> - collection, the method must create a <code><a href="#td">td</a></code> - element, append it to the <code><a href="#tr">tr</a></code> element, and - return the newly created <code><a href="#td">td</a></code> element. - - <p>Otherwise, the method must create a <code><a href="#td">td</a></code> - element, insert it as a child of the <code><a href="#tr">tr</a></code> - element, immediately before the <var title="">index</var>th <code><a - href="#td">td</a></code> or <code><a href="#th">th</a></code> element in - the <code title=dom-tr-cells><a href="#cells">cells</a></code> collection, - and finally must return the newly created <code><a - href="#td">td</a></code> element. - - <p>The <dfn id=deletecell title=dom-tr-deleteCell><code>deleteCell(<var - title="">index</var>)</code></dfn> method must remove the <var - title="">index</var>th element in the <code title=dom-tr-cells><a - href="#cells">cells</a></code> collection from its parent. If <var - title="">index</var> is less than zero or greater than or equal to the - number of elements in the <code title=dom-tr-cells><a - href="#cells">cells</a></code> collection, the method must instead raise - an <code>INDEX_SIZE_ERR</code> exception. - - <h4 id=the-td><span class=secno>3.15.9. </span>The <dfn - id=td><code>td</code></dfn> element</h4> - <!-- element has no special category --> - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>As a child of a <code><a href="#tr">tr</a></code> element. - - <dt>Content model: - - <dd>Zero or more <a href="#block-level0">block-level elements</a>, or <a - href="#inline-level0">inline-level content</a> (but not both). - - <dt>Element-specific attributes: - - <dd><code title=attr-td-colspan><a href="#colspan">colspan</a></code> - - <dd><code title=attr-td-rowspan><a href="#rowspan">rowspan</a></code> - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmltablecellelement>HTMLTableCellElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute long <a href="#colspan0" title=dom-td-colSpan>colSpan</a>; - attribute long <a href="#rowspan0" title=dom-td-rowSpan>rowSpan</a>; - readonly attribute long <a href="#cellindex" title=dom-td-cellIndex>cellIndex</a>; -};</pre> - </dl> - - <p>The <code><a href="#td">td</a></code> element represents a data <a - href="#cell" title=concept-cell>cell</a> in a table. - - <p>The <code><a href="#td">td</a></code> element may have a <dfn id=colspan - title=attr-td-colspan><code>colspan</code></dfn> content attribute - specified, whose value must be a <a href="#valid">valid non-negative - integer</a> greater than zero. Its default value, which must be used if <a - href="#rules" title="rules for parsing non-negative integers">parsing the - attribute as a non-negative integer</a> returns either an error or zero, - is 1. - - <p>The <code><a href="#td">td</a></code> element may also have a <dfn - id=rowspan title=attr-td-rowspan><code>rowspan</code></dfn> content - attribute specified, whose value must be a <a href="#valid">valid - non-negative integer</a>. Its default value, which must be used if <a - href="#rules" title="rules for parsing non-negative integers">parsing the - attribute as a non-negative integer</a> returns an error, is also 1. - - <p>The <code><a href="#td">td</a></code> element and its <code - title=attr-td-colspan><a href="#colspan">colspan</a></code> and <code - title=attr-td-rowspan><a href="#rowspan">rowspan</a></code> attributes - take part in the <a href="#table0">table model</a>. - - <p>The <dfn id=colspan0 title=dom-td-colspan><code>colspan</code></dfn> DOM - attribute must <a href="#reflect">reflect</a> the content attribute of the - same name, with the exception that on setting, if the new value is 0, then - an <code>INDEX_SIZE_ERR</code> exception must be raised. - - <p>The <dfn id=rowspan0 title=dom-td-rowspan><code>rowspan</code></dfn> DOM - attribute must <a href="#reflect">reflect</a> the content attribute of the - same name. - - <p>The <dfn id=cellindex - title=dom-td-cellIndex><code>cellIndex</code></dfn> DOM attribute must, if - the element has a parent <code><a href="#tr">tr</a></code> element, return - the index of the cell's element in the parent element's <code - title=dom-tr-cells><a href="#cells">cells</a></code> collection. If there - is no such parent element, then the attribute must return 0. - - <h4 id=the-th><span class=secno>3.15.10. </span>The <dfn - id=th><code>th</code></dfn> element</h4> - <!-- element has no special category --> - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>As a child of a <code><a href="#tr">tr</a></code> element. - - <dt>Content model: - - <dd>Zero or more <a href="#block-level0">block-level elements</a>, or <a - href="#inline-level0">inline-level content</a> (but not both). - - <dt>Element-specific attributes: - - <dd><code title=attr-th-colspan><a href="#colspan1">colspan</a></code> - - <dd><code title=attr-th-rowspan><a href="#rowspan1">rowspan</a></code> - - <dd><code title=attr-th-scope><a href="#scope0">scope</a></code> - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmltableheadercellelement>HTMLTableHeaderCellElement</dfn> : <a href="#htmltablecellelement">HTMLTableCellElement</a> { - attribute DOMString <a href="#scope1" title=dom-th-scope>scope</a>; -};</pre> - </dl> - - <p>The <code><a href="#th">th</a></code> element represents a header <a - href="#cell" title=concept-cell>cell</a> in a table. - - <p>The <code><a href="#th">th</a></code> element may have a <dfn - id=colspan1 title=attr-th-colspan><code>colspan</code></dfn> content - attribute specified, whose value must be a <a href="#valid">valid - non-negative integer</a> greater than zero. Its default value, which must - be used if <a href="#rules" title="rules for parsing non-negative - integers">parsing the attribute as a non-negative integer</a> returns - either an error or zero, is 1. - - <p>The <code><a href="#th">th</a></code> element may also have a <dfn - id=rowspan1 title=attr-th-rowspan><code>rowspan</code></dfn> content - attribute specified, whose value must be a <a href="#valid">valid - non-negative integer</a>. Its default value, which must be used if <a - href="#rules" title="rules for parsing non-negative integers">parsing the - attribute as a non-negative integer</a> returns an error, is also 1. - - <p>The <code><a href="#th">th</a></code> element may have a <dfn id=scope0 - title=attr-th-scope><code>scope</code></dfn> content attribute specified. - The <code title=attr-th-scope><a href="#scope0">scope</a></code> attribute - is an <a href="#enumerated">enumerated attribute</a> with five states, - four of which have explicit keywords: - - <dl> - <dt>The <dfn id=row title=attr-th-scope-row><code>row</code></dfn> - keyword, which maps to the <em>row</em> state - - <dd>The <em>row</em> state means the header cell applies to all the - remaining cells in the row. - - <dt>The <dfn id=col0 title=attr-th-scope-col><code>col</code></dfn> - keyword, which maps to the <em>column</em> state - - <dd>The <em>column</em> state means the header cell applies to all the - remaining cells in the column. - - <dt>The <dfn id=rowgroup - title=attr-th-scope-rowgroup><code>rowgroup</code></dfn> keyword, which - maps to the <em>row group</em> state - - <dd>The <em>row group</em> state means the header cell applies to all the - remaining cells in the row group. - - <dt>The <dfn id=colgroup0 - title=attr-th-scope-colgroup><code>colgroup</code></dfn> keyword, which - maps to the <em>column group</em> state - - <dd>The <em>column group</em> state means the header cell applies to all - the remaining cells in the column group. - - <dt>The <em>auto</em> state - - <dd>The <em>auto</em> state makes the header cell apply to a set of cells - selected based on context. - </dl> - - <p>The <code title=attr-th-scope><a href="#scope0">scope</a></code> - attribute's <em>missing value default</em> is the <em>auto</em> state. - - <p>The exact effect of these values is described in detail in the <a - href="#algorithm2">algorithm for assigning header cells to data cells</a>, - which user agents must apply to determine the relationships between data - cells and header cells. - - <p>The <code><a href="#th">th</a></code> element and its <code - title=attr-th-colspan><a href="#colspan1">colspan</a></code>, <code - title=attr-th-rowspan><a href="#rowspan1">rowspan</a></code>, and <code - title=attr-th-scope><a href="#scope0">scope</a></code> attributes take - part in the <a href="#table0">table model</a>. - - <p>The <dfn id=scope1 title=dom-th-scope><code>scope</code></dfn> DOM - attribute must <a href="#reflect">reflect</a> the content attribute of the - same name. - - <p>The <code><a - href="#htmltableheadercellelement">HTMLTableHeaderCellElement</a></code> - interface inherits from the <code><a - href="#htmltablecellelement">HTMLTableCellElement</a></code> interface and - therefore also has the DOM attributes defined above in the <code><a - href="#td">td</a></code> section. - - <h4 id=processing><span class=secno>3.15.11. </span>Processing model</h4> - - <p>The various table elements and their content attributes together define - the <dfn id=table0>table model</dfn>. - - <p>A <dfn id=table1 title=concept-table>table</dfn> consists of cells - aligned on a two-dimensional grid of <dfn id=slots - title=concept-slots>slots</dfn> with coordinates (<var title="">x</var>, - <var title="">y</var>). The grid is finite, and is either empty or has one - or more slots. If the grid has one or more slots, then the <var - title="">x</var> coordinates are always in the range - <span>1 ≤ <var title="">x</var> ≤ <var - title="">x<sub title="">max</sub></var></span>, and the <var - title="">y</var> coordinates are always in the range - <span>1 ≤ <var title="">y</var> ≤ <var - title="">y<sub title="">max</sub></var></span>. If one or both of <var - title="">x<sub title="">max</sub></var> and <var title="">y<sub - title="">max</sub></var> are zero, then the table is empty (has no slots). - Tables correspond to <code><a href="#table">table</a></code> elements. - - <p>A <dfn id=cell title=concept-cell>cell</dfn> is a set of slots anchored - at a slot (<var title="">cell<sub title="">x</sub></var>, <var - title="">cell<sub title="">y</sub></var>), and with a particular <var - title="">width</var> and <var title="">height</var> such that the cell - covers all the slots with coordinates (<var title="">x</var>, <var - title="">y</var>) where <span><var title="">cell<sub - title="">x</sub></var> ≤ <var - title="">x</var> < <var title="">cell<sub - title="">x</sub></var>+<var title="">width</var></span> and <span><var - title="">cell<sub title="">y</sub></var> ≤ <var - title="">y</var> < <var title="">cell<sub - title="">y</sub></var>+<var title="">height</var></span>. Cell can either - be <em>data cells</em> or <em>header cells</em>. Data cells correspond to - <code><a href="#td">td</a></code> elements, and have zero or more - associated header cells. Header cells correspond to <code><a - href="#th">th</a></code> elements. - - <p>A <dfn id=row0 title=concept-row>row</dfn> is a complete set of slots - from <span><var title="">x</var>=1</span> to <span><var - title="">x</var>=<var title="">x<sub title="">max</sub></var></span>, for - a particular value of <var title="">y</var>. Rows correspond to <code><a - href="#tr">tr</a></code> elements. - - <p>A <dfn id=column title=concept-column>column</dfn> is a complete set of - slots from <span><var title="">y</var>=1</span> to <span><var - title="">y</var>=<var title="">y<sub title="">max</sub></var></span>, for - a particular value of <var title="">x</var>. Columns can correspond to - <code><a href="#col">col</a></code> elements, but in the absense of - <code><a href="#col">col</a></code> elements are implied. - - <p>A <dfn id=row-group title=concept-row-group>row group</dfn> is a set of - <a href="#row0" title=concept-row>rows</a> anchored at a slot (1, <var - title="">group<sub title="">y</sub></var>) with a particular <var - title="">height</var> such that the row group covers all the slots with - coordinates (<var title="">x</var>, <var title="">y</var>) where - <span>1 ≤ <var title="">x</var> < <var - title="">x<sub title="">max</sub></var></span> and <span><var - title="">group<sub title="">y</sub></var> ≤ <var - title="">y</var> < <var title="">group<sub - title="">y</sub></var>+<var title="">height</var></span>. Row groups - correspond to <code><a href="#tbody">tbody</a></code>, <code><a - href="#thead0">thead</a></code>, and <code><a - href="#tfoot0">tfoot</a></code> elements. Not every row is necessarily in - a row group. - - <p>A <dfn id=column0 title=concept-column-group>column group</dfn> is a set - of <a href="#column" title=concept-column>columns</a> anchored at a slot - (<var title="">group<sub title="">x</sub></var>, 1) with a particular <var - title="">width</var> such that the column group covers all the slots with - coordinates (<var title="">x</var>, <var title="">y</var>) where - <span><var title="">group<sub title="">x</sub></var> ≤ <var - title="">x</var> < <var title="">group<sub - title="">x</sub></var>+<var title="">width</var></span> and - <span>1 ≤ <var title="">y</var> < <var - title="">y<sub title="">max</sub></var></span>. Column groups correspond - to <code><a href="#colgroup">colgroup</a></code> elements. Not every - column is necessarily in a column group. - - <p><a href="#row-group" title=concept-row-group>Row groups</a> cannot - overlap each other. Similarly, <a href="#column0" - title=concept-column-group>column groups</a> cannot overlap each other. - - <p>A <a href="#cell" title=concept-cell>cell</a> cannot cover slots that - are from two or more <a href="#row-group" title=concept-row-group>row - groups</a>. It is, however, possible for a cell to be in multiple <a - href="#column0" title=concept-column-group>column groups</a>. All the - slots that form part of one cell are part of zero or one <a - href="#row-group" title=concept-row-group>row groups</a> and zero or more - <a href="#column0" title=concept-column-group>column groups</a>. - - <p>In addition to <a href="#cell" title=concept-cell>cells</a>, <a - href="#column" title=concept-column>columns</a>, <a href="#row0" - title=concept-row>rows</a>, <a href="#row-group" - title=concept-row-group>row groups</a>, and <a href="#column0" - title=concept-column-group>column groups</a>, <a href="#table1" - title=concept-table>tables</a> can have a <code><a - href="#caption0">caption</a></code> element associated with them. This - gives the table a heading, or legend. - - <p>A <dfn id=table2>table model error</dfn> is an error with the data - represented by <code><a href="#table">table</a></code> elements and their - descendants. Documents must not have table model errors. - - <h5 id=forming><span class=secno>3.15.11.1. </span>Forming a table</h5> - - <p>To determine which elements correspond to which slots in a <a - href="#table1" title=concept-table>table</a> associated with a <code><a - href="#table">table</a></code> element, to determine the dimensions of the - table (<var title="">x<sub title="">max</sub></var> and <var - title="">y<sub title="">max</sub></var>), and to determine if there are - any <a href="#table2" title="table model error">table model errors</a>, - user agents must use the following algorithm: - - <ol> - <li> - <p>Let <var title="">x<sub title="">max</sub></var> be zero.</p> - - <li> - <p>Let <var title="">y<sub title="">max</sub></var> be zero.</p> - - <li> - <p>Let <var title="">the table</var> be the <a href="#table1" - title=concept-table>table</a> represented by the <code><a - href="#table">table</a></code> element. The <var title="">x<sub - title="">max</sub></var> and <var title="">y<sub - title="">max</sub></var> variables give <var title="">the table</var>'s - extent. <var title="">The table</var> is initially empty.</p> - - <li> - <p>If the <code><a href="#table">table</a></code> element has no table - children, then return <var title="">the table</var> (which will be - empty), and abort these steps.</p> - - <li> - <p>Let the <var title="">current element</var> be the first element child - of the <code><a href="#table">table</a></code> element.</p> - - <p>If a step in this algorithm ever requires the <var title="">current - element</var> to be advanced to the next child of the <code><a - href="#table">table</a></code> when there is no such next child, then - the algorithm must be aborted at that point and the algorithm must - return <var title="">the table</var>.</p> - - <li> - <p>While the <var title="">current element</var> is not one of the - following elements, advance the <var title="">current element</var> to - the next child of the <code><a href="#table">table</a></code>:</p> - - <ul class=brief> - <li><code><a href="#caption0">caption</a></code> - - <li><code><a href="#colgroup">colgroup</a></code> - - <li><code><a href="#thead0">thead</a></code> - - <li><code><a href="#tbody">tbody</a></code> - - <li><code><a href="#tfoot0">tfoot</a></code> - - <li><code><a href="#tr">tr</a></code> - </ul> - - <li> - <p>If the <var title="">current element</var> is a <code><a - href="#caption0">caption</a></code>, then that is the <code><a - href="#caption0">caption</a></code> element associated with <var - title="">the table</var>. Otherwise, it has no associated <code><a - href="#caption0">caption</a></code> element.</p> - - <li> - <p>If the <var title="">current element</var> is a <code><a - href="#caption0">caption</a></code>, then while the <var - title="">current element</var> is not one of the following elements, - advance the <var title="">current element</var> to the next child of the - <code><a href="#table">table</a></code>:</p> - - <ul class=brief> - <li><code><a href="#colgroup">colgroup</a></code> - - <li><code><a href="#thead0">thead</a></code> - - <li><code><a href="#tbody">tbody</a></code> - - <li><code><a href="#tfoot0">tfoot</a></code> - - <li><code><a href="#tr">tr</a></code> - </ul> - - <p>(Otherwise, the <var title="">current element</var> will already be - one of those elements.)</p> - - <li> - <p>If the <var title="">current element</var> is a <code><a - href="#colgroup">colgroup</a></code>, follow these substeps:</p> - - <ol> - <li> - <p>Let <var title="">next column</var> be 1.</p> - - <li> - <p><em>Column groups.</em> Process the <var title="">current - element</var> according to the appropriate one of the following two - cases:</p> - - <dl class=switch> - <dt>If the <var title="">current element</var> has any <code><a - href="#col">col</a></code> element children - - <dd> - <p>Follow these steps:</p> - - <ol> - <li> - <p>Let <var title="">x<sub title="">start</sub></var> have the - value <span><var title="">x<sub title="">max</sub></var>+1</span>.</p> - - <li> - <p>Let the <var title="">current column</var> be the first <code><a - href="#col">col</a></code> element child of the <code><a - href="#colgroup">colgroup</a></code> element.</p> - - <li> - <p><em>Columns.</em> If the <var title="">current column</var> - <code><a href="#col">col</a></code> element has a <code - title=attr-col-span><a href="#span2">span</a></code> attribute, - then parse its value using the <a href="#rules">rules for parsing - non-negative integers</a>.</p> - - <p>If the result of parsing the value is not an error or zero, then - let <var title="">span</var> be that value.</p> - - <p>Otherwise, if the <code><a href="#col">col</a></code> element - has no <code title=attr-col-span><a href="#span2">span</a></code> - attribute, or if trying to parse the attribute's value resulted in - an error, then let <var title="">span</var> be 1.</p> - - <li> - <p>Increase <var title="">x<sub title="">max</sub></var> by <var - title="">span</var>.</p> - - <li> - <p>Let the last <var title="">span</var> <a href="#column" - title=concept-column>columns</a> in <var title="">the table</var> - correspond to the <var title="">current column</var> <code><a - href="#col">col</a></code> element.</p> - - <li> - <p>If <var title="">current column</var> is not the last <code><a - href="#col">col</a></code> element child of the <code><a - href="#colgroup">colgroup</a></code> element, then let the <var - title="">current column</var> be the next <code><a - href="#col">col</a></code> element child of the <code><a - href="#colgroup">colgroup</a></code> element, and return to the - third step of this innermost group of steps (columns).</p> - - <li> - <p>Let all the last <a href="#column" - title=concept-column>columns</a> in <var title="">the table</var> - from <span>x=<var title="">x<sub title="">start</sub></var></span> - to <span>x=<var title="">x<sub title="">max</sub></var></span> - form a new <a href="#column0" title=concept-column-group>column - group</a>, anchored at the slot (<var title="">x<sub - title="">start</sub></var>, 1), with width <var title="">x<sub - title="">max</sub></var>-<var title="">x<sub - title="">start</sub></var>-1, corresponding to the <code><a - href="#colgroup">colgroup</a></code> element.</p> - </ol> - - <dt>If the <var title="">current element</var> has no <code><a - href="#col">col</a></code> element children - - <dd> - <ol> - <li> - <p>If the <code><a href="#colgroup">colgroup</a></code> element has - a <code title=attr-colgroup-span><a href="#span0">span</a></code> - attribute, then parse its value using the <a href="#rules">rules - for parsing non-negative integers</a>.</p> - - <p>If the result of parsing the value is not an error or zero, then - let <var title="">span</var> be that value.</p> - - <p>Otherwise, if the <code><a href="#colgroup">colgroup</a></code> - element has no <code title=attr-col-span><a - href="#span2">span</a></code> attribute, or if trying to parse the - attribute's value resulted in an error, then let <var - title="">span</var> be 1.</p> - - <li> - <p>Increase <var title="">x<sub title="">max</sub></var> by <var - title="">span</var>.</p> - - <li> - <p>Let the last <var title="">span</var> <a href="#column" - title=concept-column>columns</a> in <var title="">the table</var> - form a new <a href="#column0" title=concept-column-group>column - group</a>, anchored at the slot (<var title="">x<sub - title="">max</sub></var>-<var title="">span</var>+1, 1), with - width <var title="">span</var>, corresponding to the <code><a - href="#colgroup">colgroup</a></code> element.</p> - </ol> - </dl> - - <li> - <p>Advance the <var title="">current element</var> to the next child of - the <code><a href="#table">table</a></code>.</p> - - <li> - <p>While the <var title="">current element</var> is not one of the - following elements, advance the <var title="">current element</var> to - the next child of the <code><a href="#table">table</a></code>:</p> - - <ul class=brief> - <li><code><a href="#colgroup">colgroup</a></code> - - <li><code><a href="#thead0">thead</a></code> - - <li><code><a href="#tbody">tbody</a></code> - - <li><code><a href="#tfoot0">tfoot</a></code> - - <li><code><a href="#tr">tr</a></code> - </ul> - - <li> - <p>If the <var title="">current element</var> is a <code><a - href="#colgroup">colgroup</a></code> element, jump to step 2 in these - substeps (column groups).</p> - </ol> - - <li> - <p>Let <var title="">y<sub title="">current</sub></var> be zero. When the - algorithm is aborted, if <var title="">y<sub - title="">current</sub></var> does not equal <var title="">y<sub - title="">max</sub></var>, then that is a <a href="#table2">table model - error</a>.</p> - - <li> - <p>Let the <var title="">list of downward-growing cells</var> be an empty - list.</p> - - <li> - <p><em>Rows.</em> While the <var title="">current element</var> is not - one of the following elements, advance the <var title="">current - element</var> to the next child of the <code><a - href="#table">table</a></code>:</p> - - <ul class=brief> - <li><code><a href="#thead0">thead</a></code> - - <li><code><a href="#tbody">tbody</a></code> - - <li><code><a href="#tfoot0">tfoot</a></code> - - <li><code><a href="#tr">tr</a></code> - </ul> - - <li> - <p>If the <var title="">current element</var> is a <code><a - href="#tr">tr</a></code>, then run the <a href="#algorithm0">algorithm - for processing rows</a> (defined below), then return to the previous - step (rows).</p> - - <li> - <p>Otherwise, run the <a href="#algorithm">algorithm for ending a row - group</a>.</p> - - <li> - <p>Let <var title="">y<sub title="">start</sub></var> have the value - <span><var title="">y<sub title="">max</sub></var>+1</span>.</p> - - <li> - <p>For each <code><a href="#tr">tr</a></code> element that is a child of - the <var title="">current element</var>, in tree order, run the <a - href="#algorithm0">algorithm for processing rows</a> (defined below).</p> - - <li> <!-- if we added any rows, make them part of a row group --> - <p>If <span><var title="">y<sub - title="">max</sub></var> ≥ <var title="">y<sub - title="">start</sub></var></span>, then let all the last <a href="#row0" - title=concept-row>rows</a> in <var title="">the table</var> from - <span>y=<var title="">y<sub title="">start</sub></var></span> to - <span>y=<var title="">y<sub title="">max</sub></var></span> form a new - <a href="#row-group" title=concept-row-group>row group</a>, anchored at - the slot with coordinate (1, <var title="">y<sub - title="">start</sub></var>), with height <var title="">y<sub - title="">max</sub></var>-<var title="">y<sub - title="">start</sub></var>+1, corresponding to the <var title="">current - element</var>.</p> - - <li> - <p>Run the <a href="#algorithm">algorithm for ending a row group</a> - again.</p> - - <li> - <p>Return to step 12 (rows).</p> - </ol> - - <p>The <dfn id=algorithm>algorithm for ending a row group</dfn>, which is - invoked by the set of steps above when starting and eding a block of rows, - is: - - <ol> - <li> - <p>If <var title="">y<sub title="">current</sub></var> is less than <var - title="">y<sub title="">max</sub></var>, then this is a <a - href="#table2">table model error</a>.</p> - - <li> - <p>While <var title="">y<sub title="">current</sub></var> is less than - <var title="">y<sub title="">max</sub></var>, follow these steps:</p> - - <ol> - <li> - <p>Increase <var title="">y<sub title="">current</sub></var> by 1.</p> - - <li> - <p>Run the <a href="#algorithm1">algorithm for growing downward-growing - cells</a>.</p> - </ol> - - <li> - <p>Empty the <var title="">list of downward-growing cells</var>.</p> - </ol> - - <p>The <dfn id=algorithm0>algorithm for processing rows</dfn>, which is - invoked by the set of steps above for processing <code><a - href="#tr">tr</a></code> elements, is: - - <ol> - <li> - <p>Increase <var title="">y<sub title="">current</sub></var> by 1.</p> - <!-- ymax is increased below once we know cell dimensions --> - - <li> - <p>Run the <a href="#algorithm1">algorithm for growing downward-growing - cells</a>.</p> - - <li> - <p>Let <var title="">x<sub title="">current</sub></var> be 1.</p> - <!-- xmax is increased below once we know cell dimensions --> - - <li> - <p>If the <code><a href="#tr">tr</a></code> element being processed - contains no <code><a href="#td">td</a></code> or <code><a - href="#th">th</a></code> elements, then abort this set of steps and - return to the algorithm above.</p> - - <li> - <p>Let <var title="">current cell</var> be the first <code><a - href="#td">td</a></code> or <code><a href="#th">th</a></code> element in - the <code><a href="#tr">tr</a></code> element being processed.</p> - - <li> - <p><em>Cells.</em> While <var title="">x<sub title="">current</sub></var> - is less than or equal to <var title="">x<sub title="">max</sub></var> - and the slot with coordinate (<var title="">x<sub - title="">current</sub></var>, <var title="">y<sub - title="">current</sub></var>) already has a cell assigned to it, - increase <var title="">x<sub title="">current</sub></var> by 1.</p> - - <li> - <p>If <var title="">x<sub title="">current</sub></var> is greater than - <var title="">x<sub title="">max</sub></var>, increase <var - title="">x<sub title="">max</sub></var> by 1 (which will make them - equal).</p> - - <li> - <p>If the <var title="">current cell</var> has a <code - title="">colspan</code> attribute, then <span title="rules for parsing - non-negative integer values">parse that attribute's value</span>, and - let <var title="">colspan</var> be the result.</p> - - <p>If parsing that value failed, or returned zero, or if the attribute is - absent, then let <var title="">colspan</var> be 1, instead.</p> - - <li> - <p>If the <var title="">current cell</var> has a <code - title="">rowspan</code> attribute, then <span title="rules for parsing - non-negative integer values">parse that attribute's value</span>, and - let <var title="">rowspan</var> be the result.</p> - - <p>If parsing that value failed or if the attribute is absent, then let - <var title="">rowspan</var> be 1, instead.</p> - - <li> - <p>If <var title="">rowspan</var> is zero, then let <var title="">cell - grows downward</var> be true, and set <var title="">rowspan</var> to 1. - Otherwise, let <var title="">cell grows downward</var> be false.</p> - - <li> - <p>If <span><var title="">x<sub - title="">max</sub></var> < <var title="">x<sub - title="">current</sub></var>+<var title="">colspan</var>-1</span>, then - let <var title="">x<sub title="">max</sub></var> be <var title="">x<sub - title="">current</sub></var>+<var title="">colspan</var>-1.</p> - - <li> - <p>If <span><var title="">y<sub - title="">max</sub></var> < <var title="">y<sub - title="">current</sub></var>+<var title="">rowspan</var>-1</span>, then - let <var title="">y<sub title="">max</sub></var> be <var title="">y<sub - title="">current</sub></var>+<var title="">rowspan</var>-1.</p> - - <li> - <p>Let the slots with coordinates (<var title="">x</var>, <var - title="">y</var>) such that <span><var title="">x<sub - title="">current</sub></var> ≤ <var - title="">x</var> < <var title="">x<sub - title="">current</sub></var>+<var title="">colspan</var></span> and - <span><var title="">y<sub - title="">current</sub></var> ≤ <var - title="">y</var> < <var title="">y<sub - title="">current</sub></var>+<var title="">rowspan</var></span> be - covered by a new <a href="#cell" title=concept-cell>cell</a> <var - title="">c</var>, anchored at (<var title="">x<sub - title="">current</sub></var>, <var title="">y<sub - title="">current</sub></var>), which has width <var - title="">colspan</var> and height <var title="">rowspan</var>, - corresponding to the <var title="">current cell</var> element.</p> - - <p>If the <var title="">current cell</var> element is a <code><a - href="#th">th</a></code> element, let this new cell <var - title="">c</var> be a header cell; otherwise, let it be a data cell. To - establish what header cells apply to a data cell, use the <a - href="#algorithm2">algorithm for assigning header cells to data - cells</a> described in the next section.</p> - - <p>If any of the slots involved already had a <a href="#cell" - title=concept-cell>cell</a> covering them, then this is a <a - href="#table2">table model error</a>. Those slots now have two cells - overlapping.</p> - - <li> - <p>If <var title="">cell grows downward</var> is true, then add the tuple - {<var title="">c</var>, <var title="">x<sub - title="">current</sub></var>, <var title="">colspan</var>} to the <var - title="">list of downward-growing cells</var>.</p> - - <li> - <p>Increase <var title="">x<sub title="">current</sub></var> by <var - title="">colspan</var>.</p> - - <li> - <p>If <var title="">current cell</var> is the last <code><a - href="#td">td</a></code> or <code><a href="#th">th</a></code> element in - the <code><a href="#tr">tr</a></code> element being processed, then - abort this set of steps and return to the algorithm above.</p> - - <li> - <p>Let <var title="">current cell</var> be the next <code><a - href="#td">td</a></code> or <code><a href="#th">th</a></code> element in - the <code><a href="#tr">tr</a></code> element being processed.</p> - - <li> - <p>Return to step 5 (cells).</p> - </ol> - - <p>The <dfn id=algorithm1>algorithm for growing downward-growing - cells</dfn>, used when adding a new row, is as follows: - - <ol> - <li> - <p>If the <var title="">list of downward-growing cells</var> is empty, do - nothing. Abort these steps; return to the step that invoked this - algorithm.</p> - - <li> - <p>Otherwise, if <var title="">y<sub title="">max</sub></var> is less - than <var title="">y<sub title="">current</sub></var>, then increase - <var title="">y<sub title="">max</sub></var> by 1 (this will make it - equal to <var title="">y<sub title="">current</sub></var>).</p> - - <li> - <p>For each {<var title="">cell</var>, <var title="">cell<sub - title="">x</sub></var>, <var title="">width</var>} tuple in the <var - title="">list of downward-growing cells</var>, extend the <a - href="#cell" title=concept-cell>cell</a> <var title="">cell</var> so - that it also covers the slots with coordinates (<var title="">x</var>, - <var title="">y<sub title="">current</sub></var>), where <span><var - title="">cell<sub title="">x</sub></var> ≤ <var - title="">x</var> < <var title="">cell<sub - title="">x</sub></var>+<var title="">width</var>-1</span>.</p> - </ol> - - <p>If, after establishing which elements correspond to which slots, there - exists a <a href="#column" title=concept-column>column</a> in the <a - href="#table1" title=concept-table>table</a> containing only <span - title=concept-slot>slots</span> that do not have a <a href="#cell" - title=concept-cell>cell</a> anchored to them, then this is a <a - href="#table2">table model error</a>. - - <h5 id=header-and-data-cell-semantics><span class=secno>3.15.11.2. - </span>Forming relationships between data cells and header cells</h5> - - <p>Each data cell can be assigned zero or more header cells. The <dfn - id=algorithm2>algorithm for assigning header cells to data cells</dfn> is - as follows. - - <p>For each header cell in the table, in <a href="#tree-order">tree - order</a>: - - <ol> - <li> - <p>Let (<var title="">header<sub title="">x</sub></var>, <var - title="">header<sub title="">y</sub></var>) be the coordinate of the - slot to which the header cell is anchored.</p> - - <li> - <p>Examine the <code title=attr-th-scope><a - href="#scope0">scope</a></code> attribute of the <code><a - href="#th">th</a></code> element corresponding to the header cell, and, - based on its state, apply the appropriate substep:</p> - - <dl class=switch> - <dt>If it is in the <em title=attr-th-scope-row><a - href="#row">row</a></em> state - - <dd> - <p>Assign the header cell to any data cells anchored at slots with - coordinates (<var title="">data<sub title="">x</sub></var>, <var - title="">data<sub title="">y</sub></var>) where <span><var - title="">header<sub title="">x</sub></var> < <var - title="">data<sub title="">x</sub></var> ≤ <var - title="">x<sub title="">max</sub></var></span> and <span><var - title="">data<sub title="">y</sub></var> = <var - title="">header<sub title="">y</sub></var></span>.</p> - - <dt>If it is in the <em title=attr-th-scope-col><a - href="#col0">column</a></em> state - - <dd> - <p>Assign the header cell to any data cells anchored at slots with - coordinates (<var title="">data<sub title="">x</sub></var>, <var - title="">data<sub title="">y</sub></var>) where <span><var - title="">data<sub title="">x</sub></var> = <var - title="">header<sub title="">x</sub></var></span> and <span><var - title="">header<sub title="">y</sub></var> < <var - title="">data<sub title="">y</sub></var> ≤ <var - title="">y<sub title="">max</sub></var></span>.</p> - - <dt>If it is in the <em title=attr-th-scope-rowgroup><a - href="#rowgroup">row group</a></em> state - - <dd> - <p>If the header cell is not in a <a href="#row-group" - title=concept-row-group>row group</a>, then don't assign the header - cell to any data cells.</p> - - <p>Otherwise, let (1, <var title="">group<sub title="">y</sub></var>) - be the slot at which the row group is anchored, let <var - title="">height</var> be the number of rows in the row group, and - assign the header cell to any data cells anchored at slots with - coordinates (<var title="">data<sub title="">x</sub></var>, <var - title="">data<sub title="">y</sub></var>) where <span><var - title="">header<sub title="">x</sub></var> ≤ <var - title="">data<sub title="">x</sub></var> ≤ <var - title="">x<sub title="">max</sub></var></span> and <span><var - title="">header<sub title="">y</sub></var> ≤ <var - title="">data<sub title="">y</sub></var> < <var - title="">group<sub title="">y</sub></var>+<var - title="">height</var></span>.</p> - - <dt>If it is in the <em title=attr-th-scope-colgroup><a - href="#colgroup0">column group</a></em> state - - <dd> - <p>If the header cell is not in a <a href="#column0" - title=concept-column-group>column group</a>, then don't assign the - header cell to any data cells.</p> - - <p>Otherwise, let (<var title="">group<sub title="">x</sub></var>, 1) - be the slot at which the column group is anchored, let <var - title="">width</var> be the number of columns in the column group, and - assign the header cell to any data cells anchored at slots with - coordinates (<var title="">data<sub title="">x</sub></var>, <var - title="">data<sub title="">y</sub></var>) where <span><var - title="">header<sub title="">x</sub></var> ≤ <var - title="">data<sub title="">x</sub></var> < <var - title="">group<sub title="">x</sub></var>+<var - title="">width</var></span> and <span><var title="">header<sub - title="">y</sub></var> ≤ <var title="">data<sub - title="">y</sub></var> ≤ <var title="">y<sub - title="">max</sub></var></span>.</p> - - <dt>Otherwise, it is in the <em title="">auto</em> state - - <dd> - <p>If the header cell is not in the first row of the table, or not in - the first cell of a row, then don't assign the header cell to any data - cells.</p> - - <p>Otherwise, if the header cell is in the first row of the table, - assign the header cell to any data cells anchored at slots with - coordinates (<var title="">data<sub title="">x</sub></var>, <var - title="">data<sub title="">y</sub></var>) where <span><var - title="">data<sub title="">x</sub></var> = <var - title="">header<sub title="">x</sub></var></span> and <span><var - title="">header<sub title="">y</sub></var> < <var - title="">data<sub title="">y</sub></var> ≤ <var - title="">y<sub title="">max</sub></var></span>.</p> - - <p>Otherwise, the header cell is in the first column of the table; - assign the header cell to any data cells anchored at slots with - coordinates (<var title="">data<sub title="">x</sub></var>, <var - title="">data<sub title="">y</sub></var>) where <span><var - title="">header<sub title="">x</sub></var> < <var - title="">data<sub title="">x</sub></var> ≤ <var - title="">x<sub title="">max</sub></var></span> and <span><var - title="">data<sub title="">y</sub></var> = <var - title="">header<sub title="">y</sub></var></span>.</p> - </dl> - </ol> - - <h3 id=forms><span class=secno>3.16. </span>Forms</h3> - <!-- XXX everything in WF2 --> - - <p class=big-issue>This section will contain definitions of the - <code>form</code> element and so forth. - - <p class=big-issue>This section will be a rewrite of the HTML4 Forms and - Web Forms 2.0 specifications, with hopefully no normative changes.</p> - <!-- From HTML4: BUTTON FIELDSET FORM INPUT LABEL OPTGROUP OPTION - SELECT TEXTAREA --> - - <h4 id=the-form><span class=secno>3.16.1. </span>The <code>form</code> - element</h4> - - <h4 id=the-fieldset><span class=secno>3.16.2. </span>The - <code>fieldset</code> element</h4> - - <h4 id=the-input><span class=secno>3.16.3. </span>The <code>input</code> - element</h4> - - <h4 id=the-button><span class=secno>3.16.4. </span>The <code>button</code> - element</h4> - - <h4 id=the-label><span class=secno>3.16.5. </span>The <code>label</code> - element</h4> - - <h4 id=the-select><span class=secno>3.16.6. </span>The <code>select</code> - element</h4> - - <h4 id=the-datalist><span class=secno>3.16.7. </span>The - <code>datalist</code> element</h4> - - <h4 id=the-optgroup><span class=secno>3.16.8. </span>The - <code>optgroup</code> element</h4> - - <h4 id=the-option><span class=secno>3.16.9. </span>The <code>option</code> - element</h4> - - <h4 id=the-textarea><span class=secno>3.16.10. </span>The - <code>textarea</code> element</h4> - - <h4 id=the-output><span class=secno>3.16.11. </span>The <code>output</code> - element</h4> - - <h4 id=processing0><span class=secno>3.16.12. </span>Processing model</h4> - - <p class=big-issue>See <a - href="http://www.whatwg.org/specs/web-forms/current-work/#extend-form-controls">WF2</a> - for now - - <h5 id=form-submission><span class=secno>3.16.12.1. </span>Form submission</h5> - - <p class=big-issue>See <a - href="http://www.whatwg.org/specs/web-forms/current-work/#form-submission">WF2</a> - for now - - <h3 id=scripting0><span class=secno>3.17. </span>Scripting</h3> - - <h4 id=script><span class=secno>3.17.1. </span>The <dfn - id=script0><code>script</code></dfn> element</h4> - - <p><a href="#block-level0" title="block-level elements">Block-level - element</a>, <a href="#strictly">strictly inline-level content</a>, and <a - href="#metadata" title="metadata elements">metadata element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>In a <code><a href="#head">head</a></code> element. - - <dd>Where <a href="#block-level0">block-level elements</a> are expected. - - <dd>Where <a href="#inline-level0">inline-level content</a> is expected. - - <dt>Content model: - - <dd>If there is no <code title=attr-script-src><a - href="#src9">src</a></code> attribute, depends on the value of the <code - title=attr-script-type><a href="#type11">type</a></code> attribute. - - <dd>If there <em>is</em> a <code title=attr-script-src><a - href="#src9">src</a></code> attribute, the element must be empty. - - <dt>Element-specific attributes: - - <dd><code title=attr-script-src><a href="#src9">src</a></code> - - <dd><code title=attr-script-defer><a href="#defer">defer</a></code> - - <dd><code title=attr-script-async><a href="#async">async</a></code> - - <dd><code title=attr-script-type><a href="#type11">type</a></code> - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmlscriptelement>HTMLScriptElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute DOMString <code title=dom-script-src><a href="#src10">src</a></code>; - attribute boolean <code title=dom-script-defer><a href="#defer0">defer</a></code>; - attribute boolean <code title=dom-script-async><a href="#async0">async</a></code>; - attribute DOMString <code title=dom-script-type><a href="#type12">type</a></code>; - attribute DOMString <code title=dom-script-text><a href="#text0">text</a></code>; -};</pre> - </dl> - - <p>The <code><a href="#script0">script</a></code> element allows authors to - include dynamic script in their documents. - - <p>When the <dfn id=src9 title=attr-script-src><code>src</code></dfn> - attribute is set, the <code><a href="#script0">script</a></code> element - refers to an external file. The value of the attribute must be a URI (or - IRI). - - <p>If the <code title=attr-script-src><a href="#src9">src</a></code> - attribute is not set, then the script is given by the contents of the - element. - - <p>The language of the script may be given by the <dfn id=type11 - title=attr-script-type><code>type</code></dfn> attribute. If the attribute - is present, its value must be a valid MIME type, optionally with - parameters. <a href="#refsRFC2046">[RFC2046]</a> - - <p>The <dfn id=defer title=attr-script-defer><code>defer</code></dfn> and - <dfn id=async title=attr-script-async><code>async</code></dfn> attributes - are <a href="#boolean0" title="boolean attribute">boolean attributes</a> - that indicate how the script should be executed. - - <p>There are three possible modes that can be selected using these - attributes. If the <code title=attr-script-defer><a - href="#defer">defer</a></code> attribute is present, then the script is - executed when the page has finished parsing. If the <code - title=attr-script-defer><a href="#defer">defer</a></code> attribute is not - present but the <code title=attr-script-async><a - href="#async">async</a></code> attribute is present, then the script will - be executed asynchronously, as soon as it is available. If neither - attribute is present, then the script is downloaded and executed - immediately, before the user agent continues parsing the page. The exact - processing details for these attributes is described below. - - <p>The <code title=attr-script-async><a href="#async">async</a></code> - attribute must not be specified if the <code title=attr-script-defer><a - href="#defer">defer</a></code> attribute is specified. - - <p>Changing the <code title=attr-script-src><a href="#src9">src</a></code>, - <code title=attr-script-type><a href="#type11">type</a></code>, <code - title=attr-script-defer><a href="#defer">defer</a></code> and <code - title=attr-script-async><a href="#async">async</a></code> attributes - dynamically has no direct effect; these attribute are only used at - specific times described below (namely, when the element is inserted into - the document). - - <p><code><a href="#script0">script</a></code> elements have three - associated pieces of metadata. The first is a flag indicating whether or - not the script block has been <dfn id=already>"already executed"</dfn>. - Initially, <code><a href="#script0">script</a></code> elements must have - this flag unset (script blocks, when created, are not "already executed"). - When a <code><a href="#script0">script</a></code> element is cloned, the - "already executed" flag, if set, must be propagated to the clone when it - is created. The second is a flag indicating whether the element was <dfn - id=parser-inserted>"parser-inserted"</dfn>. This flag is set by the <a - href="#html-0">HTML parser</a> and is used to handle <code - title=dom-document-write-HTML><a - href="#document.write0">document.write()</a></code> calls. The third piece - of metadata is <dfn id=the-scripts><var>the script's type</var></dfn>. It - is determined when the script is run, based on the attributes on the - element at that time. - - <p><dfn id=running0 title="running a script">Running a script</dfn>: when a - script block is <span>inserted into a document</span>, the user agent must - act as follows: - - <ol> - <li> - <p>If the <code><a href="#script0">script</a></code> element has a <code - title=attr-script-type><a href="#type11">type</a></code> attribute but - its value is the empty string, or if the <code><a - href="#script0">script</a></code> element has no <code - title=attr-script-type><a href="#type11">type</a></code> attribute but - it has a <code title=attr-script-language>language</code> attribute, and - <em>that</em> attribute's value is the empty string, let <var><a - href="#the-scripts">the script's type</a></var> for this <code><a - href="#script0">script</a></code> element be "<code - title="">text/javascript</code>".</p> - - <p>Otherwise, if the <code><a href="#script0">script</a></code> element - has a <code title=attr-script-type><a href="#type11">type</a></code> - attribute, let <var><a href="#the-scripts">the script's type</a></var> - for this <code><a href="#script0">script</a></code> element be the value - of that attribute.</p> - - <p>Otherwise, if the element has a <code - title=attr-script-language>language</code> attribute, let <var><a - href="#the-scripts">the script's type</a></var> for this <code><a - href="#script0">script</a></code> element be the concatenation of the - string "<code title="">text/</code>" followed by the value of the <code - title=attr-script-language>language</code> attribute.</p> - - <li> - <p>If <a href="#scripting1">scripting is disabled</a>, or if the - <code>Document</code> has <code title=dom-document-designMode><a - href="#designMode">designMode</a></code> enabled, or if the user agent - does not <a href="#support">support the scripting language</a> given by - <var><a href="#the-scripts">the script's type</a></var> for this - <code><a href="#script0">script</a></code> element, or if the <code><a - href="#script0">script</a></code> element has its <a - href="#already">"already executed"</a> flag set, then the user agent - must abort these steps at this point. The script is not executed.</p> - - <li> - <p>The user agent must set the element's <a href="#already">"already - executed"</a> flag.</p> - - <li> - <p>If the element has a <code title=attr-script-src><a - href="#src9">src</a></code> attribute, then a load for the specified - content must be started.</p> - - <p class=note>Later, once the load has completed, the user agent will - have to complete <a href="#when-a" title="when a script completes - loading">the steps described below</a>.</p> - - <p>For performance reasons, user agents may start loading the script as - soon as the attribute is set, instead, in the hope that the element will - be inserted into the document. Either way, once the element is inserted - into the document, the load must have started. If the UA performs such - prefetching, but the element is never inserted in the document, or the - <code title=attr-script-src><a href="#src9">src</a></code> attribute is - dynamically changed, then the user agent will not execute the script, - and the load will have been effectively wasted.</p> - - <li> - <p>Then, the first of the following options that describes the situation - must be followed:</p> - - <dl class=switch> - <dt>If the document is still being parsed, and the element has a <code - title=attr-script-defer><a href="#defer">defer</a></code> attribute - - <dd>The element must be added to the end of the <a href="#list-of">list - of scripts that will execute when the document has finished - parsing</a>. The user agent must begin <a href="#when-a" title="when a - script completes loading">the next set of steps</a> when the script is - ready. <span class=big-issue>This isn't compatible with IE for inline - deferred scripts, but then what IE does is pretty hard to pin down - exactly. Do we want to keep this like it is? Be more compatible?</span> - <!--XXX - http://www.websiteoptimization.com/speed/tweak/defer/test/ - internal deferred scripts execute before any external scripts execute, or before the LOAD if there are none - external deferred scripts execute before the LOAD - --> - - - <dt>If the element has an <code title=attr-script-async><a - href="#async">async</a></code> attribute and a <code - title=attr-script-src><a href="#src9">src</a></code> attribute - - <dd>The element must be added to the end of the <a href="#list-of0">list - of scripts that will execute asynchronously</a>. The user agent must - jump to <a href="#when-a" title="when a script completes loading">the - next set of steps</a> once the script is ready. - - <dt>If the element has an <code title=attr-script-async><a - href="#async">async</a></code> attribute but no <code - title=attr-script-src><a href="#src9">src</a></code> attribute, and the - <a href="#list-of0">list of scripts that will execute - asynchronously</a> is not empty - - <dd>The element must be added to the end of the <a href="#list-of0">list - of scripts that will execute asynchronously</a>. - - <dt>If the element has a <code title=attr-script-src><a - href="#src9">src</a></code> attribute and has been flagged as <a - href="#parser-inserted">"parser-inserted"</a> - - <dd>The element is <a href="#the-script">the script that will execute as - soon as the parser resumes</a>. (There can only be one such script at a - time.) - - <dt>If the element has a <code title=attr-script-src><a - href="#src9">src</a></code> attribute - - <dd>The element must be added to the end of the <a href="#list-of1">list - of scripts that will execute as soon as possible</a>. The user agent - must jump to <a href="#when-a" title="when a script completes - loading">the next set of steps</a> when the script is ready. - - <dt>Otherwise - - <dd>The user agent must immediately <a href="#executing0" - title="executing a script block">execute the script</a>, even if other - scripts are already executing. - </dl> - </ol> - - <p><dfn id=when-a title="when a script completes loading">When a script - completes loading</dfn>: If a script whose element was added to one of the - lists mentioned above completes loading while the document is still being - parsed, then the parser handles it. Otherwise, when a script completes - loading, the UA must follow the following steps as soon as as any other - scripts that may be executing have finished executing: - - <dl class=switch> - <dt>If the script's element was added to the <dfn id=list-of>list of - scripts that will execute when the document has finished parsing</dfn>: - - <dd> - <ol> - <li> - <p>If the script's element is not the first element in the list, then - do nothing yet. Stop going through these steps.</p> - - <li> - <p>Otherwise, <a href="#executing0" title="executing a script - block">execute the script</a> (that is, the script associated with the - first element in the list).</p> - - <li> - <p>Remove the script's element from the list (i.e. shift out the first - entry in the list).</p> - - <li> - <p>If there are any more entries in the list, and if the script - associated with the element that is now the first in the list is - already loaded, then jump back to step two to execute it.</p> - </ol> - - <dt>If the script's element was added to the <dfn id=list-of0>list of - scripts that will execute asynchronously</dfn>: - - <dd> - <ol> - <li> - <p>If the script is not the first element in the list, then do nothing - yet. Stop going through these steps.</p> - - <li> - <p><a href="#executing0" title="executing a script block">Execute the - script</a> (the script associated with the first element in the list).</p> - - <li> - <p>Remove the script's element from the list (i.e. shift out the first - entry in the list).</p> - - <li> - <p>If there are any more scripts in the list, and the element now at - the head of the list had no <code title=attr-script-src><a - href="#src9">src</a></code> attribute when it was added to the list, - or had one, but its associated script has finished loading, then jump - back to step two to execute the script associated with this element.</p> - </ol> - - <dt>If the script's element was added to the <dfn id=list-of1>list of - scripts that will execute as soon as possible</dfn>: - - <dd> - <ol> - <li> - <p><a href="#executing0" title="executing a script block">Execute the - script</a>.</p> - - <li> - <p>Remove the script's element from the list.</p> - </ol> - - <dt>If the script is <dfn id=the-script>the script that will execute as - soon as the parser resumes</dfn>: - - <dd> - <p>The script will be handled <a href="#scriptTagParserResumes">when the - parser resumes</a> (amazingly enough).</p> - </dl> - - <p>The download of an external script must <a href="#delays">delay the - <code title=event-load>load</code> event</a>. - - <p><dfn id=executing0 title="executing a script block">Executing a script - block</dfn>: If the load resulted in an error (for example a DNS error, or - an HTTP 404 error), then executing the script must just consist of <a - href="#firing5" title="fire an error event">firing an <code - title=event-error>error</code> event</a> at the element. - - <p>If the load was successful, then first the user agent must <a - href="#firing4">fire a <code title=event-load>load</code> event</a> at the - element, and then, if <a href="#scripting2">scripting is enabled</a>, and - the <code>Document</code> does not have <code - title=dom-document-designMode><a href="#designMode">designMode</a></code> - enabled, and the <code>Document</code> is the <a href="#active">active - document</a> in its <a href="#browsing0">browsing context</a>, the user - agent must execute the script: - - <p>If the script is from an external file, then that file must be used as - the file to execute. - - <p>If the script is inline, then, for scripting languages that consist of - pure text, user agents must use the value of the DOM <code - title=dom-script-text><a href="#text0">text</a></code> attribute (defined - below) as the script to execute, and for XML-based scripting languages, - user agents must use all the child nodes of the <code><a - href="#script0">script</a></code> element as the script to execute. - - <p>In any case, the user agent must execute the script according to the - semantics defined by the language associated with <var><a - href="#the-scripts">the script's type</a></var> (see the <a - href="#scriptingLanguages">scripting languages</a> section below). - - <p>Scripts must be executed in the scope of the <a - href="#browsing0">browsing context</a> of the element's - <code>Document</code>. - - <p class=note>The element's attributes' values might have changed between - when the element was inserted into the document and when the script has - finished loading, as may its other attributes; similarly, the element - itself might have been taken back out of the DOM, or had other changes - made. These changes do not in any way affect the above steps; only the - values of the attributes at the time the <code><a - href="#script0">script</a></code> element is first inserted into the - document matter. - - <p>The DOM attributes <dfn id=src10 - title=dom-script-src><code>src</code></dfn>, <dfn id=type12 - title=dom-script-type><code>type</code></dfn>, <dfn id=defer0 - title=dom-script-defer><code>defer</code></dfn>, <dfn id=async0 - title=dom-script-async><code>async</code></dfn>, each must <a - href="#reflect">reflect</a> the respective content attributes of the same - name. - - <p>The DOM attribute <dfn id=text0 - title=dom-script-text><code>text</code></dfn> must return a concatenation - of the contents of all the <a href="#text-node" title="text node">text - nodes</a> that are direct children of the <code><a - href="#script0">script</a></code> element (ignoring any other nodes such - as comments or elements), in tree order. On setting, it must act the same - way as the <code><a href="#textcontent">textContent</a></code> DOM - attribute. - - <h5 id=scriptingLanguages><span class=secno>3.17.1.1. </span>Scripting - languages</h5> - - <p>A user agent is said to <dfn id=support>support the scripting - language</dfn> if <var><a href="#the-scripts">the script's type</a></var> - matches the MIME type of a scripting language that the user agent - implements. - - <p>The following lists some MIME types and the languages to which they - refer: - - <dl> - <dt><code>text/javascript</code> - - <dd>ECMAScript. <a href="#refsECMA262">[ECMA262]</a> - - <dt><code>text/javascript;e4x=1</code> - - <dd>ECMAScript with ECMAScript for XML. <a - href="#refsECMA357">[ECMA357]</a> - </dl> - - <p>User agents may support other MIME types and other languages. - - <p>When examining types to determine if they support the language, user - agents must not ignore unknown MIME parameters — types with unknown - parameters must be assumed to be unsupported.</p> - <!-- - XXX we should reference #refsRFC4329 http://www.ietf.org/rfc/rfc4329 - --> - - <h4 id=the-noscript><span class=secno>3.17.2. </span>The <dfn - id=noscript><code>noscript</code></dfn> element</h4> - - <p>When <a href="#scripting1">scripting is disabled</a>: <a - href="#transparent0">transparent</a> <a href="#block-level0" - title="block-level elements">block-level element</a>, and <a - href="#transparent0">transparent</a> <a href="#strictly">strictly - inline-level content</a>. - - <p>When <a href="#scripting2">scripting is enabled</a>: <a - href="#block-level0" title="block-level elements">block-level element</a>, - and <a href="#strictly">strictly inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>In a <code><a href="#head">head</a></code> element of an <a - href="#html-" title=">HTML documents">HTML document</a>, if there are no - ancestor <code><a href="#noscript">noscript</a></code> elements. - - <dd>Where <a href="#block-level0">block-level elements</a> are expected in - <a href="#html-">HTML documents</a>, if there are no ancestor <code><a - href="#noscript">noscript</a></code> elements. - - <dd>Where <a href="#inline-level0">inline-level content</a> is expected in - <a href="#html-">HTML documents</a>, if there are no ancestor <code><a - href="#noscript">noscript</a></code> elements. - - <dt>Content model: - - <dd>When <a href="#scripting1">scripting is disabled</a>: <a - href="#transparent0">transparent</a>, but there must be no <code><a - href="#noscript">noscript</a></code> element descendants. - - <dd>When <a href="#scripting2">scripting is enabled</a>: Text that - conforms to the requirements given in the prose. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#noscript">noscript</a></code> element does not - represent anything. It is used to present different markup to user agents - that support scripting and those that don't support scripting, by - affecting how the document is parsed. - - <p>The <code><a href="#noscript">noscript</a></code> element must not be - used in <a href="#xml-documents">XML documents</a>. - - <p>When used in <a href="#html-">HTML documents</a>, the allowed content - model depends on whether scripting is enabled or not. - - <p>If <a href="#scripting1">scripting is disabled</a>, then the content - model of a <code><a href="#noscript">noscript</a></code> element is <a - href="#transparent0">transparent</a>, with the additional restriction that - a <code><a href="#noscript">noscript</a></code> element must not have a - <code><a href="#noscript">noscript</a></code> element as an ancestor (that - is, <code><a href="#noscript">noscript</a></code> can't be nested). - - <p>If <a href="#scripting2">scripting is enabled</a>, then the content - model of a <code><a href="#noscript">noscript</a></code> element is text, - except that the text must be such that running the following algorithm - results in a conforming document with no <code><a - href="#noscript">noscript</a></code> elements and no <code><a - href="#script0">script</a></code> elements, and such that no step in the - algorithm causes an <a href="#html-0">HTML parser</a> to flag a <a - href="#parse">parse error</a>: - - <ol> - <li>Remove every <code><a href="#script0">script</a></code> element from - the document. - - <li>Make a list of every <code><a href="#noscript">noscript</a></code> - element in the document. For every <code><a - href="#noscript">noscript</a></code> element in that list, perform the - following steps: - <ol> - <li>Let the <var title="">parent element</var> be the parent element of - the <code><a href="#noscript">noscript</a></code> element. - - <li>Take all the children of the <var title="">parent element</var> that - come before the <code><a href="#noscript">noscript</a></code> element, - and call these elements <var title="">the before children</var>. - - <li>Take all the children of the <var title="">parent element</var> that - come <em>after</em> the <code><a href="#noscript">noscript</a></code> - element, and call these elements <var title="">the after - children</var>. - - <li>Let <var title="">s</var> be the concatenation of all the <a - href="#text-node">text node</a> children of the <code><a - href="#noscript">noscript</a></code> element. - - <li>Set the <code title=dom-innerHTML-HTML><a - href="#innerhtml0">innerHTML</a></code> attribute of the <var - title="">parent element</var> to the value of <var title="">s</var>. - (This, as a side-effect, causes the <code><a - href="#noscript">noscript</a></code> element to be removed from the - document.) - - <li>Insert <var title="">the before children</var> at the start of the - <var title="">parent element</var>, preserving their original relative - order. - - <li>Insert <var title="">the after children</var> at the end of the <var - title="">parent element</var>, preserving their original relative - order. - </ol> - </ol> - - <p>The <code><a href="#noscript">noscript</a></code> element has no other - requirements. In particular, children of the <code><a - href="#noscript">noscript</a></code> element are not exempt from form - submission, scripting, and so forth, even when scripting is enabled. - - <p class=note>All these contortions are required because, for historical - reasons, the <code><a href="#noscript">noscript</a></code> element causes - the <a href="#html-0">HTML parser</a> to act differently based on whether - scripting is enabled or not. The element is not allowed in XML, because in - XML the parser is not affected by such state, and thus the element would - not have the desired effect. - - <h4 id=the-event-source><span class=secno>3.17.3. </span>The <dfn - id=event-source><code>event-source</code></dfn> element</h4> - - <p><a href="#block-level0" title="block-level elements">Block-level - element</a>, <a href="#strictly">strictly inline-level content</a>, and <a - href="#metadata" title="metadata elements">metadata element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>In a <code><a href="#head">head</a></code> element. - - <dd>Where <a href="#block-level0">block-level elements</a> are expected. - - <dd>Where <a href="#inline-level0">inline-level content</a> is expected. - - <dt>Content model: - - <dd>Empty. - - <dt>Element-specific attributes: - - <dd><code title=attr-event-source-src><a href="#src11">src</a></code> - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmleventsourceelement>HTMLEventSourceElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute DOMString <a href="#src12" title=dom-event-source-src>src</a>; -};</pre> - </dl> - - <p>The <code><a href="#event-source">event-source</a></code> element - represents a target for events generated by a remote server. - - <p>The <dfn id=src11 title=attr-event-source-src><code>src</code></dfn> - attribute, if specified, must give a URI (or IRI) pointing to a resource - that uses the <code>application/x-dom-event-stream</code> format. - - <p>When the element is inserted into the document, if it has the <code - title=attr-event-source-src><a href="#src11">src</a></code> attribute - specified, the user agent must act as if the <code - title=dom-remoteEventTarget-addEventSource><a - href="#addeventsource">addEventSource()</a></code> method on the <code><a - href="#event-source">event-source</a></code> element had been invoked with - the URI resulting from resolving the <code title=attr-event-source-src><a - href="#src11">src</a></code> attribute's value to an absolute URI. - - <p>While the element is in a document, if its <code - title=attr-event-source-src><a href="#src11">src</a></code> attribute is - mutated, the user agent must act as if first the <code - title=dom-remoteEventTarget-removeEventSource><a - href="#removeeventsource">removeEventSource()</a></code> method on the - <code><a href="#event-source">event-source</a></code> element had been - invoked with the URI resulting from resolving the old value of the - attribute to an absolute URI, and then as if the <code - title=dom-remoteEventTarget-addEventSource><a - href="#addeventsource">addEventSource()</a></code> method on the element - had been invoked with the URI resulting from resolving the <em>new</em> - value of the <code title=attr-event-source-src><a - href="#src11">src</a></code> attribute to an absolute URI. - - <p>When the element is removed from the document, if it has the <code - title=attr-event-source-src><a href="#src11">src</a></code> attribute - specified, or, when the <code title=attr-event-source-src><a - href="#src11">src</a></code> attribute is about to be removed, the user - agent must act as if the <code - title=dom-remoteEventTarget-removeEventSource><a - href="#removeeventsource">removeEventSource()</a></code> method on the - <code><a href="#event-source">event-source</a></code> element had been - invoked with the URI resulting from resolving the <code - title=attr-event-source-src><a href="#src11">src</a></code> attribute's - value to an absolute URI. - - <p>There can be more than one <code><a - href="#event-source">event-source</a></code> element per document, but - authors should take care to avoid opening multiple connections to the same - server as HTTP recommends a limit to the number of simultaneous - connections that a user agent can open per server.</p> - <!-- XXX should we make 'load', 'error', 'abort' events fire on this - element? --> - - <p>The <dfn id=src12 title=dom-event-source-src><code>src</code></dfn> DOM - attribute must reflect the content attribute of the same name. - - <h3 id=interactive><span class=secno>3.18. </span>Interactive elements</h3> - - <h4 id=the-details><span class=secno>3.18.1. </span>The <dfn - id=details><code>details</code></dfn> element</h4> - - <p><a href="#interactive1" title="interactive elements">Interactive</a>, <a - href="#block-level0" title="block-level elements">block-level element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> are expected. - - <dt>Content model: - - <dd>One <code><a href="#legend">legend</a></code> element followed by - either one or more <a href="#block-level0">block-level elements</a> or <a - href="#inline-level0">inline-level content</a> (but not both). - - <dt>Element-specific attributes: - - <dd><code title=attr-details-open><a href="#open0">open</a></code> - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmldetailselement>HTMLDetailsElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute boolean <a href="#open1" title=dom-details-open>open</a>; -};</pre> - </dl> - - <p>The <code><a href="#details">details</a></code> element represents - additional information or controls which the user can obtain on demand. - - <p>The first element child of a <code><a href="#details">details</a></code> - element, if it is a <code><a href="#legend">legend</a></code> element, - represents the summary of the details. - - <p>If the first element is not a <code><a href="#legend">legend</a></code> - element, the UA should provide its own legend (e.g. "Details"). - - <p>The <dfn id=open0 title=attr-details-open><code>open</code></dfn> - content attribute is a <a href="#boolean0">boolean attribute</a>. If - present, it indicates that the details should be shown to the user. If the - attribute is absent, the details should not be shown. - - <p>If the attribute is removed, then the details should be hidden. If the - attribute is added, the details should be shown. - - <p>The user should be able to request that the details be shown or hidden. - - <p>The <dfn id=open1 title=dom-details-open><code>open</code></dfn> - attribute must <a href="#reflect">reflect</a> the <code - title=attr-details-open><a href="#open0">open</a></code> content - attribute.</p> - <!-- -http://mail.gnome.org/archives/usability/2006-June/msg00015.html -http://developer.apple.com/documentation/UserExperience/Conceptual/OSXHIGuidelines/XHIGControls/chapter_18_section_7.html -https://www.google.com/base/settings ---> - - <p class=big-issue>Rendering will be described in the Rendering section in - due course. Basically CSS :open and :closed match the element, it's a - block-level element by default, and when it matches :closed it renders as - if it had an XBL binding attached to it whose template was just - <code><template>▶<content - includes="legend:first-child">Details</content></template></code>, - and when it's :open it acts as if it had an XBL binding attached to it - whose template was just <code><template>▼<content - includes="legend:first-child">Details</content><content/></template></code> - or some such. - - <p class=big-issue>Clicking the legend would make it open/close (and would - change the content attribute). Question: Do we want the content attribute - to reflect the actual state like this? I think we do, the DOM not - reflecting state has been a pain in the neck before. But is it - semantically ok? - - <h4 id=datagrid><span class=secno>3.18.2. </span>The <dfn - id=datagrid0><code>datagrid</code></dfn> element</h4> - - <p><a href="#interactive1" title="interactive elements">Interactive</a>, <a - href="#block-level0" title="block-level elements">block-level element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> are expected, - if there are no ancestor <a href="#interactive1">interactive - elements</a>. - - <dt>Content model: - - <dd>Either: Nothing. - - <dd>Or: One or more <a href="#block-level0">block-level elements</a>, the - first of which is not a <code><a href="#table">table</a></code> element. - - <dd>Or: A single <code><a href="#table">table</a></code> element. - - <dd>Or: A single <code>select</code> element. - - <dd>Or: A single <code>datalist</code> element. - - <dt>Element-specific attributes: - - <dd><code title=attr-datagrid-multiple><a - href="#multiple0">multiple</a></code> - - <dd><code title=attr-datagrid-disabled><a - href="#disabled3">disabled</a></code> - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmldatagridelement>HTMLDataGridElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute <a href="#datagriddataprovider">DataGridDataProvider</a> <a href="#data2" title=dom-datagrid-data>data</a>; - readonly attribute <a href="#datagridselection">DataGridSelection</a> <a href="#selection0" title=dom-datagrid-selection>selection</a>; - attribute boolean <a href="#multiple" title=dom-datagrid-multiple>multiple</a>; - attribute boolean <a href="#disabled2" title=dom-datagrid-disabled>disabled</a>; - void <a href="#updateeverything" title=dom-datagrid-updateEverything>updateEverything</a>(); - void <a href="#updaterowschanged" title=dom-datagrid-updateRowsChanged>updateRowsChanged</a>(in <a href="#rowspecification">RowSpecification</a> row, in unsigned long count); - void <a href="#updaterowsinserted" title=dom-datagrid-updateRowsInserted>updateRowsInserted</a>(in <a href="#rowspecification">RowSpecification</a> row, in unsigned long count); - void <a href="#updaterowsremoved" title=dom-datagrid-updateRowsRemoved>updateRowsRemoved</a>(in <a href="#rowspecification">RowSpecification</a> row, in unsigned long count); - void <a href="#updaterowchanged" title=dom-datagrid-updateRowChanged>updateRowChanged</a>(in <a href="#rowspecification">RowSpecification</a> row); - void <a href="#updatecolumnchanged" title=dom-datagrid-updateColumnChanged>updateColumnChanged</a>(in unsigned long column); - void <a href="#updatecellchanged" title=dom-datagrid-updateCellChanged>updateCellChanged</a>(in <a href="#rowspecification">RowSpecification</a> row, in unsigned long column); -};</pre> - </dl> - - <p class=big-issue>One possible thing to be added is a way to detect when a - row/selection has been deleted, activated, etc, by the user (delete key, - enter key, etc).</p> - <!-- XXXPA --> - - <p class=big-issue>This element is defined as interactive, which means it - can't contain other interactive elements, despite the fact that we expect - it to work with other interactive elements e.g. checkboxes and input - fields. It should be called something like a Leaf Interactive Element or - something, which counts for ancestors looking in and not descendants - looking out. - - <p>The <code><a href="#datagrid0">datagrid</a></code> element represents an - interactive representation of tree, list, or tabular data. - - <p>The data being presented can come either from the content, as elements - given as children of the <code><a href="#datagrid0">datagrid</a></code> - element, or from a scripted data provider given by the <code - title=dom-datagrid-data><a href="#data2">data</a></code> DOM attribute. - - <p>The <code title=attr-datagrid-multiple><a - href="#multiple0">multiple</a></code> and <code - title=attr-datagrid-disabled><a href="#disabled3">disabled</a></code> - attributes are <a href="#boolean0" title="boolean attribute">boolean - attributes</a>. Their effects are described in the processing model - sections below. - - <p>The <dfn id=multiple - title=dom-datagrid-multiple><code>multiple</code></dfn> and <dfn - id=disabled2 title=dom-datagrid-disabled><code>disabled</code></dfn> DOM - attributes must <a href="#reflect">reflect</a> the <code - title=attr-datagrid-multiple><a href="#multiple0">multiple</a></code> and - <code title=attr-datagrid-disabled><a - href="#disabled3">disabled</a></code> content attributes respectively. - - <h5 id=the-datagrid><span class=secno>3.18.2.1. </span>The <code><a - href="#datagrid0">datagrid</a></code> data model</h5> - - <p><em>This section is non-normative.</em> - - <p>In the <code><a href="#datagrid0">datagrid</a></code> data model, data - is structured as a set of rows representing a tree, each row being split - into a number of columns. The columns are always present in the data - model, although individual columns may be hidden in the presentation. - - <p>Each row can have child rows. Child rows may be hidden or shown, by - closing or opening (respectively) the parent row. - - <p>Rows are referred to by the path along the tree that one would take to - reach the row, using zero-based indices. Thus, the first row of a list is - row "0", the second row is row "1"; the first child row of the first row - is row "0,0", the second child row of the first row is row "0,1"; the - fourth child of the seventh child of the third child of the tenth row is - "9,2,6,3", etc. - - <p>The columns can have captions. Those captions are not considered a row - in their own right, they are obtained separately. - - <p>Selection of data in a <code><a href="#datagrid0">datagrid</a></code> - operates at the row level. If the <code title=attr-datagrid-multiple><a - href="#multiple0">multiple</a></code> attribute is present, multiple rows - can be selected at once, otherwise the user can only select one row at a - time. - - <p>The <code><a href="#datagrid0">datagrid</a></code> element can be - disabled entirely by setting the <code title=attr-datagrid-disabled><a - href="#disabled3">disabled</a></code> attribute.</p> - <!--XXXDND - <p class="big-issue">selection draggable [normative definitions are - in the interactive part below]</p> ---> - - <p>Columns, rows, and cells can each have specific flags, known as classes, - applied to them by the data provider. These classes <a - href="#datagridClassSummary">affect the functionality</a> of the <code><a - href="#datagrid0">datagrid</a></code> element, and are also <a - href="#datagridPseudos">passed to the style system</a>. They are similar - in concept to the <code title=attr-class><a href="#class">class</a></code> - attribute, except that they are not specified on elements but are given by - scripted data providers.</p> - <!-- XXX check xrefs --> - - <h5 id=how-rows><span class=secno>3.18.2.2. </span>How rows are identified</h5> - - <p>The chains of numbers that give a row's path, or identifier, are - represented by objects that implement the <a - href="#rowspecification">RowSpecification</a> interface. - - <pre class=idl>interface <dfn id=rowspecification>RowSpecification</dfn> { - // binding-specific interface -};</pre> - - <p>In ECMAScript, two classes of objects are said to implement this - interface: Numbers representing non-negative integers, and homogeneous - arrays of Numbers representing non-negative integers. Thus, - <code>[1,0,9]</code> is a <a - href="#rowspecification">RowSpecification</a>, as is <code>1</code> on its - own. However, <code>[1,0.2,9]</code> is not a <a - href="#rowspecification">RowSpecification</a> object, since its second - value is not an integer. - - <p>User agents must always represent <code><a - href="#rowspecification">RowSpecification</a></code>s in ECMAScript by - using arrays, even if the path only has one number. - - <p>The root of the tree is represented by the empty path; in ECMAScript, - this is the empty array (<code>[]</code>). Only the <code - title=dom-provider-getRowCount><a - href="#getrowcount">getRowCount()</a></code> and <code - title=dom-provider-getChildAtPosition><a - href="#getchildatposition">GetChildAtPosition()</a></code> methods ever - get called with the empty path. - - <h5 id=the-data><span class=secno>3.18.2.3. </span>The data provider - interface</h5> - - <p><em>The conformance criteria in this section apply to any implementation - of the <code><a - href="#datagriddataprovider">DataGridDataProvider</a></code>, including - (and most commonly) the content author's implementation(s).</em> - - <pre class=idl>// To be implemented by Web authors as a JS object -interface <dfn id=datagriddataprovider>DataGridDataProvider</dfn> { - void <a href="#initialize" title=dom-provider-initialize>initialize</a>(in HTMLDataGridElement datagrid); - unsigned long <a href="#getrowcount" title=dom-provider-getRowCount>getRowCount</a>(in <a href="#rowspecification">RowSpecification</a> row); - unsigned long <a href="#getchildatposition" title=dom-provider-getChildAtPosition>getChildAtPosition</a>(in <a href="#rowspecification">RowSpecification</a> parentRow, in unsigned long position); - unsigned long <a href="#getcolumncount" title=dom-provider-getColumnCount>getColumnCount</a>(); - DOMString <a href="#getcaptiontext" title=dom-provider-getCaptionText>getCaptionText</a>(in unsigned long column); - void <a href="#getcaptionclasses" title=dom-provider-getCaptionClasses>getCaptionClasses</a>(in unsigned long column, in DOMTokenList classes); - DOMString <a href="#getrowimage" title=dom-provider-getRowImage>getRowImage</a>(in <a href="#rowspecification">RowSpecification</a> row); - <a href="#htmlmenuelement">HTMLMenuElement</a> <a href="#getrowmenu" title=dom-provider-getRowMenu>getRowMenu</a>(in <a href="#rowspecification">RowSpecification</a> row); - void <a href="#getrowclasses" title=dom-provider-getRowClasses>getRowClasses</a>(in <a href="#rowspecification">RowSpecification</a> row, in DOMTokenList classes); - DOMString <a href="#getcelldata" title=dom-provider-getCellData>getCellData</a>(in <a href="#rowspecification">RowSpecification</a> row, in unsigned long column); - void <a href="#getcellclasses" title=dom-provider-getCellClasses>getCellClasses</a>(in <a href="#rowspecification">RowSpecification</a> row, in unsigned long column, in DOMTokenList classes); -<!--XXXDND - boolean <span title="dom-provider-canDrop">canDrop</span>(in <span>RowSpecification</span> row, in <span>RowSpecification</span> position, data); - boolean <span title="dom-provider-dropped">dropped</span>(in <span>RowSpecification</span> row, in <span>RowSpecification</span> position, data); ---> void <a href="#togglecolumnsortstate" title=dom-provider-toggleColumnSortState>toggleColumnSortState</a>(in unsigned long column); - void <a href="#setcellcheckedstate" title=dom-provider-setCellCheckedState>setCellCheckedState</a>(in <a href="#rowspecification">RowSpecification</a> row, in unsigned long column, in long state); - void <a href="#cyclecell" title=dom-provider-cycleCell>cycleCell</a>(in <a href="#rowspecification">RowSpecification</a> row, in unsigned long column); - void <a href="#editcell" title=dom-provider-editCell>editCell</a>(in <a href="#rowspecification">RowSpecification</a> row, in unsigned long column, in DOMString data); -<!--XXXPA - void <span title="dom-provider-performAction">performAction</span>(in DOMString action); // required if .performAction() is ever invoked on the datagrid - void <span title="dom-provider-performActionOnRow">performActionOnRow</span>(in <span>RowSpecification</span> row, in DOMString action); // required if getRowClasses ever includes 'deletable' or if <span title="dom-provider-.performActionOnRow">.performActionOnRow</span>() is ever invoked on the datagrid - void <span title="dom-provider-performActionOnCell">performActionOnCell</span>(in <span>RowSpecification</span> row, in unsigned long column, in DOMString action); // required if .performActionOnCell() is ever invoked on the datagrid --->};</pre> - <!-- based on http://lxr.mozilla.org/seamonkey/source/layout/xul/base/src/tree/public/nsITreeView.idl --> - - <p>The <code><a - href="#datagriddataprovider">DataGridDataProvider</a></code> interface - represents the interface that objects must implement to be used as custom - data views for <code><a href="#datagrid0">datagrid</a></code> elements. - - <p>Not all the methods are required. The minimum number of methods that - must be implemented in a useful view is two: the <code - title=dom-provider-getRowCount><a - href="#getrowcount">getRowCount()</a></code> and <code - title=dom-provider-getCellData><a - href="#getcelldata">getCellData()</a></code> methods. - - <p>Once the object is written, it must be hooked up to the <code><a - href="#datagrid0">datagrid</a></code> using the <dfn id=data2 - title=dom-datagrid-data><code>data</code></dfn> DOM attribute. - - <p>The following methods may be usefully implemented: - - <dl> - <dt><dfn id=initialize title=dom-provider-initialize><code>initialize(<var - title="">datagrid</var>)</code></dfn> - - <dd>Called by the <code><a href="#datagrid0">datagrid</a></code> element - (the one given by the <var title="">datagrid</var> argument) after it has - first populated itself. This would typically be used to set the initial - selection of the <code><a href="#datagrid0">datagrid</a></code> element - when it is first loaded. The data provider could also use this method - call to register a <code title=event-select><a - href="#select">select</a></code> event handler on the <code><a - href="#datagrid0">datagrid</a></code> in order to monitor selection - changes. - - <dt><dfn id=getrowcount - title=dom-provider-getRowCount><code>getRowCount(<var - title="">row</var>)</code></dfn> - - <dd>Must return the number of rows that are children of the specified <var - title="">row</var>, including rows that are off-screen. If <var - title="">row</var> is empty, then the number of rows at the top level - must be returned. If the value that this method would return for a given - <var title="">row</var> changes, the relevant update methods on the - <code><a href="#datagrid0">datagrid</a></code> must be called first. - Otherwise, this method must always return the same number. For a list (as - opposed to a tree), this method must return 0 whenever it is called with - a <var title="">row</var> identifier that is not empty. - - <dt><dfn id=getchildatposition - title=dom-provider-getChildAtPosition><code>getChildAtPosition(<var - title="">parentRow</var>, <var title="">position</var>)</code></dfn> - - <dd>Must return the index of the row that is a child of <var - title="">parentRow</var> and that is to be positioned as the <var - title="">position</var>th row under <var title="">parentRow</var> when - rendering the children of <var title="">parentRow</var>. If <var - title="">parentRow</var> is empty, then <var title="">position</var> - refers to the <var title="">position</var>th row at the top level of the - data grid. May be omitted if the rows are always to be sorted in the - natural order. (The natural order is the one where the method always - returns <var title="">position</var>.) For a given <var - title="">parentRow</var>, this method must never return the same value - for different values of <var title="">position</var>. The returned value - <var title="">x</var> must be in the range 0 ≤ <var - title="">x</var> < <var title="">n</var>, where <var - title="">n</var> is the value returned by <code - title=dom-provider-getRowCount><a href="#getrowcount">getRowCount(<var - title="">parentRow</var>)</a></code>. - - <dt><dfn id=getcolumncount - title=dom-provider-getColumnCount><code>getColumnCount()</code></dfn> - - <dd>Must return the number of columns currently in the data model - (including columns that might be hidden). May be omitted if there is only - one column. If the value that this method would return changes, the - <code><a href="#datagrid0">datagrid</a></code>'s <code - title=dom-datagrid-updateEverything><a - href="#updateeverything">updateEverything()</a></code> method must be - called. - - <dt><dfn id=getcaptiontext - title=dom-provider-getCaptionText><code>getCaptionText(<var - title="">column</var>)</code></dfn> - - <dd>Must return the caption, or label, for column <var - title="">column</var>. May be omitted if the columns have no captions. If - the value that this method would return changes, the <code><a - href="#datagrid0">datagrid</a></code>'s <code - title=dom-datagrid-updateColumnChanged><a - href="#updatecolumnchanged">updateColumnChanged()</a></code> method must - be called with the appropriate column index. - - <dt><dfn id=getcaptionclasses - title=dom-provider-getCaptionClasses><code>getCaptionClasses(<var - title="">column</var>, <var title="">classes</var>)</code></dfn> - - <dd>Must add the classes that apply to column <var title="">column</var> - to the <var title="">classes</var> object. May be omitted if the columns - have no special classes. If the classes that this method would add - changes, the <code><a href="#datagrid0">datagrid</a></code>'s <code - title=dom-datagrid-updateColumnChanged><a - href="#updatecolumnchanged">updateColumnChanged()</a></code> method must - be called with the appropriate column index. Some classes have <a - href="#datagridClassSummary">predefined meanings</a>. - - <dt><dfn id=getrowimage - title=dom-provider-getRowImage><code>getRowImage(<var - title="">row</var>)</code></dfn> - - <dd>Must return a URI to an image that represents row <var - title="">row</var>, or the empty string if there is no applicable image. - May be omitted if no rows have associated images. If the value that this - method would return changes, the <code><a - href="#datagrid0">datagrid</a></code>'s update methods must be called to - update the row in question. - - <dt><dfn id=getrowmenu title=dom-provider-getRowMenu><code>getRowMenu(<var - title="">row</var>)</code></dfn> - - <dd>Must return an <code><a - href="#htmlmenuelement">HTMLMenuElement</a></code> object that is to be - used as a context menu for row <var title="">row</var>, or null if there - is no particular context menu. May be omitted if none of the rows have a - special context menu. As this method is called immediately before showing - the menu in question, no precautions need to be taken if the return value - of this method changes. - - <dt><dfn id=getrowclasses - title=dom-provider-getRowClasses><code>getRowClasses(<var - title="">row</var>, <var title="">classes</var>)</code></dfn> - - <dd>Must add the classes that apply to row <var title="">row</var> to the - <var title="">classes</var> object. May be omitted if the rows have no - special classes. If the classes that this method would add changes, the - <code><a href="#datagrid0">datagrid</a></code>'s update methods must be - called to update the row in question. Some classes have <a - href="#datagridClassSummary">predefined meanings</a>. - - <dt><dfn id=getcelldata - title=dom-provider-getCellData><code>getCellData(<var title="">row</var>, - <var title="">column</var>)</code></dfn> - - <dd>Must return the value of the cell on row <var title="">row</var> in - column <var title="">column</var>. For text cells, this must be the text - to show for that cell. For <a href="#progress1" - title=datagrid-cell-class-progress>progress bar cells</a>, this must be - either a floating point number in the range 0.0 to 1.0 (converted to a - string representation<!-- XXX this isn't - technically enough to define what the author must be doing here, - but let's let that slide until someone notices -->), - indicating the fraction of the progress bar to show as full (1.0 meaning - complete), or the empty string, indicating an indeterminate progress bar. - If the value that this method would return changes, the <code><a - href="#datagrid0">datagrid</a></code>'s update methods must be called to - update the rows that changed. If only one cell changed, the <code - title=dom-datagrid-updateCellChanged><a - href="#updatecellchanged">updateCellChanged()</a></code> method may be - used. - - <dt><dfn id=getcellclasses - title=dom-provider-getCellClasses><code>getCellClasses(<var - title="">row</var>, <var title="">column</var>, <var - title="">classes</var>)</code></dfn> - - <dd>Must add the classes that apply to the cell on row <var - title="">row</var> in column <var title="">column</var> to the <var - title="">classes</var> object. May be omitted if the cells have no - special classes. If the classes that this method would add changes, the - <code><a href="#datagrid0">datagrid</a></code>'s update methods must be - called to update the rows or cells in question. Some classes have <a - href="#datagridClassSummary">predefined meanings</a>. - - <dt><dfn id=togglecolumnsortstate - title=dom-provider-toggleColumnSortState><code>toggleColumnSortState(<var - title="">column</var>)</code></dfn> - - <dd>Called by the <code><a href="#datagrid0">datagrid</a></code> when the - user tries to sort the data using a particular column <var - title="">column</var>. The data provider must update its state so that - the <code title=dom-provider-getChildAtPosition><a - href="#getchildatposition">GetChildAtPosition()</a></code> method returns - the new order, and the classes of the columns returned by <code - title=dom-provider-getCaptionClasses><a - href="#getcaptionclasses">getCaptionClasses()</a></code> represent the - new sort status. There is no need to tell the <code><a - href="#datagrid0">datagrid</a></code> that it the data has changed, as - the <code><a href="#datagrid0">datagrid</a></code> automatically assumes - that the entire data model will need updating. - - <dt><dfn id=setcellcheckedstate - title=dom-provider-setCellCheckedState><code>setCellCheckedState(<var - title="">row</var>, <var title="">column</var>, <var - title="">state</var>)</code></dfn> - - <dd>Called by the <code><a href="#datagrid0">datagrid</a></code> when the - user changes the state of a checkbox cell on row <var title="">row</var>, - column <var title="">column</var>. The checkbox should be toggled to the - state given by <var title="">state</var>, which is a positive integer (1) - if the checkbox is to be checked, zero (0) if it is to be unchecked, and - a negative number (-1) if it is to be set to the indeterminate state. - There is no need to tell the <code><a - href="#datagrid0">datagrid</a></code> that the cell has changed, as the - <code><a href="#datagrid0">datagrid</a></code> automatically assumes that - the given cell will need updating. - - <dt><dfn id=cyclecell title=dom-provider-cycleCell><code>cycleCell(<var - title="">row</var>, <var title="">column</var>)</code></dfn> - - <dd>Called by the <code><a href="#datagrid0">datagrid</a></code> when the - user changes the state of a cyclable cell on row <var title="">row</var>, - column <var title="">column</var>. The data provider should change the - state of the cell to the new state, as appropriate. There is no need to - tell the <code><a href="#datagrid0">datagrid</a></code> that the cell has - changed, as the <code><a href="#datagrid0">datagrid</a></code> - automatically assumes that the given cell will need updating. - - <dt><dfn id=editcell title=dom-provider-editCell><code>editCell(<var - title="">row</var>, <var title="">column</var>, <var - title="">data</var>)</code></dfn> - - <dd>Called by the <code><a href="#datagrid0">datagrid</a></code> when the - user edits the cell on row <var title="">row</var>, column <var - title="">column</var>. The new value of the cell is given by <var - title="">data</var>. The data provider should update the cell - accordingly. There is no need to tell the <code><a - href="#datagrid0">datagrid</a></code> that the cell has changed, as the - <code><a href="#datagrid0">datagrid</a></code> automatically assumes that - the given cell will need updating.</dd> - <!--XXXPA - void performAction(in DOMString action); // required if .performAction() is ever invoked on the datagrid - void performActionOnRow(in <span>RowSpecification</span> row, in DOMString action); // required if getRowClasses ever includes 'deletable' or if .performActionOnRow() is ever invoked on the datagrid - void performActionOnCell(in <span>RowSpecification</span> row, in unsigned long column, in DOMString action); // required if .performActionOnCell() is ever invoked on the datagrid ---> - </dl> - - <p>The following classes (for rows, columns, and cells) may be usefully - used in conjunction with this interface: - - <table id=datagridClassSummary> - <tbody> - <tr> - <th>Class name - - <th>Applies to - - <th>Description - - <tr> - <td><!--checked--><dfn id=checked - title=datagrid-cell-class-checked><code>checked</code></dfn> - - <td>Cells - - <td>The cell has a checkbox and it is checked. (The <code - title=datagrid-cell-class-cyclable><a - href="#cyclable">cyclable</a></code> and <code - title=datagrid-cell-class-progress><a - href="#progress1">progress</a></code> classes override this, though.) - - <tr> - <td><!--cyclable--><dfn id=cyclable - title=datagrid-cell-class-cyclable><code>cyclable</code></dfn> - - <td>Cells - - <td>The cell can be cycled through multiple values. (The <code - title=datagrid-cell-class-progress><a - href="#progress1">progress</a></code> class overrides this, though.) - - <tr> - <td><!--editable--><dfn id=editable - title=datagrid-cell-class-editable><code>editable</code></dfn> - - <td>Cells - - <td>The cell can be edited. (The <code - title=datagrid-cell-class-cyclable><a - href="#cyclable">cyclable</a></code>, <code - title=datagrid-cell-class-progress><a - href="#progress1">progress</a></code>, <code - title=datagrid-cell-class-checked><a - href="#checked">checked</a></code>, <code - title=datagrid-cell-class-checked><a - href="#checked">unchecked</a></code> and <code - title=datagrid-cell-class-checked><a - href="#checked">indeterminate</a></code> classes override this, - though.) - - <tr> - <td><!--header--><dfn id=header0 - title=datagrid-row-class-header><code>header</code></dfn> - - <td>Rows - - <td>The row is a heading, not a data row. - - <tr> - <td><!--indeterminate--><dfn id=indeterminate - title=datagrid-cell-class-indeterminate><code>indeterminate</code></dfn> - - <td>Cells - - <td>The cell has a checkbox, and it can be set to an indeterminate - state. If neither the <code title=datagrid-cell-class-checked><a - href="#checked">checked</a></code> nor <code - title=datagrid-cell-class-checked><a - href="#checked">unchecked</a></code> classes are present, then the - checkbox is in that state, too. (The <code - title=datagrid-cell-class-cyclable><a - href="#cyclable">cyclable</a></code> and <code - title=datagrid-cell-class-progress><a - href="#progress1">progress</a></code> classes override this, though.) - - <tr> - <td><!--initially-hidden--><dfn id=initially-hidden - title=datagrid-column-class-initially-hidden><code>initially-hidden</code></dfn> - - <td>Columns - - <td>The column will not be shown when the <code><a - href="#datagrid0">datagrid</a></code> is initially rendered. If this - class is not present on the column when the <code><a - href="#datagrid0">datagrid</a></code> is initially rendered, the column - will be visible if space allows. - - <tr> - <td><!--initially-closed--><dfn id=initially-closed - title=datagrid-row-class-initially-closed><code>initially-closed</code></dfn> - - <td>Rows - - <td>The row will be closed when the <code><a - href="#datagrid0">datagrid</a></code> is initially rendered. If neither - this class nor the <code title=datagrid-row-class-initially-open><a - href="#initially-open">initially-open</a></code> class is present on - the row when the <code><a href="#datagrid0">datagrid</a></code> is - initially rendered, the initial state will depend on platform - conventions. - - <tr> - <td><!--initially-open--><dfn id=initially-open - title=datagrid-row-class-initially-open><code>initially-open</code></dfn> - - <td>Rows - - <td>The row will be opened when the <code><a - href="#datagrid0">datagrid</a></code> is initially rendered. If neither - this class nor the <code title=datagrid-row-class-initially-closed><a - href="#initially-closed">initially-closed</a></code> class is present - on the row when the <code><a href="#datagrid0">datagrid</a></code> is - initially rendered, the initial state will depend on platform - conventions. - - <tr> - <td><!--progress--><dfn id=progress1 - title=datagrid-cell-class-progress><code>progress</code></dfn> - - <td>Cells - - <td>The cell is a progress bar. - - <tr> - <td><!--reversed--><dfn id=reversed - title=datagrid-column-class-reversed><code>reversed</code></dfn> - - <td>Columns - - <td>If the cell is sorted, the sort direction is descending, instead of - ascending. - - <tr> - <td><!--selectable-separator--><dfn id=selectable-separator - title=datagrid-row-class-selectable-separator><code>selectable-separator</code></dfn> - - <td>Rows - - <td>The row is a normal, selectable, data row, except that instead of - having data, it only has a separator. (The <code - title=datagrid-row-class-header><a href="#header0">header</a></code> - and <code title=datagrid-row-class-separator><a - href="#separator">separator</a></code> classes override this, though.) - - <tr> - <td><!--separator--><dfn id=separator - title=datagrid-row-class-separator><code>separator</code></dfn> - - <td>Rows - - <td>The row is a separator row, not a data row. (The <code - title=datagrid-row-class-header><a href="#header0">header</a></code> - class overrides this, though.) - - <tr> - <td><!--sortable--><dfn id=sortable - title=datagrid-column-class-sortable><code>sortable</code></dfn> - - <td>Columns - - <td>The data can be sorted by this column. - - <tr> - <td><!--sorted--><dfn id=sorted - title=datagrid-column-class-sorted><code>sorted</code></dfn> - - <td>Columns - - <td>The data is sorted by this column. Unless the <code - title=datagrid-column-class-reversed><a - href="#reversed">reversed</a></code> class is also present, the sort - direction is ascending. - - <tr> - <td><!--unchecked--><dfn id=unchecked - title=datagrid-cell-class-unchecked><code>unchecked</code></dfn> - - <td>Cells - - <td>The cell has a checkbox and, unless the <code - title=datagrid-cell-class-checked><a href="#checked">checked</a></code> - class is present as well, it is unchecked. (The <code - title=datagrid-cell-class-cyclable><a - href="#cyclable">cyclable</a></code> and <code - title=datagrid-cell-class-progress><a - href="#progress1">progress</a></code> classes override this, though.) - </tr> - <!--XXXPA - <tr> - <td><!- -deletable- -><dfn title="datagrid-row-class-deletable"><code>deletable</code></dfn></td> - <td>Rows</td> - <td></td> - </tr> ---> - </table> - - <h5 id=the-default><span class=secno>3.18.2.4. </span>The default data - provider</h5> - - <p>The user agent must supply a default data provider for the case where - the <code><a href="#datagrid0">datagrid</a></code>'s <code - title=dom-datagrid-data><a href="#data2">data</a></code> attribute is - null. It must act as described in this section. - - <p>The behaviour of the default data provider depends on the nature of the - first element child of the <code><a href="#datagrid0">datagrid</a></code>. - - <dl class=switch> - <dt>While the first element child is a <code><a - href="#table">table</a></code> element - - <dd> - <p><strong><code title=dom-provider-getRowCount><a - href="#getrowcount">getRowCount(<var - title="">row</var>)</a></code></strong>: The number of rows returned by - the default data provider for the root of the tree (when <var - title="">row</var> is empty) must be the total number of <code><a - href="#tr">tr</a></code> elements that are children of <code><a - href="#tbody">tbody</a></code> elements that are children of the - <code><a href="#table">table</a></code>, if there are any such child - <code><a href="#tbody">tbody</a></code> elements. If there are no such - <code><a href="#tbody">tbody</a></code> elements then the number of rows - returned for the root must be the number of <code><a - href="#tr">tr</a></code> elements that are children of the <code><a - href="#table">table</a></code>.</p> - - <p>When <var title="">row</var> is not empty, the number of rows returned - must be zero.</p> - - <p class=note>The <code><a href="#table">table</a></code>-based default - data provider cannot represent a tree.</p> - - <p class=note>Rows in <code><a href="#thead0">thead</a></code> elements - do not contribute to the number of rows returned, although they do - affect the columns and column captions. Rows in <code><a - href="#tfoot0">tfoot</a></code> elements are <a href="#ignored" - title=ignore>ignored</a> completely by this algorithm.</p> - - <p id=defaultDataProviderTableMapper><strong><code - title=dom-provider-getChildAtPosition><a - href="#getchildatposition">getChildAtPosition(<var title="">row</var>, - <var title="">i</var>)</a></code></strong>: The default data provider - must return the mapping appropriate to the <a - href="#defaultDataProviderTableSort">current sort order</a>.</p> - - <p><strong><code title=dom-provider-getColumnCount><a - href="#getcolumncount">getColumnCount()</a></code></strong>: The number - of columns returned must be the number of <code><a - href="#td">td</a></code> element children in the first <code><a - href="#tr">tr</a></code> element child of the first <code><a - href="#tbody">tbody</a></code> element child of the <code><a - href="#table">table</a></code>, if there are any such <code><a - href="#tbody">tbody</a></code> elements. If there are no such <code><a - href="#tbody">tbody</a></code> elements, then it must be the number of - <code><a href="#td">td</a></code> element children in the first <code><a - href="#tr">tr</a></code> element child of the <code><a - href="#table">table</a></code>, if any, or otherwise 1. If the number - that would be returned by these rules is 0, then 1 must be returned - instead.</p> - - <p><strong><code title=dom-provider-getCaptionText><a - href="#getcaptiontext">getCaptionText(<var - title="">i</var>)</a></code></strong>: If the <code><a - href="#table">table</a></code> has no <code><a - href="#thead0">thead</a></code> element child, or if its first <code><a - href="#thead0">thead</a></code> element child has no <code><a - href="#tr">tr</a></code> element child, the default data provider must - return the empty string for all captions. Otherwise, the value of the - <code><a href="#textcontent">textContent</a></code> attribute of the - <var title="">i</var>th <code><a href="#th">th</a></code> element child - of the first <code><a href="#tr">tr</a></code> element child of the - first <code><a href="#thead0">thead</a></code> element child of the - <code><a href="#table">table</a></code> element must be returned. If - there is no such <code><a href="#th">th</a></code> element, the empty - string must be returned.</p> - - <p><strong><code title=dom-provider-getCaptionClasses><a - href="#getcaptionclasses">getCaptionClasses(<var title="">i</var>, <var - title="">classes</var>)</a></code></strong>: If the <code><a - href="#table">table</a></code> has no <code><a - href="#thead0">thead</a></code> element child, or if its first <code><a - href="#thead0">thead</a></code> element child has no <code><a - href="#tr">tr</a></code> element child, the default data provider must - not add any classes for any of the captions. Otherwise, each class in - the <code title=attr-class><a href="#class">class</a></code> attribute - of the <var title="">i</var>th <code><a href="#th">th</a></code> element - child of the first <code><a href="#tr">tr</a></code> element child of - the first <code><a href="#thead0">thead</a></code> element child of the - <code><a href="#table">table</a></code> element must be added to the - <var title="">classes</var>. If there is no such <code><a - href="#th">th</a></code> element, no classes must be added. The user - agent must then:</p> - - <ol> - <li>Remove the <code title=datagrid-column-class-sorted><a - href="#sorted">sorted</a></code> and <code - title=datagrid-column-class-reversed><a - href="#reversed">reversed</a></code> classes. - - <li>If the <code><a href="#table">table</a></code> element has a <code - title=attr-class><a href="#class">class</a></code> attribute that - includes the <code title="">sortable</code> class, add the <code - title=datagrid-column-class-sortable><a - href="#sortable">sortable</a></code> class. - - <li>If the column is the one currently being used to sort the data, add - the <code title=datagrid-column-class-sorted><a - href="#sorted">sorted</a></code> class. - - <li>If the column is the one currently being used to sort the data, and - it is sorted in descending order, add the <code - title=datagrid-column-class-reversed><a - href="#reversed">reversed</a></code> class as well. - </ol> - - <p>The various row- and cell- related methods operate relative to a - particular element, the element of the row or cell specified by their - arguments.</p> - - <p><strong>For rows</strong>: Since the default data provider for a - <code><a href="#table">table</a></code> always returns 0 as the number - of children for any row other than the root, the path to the row passed - to these methods will always consist of a single number. In the prose - below, this number is referred to as <var title="">i</var>.</p> - - <p>If the <code><a href="#table">table</a></code> has <code><a - href="#tbody">tbody</a></code> element children, the element for the - <var title="">i</var>th row is the <var title="">i</var>th <code><a - href="#tr">tr</a></code> element that is a child of a <code><a - href="#tbody">tbody</a></code> element that is a child of the <code><a - href="#table">table</a></code> element. If the <code><a - href="#table">table</a></code> does not have <code><a - href="#tbody">tbody</a></code> element children, then the element for - the <var title="">i</var>th real row is the <var title="">i</var>th - <code><a href="#tr">tr</a></code> element that is a child of the - <code><a href="#table">table</a></code> element.</p> - - <p><strong>For cells</strong>: Given a row and its element, the row's - <var title="">i</var>th cell's element is the <var title="">i</var>th - <code><a href="#td">td</a></code> element child of the row element.</p> - - <p class=note>The <code>colspan</code> and <code>rowspan</code> - attributes are <a href="#ignored" title=ignore>ignored</a> by this - algorithm.</p> - - <p><strong><code title=dom-provider-getRowImage><a - href="#getrowimage">getRowImage(<var - title="">i</var>)</a></code></strong>: If the row's first cell's element - has an <code><a href="#img">img</a></code> element child, then the URI - of the row's image is the URI of the first <code><a - href="#img">img</a></code> element child of the row's first cell's - element. Otherwise, the URI of the row's image is the empty string.</p> - <!-- XXX well. that sentence could - have gone better, that's for sure. --> - - <p><strong><code title=dom-provider-getRowMenu><a - href="#getrowmenu">getRowMenu(<var - title="">i</var>)</a></code></strong>: If the row's first cell's element - has a <code><a href="#menu">menu</a></code> element child, then the - row's menu is the first <code><a href="#menu">menu</a></code> element - child of the row's first cell's element. Otherwise, the row has no menu.</p> - - <p><strong><code title=dom-provider-getRowClasses><a - href="#getrowclasses">getRowClasses(<var title="">i</var>, <var - title="">classes</var>)</a></code></strong>: The default data provider - must never add a class to the row's classes.</p> - - <p id=defaultDataProviderTableSort><strong><code - title=dom-provider-toggleColumnSortState><a - href="#togglecolumnsortstate">toggleColumnSortState(<var - title="">i</var>)</a></code></strong>: If the data is already being - sorted on the given column, then the user agent must change the current - sort mapping to be the inverse of the current sort mapping; if the sort - order was ascending before, it is now descending, otherwise it is now - ascending. Otherwise, if the current sort column is another column, or - the data model is currently not sorted, the user agent must create a new - mapping, which maps rows in the data model to rows in the DOM so that - the rows in the data model are sorted by the specified column, in - ascending order. (Which sort comparison operator to use is left up to - the UA to decide.)</p> - - <p>When the sort mapping is changed, the values returned by the <code - title=dom-provider-getChildAtPosition><a - href="#getchildatposition">getChildAtPosition()</a></code> method for - the default data provider <a href="#defaultDataProviderTableMapper">will - change appropriately</a>.</p> - - <p><strong><code title=dom-provider-getCellData><a - href="#getcelldata">getCellData(<var title="">i</var>, <var - title="">j</var>)</a></code>, <code title=dom-provider-getCellClasses><a - href="#getcellclasses">getCellClasses(<var title="">i</var>, <var - title="">j</var>, <var title="">classes</var>)</a></code>, <code - title=dom-provider-setCellCheckedState><a - href="#setcellcheckedstate">getCellCheckedState(<var title="">i</var>, - <var title="">j</var>, <var title="">state</var>)</a></code>, <code - title=dom-provider-cycleCell><a href="#cyclecell">cycleCell(<var - title="">i</var>, <var title="">j</var>)</a></code>, and <code - title=dom-provider-editCell><a href="#editcell">editCell(<var - title="">i</var>, <var title="">j</var>, <var - title="">data</var>)</a></code></strong>: See <a - href="#commonDefaultDataGridMethodDefinitions">the common definitions - below</a>.</p> - - <p>The data provider must call the <code><a - href="#datagrid0">datagrid</a></code>'s update methods appropriately - whenever the descendants of the <code><a - href="#datagrid0">datagrid</a></code> mutate. For example, if a <code><a - href="#tr">tr</a></code> is removed, then the <code - title=dom-datagrid-updateRowsRemoved><a - href="#updaterowsremoved">updateRowsRemoved()</a></code> methods would - probably need to be invoked, and any change to a cell or its descendants - must cause the cell to be updated. If the <code><a - href="#table">table</a></code> element stops being the first child of - the <code><a href="#datagrid0">datagrid</a></code>, then the data - provider must call the <code title=dom-datagrid-updateEverything><a - href="#updateeverything">updateEverything()</a></code> method on the - <code><a href="#datagrid0">datagrid</a></code>. Any change to a cell - that is in the column that the data provider is currently using as its - sort column must also cause the sort to be reperformed, with a call to - <code title=dom-datagrid-updateEverything><a - href="#updateeverything">updateEverything()</a></code> if the change did - affect the sort order.</p> - - <dt>While the first element child is a <code>select</code> or - <code>datalist</code> element - - <dd> - <p>The default data provider must return 1 for the column count, the - empty string for the column's caption, and must not add any classes to - the column's classes.</p> - - <p>For the rows, assume the existence of a node filter view of the - descendants of the first element child of the <code><a - href="#datagrid0">datagrid</a></code> element (the <code>select</code> - or <code>datalist</code> element), that skips all nodes other than - <code>optgroup</code> and <code>option</code> elements, as well as any - descendents of any <code>option</code> elements.</p> - - <p>Given a path <var title="">row</var>, the corresponding element is the - one obtained by drilling into the view, taking the child given by the - path each time.</p> - - <div class=example> - <p>Given the following XML markup:</p> - - <pre><datagrid> - <select> - <!-- the options and optgroups have had their labels and values removed - to make the underlying structure clearer --> - <optgroup> - <option/> - <option/> - </optgroup> - <optgroup> - <option/> - <optgroup id="a"> - <option/> - <option/> - <bogus/> - <option id="b"/> - </optgroup> - <option/> - </optgroup> - </select> -</datagrid></pre> - - <p>The path "1,1,2" would select the element with ID "b". In the - filtered view, the text nodes, comment nodes, and bogus elements are - ignored; so for instance, the element with ID "a" (path "1,1") has only - 3 child nodes in the view.</p> - </div> - - <p><code title=dom-provider-getRowCount><a - href="#getrowcount">getRowCount(<var title="">row</var>)</a></code> must - drill through the view to find the element corresponding to the method's - argument, and return the number of child nodes in the filtered view that - the corresponding element has. (If the <var title="">row</var> is empty, - the corresponding element is the <code>select</code> element at the root - of the filtered view.)</p> - - <p><code title=dom-provider-getChildAtPosition><a - href="#getchildatposition">getChildAtPosition(<var title="">row</var>, - <var title="">position</var>)</a></code> must return <var - title="">position</var>. (The <code>select</code>/<code>datalist</code> - default data provider does not support sorting the data grid.)</p> - - <p><code title=dom-provider-getRowImage><a - href="#getrowimage">getRowImage(<var title="">i</var>)</a></code> must - return the empty string, <code title=dom-provider-getRowMenu><a - href="#getrowmenu">getRowMenu(<var title="">i</var>)</a></code> must - return null.</p> - - <p><code title=dom-provider-getRowClasses><a - href="#getrowclasses">getRowClasses(<var title="">row</var>, <var - title="">classes</var>)</a></code> must add the classes from the - following list to <var title="">classes</var> when their condition is - met:</p> - - <ul> - <li>If the <var title="">row</var>'s corresponding element is an - <code>optgroup</code> element: <code title=datagrid-row-class-header><a - href="#header0">header</a></code> - - <li>If the <var title="">row</var>'s corresponding element contains - other elements that are also in the view, and the element's <code - title=attr-class><a href="#class">class</a></code> attribute contains - the <code title="">closed</code> class: <code - title=datagrid-row-class-initially-closed><a - href="#initially-closed">initially-closed</a></code> - - <li>If the <var title="">row</var>'s corresponding element contains - other elements that are also in the view, and the element's <code - title=attr-class><a href="#class">class</a></code> attribute contains - the <code title="">open</code> class: <code - title=datagrid-row-class-initially-open><a - href="#initially-open">initially-open</a></code> - </ul> - - <p>The <code title=dom-provider-getCellData><a - href="#getcelldata">getCellData(<var title="">row</var>, <var - title="">cell</var>)</a></code> method must return the value of the - <code title=attr-optgroup-label>label</code> attribute if the <var - title="">row</var>'s corresponding element is an <code>optgroup</code> - element, otherwise, if the <var title="">row</var>'s corresponding - element is an <code>option</code>element, its <code - title=attr-option-label>label</code> attribute if it has one, otherwise - the value of its <code><a href="#textcontent">textContent</a></code> DOM - attribute.</p> - - <p>The <code title=dom-provider-getCellClasses><a - href="#getcellclasses">getCellClasses(<var title="">row</var>, <var - title="">cell</var>, <var title="">classes</var>)</a></code> method must - add no classes.</p> - - <p class=big-issue><!-- select-provider-selection - XXX-->autoselect - some rows when initialised, reflect the selection in the select, reflect - the multiple attribute somehow.</p> - - <p>The data provider must call the <code><a - href="#datagrid0">datagrid</a></code>'s update methods appropriately - whenever the descendants of the <code><a - href="#datagrid0">datagrid</a></code> mutate.</p> - - <dt>While the first element child is another element - - <dd> - <p>The default data provider must return 1 for the column count, the - empty string for the column's caption, and must not add any classes to - the column's classes.</p> - - <p>For the rows, assume the existence of a node filter view of the - descendants of the <code><a href="#datagrid0">datagrid</a></code> that - skips all nodes other than <code><a href="#li">li</a></code>, <code><a - href="#h1">h1</a></code>-<code><a href="#h6">h6</a></code>, and <code><a - href="#hr">hr</a></code> elements, and skips any descendants of <code><a - href="#menu">menu</a></code> elements.</p> - - <p>Given this view, each element in the view represents a row in the data - model. The element corresponding to a path <var title="">row</var> is - the one obtained by drilling into the view, taking the child given by - the path each time. The element of the row of a particular method call - is the element given by drilling into the view along the path given by - the method's arguments.</p> - - <p><code title=dom-provider-getRowCount><a - href="#getrowcount">getRowCount(<var title="">row</var>)</a></code> must - return the number of child elements in this view for the given row, or - the number of elements at the root of the view if the <var - title="">row</var> is empty.</p> - - <div class=example> - <p>In the following example, the elements are identified by the paths - given by their child text nodes:</p> - - <pre><datagrid> - <ol> - <li> row 0 </li> - <li> row 1 - <ol> - <li> row 1,0 </li> - </ol> - </li> - <li> row 2 </li> - </ol> -</datagrid></pre> - - <p>In this example, only the <code><a href="#li">li</a></code> elements - actually appear in the data grid; the <code><a href="#ol">ol</a></code> - element does not affect the data grid's processing model.</p> - </div> - - <p><code title=dom-provider-getChildAtPosition><a - href="#getchildatposition">getChildAtPosition(<var title="">row</var>, - <var title="">position</var>)</a></code> must return <var - title="">position</var>. (The generic default data provider does not - support sorting the data grid.)</p> - - <p><code title=dom-provider-getRowImage><a - href="#getrowimage">getRowImage(<var title="">i</var>)</a></code> must - return the URI of the image given by the first <code><a - href="#img">img</a></code> element descendant (in the real DOM) of the - row's element, that is not also a descendant of another element in the - filtered view that is a descendant of the row's element.</p> - - <div class=example> - <p>In the following example, the row with path "1,0" returns - "http://example.com/a" as its image URI, and the other rows (including - the row with path "1") return the empty string:</p> - - <pre><datagrid> - <ol> - <li> row 0 </li> - <li> row 1 - <ol> - <li> row 1,0 <img src="http://example.com/a" alt=""> </li> - </ol> - </li> - <li> row 2 </li> - </ol> -</datagrid></pre> - </div> - - <p><code title=dom-provider-getRowMenu><a - href="#getrowmenu">getRowMenu(<var title="">i</var>)</a></code> must - return the first <code><a href="#menu">menu</a></code> element - descendant (in the real DOM) of the row's element, that is not also a - descendant of another element in the filtered view that is a decsendant - of the row's element. (This is analogous to the image case above.)</p> - - <p><code title=dom-provider-getRowClasses><a - href="#getrowclasses">getRowClasses(<var title="">i</var>, <var - title="">classes</var>)</a></code> must add the classes from the - following list to <var title="">classes</var> when their condition is - met:</p> - - <ul> - <li>If the row's element contains other elements that are also in the - view, and the element's <code title=attr-class><a - href="#class">class</a></code> attribute contains the <code - title="">closed</code> class: <code - title=datagrid-row-class-initially-closed><a - href="#initially-closed">initially-closed</a></code> - - <li>If the row's element contains other elements that are also in the - view, and the element's <code title=attr-class><a - href="#class">class</a></code> attribute contains the <code - title="">open</code> class: <code - title=datagrid-row-class-initially-open><a - href="#initially-open">initially-open</a></code> - - <li>If the row's element is an <code><a - href="#h1">h1</a></code>-<code><a href="#h6">h6</a></code> element: - <code title=datagrid-row-class-header><a - href="#header0">header</a></code> - - <li>If the row's element is an <code><a href="#hr">hr</a></code> - element: <code title=datagrid-row-class-separator><a - href="#separator">separator</a></code></li> - <!-- - XXX no way to get selectable-separator --> - </ul> - - <p>The <code title=dom-provider-getCellData><a - href="#getcelldata">getCellData(<var title="">i</var>, <var - title="">j</var>)</a></code>, <code title=dom-provider-getCellClasses><a - href="#getcellclasses">getCellClasses(<var title="">i</var>, <var - title="">j</var>, <var title="">classes</var>)</a></code>, <code - title=dom-provider-setCellCheckedState><a - href="#setcellcheckedstate">getCellCheckedState(<var title="">i</var>, - <var title="">j</var>, <var title="">state</var>)</a></code>, <code - title=dom-provider-cycleCell><a href="#cyclecell">cycleCell(<var - title="">i</var>, <var title="">j</var>)</a></code>, and <code - title=dom-provider-editCell><a href="#editcell">editCell(<var - title="">i</var>, <var title="">j</var>, <var - title="">data</var>)</a></code> methods must act as described in <a - href="#commonDefaultDataGridMethodDefinitions">the common definitions - below</a>, treating the row's element as being the cell's element.</p> - - <p class=big-issue id=generic-provider-selection>selection handling?</p> - - <p>The data provider must call the <code><a - href="#datagrid0">datagrid</a></code>'s update methods appropriately - whenever the descendants of the <code><a - href="#datagrid0">datagrid</a></code> mutate.</p> - - <dt>Otherwise, while there is no element child - - <dd> - <p>The data provider must return 0 for the number of rows, 1 for the - number of columns, the empty string for the first column's caption, and - must add no classes when asked for that column's classes. If the - <code><a href="#datagrid0">datagrid</a></code>'s child list changes such - that there is a first element child, then the data provider must call - the <code title=dom-datagrid-updateEverything><a - href="#updateeverything">updateEverything()</a></code> method on the - <code><a href="#datagrid0">datagrid</a></code>.</p> - </dl> - - <h6 id=commonDefaultDataGridMethodDefinitions><span class=secno>3.18.2.4.1. - </span>Common default data provider method definitions for cells</h6> - - <p>These definitions are used for the cell-specific methods of the default - data providers (other than in the - <code>select</code>/<code>datalist</code> case). How they behave is based - on the contents of an element that represents the cell given by their - first two arguments. Which element that is is defined in the previous - section. - - <dl> - <dt>Cyclable cells - - <dd> - <p>If the first element child of a cell's element is a - <code>select</code> element that has a no <code - title=attr-select-multiple>multiple</code> attribute and has at least - one <code>option</code> element descendent, then the cell acts as a - cyclable cell.</p> - - <p>The "current" <code>option</code> element is the selected - <code>option</code> element, or the first <code>option</code> element if - none is selected.</p> - - <p>The <code title=dom-provider-getCellData><a - href="#getcelldata">getCellData()</a></code> method must return the - <code><a href="#textcontent">textContent</a></code> of the current - <code>option</code> element (the <code - title=attr-option-label>label</code> attribute is <a href="#ignored" - title=ignore>ignored</a> in this context as the <code>optgroup</code>s - are not displayed).</p> - - <p>The <code title=dom-provider-getCellClasses><a - href="#getcellclasses">getCellClasses()</a></code> method must add the - <code title=datagrid-cell-class-cyclable><a - href="#cyclable">cyclable</a></code> class and then all the classes of - the current <code>option</code> element.</p> - - <p>The <code title=dom-provider-cycleCell><a - href="#cyclecell">cycleCell()</a></code> method must change the - selection of the <code>select</code> element such that the next - <code>option</code> element after the current <code>option</code> - element is the only one that is selected (in <a href="#tree-order">tree - order</a>). If the current <code>option</code> element is the last - <code>option</code> element descendent of the <code>select</code>, then - the first <code>option</code> element descendent must be selected - instead.</p> - - <p>The <code title=dom-provider-setCellCheckedState><a - href="#setcellcheckedstate">setCellCheckedState()</a></code> and <code - title=dom-provider-editCell><a href="#editcell">editCell()</a></code> - methods must do nothing.</p> - - <dt>Progress bar cells - - <dd> - <p>If the first element child of a cell's element is a <code><a - href="#progress">progress</a></code> element, then the cell acts as a - progress bar cell.</p> - - <p>The <code title=dom-provider-getCellData><a - href="#getcelldata">getCellData()</a></code> method must return the - value returned by the <code><a href="#progress">progress</a></code> - element's <code title=dom-progress-position><a - href="#position">position</a></code> DOM attribute.</p> - - <p>The <code title=dom-provider-getCellClasses><a - href="#getcellclasses">getCellClasses()</a></code> method must add the - <code title=datagrid-cell-class-progress><a - href="#progress1">progress</a></code> class.</p> - - <p>The <code title=dom-provider-setCellCheckedState><a - href="#setcellcheckedstate">setCellCheckedState()</a></code>, <code - title=dom-provider-cycleCell><a - href="#cyclecell">cycleCell()</a></code>, and <code - title=dom-provider-editCell><a href="#editcell">editCell()</a></code> - methods must do nothing.</p> - - <dt>Checkbox cells - - <dd> - <p>If the first element child of a cell's element is an - <code>input</code> element that has a <code - title=attr-input-type>type</code> attribute with the value <code - title="">checkbox</code>, then the cell acts as a check box cell.</p> - - <p>The <code title=dom-provider-getCellData><a - href="#getcelldata">getCellData()</a></code> method must return the - <code><a href="#textcontent">textContent</a></code> of the cell element.</p> - - <p>The <code title=dom-provider-getCellClasses><a - href="#getcellclasses">getCellClasses()</a></code> method must add the - <code title=datagrid-cell-class-checked><a - href="#checked">checked</a></code> class if the <code>input</code> - element is <span title=dom-input-checked>checked</span>, and the <code - title=datagrid-cell-class-unchecked><a - href="#unchecked">unchecked</a></code> class otherwise.</p> - - <p>The <code title=dom-provider-setCellCheckedState><a - href="#setcellcheckedstate">setCellCheckedState()</a></code> method must - set the <code>input</code> element's checkbox <span - title=dom-input-checked>state</span> to checked if the method's third - argument is 1, and to unchecked otherwise.</p> - - <p>The <code title=dom-provider-cycleCell><a - href="#cyclecell">cycleCell()</a></code> and <code - title=dom-provider-editCell><a href="#editcell">editCell()</a></code> - methods must do nothing.</p> - - <dt>Editable cells - - <dd> - <p>If the first element child of a cell's element is an - <code>input</code> element that has a <code - title=attr-input-type>type</code> attribute with the value <code - title="">text</code> or that has no <code - title=attr-input-type>type</code> attribute at all, then the cell acts - as an editable cell.</p> - - <p>The <code title=dom-provider-getCellData><a - href="#getcelldata">getCellData()</a></code> method must return the - <code title=dom-input-value>value</code> of the <code>input</code> - element.</p> - - <p>The <code title=dom-provider-getCellClasses><a - href="#getcellclasses">getCellClasses()</a></code> method must add the - <code title=datagrid-cell-class-editable><a - href="#editable">editable</a></code> class.</p> - - <p>The <code title=dom-provider-editCell><a - href="#editcell">editCell()</a></code> method must set the - <code>input</code> element's <code title=dom-input-value>value</code> - DOM attribute to the value of the third argument to the method.</p> - - <p>The <code title=dom-provider-setCellCheckedState><a - href="#setcellcheckedstate">setCellCheckedState()</a></code> and <code - title=dom-provider-cycleCell><a href="#cyclecell">cycleCell()</a></code> - methods must do nothing.</p> - </dl> - <!-- XXX Calculated cells, like in spreadsheets? --> - - <h5 id=populating><span class=secno>3.18.2.5. </span>Populating the - <code><a href="#datagrid0">datagrid</a></code> element</h5> - - <p>A <code><a href="#datagrid0">datagrid</a></code> must be disabled until - its end tag has been parsed (in the case of a <code><a - href="#datagrid0">datagrid</a></code> element in the original document - markup) or until it has been inserted into the document (in the case of a - dynamically created element). After that point, the element must fire a - single <code title=event-load><a href="#load0">load</a></code> event at - itself, which doesn't bubble and cannot be canceled. - - <p class=big-issue>The end-tag parsing thing should be moved to the parsing - section. - - <p>The <code><a href="#datagrid0">datagrid</a></code> must then populate - itself using the data provided by the data provider assigned to the <code - title=dom-datagrid-data><a href="#data2">data</a></code> DOM attribute. - After the view is populated (using the methods described below), the - <code><a href="#datagrid0">datagrid</a></code> must invoke the <code - title=dom-provider-initialize><a - href="#initialize">initialize()</a></code> method on the data provider - specified by the <code title=dom-datagrid-data><a - href="#data2">data</a></code> attribute, passing itself (the <code><a - href="#htmldatagridelement">HTMLDataGridElement</a></code> object) as the - only argument. - - <p>When the <code title=dom-datagrid-data><a href="#data2">data</a></code> - attribute is null, the <code><a href="#datagrid0">datagrid</a></code> must - use the default data provider described in the previous section. - - <p>To obtain data from the data provider, the element must invoke methods - on the data provider object in the following ways: - - <dl> - <dt>To determine the total number of columns - - <dd>Invoke the <code title=dom-provider-getColumnCount><a - href="#getcolumncount">getColumnCount()</a></code> method with no - arguments. The return value is the number of columns. If the return value - is zero or negative, not an integer, or simply not a numeric type, or if - the method is not defined, then 1 must be used instead. - - <dt>To get the captions to use for the columns - - <dd>Invoke the <code title=dom-provider-getCaptionText><a - href="#getcaptiontext">getCaptionText()</a></code> method with the index - of the column in question. The index <var title="">i</var> must be in the - range 0 ≤ <var title="">i</var> < <var title="">N</var>, where <var - title="">N</var> is the total number of columns. The return value is the - string to use when referring to that column. If the method returns null - or the empty string, the column has no caption. If the method is not - defined, then none of the columns have any captions. - - <dt>To establish what classes apply to a column - - <dd>Invoke the <code title=dom-provider-getCaptionClasses><a - href="#getcaptionclasses">getCaptionClasses()</a></code> method with the - index of the column in question, and an object implementing the <code><a - href="#domtokenlist0">DOMTokenList</a></code> interface, associated with - an anonymous empty string. The index <var title="">i</var> must be in the - range 0 ≤ <var title="">i</var> < <var title="">N</var>, where <var - title="">N</var> is the total number of columns. The tokens contained in - the string underlying <code><a - href="#domtokenlist0">DOMTokenList</a></code> object when the method - returns represent the classes that apply to the given column. If the - method is not defined, no classes apply to the column. - - <dt>To establish whether a column should be initially included in the - visible columns - - <dd>Check whether the <code - title=datagrid-column-class-initially-hidden><a - href="#initially-hidden">initially-hidden</a></code> class applies to the - column. If it does, then the column should not be initially included; if - it does not, then the column should be initially included. - - <dt id=columnType2>To establish whether the data can be sorted relative to - a particular column - - <dd>Check whether the <code title=datagrid-column-class-sortable><a - href="#sortable">sortable</a></code> class applies to the column. If it - does, then the user should be able to ask the UA to display the data - sorted by that column; if it does not, then the user agent must not allow - the user to ask for the data to be sorted by that column. - - <dt>To establish if a column is a sorted column - - <dd>If the user agent can handle multiple columns being marked as sorted - simultaneously: Check whether the <code - title=datagrid-column-class-sorted><a href="#sorted">sorted</a></code> - class applies to the column. If it does, then that column is the sorted - column, otherwise it is not. - - <dd>If the user agent can only handle one column being marked as sorted at - a time: Check each column in turn, starting with the first one, to see - whether the <code title=datagrid-column-class-sorted><a - href="#sorted">sorted</a></code> class applies to that column. The first - column that has that class, if any, is the sorted column. If none of the - columns have that class, there is no sorted column. - - <dt>To establish the sort direction of a sorted column - - <dd>Check whether the <code title=datagrid-column-class-reversed><a - href="#reversed">reversed</a></code> class applies to the column. If it - does, then the sort direction is descending (down; first rows have the - highest values), otherwise it is ascending (up; first rows have the - lowest values). - - <dt>To determine the total number of rows - - <dd>Determine the number of rows for the root of the data grid, and - determine the number of child rows for each open row. The total number of - rows is the sum of all these numbers. - - <dt>To determine the number of rows for the root of the data grid - - <dd>Invoke the <code title=dom-provider-getRowCount><a - href="#getrowcount">getRowCount()</a></code> method with a <code><a - href="#rowspecification">RowSpecification</a></code> object representing - the empty path as its only argument. The return value is the number of - rows at the top level of the data grid. If the return value of the method - is negative, not an integer, or simply not a numeric type, or if the - method is not defined, then zero must be used instead. - - <dt>To determine the number of child rows for a row - - <dd>Invoke the <code title=dom-provider-getRowCount><a - href="#getrowcount">getRowCount()</a></code> method with a <code><a - href="#rowspecification">RowSpecification</a></code> object representing - the path to the row in question. The return value is the number of child - rows for the given row. If the return value of the method is negative, - not an integer, or simply not a numeric type, or if the method is not - defined, then zero must be used instead. - - <dt>To determine what order to render rows in - - <dd> - <p>Invoke the <code title=dom-provider-getChildAtPosition><a - href="#getchildatposition">getChildAtPosition()</a></code> method with a - <code><a href="#rowspecification">RowSpecification</a></code> object - representing the path to the parent of the rows that are being rendered - as the first argument, and the position that is being rendered as the - second argument. The return value is the index of the row to render in - that position.</p> - - <div class=example> - <p>If the rows are:</p> - - <ol> - <li> Row "0" - <ol> - <li> Row "0,0" - - <li> Row "0,1" - </ol> - - <li> Row "1" - <ol> - <li> Row "1,0" - - <li> Row "1,1" - </ol> - </ol> - - <p>...and the <code title=dom-provider-getChildAtPosition><a - href="#getchildatposition">getChildAtPosition()</a></code> method is - implemented as follows:</p> - - <pre>function getChildAtPosition(parent, child) { - // always return the reverse order - return getRowCount(parent)-child-1; -}</pre> - - <p>...then the rendering would actually be:</p> - - <ol> - <li> Row "1" - <ol> - <li> Row "1,1" - - <li> Row "1,0" - </ol> - - <li> Row "0" - <ol> - <li> Row "0,1" - - <li> Row "0,0" - </ol> - </ol> - </div> - - <p>If the return value of the method is negative, larger than the number - of rows that the <code title=dom-provider-getRowCount><a - href="#getrowcount">getRowCount()</a></code> method reported for that - parent, not an integer, or simply not a numeric type, then the entire - data grid should be disabled. Similarly, if the method returns the same - value for two or more different values for the second argument (with the - same first argument, and assuming that the data grid hasn't had relevant - update methods invoked in the meantime), then the data grid should be - disabled. Instead of disabling the data grid, the user agent may act as - if the <code title=dom-provider-getChildAtPosition><a - href="#getchildatposition">getChildAtPosition()</a></code> method was - not defined on the data provider (thus disabling sorting for that data - grid, but still letting the user interact with the data). If the method - is not defined, then the return value must be assumed to be the same as - the second argument (an indentity transform; the data is rendered in its - natural order).</p> - - <dt>To establish what classes apply to a row - - <dd>Invoke the <code title=dom-provider-getRowClasses><a - href="#getrowclasses">getRowClasses()</a></code> method with a <code><a - href="#rowspecification">RowSpecification</a></code> object representing - the row in question, and a <code><a - href="#domtokenlist0">DOMTokenList</a></code> associated with an empty - string. The tokens contained in the <code><a - href="#domtokenlist0">DOMTokenList</a></code> object's underlying string - when the method returns represent the classes that apply to the row in - question. If the method is not defined, no classes apply to the row. - - <dt>To establish whether a row is a data row or a special row - - <dd>Examine the classes that apply to the row. If the <code - title=datagrid-row-class-header><a href="#header0">header</a></code> - class applies to the row, then it is not a data row, it is a subheading. - The data from the first cell of the row is the text of the subheading, - the rest of the cells must be ignored. Otherwise, if the <code - title=datagrid-row-class-separator><a - href="#separator">separator</a></code> class applies to the row, then in - the place of the row, a separator should be shown. Otherwise, if the - <code title=datagrid-row-class-selectable-separator><a - href="#selectable-separator">selectable-separator</a></code> class - applies to the row, then the row should be a data row, but represented as - a separator. (The difference between a <code - title=datagrid-row-class-separator><a - href="#separator">separator</a></code> and a <code - title=datagrid-row-class-selectable-separator><a - href="#selectable-separator">selectable-separator</a></code> is that the - former is not an item that can be actually selected, whereas the second - can be selected and thus has a context menu that applies to it, and so - forth.) For both kinds of separator rows, the data of the rows' cells - must all be ignored. If none of those three classes apply then the row is - a simple data row. - - <dt id=rowType1>To establish whether a row is openable - - <dd>Determine the number of child rows for that row. If there are one or - more child rows, then the row is openable. - - <dt>To establish whether a row should be initially open or closed - - <dd>If <a href="#rowType1">the row is openable</a>, examine the classes - that apply to the row. If the <code - title=datagrid-row-class-initially-open><a - href="#initially-open">initially-open</a></code> class applies to the - row, then it should be initially open. Otherwise, if the <code - title=datagrid-row-class-initially-closed><a - href="#initially-closed">initially-closed</a></code> class applies to the - row, then it must be initially closed. Otherwise, if neither class - applies to the row, or if the row is not openable, then the initial state - of the row is entirely up to the UA.</dd> - <!-- XXXPA - <dt>To establish whether a row is deletable</dt> - - <dd>Check whether the <code - title="datagrid-row-class-deletable">deletable</code> class applies - to the row. If it does, the row is deletable, and interactive user - agents should provide a way for the user to request that the row be - deleted. (See the <code - title="dom-provider-performActionOnRow">performActionOnRow()</code> - method for more details.) Otherwise, the user agent should not - provide the user with a method for requesting that the row be - deleted.</dd> ---> - - <dt>To obtain a URI to an image representing a row - - <dd>Invoke the <code title=dom-provider-getRowImage><a - href="#getrowimage">getRowImage()</a></code> method with a <code><a - href="#rowspecification">RowSpecification</a></code> object representing - the row in question. The return value is a string representing a URI (or - IRI) to an image. Relative URIs must be interpreted relative to the - <code><a href="#datagrid0">datagrid</a></code>'s base URI. If the method - returns the empty string, null, or if the method is not defined, then the - row has no associated image. - - <dt>To obtain a context menu appropriate for a particular row - - <dd>Invoke the <code title=dom-provider-getRowMenu><a - href="#getrowmenu">getRowMenu()</a></code> method with a <code><a - href="#rowspecification">RowSpecification</a></code> object representing - the row in question. The return value is a reference to an object - implementing the <code><a - href="#htmlmenuelement">HTMLMenuElement</a></code> interface, i.e. a - <code><a href="#menu">menu</a></code> element DOM node. (This element - must then be interpreted as described in the section on context menus to - obtain the actual context menu to use.<!-- XXXX update once menu section - works; with xrefs -->) - If the method returns something that is not an <code><a - href="#htmlmenuelement">HTMLMenuElement</a></code>, or if the method is - not defined, then the row has no associated context menu. User agents may - provide their own default context menu, and may add items to the - author-provided context menu. For example, such a menu could allow the - user to change the presentation of the <code><a - href="#datagrid0">datagrid</a></code> element. - - <dt>To establish the value of a particular cell - - <dd>Invoke the <code title=dom-provider-getCellData><a - href="#getcelldata">getCellData()</a></code> method with the first - argument being a <code><a - href="#rowspecification">RowSpecification</a></code> object representing - the row of the cell in question and the second argument being the index - of the cell's column. The second argument must be a non-negative integer - less than the total number of columns. The return value is the value of - the cell. If the return value is null or the empty string, or if the - method is not defined, then the cell has no data. (For progress bar - cells, the cell's value must be further interpreted, as described below.) - - <dt>To establish what classes apply to a cell - - <dd>Invoke the <code title=dom-provider-getCellClasses><a - href="#getcellclasses">getCellClasses()</a></code> method with the first - argument being a <code><a - href="#rowspecification">RowSpecification</a></code> object representing - the row of the cell in question, the second argument being the index of - the cell's column, and the third being an object implementing the - <code><a href="#domtokenlist0">DOMTokenList</a></code> interface, - associated with an empty string. The second argument must be a - non-negative integer less than the total number of columns. The tokens - contained in the <code><a href="#domtokenlist0">DOMTokenList</a></code> - object's underlying string when the method returns represent the classes - that apply to that cell. If the method is not defined, no classes apply - to the cell. - - <dt id=cellType1>To establish how the type of a cell - - <dd>Examine the classes that apply to the cell. If the <code - title=datagrid-cell-class-progress><a - href="#progress1">progress</a></code> class applies to the cell, it is a - progress bar. Otherwise, if the <code - title=datagrid-cell-class-cyclable><a - href="#cyclable">cyclable</a></code> class applies to the cell, it is a - cycling cell whose value can be cycled between multiple states. - Otherwise, none of these classes apply, and the cell is a simple text - cell. - - <dt>To establish the value of a progress bar cell - - <dd>If the value <var title="">x</var> of the cell is a string that can be - <a href="#rules1" title="rules for parsing floating point number - values">converted to a floating-point number</a> in the range - 0.0 ≤ <var title="">x</var> ≤ 1.0, then the - progress bar has that value (0.0 means no progress, 1.0 means complete). - Otherwise, the progress bar is an indeterminate progress bar. - - <dt id=cellType2>To establish how a simple text cell should be presented - - <dd>Check whether one of the <code title=datagrid-cell-class-checked><a - href="#checked">checked</a></code>, <code - title=datagrid-cell-class-unchecked><a - href="#unchecked">unchecked</a></code>, or <code - title=datagrid-cell-class-indeterminate><a - href="#indeterminate">indeterminate</a></code> classes applies to the - cell. If any of these are present, then the cell has a checkbox, - otherwise none are present and the cell does not have a checkbox. If the - cell has no checkbox, check whether the <code - title=datagrid-cell-class-editable><a - href="#editable">editable</a></code> class applies to the cell. If it - does, then the cell value is editable, otherwise the cell value is - static. - - <dt>To establish the state of a cell's checkbox, if it has one - - <dd>Check whether the <code title=datagrid-cell-class-checked><a - href="#checked">checked</a></code> class applies to the cell. If it does, - the cell is checked. Otherwise, check whether the <code - title=datagrid-cell-class-unchecked><a - href="#unchecked">unchecked</a></code> class applies to the cell. If it - does, the cell is unchecked. Otherwise, the <code - title=datagrid-cell-class-indeterminate><a - href="#indeterminate">indeterminate</a></code> class appplies to the cell - and the cell's checkbox is in an indeterminate state. When the <code - title=datagrid-cell-class-indeterminate><a - href="#indeterminate">indeterminate</a></code> class appplies to the - cell, the checkbox is a tristate checkbox, and the user can set it to the - indeterminate state. Otherwise, only the <code - title=datagrid-cell-class-checked><a href="#checked">checked</a></code> - and/or <code title=datagrid-cell-class-unchecked><a - href="#unchecked">unchecked</a></code> classes apply to the cell, and the - cell can only be toggled betwen those two states. - </dl> - - <p>If the data provider ever raises an exception while the <code><a - href="#datagrid0">datagrid</a></code> is invoking one of its methods, the - <code><a href="#datagrid0">datagrid</a></code> must act, for the purposes - of that particular method call, as if the relevant method had not been - defined. - - <p>A <code><a href="#rowspecification">RowSpecification</a></code> object - <var title="">p</var> with <var title="">n</var> path components passed to - a method of the data provider must fulfill the constraint - <span>0 ≤ <var title="">p<sub title=""><var - title="">i</var></sub></var> < <var title="">m</var>-1</span> - for all integer values of <var title="">i</var> in the range - <span>0 ≤ <var title="">i</var> < <var - title="">n</var>-1</span>, where <var title="">m</var> is the value that - was last returned by the <code title=dom-provider-getRowCount><a - href="#getrowcount">getRowCount()</a></code> method when it was passed the - <code><a href="#rowspecification">RowSpecification</a></code> object <var - title="">q</var> with <span><var title="">i</var>-1</span> items, where - <span><var title="">p<sub title=""><var - title="">i</var></sub></var> = <var title="">q<sub title=""><var - title="">i</var></sub></var></span> for all integer values of <var - title="">i</var> in the range <span>0 ≤ <var - title="">i</var> < <var title="">n</var>-1</span>, with any - changes implied by the update methods taken into account. - - <p id=inconsistentDataProvider>The data model is considered stable: user - agents may assume that subsequent calls to the data provider methods will - return the same data, until one of the update methods is called on the - <code><a href="#datagrid0">datagrid</a></code> element. If a user agent is - returned inconsistent data, for example if the number of rows returned by - <code title=dom-provider-getRowCount><a - href="#getrowcount">getRowCount()</a></code> varies in ways that do not - match the calls made to the update methods, the user agent may disable the - <code><a href="#datagrid0">datagrid</a></code>. User agents that do not - disable the <code><a href="#datagrid0">datagrid</a></code> in inconsistent - cases must honour the most recently returned values. - - <p>User agents may cache returned values so that the data provider is never - asked for data that could contradict earlier data. User agents must not - cache the return value of the <code title=dom-provider-getRowMenu><a - href="#getrowmenu">getRowMenu</a></code> method. - - <p>The exact algorithm used to populate the data grid is not defined here, - since it will differ based on the presentation used. However, the - behaviour of user agents must be consistent with the descriptions above. - For example, it would be non-conformant for a user agent to make cells - have both a checkbox and be editable, as the descriptions above state that - cells that have a checkbox cannot be edited.</p> - <!-- XXX speaking of which, do we actually want that - limitation? --> - - <h5 id=updating><span class=secno>3.18.2.6. </span>Updating the <code><a - href="#datagrid0">datagrid</a></code></h5> - - <p>Whenever the <code title=dom-datagrid-data><a - href="#data2">data</a></code> attribute is set to a new value, the - <code><a href="#datagrid0">datagrid</a></code> must clear the current - selection, remove all the displayed rows, and plan to repopulate itself - using the information from the new data provider at the earliest - opportunity. - - <p>There are a number of update methods that can be invoked on the <code><a - href="#datagrid0">datagrid</a></code> element to cause it to refresh - itself in slightly less drastic ways: - - <p>When the <dfn id=updateeverything - title=dom-datagrid-updateEverything><code>updateEverything()</code></dfn> - method is called, the user agent must repopulate the entire <code><a - href="#datagrid0">datagrid</a></code>. If the number of rows decreased, - the selection must be updated appropriately. If the number of rows - increased, the new rows should be left unselected. - - <p>When the <dfn id=updaterowschanged - title=dom-datagrid-updateRowsChanged><code>updateRowsChanged(<var - title="">row</var>, <var title="">count</var>)</code></dfn> method is - called, the user agent must refresh the rendering of the rows starting - from the row specified by <var title="">row</var>, and including the <var - title="">count</var> next siblings of the row (or as many next siblings as - it has, if that is less than <var title="">count</var>), including all - descendant rows. - - <p>When the <dfn id=updaterowsinserted - title=dom-datagrid-updateRowsInserted><code>updateRowsInserted(<var - title="">row</var>, <var title="">count</var>)</code></dfn> method is - called, the user agent must assume that <var title="">count</var> new rows - have been inserted, such that the first new row is indentified by <var - title="">row</var>. The user agent must update its rendering and the - selection accordingly. The new rows should not be selected. - - <p>When the <dfn id=updaterowsremoved - title=dom-datagrid-updateRowsRemoved><code>updateRowsRemoved(<var - title="">row</var>, <var title="">count</var>)</code></dfn> method is - called, the user agent must assume that <var title="">count</var> rows - have been removed starting from the row that used to be identifier by <var - title="">row</var>. The user agent must update its rendering and the - selection accordingly. - - <p>The <dfn id=updaterowchanged - title=dom-datagrid-updateRowChanged><code>updateRowChanged(<var - title="">row</var>)</code></dfn> method must be exactly equivalent to - calling <code title=dom-datagrid-updateRowsChanged><a - href="#updaterowschanged">updateRowsChanged(<var title="">row</var>, - 1)</a></code>. - - <p>When the <dfn id=updatecolumnchanged - title=dom-datagrid-updateColumnChanged><code>updateColumnChanged(<var - title="">column</var>)</code></dfn> method is called, the user agent must - refresh the rendering of the specified column <var title="">column</var>, - for all rows. - - <p>When the <dfn id=updatecellchanged - title=dom-datagrid-updateCellChanged><code>updateCellChanged(<var - title="">row</var>, <var title="">column</var>)</code></dfn> method is - called, the user agent must refresh the rendering of the cell on row <var - title="">row</var>, in column <var title="">column</var>. - - <p>Any effects the update methods have on the <code><a - href="#datagrid0">datagrid</a></code>'s selection is not considered a - change to the selection, and must therefore not fire the <code - title=event-select><a href="#select">select</a></code> event. - - <p>These update methods should only be called by the data provider, or code - acting on behalf of the data provider. In particular, calling the <code - title=dom-datagrid-updateRowsInserted><a - href="#updaterowsinserted">updateRowsInserted()</a></code> and <code - title=dom-datagrid-updateRowsRemoved><a - href="#updaterowsremoved">updateRowsRemoved()</a></code> methods without - actually inserting or removing rows from the data provider is <a - href="#inconsistentDataProvider">likely to result in inconsistent - renderings</a>, and the user agent is likely to disable the data grid. - - <h5 id=requirements><span class=secno>3.18.2.7. </span>Requirements for - interactive user agents</h5> - - <p><em>This section only applies to interactive user agents.</em> - - <p>If the <code><a href="#datagrid0">datagrid</a></code> element has a <dfn - id=disabled3 title=attr-datagrid-disabled><code>disabled</code></dfn> - attribute, then the user agent must disable the <code><a - href="#datagrid0">datagrid</a></code>, preventing the user from - interacting with it. The <code><a href="#datagrid0">datagrid</a></code> - element should still continue to update itself when the data provider - signals changes to the data, though. Obviously, conformance requirements - stating that <code><a href="#datagrid0">datagrid</a></code> elements must - react to users in particular ways do not apply when one is disabled. - - <p>If <a href="#rowType1">a row is openable</a>, then the user should be - able to toggle its open/closed state. When a row's open/closed state - changes, the user agent must update the rendering to match the new state. - - <p>If a cell is a cell whose value <a href="#cellType1">can be cycled - between multiple states</a>, then the user must be able to activate the - cell to cycle its value. When the user activates this "cycling" behaviour - of a cell, then the <code><a href="#datagrid0">datagrid</a></code> must - invoke the data provider's <code title=dom-provider-cycleCell><a - href="#cyclecell">cycleCell()</a></code> method, with a <code><a - href="#rowspecification">RowSpecification</a></code> object representing - the cell's row as the first argument and the cell's column index as the - second. The <code><a href="#datagrid0">datagrid</a></code> must act as if - the <code><a href="#datagrid0">datagrid</a></code>'s <code - title=dom-datagrid-updateCellChanged><a - href="#updatecellchanged">updateCellChanged()</a></code> method had been - invoked with those same arguments immediately before the provider's method - was invoked. - - <p>When a cell <a href="#cellType2">has a checkbox</a>, the user must be - able to set the checkbox's state. When the user changes the state of a - checkbox in such a cell, the <code><a - href="#datagrid0">datagrid</a></code> must invoke the data provider's - <code title=dom-provider-setCellCheckedState><a - href="#setcellcheckedstate">setCellCheckedState()</a></code> method, with - a <code><a href="#rowspecification">RowSpecification</a></code> object - representing the cell's row as the first argument, the cell's column index - as the second, and the checkbox's new state as the third. The state should - be represented by the number 1 if the new state is checked, 0 if the new - state is unchecked, and -1 if the new state is indeterminate (which must - only be possible if the cell has the <code - title=datagrid-cell-class-indeterminate><a - href="#indeterminate">indeterminate</a></code> class set). The <code><a - href="#datagrid0">datagrid</a></code> must act as if the <code><a - href="#datagrid0">datagrid</a></code>'s <code - title=dom-datagrid-updateCellChanged><a - href="#updatecellchanged">updateCellChanged()</a></code> method had been - invoked, specifying the same cell, immediately before the provider's - method was invoked. - - <p>If a cell <a href="#cellType2">is editable</a>, the user must be able to - edit the data for that cell, and doing so must cause the user agent to - invoke the <code title=dom-provider-editCell><a - href="#editcell">editCell()</a></code> method of the data provider with - three arguments: a <code><a - href="#rowspecification">RowSpecification</a></code> object representing - the cell's row, the cell's column's index, and the new text entered by the - user. The user agent must act as if the <code - title=dom-datagrid-updateCellChanged><a - href="#updatecellchanged">updateCellChanged()</a></code> method had been - invoked, with the same row and column specified, immediately before the - provider's method was invoked.</p> - <!-- XXXPA <p class="big-issue">define actions (performAction(), etc)</p> --> - - <h5 id=the-selection><span class=secno>3.18.2.8. </span>The selection</h5> - - <p><em>This section only applies to interactive user agents. For other user - agents, the <code title=dom-datagrid-selection><a - href="#selection0">selection</a></code> attribute must return null.</em> - - <pre - class=idl>interface <dfn id=datagridselection>DataGridSelection</dfn> { - readonly attribute unsigned long <span title=dom-DataGridSelection-count>length</span>; - <a href="#rowspecification">RowSpecification</a> <span title=dom-DataGridSelection->item</span>(in unsigned long index); - boolean <a href="#isselected" title=dom-DataGridSelection-isSelected>isSelected</a>(in <a href="#rowspecification">RowSpecification</a> row); - void <a href="#setselected" title=dom-DataGridSelection-setSelected>setSelected</a>(in <a href="#rowspecification">RowSpecification</a> row, in boolean selected); -<!-- void <span title="dom-DataGridSelection-addRange">addRange</span>(in <span>RowSpecification</span> first, in <span>RowSpecification</span> last); - void <span title="dom-DataGridSelection-removeRange">removeRange</span>(in <span>RowSpecification</span> first, in <span>RowSpecification</span> last); -XXX selection ranges --> - void <a href="#selectall" title=dom-DataGridSelection-selectAll>selectAll</a>(); - void <a href="#invert" title=dom-DataGridSelection-invert>invert</a>(); - void <a href="#clear" title=dom-DataGridSelection-clear>clear</a>(); -};</pre> - - <p>Each <code><a href="#datagrid0">datagrid</a></code> element must keep - track of which rows are currently selected. Initially no rows are - selected, but this can be changed via the methods described in this - section. <!--XXX - select-provider-selection The default data provider, for instance, - changes which rows are selected when it is first initialised.--> - - <p>The selection of a <code><a href="#datagrid0">datagrid</a></code> is - represented by its <dfn id=selection0 - title=dom-datagrid-selection><code>selection</code></dfn> DOM attribute, - which must be a <code><a - href="#datagridselection">DataGridSelection</a></code> object. - - <p><code><a href="#datagridselection">DataGridSelection</a></code> objects - represent the rows in the selection. In the selection the rows must be - ordered in the natural order of the data provider (and not, e.g., the - rendered order). Rows that are not rendered because one of their ancestors - is closed must share the same selection state as their nearest rendered - ancestor. Such rows are not considered part of the selection for the - purposes of iterating over the selection. - - <p class=note>This selection API doesn't allow for hidden rows to be - selected because it is trivial to create a data provider that has infinite - depth, which would then require the selection to be infinite if every row, - including every hidden row, was selected. - - <p>The <dfn id=length4 - title=dom-DataGridSelection-length><code>length</code></dfn> attribute - must return the number of rows currently present in the selection. The - <dfn id=itemindex3 title=dom-DataGridSelection-item><code>item(<var - title="">index</var>)</code></dfn> method must return the <var - title="">index</var>th row in the selection. If the argument is out of - range (less than zero or greater than the number of selected rows minus - one), then it must raise an <code>INDEX_SIZE_ERR</code> exception. <a - href="#refsDOM3CORE">[DOM3CORE]</a> - - <p>The <dfn id=isselected - title=dom-DataGridSelection-isSelected><code>isSelected()</code></dfn> - method must return the selected state of the row specified by its - argument. If the specified row exists and is selected, it must return - true, otherwise it must return false. - - <p>The <dfn id=setselected - title=dom-DataGridSelection-setSelected><code>setSelected()</code></dfn> - method takes two arguments, <var title="">row</var> and <var - title="">selected</var>. When invoked, it must set the selection state of - row <var title="">row</var> to selected if <var title="">selected</var> is - true, and unselected if it is false. If <var title="">row</var> is not a - row in the data grid, the method must raise an <code>INDEX_SIZE_ERR</code> - exception. If the specified row is not rendered because one of its - ancestors is closed, the method must do nothing. - - <p>The <dfn id=selectall - title=dom-DataGridSelection-selectAll><code>selectAll()</code></dfn> - method must mark all the rows in the data grid as selected. After a call - to <code title=dom-DataGridSelection-selectAll><a - href="#selectall">selectAll()</a></code>, the <code - title=dom-DataGridSelection-length><a href="#length4">length</a></code> - attribute will return the number of rows in the data grid, not counting - children of closed rows. - - <p>The <dfn id=invert - title=dom-DataGridSelection-invert><code>invert()</code></dfn> method must - cause all the rows in the selection that were marked as selected to now be - marked as not selected, and vice versa. - - <p>The <dfn id=clear - title=dom-DataGridSelection-clear><code>clear()</code></dfn> method must - mark all the rows in the data grid to be marked as not selected. After a - call to <code title=dom-DataGridSelection-clear><a - href="#clear">clear()</a></code>, the <code - title=dom-DataGridSelection-length><a href="#length4">length</a></code> - attribute will return zero. - - <p>If the <code><a href="#datagrid0">datagrid</a></code> element has a <dfn - id=multiple0 title=attr-datagrid-multiple><code>multiple</code></dfn> - attribute, then the user must be able to select any number of rows (zero - or more). If the attribute is not present, then the user must only be able - to select a single row at a time, and selecting another one must unselect - all the other rows. - - <p class=note>This only applies to the user. Scripts can select multiple - rows even when the <code title=attr-datagrid-multiple><a - href="#multiple0">multiple</a></code> attribute is absent. - - <p>Whenever the selection of a <code><a - href="#datagrid0">datagrid</a></code> changes, whether due to the user - interacting with the element, or as a result of calls to methods of the - <code title=dom-datagrid-selection><a - href="#selection0">selection</a></code> object, a <dfn id=select - title=event-select><code>select</code></dfn><!-- XXX check if we - really should be DFNing this here. It's a DOM3 Core event. What's - our story going to be regarding events and defining them? --> - event that bubbles but is not cancelable must be fired on the <code><a - href="#datagrid0">datagrid</a></code> element. If changes are made to the - selection via calls to the object's methods during the execution of a - script<!-- XXX should xref to a better explanation -->, then the <code - title=event-select><a href="#select">select</a></code> events must be - coalesced into one, which must then be fired<!--XXX xref again--> when the - script execution has completed<!-- XXX xref -->. - - <p class=note>The <code><a - href="#datagridselection">DataGridSelection</a></code> interface has no - relation to the <code><a href="#selection1">Selection</a></code> - interface. - - <h5 id=columns><span class=secno>3.18.2.9. </span>Columns and captions</h5> - - <p><em>This section only applies to interactive user agents.</em> - - <p>Each <code><a href="#datagrid0">datagrid</a></code> element must keep - track of which columns are currently being rendered. User agents should - initially show all the columns except those with the <code - title=datagrid-column-class-initially-hidden><a - href="#initially-hidden">initially-hidden</a></code> class, but may allow - users to hide or show columns. User agents should initially display the - columns in the order given by the data provider, but may allow this order - to be changed by the user. - - <p>If columns are not being used, as might be the case if the data grid is - being presented in an icon view, or if an overview of data is being read - in an aural context, then the text of the first column of each row should - be used to represent the row. - - <p>If none of the columns have any captions (i.e. if the data provider does - not provide a <code title=dom-provider-getCaptionText><a - href="#getcaptiontext">getCaptionText()</a></code> method), then user - agents may avoid showing the column headers at all. This may prevent the - user from performing actions on the columns (such as reordering them, - changing the sort column, and so on). - - <p class=note>Whatever the order used for rendering, and irrespective of - what columns are being shown or hidden, the "first column" as referred to - in this specification is always the column with index zero, and the "last - column" is always the column with the index one less than the value - returned by the <code title=dom-provider-getcolumnCount><a - href="#getcolumncount">getColumnCount()</a></code> method of the data - provider. - - <p>If <a href="#columnType2">a column is sortable</a>, then the user must - be able to invoke it to sort the data. When the user does so, then the - <code><a href="#datagrid0">datagrid</a></code> must invoke the data - provider's <code title=dom-provider-toggleColumnSortState><a - href="#togglecolumnsortstate">toggleColumnSortState()</a></code> method, - with the column's index as the only argument. The <code><a - href="#datagrid0">datagrid</a></code> must <em>then</em> act as if the - <code><a href="#datagrid0">datagrid</a></code>'s <code - title=dom-datagrid-updateEverything><a - href="#updateeverything">updateEverything()</a></code> method had been - invoked.</p> - <!--XXXDND - <h5>Drag and drop in <code>datagrid</code>s</h5> - - <p><em>This section only applies to interactive user agents.</p> - - <p class="big-issue">define drag and drop in datagrids; selectiondraggable, etc.</p> ---> - - <h4 id=the-command><span class=secno>3.18.3. </span>The <dfn - id=command0><code>command</code></dfn> element</h4> - - <p><a href="#metadata" title="metadata elements">Metadata element</a>, and - <a href="#strictly">strictly inline-level content</a>.</p> - <!-- XXX we sure we - want it to be metadata? --> - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>In a <code><a href="#head">head</a></code> element. - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd>Empty. - - <dt>Element-specific attributes: - - <dd><code title=attr-command-type><a href="#type13">type</a></code> - - <dd><code title=attr-command-label><a href="#label">label</a></code> - - <dd><code title=attr-command-icon><a href="#icon">icon</a></code> - - <dd><code title=attr-command-hidden><a href="#hidden">hidden</a></code> - - <dd><code title=attr-command-disabled><a - href="#disabled4">disabled</a></code> - - <dd><code title=attr-command-checked><a - href="#checked0">checked</a></code> - - <dd><code title=attr-command-radiogroup><a - href="#radiogroup">radiogroup</a></code> - - <dd><code title=attr-command-default><a - href="#default1">default</a></code> - - <dd>Also, the <code title=attr-command-title><a - href="#title6">title</a></code> attribute has special semantics on this - element. - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmlcommandelement>HTMLCommandElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute DOMString <a href="#type14" title=dom-command-type>type</a>; - attribute DOMString <a href="#label0" title=dom-command-label>label</a>; - attribute DOMString <a href="#icon0" title=dom-command-icon>icon</a>; - attribute boolean <a href="#hidden0" title=dom-command-hidden>hidden</a>; - attribute boolean <a href="#disabled5" title=dom-command-disabled>disabled</a>; - attribute boolean <a href="#checked1" title=dom-command-checked>checked</a>; - attribute DOMString <a href="#radiogroup0" title=dom-command-radiogroup>radiogroup</a>; - attribute boolean <a href="#default2" title=dom-command-default>default</a>; - void <a href="#click0" title=dom-command-click>click</a>(); // shadows <code><a href="#htmlelement">HTMLElement</a></code>.<code title=dom-click><a href="#click">click()</a></code> -};</pre> - - <p>The <code title=command-ro><a href="#command2">Command</a></code> - interface must also be implemented by this element.</p> - </dl> - - <p>The <code><a href="#command0">command</a></code> element represents a - command that the user can invoke. - - <p>The <dfn id=type13 title=attr-command-type><code>type</code></dfn> - attribute indicates the kind of command: either a normal command with an - associated action, or a state or option that can be toggled, or a - selection of one item from a list of items. - - <p>The attribute's value must be either "<code title="">command</code>", - "<code title="">checkbox</code>", or "<code title="">radio</code>", - denoting each of these three types of commands respectively. The attribute - may also be omitted if the element is to represent the first of these - types, a simple command. - - <p>The <dfn id=label title=attr-command-label><code>label</code></dfn> - attribute gives the name of the command, as shown to the user. - - <p>The <dfn id=title6 title=attr-command-title><code>title</code></dfn> - attribute gives a hint describing the command, which might be shown to the - user to help him. - - <p>The <dfn id=icon title=attr-command-icon><code>icon</code></dfn> - attribute gives a picture that represents the command. If the attribute is - specified, the attribute's value must contain a URI (or IRI). - - <p>The <dfn id=hidden title=attr-command-hidden><code>hidden</code></dfn> - attribute is a <a href="#boolean0">boolean attribute</a> that, if present, - indicates that the command is not relevant and is to be hidden. - - <p>The <dfn id=disabled4 - title=attr-command-disabled><code>disabled</code></dfn> attribute is a <a - href="#boolean0">boolean attribute</a> that, if present, indicates that - the command is not available in the current state. - - <p class=note>The distinction between <a href="#disabled6" - title=command-facet-DisabledState>Disabled State</a> and <a - href="#hidden1" title=command-facet-HiddenState>Hidden State</a> is - subtle. A command should be Disabled if, in the same context, it could be - enabled if only certain aspects of the situation were changed. A command - should be marked as Hidden if, in that situation, the command will never - be enabled. For example, in the context menu for a water faucet, the - command "open" might be Disabled if the faucet is already open, but the - command "eat" would be marked Hidden since the faucet could never be - eaten. - - <p>The <dfn id=checked0 - title=attr-command-checked><code>checked</code></dfn> attribute is a <a - href="#boolean0">boolean attribute</a> that, if present, indicates that - the command is selected. - - <p>The <dfn id=radiogroup - title=attr-command-radiogroup><code>radiogroup</code></dfn> attribute - gives the name of the group of commands that will be toggled when the - command itself is toggled, for commands whose <code - title=attr-command-type><a href="#type13">type</a></code> attribute has - the value "<code title="">radio</code>". The scope of the name is the - child list of the parent element. - - <p>If the <code><a href="#command0">command</a></code> element is used when - <span title="menu generation">generating</span> a <span>context - menu</span>, then the <dfn id=default1 - title=attr-command-default><code>default</code></dfn> attribute indicates, - if present, that the command is the one that would have been invoked if - the user had directly activated the menu's subject instead of using its - context menu. The <code title=attr-command-default><a - href="#default1">default</a></code> attribute is a <a - href="#boolean0">boolean attribute</a>. - - <div class=example> - <p class=big-issue>Need an example that shows an element that, if - double-clicked, invokes an action, but that also has a context menu, - showing the various <code><a href="#command0">command</a></code> - attributes off, and that has a default command.</p> - </div> - - <p>The <dfn id=type14 title=dom-command-type><code>type</code></dfn>, <dfn - id=label0 title=dom-command-label><code>label</code></dfn>, <dfn id=icon0 - title=dom-command-icon><code>icon</code></dfn>, <dfn id=hidden0 - title=dom-command-hidden><code>hidden</code></dfn>, <dfn id=disabled5 - title=dom-command-disabled><code>disabled</code></dfn>, <dfn id=checked1 - title=dom-command-checked><code>checked</code></dfn>, <dfn id=radiogroup0 - title=dom-command-radiogroup><code>radiogroup</code></dfn>, and <dfn - id=default2 title=dom-command-default><code>default</code></dfn> DOM - attributes must <a href="#reflect">reflect</a> their respective namesake - content attributes. - - <p>The <dfn id=click0 title=dom-command-click><code>click()</code></dfn> - method's behaviour depends on the value of the <code - title=attr-command-type><a href="#type13">type</a></code> attribute of the - element, as follows: - - <dl class=switch> - <dt>If the <code title=attr-command-type><a href="#type13">type</a></code> - attribute has the value <code title="">checkbox</code> - - <dd> - <p>If the element has a <code title=attr-command-checked><a - href="#checked0">checked</a></code> attribute, the UA must remove that - attribute. Otherwise, the UA must add a <code - title=attr-command-checked><a href="#checked0">checked</a></code> - attribute, with the literal value <code title="">checked</code>. The UA - must then <a href="#firing">fire a <code title="">click</code> event</a> - at the element. - - <dt>If the <code title=attr-command-type><a href="#type13">type</a></code> - attribute has the value <code title="">radio</code> - - <dd> - <p>If the element has a parent, then the UA must walk the list of child - nodes of that parent element, and for each node that is a <code><a - href="#command0">command</a></code> element, if that element has a <code - title=attr-command-radiogroup><a - href="#radiogroup">radiogroup</a></code> attribute whose value exactly - matches the current element's (treating missing <code - title=attr-command-radiogroup><a - href="#radiogroup">radiogroup</a></code> attributes as if they were the - empty string), and has a <code title=attr-command-checked><a - href="#checked0">checked</a></code> attribute, must remove that - attribute and <a href="#firing">fire a <code title="">click</code> - event</a> at the element.</p> - - <p>Then, the element's <code title=attr-command-checked><a - href="#checked0">checked</a></code> attribute attribute must be set to - the literal value <code title="">checked</code> and a <span title="file - a click event"><code title="">click</code> event must be fired</span> at - the element. - - <dt>Otherwise - - <dd> - <p>The UA must <a href="#firing">fire a <code title="">click</code> - event</a> at the element. - </dl> - - <p class=note>Firing a synthetic <code title=event-click>click</code> event - at the element does not cause any of the actions described above to - happen. - - <p class=big-issue> should change all the above so it actually is just - trigged by a click event, then we could remove the shadowing click() - method and rely on actual events. - - <p class=big-issue>Need to define the command="" attribute - - <p class=note><code><a href="#command0">command</a></code> elements are not - rendered unless they <a href="#menu" title=menu>form part of a menu</a>. - - <h4 id=menus><span class=secno>3.18.4. </span>The <dfn - id=menu><code>menu</code></dfn> element</h4> - - <p><a href="#block-level0" title="block-level elements">Block-level - element</a>, and <a href="#structured" title="structured inline-level - elements">structured inline-level element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> are expected. - - <dd>Where <a href="#structured">structured inline-level elements</a> are - allowed. - - <dt>Content model: - - <dd>Zero or more <code><a href="#li">li</a></code> elements, or <a - href="#inline-level0">inline-level content</a> (but not both). - - <dt>Element-specific attributes: - - <dd><code title=attr-menu-type><a href="#type15">type</a></code> - - <dd><code title=attr-menu-label><a href="#label1">label</a></code> - - <dd><code title=attr-menu-autosubmit><a - href="#autosubmit">autosubmit</a></code> - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmlmenuelement>HTMLMenuElement</dfn> : <a href="#htmlelement">HTMLElement</a> { - attribute DOMString <span title=dom-menu-type>type</span>; - attribute DOMString <span title=dom-menu-label>label</span>; - attribute boolean <span title=dom-menu-autosubmit>autosubmit</span>; -};</pre> - </dl> - - <p>The <code><a href="#menu">menu</a></code> element represents a list of - commands. - - <p>The <dfn id=type15 title=attr-menu-type><code>type</code></dfn> - attribute is an <a href="#enumerated">enumerated attribute</a> indicating - the kind of menu being declared. The attribute has three states. The <code - title=attr-menu-type-context>context</code> keyword maps to the <dfn - id=context1 title="context menu state">context menu</dfn> state, in which - the element is declaring a context menu. The <code - title=attr-menu-type-toolbar>toolbar</code> keyword maps to the <dfn - id=tool-bar title="tool bar state">tool bar</dfn> state, in which the - element is declaraing a tool bar. The attribute may also be omitted. The - <i>missing value default</i> is the <dfn id=list title="list - state">list</dfn> state, which indicates that the element is merely a list - of commands that is neither declaring a context menu nor defining a tool - bar. - - <p>If a <code><a href="#menu">menu</a></code> element's <code - title=attr-menu-type><a href="#type15">type</a></code> attribute is in the - <a href="#context1" title="context menu state">context menu</a> state, - then the element represents the commands of a context menu, and the user - can only interact with the commands if that context menu is activated. - - <p>If a <code><a href="#menu">menu</a></code> element's <code - title=attr-menu-type><a href="#type15">type</a></code> attribute is in the - <a href="#tool-bar" title="tool bar state">tool bar</a> state, then the - element represents a list of active commands that the user can immediately - interact with. - - <p>If a <code><a href="#menu">menu</a></code> element's <code - title=attr-menu-type><a href="#type15">type</a></code> attribute is in the - <a href="#list" title="list state">list state, then the element either - represents an unordered list of items (each represented by an - <code>li</code> element), each of which represents a command that the user - may perform or activate, or, if the element has no <code>li</code> element - children, a <span>paragraph</span> describing available commands.</a> - - <p>The <dfn id=label1 title=attr-menu-label><code>label</code></dfn> - attribute gives the label of the menu. It is used by user agents to - display nested menus in the UI. For example, a context menu containing - another menu would use the nested menu's <code title=attr-menu-label><a - href="#label1">label</a></code> attribute for the submenu's menu label. - - <p>The <dfn id=autosubmit - title=attr-menu-autosubmit><code>autosubmit</code></dfn> attribute is a <a - href="#boolean0">boolean attribute</a> that, if present, indicates that - selections made to form controls in this menu are to result in the - control's form being immediately submitted. - - <p>If a <code title=event-change>change</code> event bubbles through a - <code><a href="#menu">menu</a></code> element, then, in addition to any - other default action that that event might have, the UA must act as if the - following was an additional default action for that event: if (when it - comes time to execute the default action) the <code><a - href="#menu">menu</a></code> element has an <code - title=attr-menu-autosubmit><a href="#autosubmit">autosubmit</a></code> - attribute, and the target of the event is an <code>input</code> element, - and that element has a <code title=attr-input-type>type</code> attribute - whose value is either <code title="">radio</code> or <code - title="">checkbox</code>, and the <code>input</code> element in question - has a non-null <code title=dom-input-form>form</code> DOM attribute, then - the UA must invoke the <code title=dom-form-submit>submit()</code> method - of the <code>form</code> element indicated by that DOM attribute. - - <h5 id=menus-intro><span class=secno>3.18.4.1. </span>Introduction</h5> - - <p><em>This section is non-normative.</em> - - <p class=big-issue>...</p> - <!-- - - - <pre><menu type="commands"> - <li> - <menu label="File"> - <button type="button" onclick="fnew()">New...</button> - <button type="button" onclick="fopen()">Open...</button> - <button type="button" onclick="fsave()" id="save">Save</button> - <button type="button" onclick="fsaveas()">Save as...</button> - </menu> - </li> - <li> - <menu label="Edit"> - <button type="button" onclick="ecopy()">Copy</button> - <button type="button" onclick="ecut()">Cut</button> - <button type="button" onclick="epaste()">Paste</button> - </menu> - </li> - <li> - <menu label="Help"> - <li><a href="help.html">Help</a></li> - <li><a href="about.html">About</a></li> - </menu> - </li> -</menubar> - -... - -<input command="save"/> <!- - This will act exactly like the - Save button above, including reflecting - its <code>disabled</code> state dynamically - -> - -</pre> - - <p>Here's some markup that falls back on the traditional abuse of - the <code>select</code> element as a navigation menu, but which is - implemented as a semi-correct menu using the new techniques of this - document:</p> - -<pre><form action="redirect.cgi"> - <menu type="commands"> - <label for="goto">Go to...</label> - <menu label="Go"> - <select id="goto" - onchange="if (this.options[this.selectedIndex].value) - window.location = this.options[this.selectedIndex].value"> - <option value="" selected="selected"> Select site: </option> - <option value="http://www.apple.com/"> Apple </option> - <option value="http://www.mozilla.org/"> Mozilla </option> - <option value="http://www.opera.com/"> Opera </option> - </select> - <span><input type="submit" value="Go"></span> - </menu> - </menubar> -</form></pre> - -<form ...> - <menu type="toolbar" autosubmit> - <li> - <select name="foo" onchange="form.submit()"> - ... - </select> - <button>Go</button> - </li> - <li> - <select name="bar" onchange="form.submit()"> - ... - </select> - <button>Go</button> - </li> - </menu> -</form> - -<form ...> - <menu type="toolbar" autosubmit> - <menu label="Foo"> - <select name="foo" onchange="form.submit()"> - ... - </select> - <button>Go</button> - </menu> - <menu label="Bar"> - <select name="bar" onchange="form.submit()"> - ... - </select> - <button>Go</button> - </menu> - </menu> -</form> - ---> - - <h5 id=building><span class=secno>3.18.4.2. </span><dfn - id=building0>Building menus</dfn></h5> - - <p>A menu consists of a list of zero or more of the following components: - - <ul class=brief> - <li><a href="#command1" title=concept-command>Commands</a>, which can be - marked as default commands - - <li>Separators - - <li>Other menus (which allows the list to be nested) - </ul> - - <p>The list corresponding to a particular <code><a - href="#menu">menu</a></code> element is built by iterating over its child - nodes. For each child node in <a href="#tree-order">tree order</a>, the - required behaviour depends on what the node is, as follows: - - <dl class=switch> - <dt>An element that <a href="#command1" title=concept-command>defines a - command</a> - - <dd>Append the command to the menu. If the element is a <code><a - href="#command0">command</a></code> element with a <code - title=attr-command-default><a href="#default1">default</a></code> - attribute, mark the command as being a default command. - - <dt>An <code><a href="#hr">hr</a></code> element - - <dt>An <code>option</code> element that has a <code - title=attr-option-value>value</code> attribute set to the empty string, - and has a <code title=attr-option-disabled>disabled</code> attribute, and - whose <code><a href="#textcontent">textContent</a></code> consists of a - string of one or more hyphens (U+002D HYPHEN-MINUS) - - <dd>Append a separator to the menu. - - <dt>An <code><a href="#li">li</a></code> element - - <dd>Iterate over the children of the <code><a href="#li">li</a></code> - element. - - <dt>A <code><a href="#menu">menu</a></code> element with no <code - title=attr-menu-label><a href="#label1">label</a></code> attribute - - <dt>A <code>select</code> element - - <dd>Append a separator to the menu, then iterate over the children of the - <code><a href="#menu">menu</a></code> or <code>select</code> element, - then append another separator. - - <dt>A <code><a href="#menu">menu</a></code> element with a <code - title=attr-menu-label><a href="#label1">label</a></code> attribute - - <dt>An <code>optgroup</code> element - - <dd>Append a submenu to the menu, using the value of the element's <code - title="">label</code> attribute as the label of the menu. The submenu - must be constructed by taking the element and creating a new menu for it - using the complete process described in this section. - - <dt>Any other node - - <dd><a href="#ignored">Ignore</a> the node. - </dl> - - <p>Once all the nodes have been processed as described above, the user - agent must the post-process the menu as follows: - - <ol> - <li>Any menu item with no label, or whose label is the empty string, must - be removed. - - <li>Any sequence of two or more separators in a row must be collapsed to a - single separator. - - <li>Any separator at the start or end of the menu must be removed. - </ol> - - <h5 id=context><span class=secno>3.18.4.3. </span><dfn id=context2>Context - menus</dfn></h5> - - <p>The <dfn id=contextmenu - title=attr-contextmenu><code>contextmenu</code></dfn> attribute gives the - element's <a href="#context2" title="context menus">context menu</a>. The - value must be the ID of a <code><a href="#menu">menu</a></code> element in - the DOM. If the node that would be obtained by the invoking the - <code>getElementById()</code> method using the attribute's value as the - only argument is null or not a <code><a href="#menu">menu</a></code> - element, then the element has no assigned context menu. Otherwise, the - element's assigned context menu is the element so identified. - - <p>When an element's context menu is requested (e.g. by the user - right-clicking the element, or pressing a context menu key), the UA must - <a href="#firing1">fire a <code title="">contextmenu</code> event</a> on - the element for which the menu was requested. - - <p class=note>Typically, therefore, the firing of the <code - title=event-contextmenu>contextmenu</code> event will be the default - action of a <code title=mouseup>mouseup</code> or <code - title=event-keyup>keyup</code> event. The exact sequence of events is - UA-dependent, as it will vary based on platform conventions. - - <p>The default action of the <code - title=event-contextmenu>contextmenu</code> event depends on whether the - element has a context menu assigned (using the <code - title=attr-contextmenu><a href="#contextmenu">contextmenu</a></code> - attribute) or not. If it does not, the default action must be for the user - agent to show its default context menu, if it has one. - - <p>If the element <em>does</em> have a context menu assigned, then the user - agent must <a href="#firing3">fire a <code title="">show</code> event</a> - on the relevant <code><a href="#menu">menu</a></code> element. - - <p>The default action of <em>this</em> event is that the user agent must - show a context menu <a href="#building0" title="building menus">built</a> - from the <code><a href="#menu">menu</a></code> element. - - <p>The user agent may also provide access to its default context menu, if - any, with the context menu shown. For example, it could merge the menu - items from the two menus together, or provide the page's context menu as a - submenu of the default menu. - - <p>If the user dismisses the menu without making a selection, nothing in - particular happens. - - <p>If the user selects a menu item that represents a <span - title=concept-commands>command</span>, then the UA must invoke that - command's <a href="#action" title=command-facet-Action>Action</a>. - - <p>Context menus must not, while being shown, reflect changes in the DOM; - they are constructed as the default action of the <code - title=event-show>show</code> event and must remain like that until - dismissed. - - <p>User agents may provide means for bypassing the context menu processing - model, ensuring that the user can always access the UA's default context - menus. For example, the user agent could handle right-clicks that have the - Shift key depressed in such a way that it does not fire the <code - title=event-contextmenu>contextmenu</code> event and instead always shows - the default context menu. - - <p>The <dfn id=contextmenu0 - title=dom-contextMenu><code>contextMenu</code></dfn> attribute must <a - href="#reflect">reflect</a> the <code title=attr-contextmenu><a - href="#contextmenu">contextmenu</a></code> content attribute. - - <h5 id=toolbars><span class=secno>3.18.4.4. </span><dfn - id=toolbars0>Toolbars</dfn></h5> - - <p>Toolbars are a kind of menu that is always visible. - - <p>When a <code><a href="#menu">menu</a></code> element has a <code - title=attr-menu-type><a href="#type15">type</a></code> attribute with the - value <code title="">toolbar</code>, then the user agent must <a - href="#building0" title="building menus">build</a> the menu for that - <code><a href="#menu">menu</a></code> element and <span - title=render-toolbar>render</span><!-- XXX xref --> it in the document in - a position appropriate for that <code><a href="#menu">menu</a></code> - element. - - <p>The user agent must reflect changes made to the <code><a - href="#menu">menu</a></code>'s DOM immediately in the UI. - - <h4 id=commands><span class=secno>3.18.5. </span>Commands</h4> - - <p>A <dfn id=command1 title=concept-command>command</dfn> is the - abstraction behind menu items, buttons, and links. Once a command is - defined, other parts of the interface can refer to the same command, - allowing many access points to a single feature to share aspects such as - the disabled state. - - <p id=facets>Commands are defined to have the following <em>facets</em>: - - <dl> - <dt><dfn id=type16 title=command-facet-Type>Type</dfn> - - <dd>The kind of command: "command", meaning it is a normal command; - "radio", meaning that triggering the command will, amongst other things, - set the <a href="#checked2" title=command-facet-CheckedState>Checked - State</a> to true (and probably uncheck some other commands); or - "checkbox", meaning that triggering the command will, amongst other - things, toggle the value of the <a href="#checked2" - title=command-facet-CheckedState>Checked State</a>. - - <dt><dfn id=id1 title=command-facet-ID>ID</dfn> - - <dd>The name of the command, for referring to the command from the markup - or from script. If a command has no ID, it is an <dfn - id=anonymous>anonymous command</dfn>. - - <dt><dfn id=label2 title=command-facet-Label>Label</dfn> - - <dd>The name of the command as seen by the user. - - <dt><dfn id=hint title=command-facet-Hint>Hint</dfn> - - <dd>A helpful or descriptive string that can be shown to the user. - - <dt><dfn id=icon1 title=command-facet-Icon>Icon</dfn> - - <dd>A graphical image that represents the action. - - <dt><dfn id=hidden1 title=command-facet-HiddenState>Hidden State</dfn> - - <dd>Whether the command is hidden or not (basically, whether it should be - shown in menus). - - <dt><dfn id=disabled6 title=command-facet-DisabledState>Disabled - State</dfn> - - <dd>Whether the command can be triggered or not. If the <a href="#hidden1" - title=command-facet-HiddenState>Hidden State</a> is true (hidden) then - the <a href="#disabled6" title=command-facet-DisabledState>Disabled - State</a> will be true (disabled) regardless. <span class=issue>We could - make this into a string value that acts as a Hint for why the command is - disabled.</span> - - <dt><dfn id=checked2 title=command-facet-CheckedState>Checked State</dfn> - - <dd>Whether the command is checked or not. - - <dt><dfn id=action title=command-facet-Action>Action</dfn> - - <dd>The actual effect that triggering the command will have. This could be - a scripted event handler, a URI to which to navigate, or a form - submission. - - <dt><dfn id=triggers title=command-facet-Triggers>Triggers</dfn> - - <dd>The list of elements that can trigger the command. The element - defining a command is always in the list of elements that can trigger the - command. For anonymous commands, only the element defining the command is - on the list, since other elements have no way to refer to it. - </dl> - - <p>Commands are represented by elements in the DOM. Any element that can - define a command also implements the <code title=command-ro><a - href="#command2">Command</a></code> interface: - - <pre - class=idl>interface <dfn id=command2 title=command-ro>Command</dfn> {<!-- - NOTE: to avoid clashing with the HTMLCommandElement interface's names, - the members of this interface use cross-references with the title - dom-command-ro-foo (note the "ro", which stands for "readonly"). ---> - readonly attribute DOMString <a href="#commandtype" title=dom-command-ro-commandType>commandType</a>; - readonly attribute DOMString <a href="#id2" title=dom-command-ro-id>id</a>; - readonly attribute DOMString <a href="#label3" title=dom-command-ro-label>label</a>; - readonly attribute DOMString <a href="#title7" title=dom-command-ro-title>title</a>; - readonly attribute DOMString <a href="#icon2" title=dom-command-ro-icon>icon</a>; - readonly attribute boolean <a href="#hidden2" title=dom-command-ro-hidden>hidden</a>; - readonly attribute boolean <a href="#disabled7" title=dom-command-ro-disabled>disabled</a>; - readonly attribute boolean <a href="#checked3" title=dom-command-ro-checked>checked</a>; - void <a href="#click1" title=dom-command-ro-click>click</a>(); - readonly attribute <a href="#htmlcollection0">HTMLCollection</a> <a href="#triggers0" title=dom-command-ro-triggers>triggers</a>; - readonly attribute <a href="#command0">Command</a> <span title=dom-command-ro-command>command</span>; -};</pre> - - <p>The <code title=command-ro><a href="#command2">Command</a></code> - interface is implemented by any element capable of defining a command. (If - an element can define a command, its definition will list this interface - explicitly.) All the attributes of the <code title=command-ro><a - href="#command2">Command</a></code> interface are read-only. Elements - implementing this interface may implement other interfaces that have - attributes with identical names but that are mutable; in bindings that - simply flatten all supported interfaces on the object, the mutable - attributes must shadow the readonly attributes defined in the <code - title=command-ro><a href="#command2">Command</a></code> interface. - - <p>The <dfn id=commandtype - title=dom-command-ro-commandType><code>commandType</code></dfn> attribute - must return a string whose value is either "<code - title="">command</code>", "<code title="">radio</code>", or "<code - title="">checked</code>", depending on whether the <a href="#type16" - title=command-facet-Type>Type</a> of the command defined by the element is - "command", "radio", or "checked" respectively. If the element does not - define a command, it must return null. - - <p>The <dfn id=id2 title=dom-command-ro-id><code>id</code></dfn> attribute - must return the command's <a href="#id1" title=command-facet-ID>ID</a>, or - null if the element does not define a command or defines an <a - href="#anonymous">anonymous command</a>. This attribute will be shadowed - by the <code title=dom-id><a href="#id0">id</a></code> DOM attribute on - the <code><a href="#htmlelement">HTMLElement</a></code> interface. - - <p>The <dfn id=label3 title=dom-command-ro-label><code>label</code></dfn> - attribute must return the command's <a href="#label2" - title=command-facet-Label>Label</a>, or null if the element does not - define a command or does not specify a <a href="#label2" - title=command-facet-Label>Label</a>. This attribute will be shadowed by - the <code title="">label</code> DOM attribute on <code>option</code> and - <code><a href="#command0">command</a></code> elements. - - <p>The <dfn id=title7 title=dom-command-ro-title><code>title</code></dfn> - attribute must return the command's <a href="#hint" - title=command-facet-Hint>Hint</a>, or null if the element does not define - a command or does not specify a <a href="#hint" - title=command-facet-Hint>Hint</a>. This attribute will be shadowed by the - <code title=dom-title><a href="#title0">title</a></code> DOM attribute on - the <code><a href="#htmlelement">HTMLElement</a></code> interface. - - <p>The <dfn id=icon2 title=dom-command-ro-icon><code>icon</code></dfn> - attribute must return an absolute URI to the command's <a href="#icon1" - title=command-facet-Icon>Icon</a>. If the element does not specify an - icon, or if the element does not define a command, then the attribute must - return null. This attribute will be shadowed by the <code - title=dom-command-icon><a href="#icon0">icon</a></code> DOM attribute on - <code><a href="#command0">command</a></code> elements. - - <p>The <dfn id=hidden2 - title=dom-command-ro-hidden><code>hidden</code></dfn> attribute must - return true if the command's <a href="#hidden1" - title=command-facet-HiddenState>Hidden State</a> is that the command is - hidden, and false if it is that the command is not hidden. If the element - does not define a command, the attribute must return false. This attribute - will be shadowed by the <code title=dom-command-hidden><a - href="#hidden0">hidden</a></code> DOM attribute on <code><a - href="#command0">command</a></code> elements. - - <p>The <dfn id=disabled7 - title=dom-command-ro-disabled><code>disabled</code></dfn> attribute must - return true if the command's <a href="#disabled6" - title=command-facet-DisabledState>Disabled State</a> is that the command - is disabled, and false if the command is not disabled. This attribute is - not affected by the command's <a href="#hidden1" - title=command-facet-HiddenState>Hidden State</a>. If the element does not - define a command, the attribute must return false. This attribute will be - shadowed by the <code title="">disabled</code> attribute on - <code>button</code>, <code>input</code>, <code>option</code>, and <code><a - href="#command0">command</a></code> elements. - - <p>The <dfn id=checked3 - title=dom-command-ro-checked><code>checked</code></dfn> attribute must - return true if the command's <a href="#checked2" - title=command-facet-CheckedState>Checked State</a> is that the command is - checked, and false if it is that the command is not checked. If the - element does not define a command, the attribute must return false. This - attribute will be shadowed by the <code title="">checked</code> attribute - on <code>input</code> and <code><a href="#command0">command</a></code> - elements. - - <p>The <dfn id=click1 title=dom-command-ro-click><code>click()</code></dfn> - method must trigger the <a href="#action" - title=command-facet-Action>Action</a> for the command. If the element does - not define a command, this method must do nothing. This method will be - shadowed by the <code title=dom-click><a href="#click">click()</a></code> - method on HTML elements, and is included only for completeness. - - <p>The <dfn id=triggers0 - title=dom-command-ro-triggers><code>triggers</code></dfn> attribute must - return a list containing the elements that can trigger the command (the - command's <a href="#triggers" title=command-facet-Triggers>Triggers</a>). - The list must be <a href="#live">live</a>. While the element does not - define a command, the list must be empty. - - <p>The <dfn id=commands0 - title=dom-document-commands><code>commands</code></dfn> attribute of the - document's <code><a href="#htmldocument">HTMLDocument</a></code> interface - must return an <code><a href="#htmlcollection0">HTMLCollection</a></code> - rooted at the <code>Document</code> node, whose filter matches only - elements that define commands and have IDs. - - <p>The following elements can define commands: <code title=a-command><a - href="#using4">a</a></code>, <code title=button-command><a - href="#using5">button</a></code>, <code title=input-command><a - href="#using6">input</a></code>, <code title=option-command><a - href="#using7">option</a></code>, <code title=command-element><a - href="#command3">command</a></code>. - - <h5 id=using><span class=secno>3.18.5.1. </span><dfn id=using4 - title=a-command>Using the <code>a</code> element to define a command</dfn></h5> - - <p>An <code><a href="#a">a</a></code> element with an <code - title=attr-hyperlink-href><a href="#href6">href</a></code> attribute <a - href="#command1" title=concept-command>defines a command</a>. - - <p>The <a href="#type16" title=command-facet-Type>Type</a> of the command - is "command". - - <p>The <a href="#id1" title=command-facet-ID>ID</a> of the command is the - value of the <code title=attr-id><a href="#id">id</a></code> attribute of - the element, if the attribute is present and not empty. Otherwise the - command is an <a href="#anonymous">anonymous command</a>. - - <p>The <a href="#label2" title=command-facet-Label>Label</a> of the command - is the string given by the element's <code><a - href="#textcontent">textContent</a></code> DOM attribute. - - <p>The <a href="#hint" title=command-facet-Hint>Hint</a> of the command is - the value of the <code title=attr-title><a href="#title">title</a></code> - attribute of the <code><a href="#a">a</a></code> element. If the attribute - is not present, the <a href="#hint" title=command-facet-Hint>Hint</a> is - the empty string. - - <p>The <a href="#icon1" title=command-facet-Icon>Icon</a> of the command is - the absolute URI of the first image in the element. Specifically, in a - depth-first search of the children of the element, the first element that - is <!--either an--> <code><a href="#img">img</a></code> element with a - <code>src</code> attribute<!--, or an <code>object</code> element - with a <code>data</code> attribute, or, if the UA supports SVG, an - <code>svg</code> element in the SVG namespace with a valid <code - title="">id</code> attribute,--> - is the one that is used as the image. - <!--If it is an <code>img</code> element then--> The URI must be taken - from the element's <code>src</code> attribute. <!--If it is - an <code>object</code> element then the URI is taken from the - <code>data</code> attribute. --> - Relative URIs must be resolved relative to the base URI of the image - element. <!-- If it is an - <code>svg</code> element then the URI is formed by taking the URI of - the document and appending a "#" (U+0023 NUMBER SIGN) and the ID of - the element.--> - If no image is found, then the Icon facet is left blank. - - <p>The <a href="#hidden1" title=command-facet-HiddenState>Hidden State</a> - and <a href="#disabled6" title=command-facet-DisabledState>Disabled - State</a> facets of the command are always false. (The command is always - enabled.) - - <p>The <a href="#checked2" title=command-facet-CheckedState>Checked - State</a> of the command is always false. (The command is never checked.) - - <p>The <a href="#action" title=command-facet-Action>Action</a> of the - command is to <a href="#firing" title="fire a click event">fire a <code - title="">click</code> event</a> at the element. - - <h5 id=using0><span class=secno>3.18.5.2. </span><dfn id=using5 - title=button-command>Using the <code>button</code> element to define a - command</dfn></h5> - - <p>A <code>button</code> element always <a href="#command1" - title=concept-command>defines a command</a>. - - <p>The <a href="#type16" title=command-facet-Type>Type</a>, <a href="#id1" - title=command-facet-ID>ID</a>, <a href="#label2" - title=command-facet-Label>Label</a>, <a href="#hint" - title=command-facet-Hint>Hint</a>, <a href="#icon1" - title=command-facet-Icon>Icon</a>, <a href="#hidden1" - title=command-facet-HiddenState>Hidden State</a>, <a href="#checked2" - title=command-facet-CheckedState>Checked State</a>, and <a href="#action" - title=command-facet-Action>Action</a> facets of the command are determined - <a href="#using4" title=a-command>as for <code>a</code> elements</a> (see - the previous section). - - <p>The <a href="#disabled6" title=command-facet-DisabledState>Disabled - State</a> of the command mirrors the disabled state of the button. - Typically this is given by the element's <code - title=attr-button-disabled>disabled</code> attribute, but certain button - types become disabled at other times too (for example, the - <code>move-up</code> button type is disabled when it would have no - effect). - - <h5 id=using1><span class=secno>3.18.5.3. </span><dfn id=using6 - title=input-command>Using the <code>input</code> element to define a - command</dfn></h5> - - <p>An <code>input</code> element whose <code - title=attr-input-type>type</code> attribute is one of <code>submit</code>, - <code>reset</code>, <code>button</code>, <code>radio</code>, - <code>checkbox</code>, <code>move-up</code>, <code>move-down</code>, - <code>add</code>, and <code>remove</code> <a href="#command1" - title=concept-command>defines a command</a>. - - <p>The <a href="#type16" title=command-facet-Type>Type</a> of the command - is "radio" if the <code title=attr-input-type>type</code> attribute has - the value <code>radio</code>, "checkbox" if the <code>type</code> - attribute has the value <code>checkbox</code>, and "command" otherwise. - - <p>The <a href="#id1" title=command-facet-ID>ID</a> of the command is the - value of the <code title=attr-id><a href="#id">id</a></code> attribute of - the element, if the attribute is present and not empty. Otherwise the - command is an <a href="#anonymous">anonymous command</a>. - - <p>The <a href="#label2" title=command-facet-Label>Label</a> of the command - depends on the Type of the command: - - <p>If the <a href="#type16" title=command-facet-Type>Type</a> is "command", - then it is the string given by the <code - title=attr-input-value>value</code> attribute, if any, and a - <span>UA-dependent value</span><!-- XXX xref--> that the UA uses to label - the button itself if the attribute is absent. - - <p>Otherwise, the <a href="#type16" title=command-facet-Type>Type</a> is - "radio" or "checkbox". If the element has a <code>label</code> element - associated with it, the <code><a - href="#textcontent">textContent</a></code> of the first such element is - the <a href="#label2" title=command-facet-Label>Label</a> (in DOM terms, - this the string given by <code><var - title="">element</var>.labels[0].textContent</code>). Otherwise, the value - of the <code>value</code> attribute, if present, is the <a href="#label2" - title=command-facet-Label>Label</a>. Otherwise, the <a href="#label2" - title=command-facet-Label>Label</a> is the empty string. - - <p>The <a href="#hint" title=command-facet-Hint>Hint</a> of the command is - the value of the <code title=attr-title><a href="#title">title</a></code> - attribute of the <code>input</code> element. If the attribute is not - present, the <a href="#hint" title=command-facet-Hint>Hint</a> is the - empty string. - - <p>There is no <a href="#icon1" title=command-facet-Icon>Icon</a> for the - command. - - <p>The <a href="#hidden1" title=command-facet-HiddenState>Hidden State</a> - of the command is always false. (The command is never hidden.) - - <p>The <a href="#disabled6" title=command-facet-DisabledState>Disabled - State</a> of the command mirrors the disabled state of the control. - Typically this is given by the element's <code - title=attr-input-disabled>disabled</code> attribute, but certain input - types become disabled at other times too (for example, the - <code>move-up</code> input type is disabled when it would have no effect). - - <p>The <a href="#checked2" title=command-facet-CheckedState>Checked - State</a> of the command is true if the command is of <a href="#type16" - title=command-facet-Type>Type</a> "radio" or "checkbox" and the element - has a <code title=attr-input-checked>checked</code> attribute, and false - otherwise. - - <p>The <a href="#action" title=command-facet-Action>Action</a> of the - command is to <a href="#firing" title="fire a click event">fire a <code - title="">click</code> event</a> at the element.</p> - <!-- XXX this - is probably wrong for radio and checkbox types, depending on how we - define <input>. --> - - <h5 id=using2><span class=secno>3.18.5.4. </span><dfn id=using7 - title=option-command>Using the <code>option</code> element to define a - command</dfn></h5> - - <p>An <code>option</code> element with an ancestor <code>select</code> - element and either no <code title=attr-option-value>value</code> attribute - or a <code title=attr-option-value>value</code> attribute that is not the - empty string <a href="#command1" title=concept-command>defines a - command</a>. - - <p>The <a href="#type16" title=command-facet-Type>Type</a> of the command - is "radio" if the <code>option</code>'s nearest ancestor - <code>select</code> element has no <code - title=attr-select-multiple>multiple</code> attribute, and "checkbox" if it - does. - - <p>The <a href="#id1" title=command-facet-ID>ID</a> of the command is the - value of the <code title=attr-id><a href="#id">id</a></code> attribute of - the element, if the attribute is present and not empty. Otherwise the - command is an <a href="#anonymous">anonymous command</a>. - - <p>The <a href="#label2" title=command-facet-Label>Label</a> of the command - is the value of the <code>option</code> element's <code - title=attr-option-label>label</code> attribute, if there is one, or the - value of the <code>option</code> element's <code><a - href="#textcontent">textContent</a></code> DOM attribute if it doesn't. - - <p>The <a href="#hint" title=command-facet-Hint>Hint</a> of the command is - the string given by the element's <code title=attr-title><a - href="#title">title</a></code> attribute, if any, and the empty string if - the attribute is absent. - - <p>There is no <a href="#icon1" title=command-facet-Icon>Icon</a> for the - command. - - <p>The <a href="#hidden1" title=command-facet-HiddenState>Hidden State</a> - of the command is always false. (The command is never hidden.) - - <p>The <a href="#disabled6" title=command-facet-DisabledState>Disabled - State</a> of the command is true (disabled) if the element has a <code - title=attr-option-disabled>disabled</code> attribute, and false otherwise. - - <p>The <a href="#checked2" title=command-facet-CheckedState>Checked - State</a> of the command is true (checked) if the element's <code - title=dom-option-selected>selected</code> DOM attribute is true, and false - otherwise. - - <p>The <a href="#action" title=command-facet-Action>Action</a> of the - command depends on its <a href="#type16" - title=command-facet-Type>Type</a>. If the command is of <a href="#type16" - title=command-facet-Type>Type</a> "radio" then this must set the <code - title=dom-option-selected>selected</code> DOM attribute of the - <code>option</code> element to true, otherwise it must toggle the state of - the <code title=dom-option-selected>selected</code> DOM attribute (set it - to true if it is false and vice versa). Then <a href="#firing0" - title="fire a change event">a <code title="">change</code> event must be - fired</a> on the <code>option</code> element's nearest ancestor - <code>select</code> element (if there is one), as if the selection had - been changed directly. - - <h5 id=using3><span class=secno>3.18.5.5. </span>Using the <dfn id=command3 - title=command-element><code>command</code></dfn> element to define a - command</h5> - - <p>A <code><a href="#command0">command</a></code> element <a - href="#command1" title=concept-command>defines a command</a>. - - <p>The <a href="#type16" title=command-facet-Type>Type</a> of the command - is "radio" if the <code><a href="#command0">command</a></code>'s <code - title=attr-command-type><a href="#type13">type</a></code> attribute is - "<code>radio</code>", "checkbox" if the attribute's value is - "<code>checkbox</code>", and "command" otherwise. - - <p>The <a href="#id1" title=command-facet-ID>ID</a> of the command is the - value of the <code title=attr-id><a href="#id">id</a></code> attribute of - the element, if the attribute is present and not empty. Otherwise the - command is an <a href="#anonymous">anonymous command</a>. - - <p>The <a href="#label2" title=command-facet-Label>Label</a> of the command - is the value of the element's <code title=attr-command-label><a - href="#label">label</a></code> attribute, if there is one, or the empty - string if it doesn't. - - <p>The <a href="#hint" title=command-facet-Hint>Hint</a> of the command is - the string given by the element's <code title=attr-command-title><a - href="#title6">title</a></code> attribute, if any, and the empty string if - the attribute is absent. - - <p>The <a href="#icon1" title=command-facet-Icon>Icon</a> for the command - is the absolute URI resulting from resolving the value of the element's - <code title=attr-command-icon><a href="#icon">icon</a></code> attribute as - a URI relative to the element's base URI. If the element has no <code - title=attr-command-icon><a href="#icon">icon</a></code> attribute then the - command has no <a href="#icon1" title=command-facet-Icon>Icon</a>. - - <p>The <a href="#hidden1" title=command-facet-HiddenState>Hidden State</a> - of the command is true (hidden) if the element has a <code - title=attr-command-hidden><a href="#hidden">hidden</a></code> attribute, - and false otherwise. - - <p>The <a href="#disabled6" title=command-facet-DisabledState>Disabled - State</a> of the command is true (disabled) if the element has either a - <code title=attr-command-disabled><a href="#disabled4">disabled</a></code> - attribute or a <code title=attr-command-hidden><a - href="#hidden">hidden</a></code> attribute (or both), and false otherwise. - - <p>The <a href="#checked2" title=command-facet-CheckedState>Checked - State</a> of the command is true (checked) if the element has a <code - title=attr-command-checked><a href="#checked0">checked</a></code> - attribute, and false otherwise. - - <p>The <a href="#action" title=command-facet-Action>Action</a> of the - command is to invoke the behaviour described in the definition of the - <code title=dom-command-click><a href="#click0">click()</a></code> method - of the <code><a href="#htmlcommandelement">HTMLCommandElement</a></code> - interface.</p> - <!-- XXX update to - point to dom-click when we remove dom-command-click --> - - <h3 id=miscellaneous><span class=secno>3.19. </span>Miscellaneous elements</h3> - - <h4 id=the-legend><span class=secno>3.19.1. </span>The <dfn - id=legend><code>legend</code></dfn> element</h4> - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>As the first child of a <code>fieldset</code> element. - - <dd>As the first child of a <code><a href="#details">details</a></code> - element. - - <dd>As a child of a <code><a href="#figure">figure</a></code> element, if - there are no other <code><a href="#legend">legend</a></code> element - children of that element. - - <dt>Content model: - - <dd>If used as a child of a <code>fieldset</code> or <code><a - href="#details">details</a></code> element: <a href="#significant" - title="significant inline content">significant</a> <a - href="#strictly">strictly inline-level content</a> - - <dd>If used as a child of a <code><a href="#figure">figure</a></code> - element: <a href="#inline-level0">inline-level content</a>. - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#legend">legend</a></code> element represents a title - or explanatory caption for the rest of the contents of the <code><a - href="#legend">legend</a></code> element's parent element. - - <h4 id=the-div><span class=secno>3.19.2. </span>The <dfn - id=div><code>div</code></dfn> element</h4> - - <p><a href="#block-level0" title="block-level elements">Block-level - element</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <a href="#block-level0">block-level elements</a> are expected. - - <dt>Content model: - - <dd>Zero or more <code><a href="#style">style</a></code> elements, - followed by either zero or more <a href="#block-level0">block-level - elements</a>, or <a href="#inline-level0">inline-level content</a> (but - not both). - - <dt>Element-specific attributes: - - <dd>None. - - <dt>DOM interface: - - <dd>No difference from <code><a - href="#htmlelement">HTMLElement</a></code>. - </dl> - - <p>The <code><a href="#div">div</a></code> element represents nothing at - all. It can be used with the <code title=attr-class><a - href="#class">class</a></code>, <code title=attr-lang><a - href="#lang">lang</a></code>/<code title=attr-xml-lang><a - href="#xmllang">xml:lang</a></code>, and <code title=attr-title><a - href="#title">title</a></code> attributes to mark up semantics common to a - group of consecutive elements. - - <h2 id=web-browsers><span class=secno>4. </span>Web browsers</h2> - - <p>This section describes features that apply most directly to Web - browsers. Having said that, unless specified elsewhere, the requirements - defined in this section <em>do</em> apply to all user agents, whether they - are Web browsers or not. - - <h3 id=windows><span class=secno>4.1. </span>Browsing contexts</h3> - - <p>A <dfn id=browsing0>browsing context</dfn> is a collection of one or - more <code>Document</code> objects, and one or more <a href="#view" - title=view>views</a>. - - <p>At any one time, one of the <code>Document</code>s in a <a - href="#browsing0">browsing context</a> is the <dfn id=active>active - document</dfn>. The collection of <code>Document</code>s is the <a - href="#browsing0">browsing context</a>'s <a href="#session">session - history</a>. - - <p>A <dfn id=view>view</dfn> is a user agent interface tied to a particular - media used for the presentation of <code>Document</code> objects in some - media. A view may be interactive. Each view is represented by an - <code>AbstractView</code> object. Each view belongs to a <a - href="#browsing0">browsing context</a>. <a - href="#refsDOM2VIEWS">[DOM2VIEWS]</a> - - <p class=note>The <code title="">document</code> attribute of an - <code>AbstractView</code> object representing a <a href="#view">view</a> - gives the <code>Document</code> object of the view's <a - href="#browsing0">browsing context</a>'s <a href="#active">active - document</a>. <a href="#refsDOM2VIEWS">[DOM2VIEWS]</a> - - <p class=note>Events that use the <code>UIEvent</code> interface are - related to a specific <a href="#view">view</a> (the view in which the - event happened); the <code>AbstractView</code> of that view is given in - the event object's <code title="">view</code> attribute. <a - href="#refsDOM3EVENTS">[DOM3EVENTS]</a> - - <p class=note>A typical Web browser has one obvious <a - href="#view">view</a> per <a href="#browsing0">browsing context</a>: the - browser's window (screen media). If a page is printed, however, a second - view becomes evident, that of the print media. The two views always share - the same underlying <code>Document</code>, but they have a different - presentation of that document. A speech browser also establishes a - browsing context, one with a view in the speech media. - - <p class=note>A <code>Document</code> does not necessarily have a <a - href="#browsing0">browsing context</a> associated with it. In particular, - data mining tools are likely to never instantiate browsing contexts. - - <p>The main <a href="#view">view</a> through which a user primarily - interacts with a user agent is the <dfn id=default3>default view</dfn>. - - <p class=note>The <a href="#default3">default view</a> of a - <code>Document</code> is given by the <code title="">defaultView</code> - attribute on the <code>Document</code> object's <code>DocumentView</code> - interface. <a href="#refsDOM3VIEWS">[DOM3VIEWS]</a> - - <p>When a <a href="#browsing0">browsing context</a> is first created, it - must be created with a single <code>Document</code> in its session - history, whose <span title="the document's address">address</span> is - <code>about:blank</code>, which is marked as being an <a href="#html-" - title="HTML documents">HTML documents</a>. The <code>Document</code> must - have a single child <code><a href="#html">html</a></code> node, which - itself has a single child <code><a href="#body0">body</a></code> node. If - the <a href="#browsing0">browsing context</a> is created specifically to - be immediately navigated, then that initial navigation will have <a - href="#replacement">replacement enabled</a>. - - <h4 id=nested><span class=secno>4.1.1. </span>Nested browsing contexts</h4> - - <p>Certain elements (for example, <code><a href="#iframe">iframe</a></code> - elements) can instantiate further <a href="#browsing0" title="browsing - context">browsing contexts</a>. These are called <dfn id=nested0 - title="nested browsing context">nested browsing contexts</dfn>. If a - browsing context <var title="">P</var> has an element in one of its - <code>Document</code>s <var title="">D</var> that nests another browsing - context <var title="">C</var> inside it, then <var title="">P</var> is - said to be the <dfn id=parent>parent browsing context</dfn> of <var - title="">C</var>, <var title="">C</var> is said to be a <dfn - id=child>child browsing context</dfn> of <var title="">P</var>, and <var - title="">C</var> is said to be <dfn id=nested1 title="browsing context - nested through">nested through</dfn> <var title="">D</var>. - - <p>The browsing context with no <a href="#parent">parent browsing - context</a> is the <dfn id=top-level>top-level browsing context</dfn> of - all the browsing contexts <a href="#nested0" title="nested browsing - context">nested</a> within it (either directly or indirectly through other - nested browsing contexts). - - <p>A <code>Document</code> is said to be <dfn id=fully>fully active</dfn> - when it is the <a href="#active">active document</a> of its <a - href="#browsing0">browsing context</a>, and either its browsing context is - a <a href="#top-level">top-level browsing context</a>, or the - <code>Document</code> <a href="#nested1" title="browsing context nested - through">through which</a> that browsing context is <a href="#nested0" - title="nested browsing context">nested</a> is itself <a - href="#fully">fully active</a>. - - <p>Because they are nested through an element, <a href="#child" - title="child browsing context">child browsing contexts</a> are always tied - to a specific <code>Document</code> in their <a href="#parent">parent - browsing context</a>. User agents must not allow the user to interact with - <a href="#child" title="child browsing context">child browsing - contexts</a> of elements that are in <code>Document</code>s that are not - themselves <a href="#fully">fully active</a>. - - <h4 id=auxiliary><span class=secno>4.1.2. </span>Auxiliary browsing - contexts</h4> - - <p>It is possible to create new browsing contexts that are related to a - <span>top level browsing context</span> without being nested through an - element. Such browsing contexts are called <dfn id=auxiliary0 - title="auxiliary browsing context">auxiliary browsing contexts</dfn>. - Auxiliary browsing contexts are always <a href="#top-level" - title="top-level browsing context">top-level browsing contexts</a>. - - <p>An <a href="#auxiliary0">auxiliary browsing context</a> has an <dfn - id=opener>opener browsing context</dfn>, which is the <a - href="#browsing0">browsing context</a> from which the <a - href="#auxiliary0">auxiliary browsing context</a> was created, and it has - a <dfn id=furthest>furthest ancestor browsing context</dfn>, which is the - <a href="#top-level">top-level browsing context</a> of the <a - href="#opener">opener browsing context</a> when the <a - href="#auxiliary0">auxiliary browsing context</a> was created. - - <p>The <dfn id=opener0 title=dom-opener><code>opener</code></dfn> DOM - attribute on the <code><a href="#window">Window</a></code> object must - return the <code><a href="#window">Window</a></code> object of the <a - href="#browsing0">browsing context</a> from which the current browsing - context was created (its <a href="#opener">opener browsing context</a>), - if there is one and it is still available. - - <h4 id=secondary><span class=secno>4.1.3. </span>Secondary browsing - contexts</h4> - - <p>User agents may support <dfn id=secondary0 title="secondary browsing - context">secondary browsing contexts</dfn>, which are <a href="#browsing0" - title="browsing context">browsing contexts</a> that form part of the user - agent's interface, apart from the main content area. - - <h4 id=threads><span class=secno>4.1.4. </span>Threads</h4> - - <p>Each <a href="#browsing0">browsing context</a> is defined as having a - list of zero or more <dfn id=directly>directly reachable browsing - contexts</dfn>. These are: - - <ul> - <li>All the <a href="#browsing0">browsing context</a>'s <a href="#child" - title="child browsing context">child browsing contexts</a>. - - <li>The <a href="#browsing0">browsing context</a>'s <a - href="#parent">parent browsing context</a>. - - <li>All the <a href="#browsing0" title="browsing context">browsing - contexts</a> that have the <a href="#browsing0">browsing context</a> as - their <a href="#opener">opener browsing context</a>. - - <li>The <a href="#browsing0">browsing context</a>'s <a - href="#opener">opener browsing context</a>. - </ul> - - <p>The transitive closure of all the <a href="#browsing0" title="browsing - context">browsing contexts</a> that are <a href="#directly">directly - reachable browsing contexts</a> consists of a <dfn id=unit-of>unit of - related browsing contexts</dfn>. - - <p>All the executable code in a <a href="#unit-of">unit of related browsing - contexts</a> must execute on a single conceptual thread. The dispatch of - events fired by the user agent (e.g. in response to user actions or - network activity) and the execution of any scripts associated with timers - must be serialised so that for each <a href="#unit-of">unit of related - browsing contexts</a> there is only one script being executed at a time. - - <h4 id=browsing><span class=secno>4.1.5. </span>Browsing context names</h4> - - <p>Browsing contexts can have a <dfn id=browsing1>browsing context - name</dfn>. By default, a browsing context has no name (its name is not - set). - - <p>A <dfn id=valid8>valid browsing context name</dfn> is any string that - does not start with a U+005F LOW LINE character, or, a string that - case-insensitively <!-- ASCII --> matches one of: <!--<code - title="">_blank</code>,--> - <code title="">_self</code>, <code title="">_parent</code>, or <code - title="">_top</code>. (Names starting with an underscore are reserved for - special keywords.) - - <p><dfn id=the-rules>The rules for chosing a browsing context given a - browsing context name</dfn> are as follows. The rules assume that they are - being applied in the context of a <a href="#browsing0">browsing - context</a>. - - <ol> - <li> - <p>If the given browsing context name is the empty string or <code - title="">_self</code>, then the chosen browsing context must be the - current one. - - <li> - <p>If the given browsing context name is <code title="">_parent</code>, - then the chosen browsing context must be the <a - href="#parent"><em>parent</em> browsing context</a> of the current one, - unless there isn't one, in which case the chosen browsing context must - be the current browsing context. - - <li> - <p>If the given browsing context name is <code title="">_top</code>, then - the chosen browsing context must be the most <a - href="#top-level">top-level browsing context</a> of the current one. - - <li> - <p>If the given browsing context name is not <code title="">_blank</code> - and there exists a browsing context whose <a href="#browsing1" - title="browsing context name">name</a> is the same as the given browsing - context name, and one of the following is true: - - <ul> - <li>Either the <a href="#origin0">origin</a> of that browsing context's - <a href="#active">active document</a> is the same as the <a - href="#origin0">origin</a> of the current browsing context's <a - href="#active">active document</a>, - - <li>Or that browsing context is an <a href="#auxiliary0">auxiliary - browsing context</a> and its <a href="#opener">opener browsing - context</a> is either the current browsing context or a browsing - context that the user agent considers is closely enough related to the - current browsing context, - - <li>Or that browsing context is not a <a href="#top-level">top-level - browsing context</a>, and the <a href="#origin0">origin</a> of the <a - href="#active">active document</a> of the <a href="#parent">parent - browsing context</a> of that browsing context is the same as the <a - href="#origin0">origin</a> of the current browsing context's <a - href="#active">active document</a>, - </ul> - - <p>...and the user agent determines that the two browsing contexts are - related enough that it is ok if they reach each other, then that - browsing context must be the chosen one. If there are multiple matching - browsing contexts, the user agent should select one in some arbitrary - consistent manner, such as the most recently opened, most recently - focused, or more closely related.</p> - - <li> - <p>Otherwise, a new browsing context is being requested, and what happens - depends on the user agent's configuration and/or abilities:</p> - - <dl> - <dt>If the user agent has been configured such that in this instance it - will create a new browsing context - - <dd>A new <a href="#auxiliary0">auxiliary browsing context</a> must be - created, with the <a href="#opener">opener browsing context</a> being - the current one. If the given browsing context name is not <code - title="">_blank</code>, then the new auxiliary browsing context's name - must be the given browsing context name (otherwise, it has no name). - The chosen browsing context must be this new browsing context. If it is - immediately <a href="#navigate" title=navigate>navigated</a>, then the - navigation will be done with <a href="#replacement">replacement - enabled</a>. - - <dt>If the user agent has been configured such that in this instance it - will reuse the current browsing context - - <dd>The chosen browsing context is the current browsing context. - - <dt>If the user agent has been configured such that in this instance it - will not find a browsing context - - <dd>There must not be a chosen browsing context. - </dl> - </ol> - - <h3 id=the-default0><span class=secno>4.2. </span>The default view</h3> - - <p>The <code>AbstractView</code> object of <a href="#default3" - title="default view">default views</a> must also implement the <code><a - href="#window">Window</a></code> object. - - <pre class=idl>interface <dfn id=window>Window</dfn> { - // the current browsing context - readonly attribute <a href="#window">Window</a> <a href="#window0" title=dom-window>window</a>; - readonly attribute <a href="#window">Window</a> <a href="#self" title=dom-self>self</a>; - attribute DOMString <a href="#name3" title=dom-name>name</a>; - readonly attribute <a href="#location2">Location</a> <a href="#location0" title=dom-document-location>location</a>; - readonly attribute <a href="#history1">History</a> <a href="#history0" title=dom-history>history</a>; - readonly attribute <a href="#undomanager">UndoManager</a> <a href="#undomanager0" title=dom-undoManager>undoManager</a>; - <a href="#selection1">Selection</a> <a href="#getselection" title=dom-getSelection>getSelection</a>(); - - // the user agent - readonly attribute <a href="#clientinformation">ClientInformation</a> <a href="#navigator" title=dom-navigator>navigator</a>; <!-- XXX IE6 also has window.clientInformation pointing to this same object --> - readonly attribute <a href="#storage2">Storage</a> <a href="#sessionstorage" title=dom-sessionStorage>sessionStorage</a>; - readonly attribute <a href="#storagelist">StorageList</a> <a href="#globalstorage" title=dom-globalStorage>globalStorage</a>; - <a href="#resultset">ResultSet</a> <a href="#executesql" title=dom-executeSql>executeSql</a>(in DOMString sqlStatement, <var title="">arguments...</var>); - - // modal user prompts - void <a href="#alert" title=dom-alert>alert</a>(in DOMString message); - boolean <a href="#confirm" title=dom-confirm>confirm</a>(in DOMString message); - DOMString <a href="#prompt" title=dom-prompt>prompt</a>(in DOMString message); - DOMString <a href="#prompt" title=dom-prompt>prompt</a>(in DOMString message, in DOMString default); - void <a href="#print" title=dom-print>print</a>(); - - // other browsing contexts - readonly attribute <a href="#window">Window</a> <a href="#frames" title=dom-frames>frames</a>; - readonly attribute unsigned long <a href="#length5" title=dom-length>length</a>; - readonly attribute <a href="#window">Window</a> <a href="#opener0" title=dom-opener>opener</a>; - <a href="#window">Window</a> <a href="#open2" title=dom-open>open</a>(); - <a href="#window">Window</a> <a href="#open2" title=dom-open>open</a>(in DOMString url); - <a href="#window">Window</a> <a href="#open2" title=dom-open>open</a>(in DOMString url, in DOMString target); - <a href="#window">Window</a> <a href="#open2" title=dom-open>open</a>(in DOMString url, in DOMString target, in DOMString features); - <a href="#window">Window</a> <a href="#open2" title=dom-open>open</a>(in DOMString url, in DOMString target, in DOMString features, in DOMString replace); - - // <a href="#event3">event handler DOM attributes</a> - attribute <span>EventListener</span> <a href="#onabort" title=handler-onabort>onabort</a>; - attribute <span>EventListener</span> <a href="#onbeforeunload" title=handler-onbeforeunload>onbeforeunload</a>; - attribute <span>EventListener</span> <a href="#onblur" title=handler-onblur>onblur</a>; - attribute <span>EventListener</span> <a href="#onchange" title=handler-onchange>onchange</a>; - attribute <span>EventListener</span> <a href="#onclick" title=handler-onclick>onclick</a>; - attribute <span>EventListener</span> <a href="#oncontextmenu" title=handler-oncontextmenu>oncontextmenu</a>; - attribute <span>EventListener</span> <a href="#ondblclick" title=handler-ondblclick>ondblclick</a>; - attribute <span>EventListener</span> <a href="#ondrag" title=handler-ondrag>ondrag</a>; - attribute <span>EventListener</span> <a href="#ondragend" title=handler-ondragend>ondragend</a>; - attribute <span>EventListener</span> <a href="#ondragenter" title=handler-ondragenter>ondragenter</a>; - attribute <span>EventListener</span> <a href="#ondragleave" title=handler-ondragleave>ondragleave</a>; - attribute <span>EventListener</span> <a href="#ondragover" title=handler-ondragover>ondragover</a>; - attribute <span>EventListener</span> <a href="#ondragstart" title=handler-ondragstart>ondragstart</a>; - attribute <span>EventListener</span> <a href="#ondrop" title=handler-ondrop>ondrop</a>; - attribute <span>EventListener</span> <a href="#onerror" title=handler-onerror>onerror</a>; - attribute <span>EventListener</span> <a href="#onfocus" title=handler-onfocus>onfocus</a>; - attribute <span>EventListener</span> <a href="#onkeydown" title=handler-onkeydown>onkeydown</a>; - attribute <span>EventListener</span> <a href="#onkeypress" title=handler-onkeypress>onkeypress</a>; - attribute <span>EventListener</span> <a href="#onkeyup" title=handler-onkeyup>onkeyup</a>; - attribute <span>EventListener</span> <a href="#onload" title=handler-onload>onload</a>; - attribute <span>EventListener</span> <a href="#onmessage" title=handler-onmessage>onmessage</a>; - attribute <span>EventListener</span> <a href="#onmousedown" title=handler-onmousedown>onmousedown</a>; - attribute <span>EventListener</span> <a href="#onmousemove" title=handler-onmousemove>onmousemove</a>; - attribute <span>EventListener</span> <a href="#onmouseout" title=handler-onmouseout>onmouseout</a>; - attribute <span>EventListener</span> <a href="#onmouseover" title=handler-onmouseover>onmouseover</a>; - attribute <span>EventListener</span> <a href="#onmouseup" title=handler-onmouseup>onmouseup</a>; - attribute <span>EventListener</span> <a href="#onmousewheel" title=handler-onmousewheel>onmousewheel</a>; - attribute <span>EventListener</span> <a href="#onresize" title=handler-onresize>onresize</a>; - attribute <span>EventListener</span> <a href="#onscroll" title=handler-onscroll>onscroll</a>; - attribute <span>EventListener</span> <a href="#onselect" title=handler-onselect>onselect</a>; - attribute <span>EventListener</span> <a href="#onsubmit" title=handler-onsubmit>onsubmit</a>; - attribute <span>EventListener</span> <a href="#onunload" title=handler-onunload>onunload</a>; -};</pre> - <!-- XXX XMLHttpRequest - http://msdn.microsoft.com/workshop/author/dhtml/reference/objects/obj_window.asp - http://www.mozilla.org/docs/dom/domref/dom_window_ref.html - http://lxr.mozilla.org/mozilla/source/dom/public/idl/base/nsIDOMWindow.idl - --> - - <p>The <dfn id=window0 title=dom-window><code>window</code></dfn>, <dfn - id=frames title=dom-frames><code>frames</code></dfn>, <dfn id=self - title=dom-self><code>self</code></dfn> DOM attributes must all return the - <code><a href="#window">Window</a></code> object itself. - - <p>The <code><a href="#window">Window</a></code> object also provides the - scope for script execution. Each <code>Document</code> in a <a - href="#browsing0">browsing context</a> has an associated <dfn - id=list-of2>list of added properties</dfn> which, when a document is <a - href="#active" title="active document">active</a>, are available on the - <code>Document</code>'s <a href="#default3">default view</a> <code><a - href="#window">Window</a></code> object. A <code>Document</code> object's - <a href="#list-of2">list of added properties</a> must be empty when the - <code>Document</code> object is created. - - <p>Objects implementing the <code><a href="#window">Window</a></code> - interface must also implement the <code>EventTarget</code> interface. - - <p class=note><code><a href="#window">Window</a></code> objects also <a - href="#get" title=dom-item>have an implicit [[Get]] method</a> which - returns <span>nested browsing contexts</span>. - - <h4 id=security1><span class=secno>4.2.1. </span>Security</h4> - - <p>User agents must raise a <a href="#security8">security exception</a> - whenever any of the members of a <code><a href="#window">Window</a></code> - object are accessed by scripts whose <a href="#origin0">origin</a> is not - the same as the <code><a href="#window">Window</a></code> object's <a - href="#browsing0">browsing context</a>'s <a href="#active">active - document</a>'s origin, with the following exceptions: - - <ul> - <li>The <code title=dom-location><a href="#location1">location</a></code> - object - </ul> - - <p>User agents must not allow scripts to override the <code - title=dom-location><a href="#location1">location</a></code> object's - setter. - - <h4 id=constructors><span class=secno>4.2.2. </span>Constructors</h4> - - <p>All <code><a href="#window">Window</a></code> objects must provide the - following constructors: - - <dl> - <dt><dfn id=audio2 title=dom-audio><code>Audio()</code></dfn> - - <dt><dfn id=audio3 title=dom-audio-s><code>Audio(<var - title="">src</var>)</code></dfn> - - <dd> - <p>When invoked as constructors, these must return a new <code><a - href="#htmlaudioelement">HTMLAudioElement</a></code> object (a new - <code><a href="#audio1">audio</a></code> element). If the <var - title=src>src</var> argument is present, the object created must have - its <code title=dom-media-src><a href="#src6">src</a></code> content - attribute set to the provided value. - - <dt><dfn id=image0 title=dom-image><code>Image()</code></dfn> - - <dt><dfn id=imagein title=dom-image-w><code>Image(in unsigned long <var - title="">w</var>)</code></dfn> - - <dt><dfn id=imagein0 title=dom-image-wh><code>Image(in unsigned long <var - title="">w</var>, in unsigned long <var title="">h</var>)</code></dfn> - - <dd> - <p>When invoked as corstructors, these must return a new <code><a - href="#htmlimageelement">HTMLImageElement</a></code> object (a new - <code><a href="#img">img</a></code> element). If the <var - title="">h</var> argument is present, the new object's <code - title=attr-img-height><a href="#height">height</a></code> content - attribute must be set to <var title="">h</var>. If the <var - title="">w</var> argument is present, the new object's <code - title=attr-img-width><a href="#width">width</a></code> content attribute - must be set to <var title="">w</var>. - - <dt><dfn id=option title=dom-option><code>Option()</code></dfn> - - <dt><dfn id=optionin title=dom-option-n><code>Option(in DOMString <var - title="">name</var>)</code></dfn> - - <dt><dfn id=optionin0 title=dom-option-nv><code>Option(in DOMString <var - title="">name</var>, in DOMString <var title="">value</var>)</code></dfn> - - <dd> - <p>When invoked as constructors, these must return a new - <code>HTMLOptionElement</code> object (a new <code>option</code> - element). <span class=big-issue>need to define argument - processing</span> - </dl> - - <p class=big-issue>And when constructors are invoked but without using the - constructor syntax...? - - <h4 id=apis-for><span class=secno>4.2.3. </span>APIs for creating and - navigating browsing contexts by name</h4> - - <p>The <dfn id=open2 title=dom-open><code>open()</code></dfn> method on - <code><a href="#window">Window</a></code> objects provides a mechanism for - <a href="#navigate" title=navigate>navigating</a> an existing <a - href="#browsing0">browsing context</a> or opening and navigating an <a - href="#auxiliary0">auxiliary browsing context</a>. - - <p>The method has four arguments, though they are all optional. - - <p>The first argument, <var title="">url</var>, gives a URI (or IRI) for a - page to load in the browsing context. If no arguments are provided, then - the <var title="">url</var> argument defaults to - "<code>about:blank</code><!-- XXX xref -->". The argument must be resolved - to an absolute URI by <span class=big-issue>...</span> - - <p>The second argument, <var title="">target</var>, specifies the <a - href="#browsing1" title="browsing context name">name</a> of the browsing - context that is to be navigated. It must be a <a href="#valid8">valid - browsing context name</a>. If fewer than two arguments are provided, then - the <var title="">name</var> argument defaults to the value - "<code>_blank</code>". - - <p>The third argument, <var title="">features</var>, has no effect and is - supported for historical reasons only. - - <p>The fourth argument, <var title="">replace</var>, specifies whether or - not the new page will <a href="#replacement" title="replacement - enabled">replace</a> the page currently loaded in the browsing context, - when <var title="">target</var> identifies an existing browsing context - (as opposed to leaving the current page in the browsing context's <a - href="#session">session history</a>). When three or fewer arguments are - provided, <var title="">replace</var> defaults to false. - - <p>When the method is invoked, the user agent must first select a <a - href="#browsing0">browsing context</a> to navigate by applying <a - href="#the-rules">the rules for chosing a browsing context given a - browsing context name</a> using the <var title="">target</var> argument as - the name and the <a href="#browsing0">browsing context</a> of the script - as the context in which the algorithm is executed, unless the user has - indicated a preference, in which case the browsing context to navigate may - instead be the one indicated by the user. - - <p class=example>For example, suppose there is a user agent that supports - control-clicking a link to open it in a new tab. If a user clicks in that - user agent on an element whose <code title=handler-onclick><a - href="#onclick">onclick</a></code> handler uses the <code - title=dom-open><a href="#open2">window.open()</a></code> API to open a - page in an iframe, but, while doing so, holds the control key down, the - user agent could override the selection of the target browsing context to - instead target a new tab. - - <p>Then, the user agent must <a href="#navigate">navigate</a> the selected - <a href="#browsing0">browsing context</a> to the URI given in <var - title="">url</var>. If the <var title="">replace</var> is true, then <a - href="#replacement" title="replacement enabled">replacement must be - enabled</a>; otherwise, it must not be enabled unless the <a - href="#browsing0">browsing context</a> was just created as part of the <a - href="#the-rules">the rules for chosing a browsing context given a - browsing context name</a>. - - <p>The <dfn id=name3 title=dom-name><code>name</code></dfn> attribute of - the <code><a href="#window">Window</a></code> object must, on getting, - return the current name of the <a href="#browsing0">browsing context</a>, - and, on setting, set the name of the <a href="#browsing0">browsing - context</a> to the new value. - - <p class=note>The name <a href="#resetBCName">gets reset</a> when the - browsing context is navigated to another domain. - - <h4 id=accessing><span class=secno>4.2.4. </span>Accessing other browsing - contexts</h4> - - <p>In ECMAScript implementations, objects that implement the <code><a - href="#window">Window</a></code> interface must have a <dfn id=get - title=dom-item>[[Get]]</dfn> method that, when invoked with a property - name that is a number <var title="">i</var>, returns the <var - title="">i</var>th <a href="#child">child browsing context</a> of the <a - href="#active" title="active document">active</a> <code>Document</code>, - sorted in document order of the elements nesting those browsing contexts. - - <p>The <dfn id=length5 title=dom-length><code>length</code></dfn> DOM - attribute on the <code><a href="#window">Window</a></code> interface must - return the number of <a href="#child" title="child browsing context">child - browsing contexts</a> of the <a href="#active" title="active - document">active</a> <code>Document</code>. - - <h3 id=history><span class=secno>4.3. </span>Session history and navigation</h3> - - <h4 id=the-session><span class=secno>4.3.1. </span>The session history of - browsing contexts</h4> - - <p>The sequence of <code>Document</code>s in a <a - href="#browsing0">browsing context</a> is its <dfn id=session>session - history</dfn>. - - <p><code><a href="#history1">History</a></code> objects provide a - representation of the pages in the session history of <a href="#browsing0" - title="browsing context">browsing contexts</a>. Each browsing context has - a distinct session history. - - <p>Each <code>Document</code> object in a browsing context's session - history is associated with a unique instance of the <code><a - href="#history1">History</a></code> object, although they all must model - the same underlying session history. - - <p>The <dfn id=history0 title=dom-history><code>history</code></dfn> - attribute of the <code><a href="#window">Window</a></code> interface must - return the object implementing the <code><a - href="#history1">History</a></code> interface for that <code><a - href="#window">Window</a></code> object's <a href="#active">active - document</a>. - - <p><code><a href="#history1">History</a></code> objects represent their <a - href="#browsing0">browsing context</a>'s session history as a flat list of - URIs and <a href="#state" title="state object">state objects</a>. (This - does not imply that the UI need be linear. See the <a - href="#history-notes">notes below</a>.) - - <p>Typically, the history list will consist of only URIs. However, a page - can <a href="#pushstate" title=dom-history-pushState>add</a> <dfn id=state - title="state object">state objects</dfn> between its entry in the session - history and the next ("forward") entry. These are then <a href="#popstate" - title=event-popstate>returned to the script</a> when the user (or script) - goes back in the history, thus enabling authors to use the "navigation" - metaphor even in one-page applications. - - <p>Entries that consist of <a href="#state" title="state object">state - objects</a> share the same <code>Document</code> as the entry for the URI - itself. Contiguous entries that differ just by fragment identifier must - also share the same <code>Document</code>. - - <p class=note>All entries that share the same <code>Document</code> (and - that are therefore merely different states of one particular document) are - contiguous by definition. - - <p>At any point, one of the entries in the session history is the <dfn - id=current0>current entry</dfn>. This is the entry representing the <a - href="#active">active document</a> of the <a href="#browsing0">browsing - context</a>. The <a href="#current0">current entry</a> is usually an entry - for the <a href="#href5" title=dom-location-href>location</a> of the - <code>Document</code>. However, it can also be one of the entries for <a - href="#state" title="state object">state objects</a> added to the history - by that document. - - <p>User agents may <dfn id=discard>discard</dfn> the DOMs of entries other - than the <a href="#current0">current entry</a> that are not referenced - from any script, reloading the pages afresh when the user or script - navigates back to such pages. This specification does not specify when - user agents should discard pages' DOMs and when they should cache them. - See the section on the <code title=event-load><a - href="#load0">load</a></code> and <code title=event-unload>unload</code> - events for more details.</p> - <!-- XXX crossref! --> - - <p>Entries that have had their DOM discarded must, for the purposes of the - algorithms given below, act as if they had not. When the user or script - navigates back or forwards to a page which has no in-memory DOM objects, - any other entries that shared the same <code>Document</code> object with - it must share the new object as well. - - <p>When a user agent discards the DOM from an entry in the session history, - it must also discard all the entries from the first state object entry for - that <code>Document</code> object up to and including the last entry for - that <code>Document</code> object (including any non-state-object entries - in that range, such as entries where the user navigated using fragment - identifiers). These entries are not recreated if the user or script - navigates back to the page. If there are no state object entries for that - <code>Document</code> object then no entries are removed. - - <h4 id=the-history><span class=secno>4.3.2. </span>The <code><a - href="#history1">History</a></code> interface</h4> - - <pre class=idl>interface <dfn id=history1>History</dfn> { - readonly attribute long <a href="#length6" title=dom-history-length>length</a>; - void <a href="#godelta" title=dom-history-go>go</a>(in long delta); - void <a href="#go" title=dom-history-go-0>go</a>(); - void <a href="#back" title=dom-history-back>back</a>(); - void <a href="#forward" title=dom-history-forward>forward</a>(); - void <a href="#pushstate" title=dom-history-pushState>pushState</a>(in DOMObject data); - void <a href="#clearstate" title=dom-history-clearState>clearState</a>(); -};</pre> - - <p>The <dfn id=length6 title=dom-history-length><code>length</code></dfn> - attribute of the <code><a href="#history1">History</a></code> interface - must return the number of entries in this <a href="#session">session - history</a>. - - <p>The actual entries are not accessible from script. - - <p>The <dfn id=godelta title=dom-history-go><code>go(<var - title="">delta</var>)</code></dfn> method causes the UA to move the number - of steps specified by <var title="">delta</var> in the session history. - - <p>If the index of the <a href="#current0">current entry</a> plus <var - title="">delta</var> is less than zero or greater than or equal to the <a - href="#length6" title=dom-history-length>number of items in the session - history</a>, then the user agent must do nothing. - - <p>If the <var title="">delta</var> is zero, then the user agent must act - as if the <code title=dom-location-reload>location.reload()</code> method - was called instead. - - <p>Otherwise, the user agent must cause the current <a - href="#browsing0">browsing context</a> to <a href="#traverse">traverse the - history</a> to the specified entry, as described below. The <dfn - id=specified>specified entry</dfn> is the one whose index equals the index - of the <a href="#current0">current entry</a> plus <var - title="">delta</var>. - - <p>When a user agent is required to <dfn id=traverse>traverse the - history</dfn> to a specified entry, the user agent must act as follows: - - <ol> - <li>If there is no longer a <code>Document</code> object for the entry in - question, the user agent must <a href="#navigate">navigate</a> the - browsing context to the location for that entry to preform an <a - href="#entry">entry update</a> of that entry, and abort these steps. The - "<a href="#navigate">navigate</a>" algorithm reinvokes this "traverse" - algorithm to complete the traversal, at which point there <em>is</em> a - <code>Document</code> object and so this step gets skipped. - - <li> - <p>If appropriate, update the <a href="#current0">current entry</a> in - the <a href="#browsing0">browsing context</a>'s <code>Document</code> - object's <code><a href="#history1">History</a></code> object to reflect - any state that the user agent wishes to persist.</p> - - <p class=example>For example, some user agents might want to persist the - scroll position, or the values of form controls.</p> - - <li> - <p>If there are any entries with state objects between the <a - href="#current0">current entry</a> and the <a - href="#specified">specified entry</a> (not inclusive), then the user - agent must iterate through every entry between the current entry and the - specified entry, starting with the entry closest to the current entry, - and ending with the one closest to the specified entry. For each entry, - if the entry is a state object, the user agent must <a - href="#activating0">activate the state object</a>. - - <li> - <p>If the <a href="#specified">specified entry</a> has a different - <code>Document</code> object than the <a href="#current0">current - entry</a> then the user agent must follow the following substeps:</p> - - <ol> - <li>The user agent must move any properties that have been added to the - browsing context's default view's <code><a - href="#window">Window</a></code> object to the <a href="#active">active - document</a>'s <code>Document</code>'s <a href="#list-of2">list of - added properties</a>. - - <li>If the browsing context is a <a href="#top-level">top-level browsing - context</a> (and not an <a href="#auxiliary0">auxiliary browsing - context</a>), and the <a href="#origin0">origin</a> of the - <code>Document</code> of the <a href="#specified">specified entry</a> - is not the same as the <a href="#origin0">origin</a> of the - <code>Document</code> of the <a href="#current0">current entry</a>, - then the following sub-sub-steps must be run: - <ol> - <li>The current <a href="#browsing1">browsing context name</a> must be - stored with all the entries in the history that are associated with - <code>Document</code> objects with the same <a - href="#origin0">origin</a> as the <a href="#active">active - document</a> <em>and</em> that are contiguous with the <a - href="#current0">current entry</a>. - - <li id=resetBCName>The browsing context's <a - href="#browsing1">browsing context name</a> must be unset. - </ol> - - <li>The user agent must make the <a href="#specified">specified - entry</a>'s <code>Document</code> object the <a href="#active">active - document</a> of the <a href="#browsing0">browsing context</a>. - - <li>If the <a href="#specified">specified entry</a> has a <a - href="#browsing1">browsing context name</a> stored with it, then the - following sub-sub-steps must be run: - <ol> - <li>The browsing context's <a href="#browsing1">browsing context - name</a> must be set to the name stored with the specified entry. - - <li>Any <a href="#browsing1">browsing context name</a> stored with the - entries in the history that are associated with <code>Document</code> - objects with the same <a href="#origin0">origin</a> as the new <a - href="#active">active document</a>, and that are contiguous with the - specified entry, must be cleared. - </ol> - - <li>The user agent must move any properties that have been added to the - <a href="#active">active document</a>'s <code>Document</code>'s <a - href="#list-of2">list of added properties</a> to browsing context's - default view's <code><a href="#window">Window</a></code> object. - </ol> - - <li> - <p>If the specified entry is a state object, the user agent must <a - href="#activating0" title="activate the state object">activate that - state object</a>. - - <li> - <p>User agents may also update other aspects of the document view when - the location changes in this way, for instance the scroll position, - values of form fields, etc. - - <li> - <p>The <a href="#current0">current entry</a> is now the <a - href="#specified">specified entry</a>. - </ol> - - <p class=big-issue>how does the changing of the global attributes affect - .watch() when seen from other Windows? - - <p>When the user navigates through a <a href="#browsing0">browsing - context</a>, e.g. using a browser's back and forward buttons, the user - agent must translate this action into the equivalent invocations of the - <code title=dom-history-go><a href="#godelta">history.go(<var - title="">delta</var>)</a></code> method on the various affected <code - title=dom-window><a href="#window0">window</a></code> objects. - - <p>Some of the other members of the <code><a - href="#history1">History</a></code> interface are defined in terms of the - <code title=dom-history-go><a href="#godelta">go()</a></code> method, as - follows: - - <table> - <tbody> - <tr> - <th>Member - - <th>Definition - - <tr> - <td><dfn id=go title=dom-history-go-0><code>go()</code></dfn> - - <td>Must do the same as <code title=dom-history-go><a - href="#godelta">go(0)</a></code> - - <tr> - <td><dfn id=back title=dom-history-back><code>back()</code></dfn> - - <td>Must do the same as <code title=dom-history-go><a - href="#godelta">go(-1)</a></code> - - <tr> - <td><dfn id=forward - title=dom-history-forward><code>forward()</code></dfn> - - <td>Must do the same as <code title=dom-history-go><a - href="#godelta">go(1)</a></code> - </table> - - <p>The <dfn id=pushstate title=dom-history-pushState><code>pushState(<var - title="">data</var>)</code></dfn> method adds a state object to the - history. - - <p>When this method is invoked, the user agent must first remove from the - <a href="#session">session history</a> any entries for that - <code>Document</code> from the entry after the <a href="#current0">current - entry</a> up to the last entry in the session history that references the - same <code>Document</code> object, if any. If the <a - href="#current0">current entry</a> is the last entry in the session - history, or if there are no entries after the <a href="#current0">current - entry</a> that reference the same <code>Document</code> object, then no - entries are removed. - - <p>Then, the user agent must add a state object entry to the session - history, after the <a href="#current0">current entry</a>, with the - specified <var title="">data</var> as the state object. - - <p>Finally, the user agent must update the <a href="#current0">current - entry</a> to be the this newly added entry. - - <p class=big-issue>There has been a suggestion that pushState() should take - a URI and a string; the URI to allow for the page to be bookmarked, and - the string to allow the UA to give the page a meaningful title in the - history state, if it shows history state.</p> - <!-- XXX could have four variants of pushState to allow - with/without URI and with/without title. Or maybe URI only makes - sense if there is a title. --> - - <p>User agents may limit the number of state objects added to the session - history per page. If a page hits the UA-defined limit, user agents must - remove the entry immediately after the first entry for that - <code>Document</code> object in the session history after having added the - new entry. (Thus the state history acts as a FIFO buffer for eviction, but - as a LIFO buffer for navigation.) - - <p>The <dfn id=clearstate - title=dom-history-clearState><code>clearState()</code></dfn> method - removes all the state objects for the <code>Document</code> object from - the session history. - - <p>When this method is invoked, the user agent must remove from the session - history all the entries from the first state object entry for that - <code>Document</code> object up to the last entry that references that - same <code>Document</code> object, if any. - - <p>Then, if the <a href="#current0">current entry</a> was removed in the - previous step, the <a href="#current0">current entry</a> must be set to - the last entry for that <code>Document</code> object in the session - history. - - <h4 id=activating><span class=secno>4.3.3. </span><dfn id=activating0 - title="activate the state object">Activating state objects</dfn></h4> - - <p>When a state object in the session history is activated (which happens - in the cases described above), the user agent must fire a <dfn id=popstate - title=event-popstate><code>popstate</code></dfn> event in no namespace on - the <a href="#the-body0">the body element</a> using the <code><a - href="#popstateevent">PopStateEvent</a></code> interface, with the state - object in the <code title=dom-PopStateEvent-state><a - href="#state0">state</a></code> attribute. This event bubbles but is not - cancelable and has no default action.</p> - <!-- XXX onpopstate should be defined somewhere --> - - <pre - class=idl>interface <dfn id=popstateevent>PopStateEvent</dfn> : Event { - readonly attribute DOMObject <a href="#state0" title=dom-PopStateEvent-state>state</a>; - void <a href="#initpopstateevent" title=dom-PopStateEvent-initPopStateEvent>initPopStateEvent</a>(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMObject statetArg); - void <a href="#initpopstateeventns" title=dom-PopStateEvent-initPopStateEventNS>initPopStateEventNS</a>(in DOMString namespaceURIArg, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMObject stateArg); -};</pre> - - <p>The <dfn id=initpopstateevent - title=dom-PopStateEvent-initPopStateEvent><code>initPopStateEvent()</code></dfn> - and <dfn id=initpopstateeventns - title=dom-PopStateEvent-initPopStateEventNS><code>initPopStateEventNS()</code></dfn> - methods must initialise the event in a manner analogous to the - similarly-named methods in the DOM3 Events interfaces. <a - href="#refsDOM3EVENTS">[DOM3EVENTS]</a> - - <p>The <dfn id=state0 - title=dom-PopStateEvent-state><code>state</code></dfn> attribute - represents the context information for the event. - - <p class=big-issue>Should we coalesce these events if they occur while the - page is away? (e.g. during traversal -- see above) - - <h4 id=the-location><span class=secno>4.3.4. </span>The <code><a - href="#location2">Location</a></code> interface</h4> - - <p>Each <code>Document</code> object in a browsing context's session - history is associated with a unique instance of a <code><a - href="#location2">Location</a></code> object. - - <p>The <dfn id=location0 - title=dom-document-location><code>location</code></dfn> attribute of the - <code><a href="#htmldocument">HTMLDocument</a></code> interface must - return the <code><a href="#location2">Location</a></code> object for that - <code>Document</code> object. - - <p>The <dfn id=location1 title=dom-location><code>location</code></dfn> - attribute of the <code><a href="#window">Window</a></code> interface must - return the <code><a href="#location2">Location</a></code> object for that - <code><a href="#window">Window</a></code> object's <a - href="#active">active document</a>. - - <p><code><a href="#location2">Location</a></code> objects provide a - representation of the URI of their document, and allow the <a - href="#current0">current entry</a> of the <a href="#browsing0">browsing - context</a>'s session history to be changed, by adding or replacing - entries in the <code title=dom-history><a - href="#history0">history</a></code> object. - - <pre class=idl>interface <dfn id=location2>Location</dfn> { - readonly attribute DOMString <a href="#href5" title=dom-location-href>href</a>; - void <a href="#assign" title=dom-location-assign>assign</a>(in DOMString url); - void <a href="#replace" title=dom-location-replace>replace</a>(in DOMString url); - void <span title=dom-location-reload>reload</span>(); - - // <a href="#uri-decomposition">URI decomposition attributes</a> <!-- blame brendan for these "innovative" names --> - readonly attribute DOMString <a href="#protocol" title=dom-location-protocol>protocol</a>; - readonly attribute DOMString <a href="#host" title=dom-location-host>host</a>; - readonly attribute DOMString <a href="#hostname" title=dom-location-hostname>hostname</a>; - readonly attribute DOMString <a href="#port" title=dom-location-port>port</a>; - readonly attribute DOMString <a href="#pathname" title=dom-location-pathname>pathname</a>; - readonly attribute DOMString <a href="#search" title=dom-location-search>search</a>; - readonly attribute DOMString <a href="#hash" title=dom-location-hash>hash</a>; -};</pre> - - <p>In the ECMAScript DOM binding, objects implementing this interface must - stringify to the same value as the <code title=dom-location-href><a - href="#href5">href</a></code> attribute. - - <p id=settingLocation>In the ECMAScript DOM binding, the <code - title="">location</code> members of the <code><a - href="#htmldocument">HTMLDocument</a></code> and <code><a - href="#window">Window</a></code> interfaces behave as if they had a - setter: user agents must treats attempts to set these <code - title="">location</code> attribute as attempts at setting the <code - title=dom-location-href><a href="#href5">href</a></code> attribute of the - relevant <code><a href="#location2">Location</a></code> object instead. - - <p>The <dfn id=href5 title=dom-location-href><code>href</code></dfn> - attribute returns the address of the page represented by the associated - <code>Document</code> object, as an absolute IRI reference. - - <p>On setting, <!--XXX Mozilla does this, but IE doesn't. What - should we do?: the behaviour depends on the context in which the - script that set the attribute is running. If the script ran as the - direct result of the execution of a <code>script</code> element in - the document represented by the <code>Location</code> object's - associated <code>Document</code> object, then the user agent must - act as if the <code title="dom-location-replace">replace()</code> - method had been called with the new value as its - argument. Otherwise,--> - the user agent must act as if the <code title=dom-location-assign><a - href="#assign">assign()</a></code> method had been called with the new - value as its argument.</p> - <!-- XXX may wish to allow - replace instead as a UI improvement --> - - <p>When the <dfn id=assign title=dom-location-assign><code>assign(<var - title="">url</var>)</code></dfn> method is invoked, the UA must <a - href="#navigate">navigate</a> the <a href="#browsing0">browsing - context</a> to the specified <var title="">url</var>. - - <p>When the <dfn id=replace title=dom-location-replace><code>replace(<var - title="">url</var>)</code></dfn> method is invoked, the UA must <a - href="#navigate">navigate</a> to the specified <var title="">url</var> - with <a href="#replacement">replacement enabled</a>. - - <p>Relative <var title="">url</var> arguments for <code - title=dom-location-assign><a href="#assign">assign()</a></code> and <code - title=dom-location-replace><a href="#replace">replace()</a></code> must be - resolved relative to the base URI of the script that made the method call.</p> - <!-- XXX what about if the base URI is data: or - javascript: or about: or something else without a way to resolve - base URIs? --> - - <p>The <code><a href="#location2">Location</a></code> interface also has - the complement of <a href="#uri-decomposition">URI decomposition - attributes</a>, <dfn id=protocol - title=dom-location-protocol><code>protocol</code></dfn>, <dfn id=host - title=dom-location-host><code>host</code></dfn>, <dfn id=port - title=dom-location-port><code>port</code></dfn>, <dfn id=hostname - title=dom-location-hostname><code>hostname</code></dfn>, <dfn id=pathname - title=dom-location-pathname><code>pathname</code></dfn>, <dfn id=search - title=dom-location-search><code>search</code></dfn>, and <dfn id=hash - title=dom-location-hash><code>hash</code></dfn>. These must follow the - rules given for URI decomposition attributes, with the <a href="#input" - title=concept-uda-input>input</a> being the address of the page - represented by the associated <code>Document</code> object, as an absolute - IRI reference (same as the <code title=dom-location-href><a - href="#href5">href</a></code> attribute), and the <a href="#common3" - title=concept-uda-setter>common setter action</a> being the same as - setting the <code title=dom-location-href><a href="#href5">href</a></code> - attribute to the new output value.</p> - <!-- - <dfn title="dom-location-reload"><code>reload()</code></dfn> - reload during resize event: - redisplay the current page (without reloading it). This - theoretically would have no effect but in practice can be useful to - work around rendering bugs. - -reload on shared Document updates all of them - -user reload must be equivalent to .reload() ---> - - <h5 id=security2><span class=secno>4.3.4.1. </span>Security</h5> - - <p>User agents must raise a <a href="#security8">security exception</a> - whenever any of the members of a <code><a - href="#location2">Location</a></code> object are accessed by scripts whose - <a href="#origin0">origin</a> is not the same as the <code><a - href="#location2">Location</a></code> object's associated - <code>Document</code>'s origin, with the following exceptions: - - <ul> - <li>The <code title=dom-location-href><a href="#href5">href</a></code> - setter - </ul> - - <p>User agents must not allow scripts to override the <code - title=dom-location-href><a href="#href5">href</a></code> attribute's - setter. - - <h4 id=history-notes><span class=secno>4.3.5. </span>Implementation notes - for session history</h4> - - <p><em>This section is non-normative.</em> - - <p>The <code><a href="#history1">History</a></code> interface is not meant - to place restrictions on how implementations represent the session history - to the user. - - <p>For example, session history could be implemented in a tree-like manner, - with each page having multiple "forward" pages. This specification doesn't - define how the linear list of pages in the <code title=dom-history><a - href="#history0">history</a></code> object are derived from the actual - session history as seen from the user's perspective. - - <p>Similarly, a page containing two <code><a - href="#iframe">iframe</a></code>s has a <code title=dom-history><a - href="#history0">history</a></code> object distinct from the <code><a - href="#iframe">iframe</a></code>s' <code title=dom-history><a - href="#history0">history</a></code> objects, despite the fact that typical - Web browsers present the user with just one "Back" button, with a session - history that interleaves the navigation of the two inner frames and the - outer page. - - <p><strong>Security:</strong> It is suggested that to avoid letting a page - "hijack" the history navigation facilities of a UA by abusing <code - title=dom-history-pushState><a href="#pushstate">pushState()</a></code>, - the UA provide the user with a way to jump back to the previous page - (rather than just going back to the previous state). For example, the back - button could have a drop down showing just the pages in the session - history, and not showing any of the states. Similarly, an aural browser - could have two "back" commands, one that goes back to the previous state, - and one that jumps straight back to the previous page. - - <p>In addition, a user agent could ignore calls to <code - title=dom-history-pushState><a href="#pushstate">pushState()</a></code> - that are invoked on a timer, or from event handlers that do not represent - a clear user action, or that are invoked in rapid succession. - - <h3 id=links><span class=secno>4.4. </span>Links</h3> - - <h4 id=hyperlink><span class=secno>4.4.1. </span>Hyperlink elements</h4> - - <p>The <code><a href="#a">a</a></code>, <code><a - href="#area">area</a></code>, and <code><a href="#link">link</a></code> - elements can, in certain situations described in the definitions of those - elements, represent <dfn id=hyperlinks title=hyperlink>hyperlinks</dfn>. - - <p>The <dfn id=href6 title=attr-hyperlink-href><code>href</code></dfn> - attribute on a hyperlink element must have a value that is a URI (or IRI). - This URI is the <em>destination resource</em> of the hyperlink. - - <div class=note> - <p>The <code title=attr-hyperlink-href><a href="#href6">href</a></code> - attribute on <code><a href="#a">a</a></code> and <code><a - href="#area">area</a></code> elements is not required; when those - elements do not have <code title=attr-hyperlink-href><a - href="#href6">href</a></code> attributes they do not represent - hyperlinks.</p> - - <p>The <code title=attr-link-href><a href="#href1">href</a></code> - attribute on the <code><a href="#link">link</a></code> element - <em>is</em> required, but whether a <code><a href="#link">link</a></code> - element represents a hyperlink or not depends on the value of the <code - title=attr-link-rel><a href="#rel">rel</a></code> attribute of that - element.</p> - </div> - - <p>The <dfn id=target3 - title=attr-hyperlink-target><code>target</code></dfn> attribute, if - present, must be a <a href="#valid8">valid browsing context name</a>. User - agents use this name when <a href="#following0">following hyperlinks</a>. - - <p>The <dfn id=ping title=attr-hyperlink-ping><code>ping</code></dfn> - attribute, if present, gives the URIs of the resources that are interested - in being notified if the user follows the hyperlink. The value must be a - space separated list of one or more URIs (or IRIs). The value is used by - the user agent when <a href="#following0">following hyperlinks</a>. - - <p>For <code><a href="#a">a</a></code> and <code><a - href="#area">area</a></code> elements that represent hyperlinks, the - relationship between the document containing the hyperlink and the - destination resource indicated by the hyperlink is given by the value of - the element's <dfn id=rel3 title=attr-hyperlink-rel><code>rel</code></dfn> - attribute, which must be an <a href="#unordered">unordered set of - space-separated tokens</a>. The <a href="#linkTypes">allowed values and - their meanings</a> are defined below. The <code - title=attr-hyperlink-rel><a href="#rel3">rel</a></code> attribute has no - default value. If the attribute is omitted or if none of the values in the - attribute are recognised by the UA, then the document has no particular - relationship with the destination resource other than there being a - hyperlink between the two. - - <p>The <dfn id=media12 title=attr-hyperlink-media><code>media</code></dfn> - attribute describes for which media the target document was designed. It - is purely advisory. The value must be a valid media query. <a - href="#refsMQ">[MQ]</a> The default, if the <code - title=attr-hyperlink-media><a href="#media12">media</a></code> attribute - is omitted or has an invalid value, is <code>all</code>. - - <p>The <dfn id=hreflang3 - title=attr-hyperlink-hreflang><code>hreflang</code></dfn> attribute on - hyperlink elements, if present, gives the language of the linked resource. - It is purely advisory. The value must be a valid RFC 3066 language code. - <a href="#refsRFC3066">[RFC3066]</a> User agents must not consider this - attribute authoritative — upon fetching the resource, user agents - must only use language information associated with the resource to - determine its language, not metadata included in the link to the resource. - - <p>The <dfn id=type17 title=attr-hyperlink-type><code>type</code></dfn> - attribute, if present, gives the MIME type of the linked resource. It is - purely advisory. The value must be a valid MIME type, optionally with - parameters. <a href="#refsRFC2046">[RFC2046]</a> User agents must not - consider the <code title=attr-hyperlink-type><a - href="#type17">type</a></code> attribute authoritative — upon - fetching the resource, user agents must not use metadata included in the - link to the resource to determine its type. - - <h4 id=following><span class=secno>4.4.2. </span><dfn - id=following0>Following hyperlinks</dfn></h4> - - <p>When a user <em>follows a hyperlink</em>, the user agent must <a - href="#navigate">navigate</a> a <a href="#browsing0">browsing context</a> - to the URI of the hyperlink. - - <p>The URI of the hyperlink is URI given by resolving the the <code - title=attr-hyperlink-href><a href="#href6">href</a></code> attribute of - that hyperlink relative to the hyperlink's element. In the case of - server-side image maps, the URI of the hyperlink must further have its - <var><a href="#hyperlink2">hyperlink suffix</a></var> appended to it. - - <p>If the user indicated a specific browsing context when following the - hyperlink, or if the user agent is configured to follow hyperlinks by - navigating a particular browsing context, then that must be the browsing - context that is navigated. - - <p>Otherwise, if the hyperlink element is an <code><a - href="#a">a</a></code> or <code><a href="#area">area</a></code> element - that has a <code title=attr-hyperlink-target><a - href="#target3">target</a></code> attribute, then the browsing context - that is navigated must be chosen by applying <a href="#the-rules">the - rules for chosing a browsing context given a browsing context name</a>, - using the value of the <code title=attr-hyperlink-target><a - href="#target3">target</a></code> attribute as the browsing context name. - If these rules result in the creation of a new <a - href="#browsing0">browsing context</a>, it must be navigated with <a - href="#replacement">replacement enabled</a>. - - <p>Otherwise, if the hyperlink element is a <a href="#sidebar0" - title=rel-sidebar-hyperlink>sidebar hyperlink</a> and the user agent - implements a feature that can be considered a secondary browsing context, - such a secondary browsing context may be selected as the browsing context - to be navigated. - - <p>Otherwise, if the hyperlink element is an <code><a - href="#a">a</a></code> or <code><a href="#area">area</a></code> element - with no <code title=attr-hyperlink-target><a - href="#target3">target</a></code> attribute, but one of the child nodes of - <a href="#the-head0">the <code>head</code> element</a> is a <code><a - href="#base">base</a></code> element with a <code - title=attr-base-target><a href="#target">target</a></code> attribute, then - the browsing context that is navigated must be chosen by applying <a - href="#the-rules">the rules for chosing a browsing context given a - browsing context name</a>, using the value of the <code - title=attr-base-target><a href="#target">target</a></code> attribute of - the first such <code><a href="#base">base</a></code> element as the - browsing context name. If these rules result in the creation of a new <a - href="#browsing0">browsing context</a>, it must be navigated with <a - href="#replacement">replacement enabled</a>. - - <p>Otherwise, the browsing context that must be navigated is the same - browsing context as the one which the hyperlink element itself is in. - - <h5 id=hyperlink0><span class=secno>4.4.2.1. </span>Hyperlink auditing</h5> - - <p>If an <code><a href="#a">a</a></code> or <code><a - href="#area">area</a></code> hyperlink element has a <code - title=attr-hyperlink-ping><a href="#ping">ping</a></code> attribute and - the user follows the hyperlink, the user agent must take the <code - title=attr-hyperlink-ping><a href="#ping">ping</a></code> attribute's - value, strip leading and trailing <a href="#space" title="space - character">spaces</a>, split the value on sequences of spaces, treat each - resulting part as a URI (resolving relative URIs according to element's - base URI) and then should send a request to each of the resulting URIs. - This may be done in parallel with the primary request, and is independent - of the result of that request. - - <p>User agents should allow the user to adjust this behaviour, for example - in conjunction with a setting that disables the sending of HTTP Referrer - headers. Based on the user's preferences, UAs may either <a - href="#ignored">ignore</a> the <code title=attr-hyperlink-ping><a - href="#ping">ping</a></code> attribute altogether, or selectively ignore - URIs in the list (e.g. ignoring any third-party URIs). - - <p>For URIs that are HTTP URIs, the requests must be performed using the - POST method (with an empty entity body in the request). User agents must - ignore any entity bodies returned in the responses, but must, unless - otherwise specified by the user, honour the HTTP headers — in - particular, HTTP cookie headers. <a href="#refsRFC2965">[RFC2965]</a> - - <p class=note>To save bandwidth, implementors might wish to consider - omitting optional headers such as <code>Accept</code> from these requests. - - <p>When the <code title=attr-hyperlink-ping><a href="#ping">ping</a></code> - attribute is present, user agents should clearly indicate to the user that - following the hyperlink will also cause secondary requests to be sent in - the background, possibly including listing the actual target URIs. - - <div class=note> - <p>The <code title=attr-hyperlink-ping><a href="#ping">ping</a></code> - attribute is redundant with pre-existing technologies like HTTP redirects - and JavaScript in allowing Web pages to track which off-site links are - most popular or allowing advertisers to track click-through rates.</p> - - <p>However, the <code title=attr-hyperlink-ping><a - href="#ping">ping</a></code> attribute provides these advantages to the - user over those alternatives:</p> - - <ul> - <li>It allows the user to see the final target URI unobscured. - - <li>It allows the UA to inform the user about the out-of-band - notifications. - - <li>It allows the paranoid user to disable the notifications without - losing the underlying link functionality. - - <li>It allows the UA to optimise the use of available network bandwidth - so that the target page loads faster. - </ul> - - <p>Thus, while it is possible to track users without this feature, authors - are encouraged to use the <code title=attr-hyperlink-ping><a - href="#ping">ping</a></code> attribute so that the user agent can improve - <!-- XXX optimise? --> the user experience.</p> - <!-- - XXX need a better way to end that sentence. It's what I mean, but - it sounds kooky. --> - </div> - - <h4 id=linkTypes><span class=secno>4.4.3. </span>Link types</h4> - - <p>The following table summarises the link types that are defined by this - specification. This table is non-normative; the actual definitions for the - link types are given in the next few sections. - - <p>In this section, the term <em>referenced document</em> refers to the - resource identified by the element representing the link, and the term - <em>current document</em> refers to the resource within which the element - representing the link finds itself. - - <p>To determine which link types apply to a <code><a - href="#link">link</a></code>, <code><a href="#a">a</a></code>, or <code><a - href="#area">area</a></code> element, the element's <code - title="">rel</code> attribute must be <a href="#split" title="split a - string on spaces">split on spaces</a>. The resulting tokens are the link - types that apply to that element. - - <table> - <thead> - <tr> - <th rowspan=2>Link type - - <th colspan=2>Effect on... - - <th rowspan=2>Brief description - - <tr> - <th><code><a href="#link">link</a></code> - - <th><code><a href="#a">a</a></code> and <code><a - href="#area">area</a></code> - - <tbody> - <tr> - <td><code title=rel-alternate><a href="#alternate">alternate</a></code></td> - <!-- second most used <link rel> value --> - - <td><a href="#hyperlink1" title="hyperlink link">Hyperlink</a> - - <td><a href="#hyperlinks">Hyperlink</a> - - <td>Gives alternate representations of the current document. - - <tr> - <td><code title=rel-archives><a href="#archives">archives</a></code> - - <td><a href="#hyperlink1" title="hyperlink link">Hyperlink</a> - - <td><a href="#hyperlinks">Hyperlink</a> - - <td>Provides a link to a collection of records, documents, or other - materials of historical interest. - - <tr> - <td><code title=rel-author><a href="#author">author</a></code> - - <td><a href="#hyperlink1" title="hyperlink link">Hyperlink</a> - - <td><a href="#hyperlinks">Hyperlink</a> - - <td>Gives a link to the current document's author. - - <tr> - <td><code title=rel-bookmark><a href="#bookmark">bookmark</a></code></td> - <!-- fourth most used <a rel> value --> - - <td><em>not allowed</em> - - <td><a href="#hyperlinks">Hyperlink</a> - - <td>Gives the permalink for the nearest ancestor section. - - <tr> - <td><code title=rel-contact><a href="#contact">contact</a></code></td> - <!-- 8th most used <a rel> value --> - - <td><a href="#hyperlink1" title="hyperlink link">Hyperlink</a> - - <td><a href="#hyperlinks">Hyperlink</a> - - <td>Gives a link to contact information for the current document. - - <tr> - <td><code title=rel-external><a href="#external">external</a></code></td> - <!-- fifth and sixth most used <a rel> value (sixth is "external nofollow") --> - - <td><em>not allowed</em> - - <td><a href="#hyperlinks">Hyperlink</a> - - <td>Indicates that the referenced document is not part of the same site - as the current document. - - <tr> - <td><code title=rel-feed><a href="#feed">feed</a></code> - - <td><a href="#hyperlink1" title="hyperlink link">Hyperlink</a> - - <td><a href="#hyperlinks">Hyperlink</a> - - <td>Gives the address of a syndication feed for the current document. - - <tr> - <td><code title=rel-first><a href="#first">first</a></code> - - <td><a href="#hyperlink1" title="hyperlink link">Hyperlink</a> - - <td><a href="#hyperlinks">Hyperlink</a> - - <td>Indicates that the current document is a part of a series, and that - the first document in the series is the referenced document. - - <tr> - <td><code title=rel-help><a href="#help">help</a></code> - - <td><a href="#hyperlink1" title="hyperlink link">Hyperlink</a> - - <td><a href="#hyperlinks">Hyperlink</a> - - <td>Provides a link to context-sensitive help. - - <tr> - <td><code title=rel-icon><a href="#icon3">icon</a></code></td> - <!-- link rel="shortcut icon" and its ilk are the fourth, sixth, and ninth most used values --> - - <td><a href="#links1" title="external resource link">External - Resource</a> - - <td><em>not allowed</em> - - <td>Imports an icon to represent the current document. - - <tr> - <td><code title=rel-index><a href="#index">index</a></code></td> - <!-- used more than "top" and "contents" on <link> (though on <a>, "contents" wins) --> - - <td><a href="#hyperlink1" title="hyperlink link">Hyperlink</a> - - <td><a href="#hyperlinks">Hyperlink</a> - - <td>Gives a link to the document that provides a table of contents or - index listing the current document. - - <tr> - <td><code title=rel-last><a href="#last">last</a></code> - - <td><a href="#hyperlink1" title="hyperlink link">Hyperlink</a> - - <td><a href="#hyperlinks">Hyperlink</a> - - <td>Indicates that the current document is a part of a series, and that - the last document in the series is the referenced document. - - <tr> - <td><code title=rel-license><a href="#license">license</a></code></td> - <!-- seventh most used <a rel> value --> - - <td><a href="#hyperlink1" title="hyperlink link">Hyperlink</a> - - <td><a href="#hyperlinks">Hyperlink</a> - - <td>Indicates that the current document is covered by the copyright - license described by the referenced document. - - <tr> - <td><code title=rel-next><a href="#next">next</a></code> - - <td><a href="#hyperlink1" title="hyperlink link">Hyperlink</a> - - <td><a href="#hyperlinks">Hyperlink</a> - - <td>Indicates that the current document is a part of a series, and that - the next document in the series is the referenced document. - - <tr> - <td><code title=rel-nofollow><a href="#nofollow">nofollow</a></code></td> - <!-- most used <a rel> value (and sixth most used is "external nofollow") --> - - <td><em>not allowed</em> - - <td><a href="#hyperlinks">Hyperlink</a> - - <td>Indicates that the current document's original author or publisher - does not endorse the referenced document. - - <tr> - <td><code title=rel-pingback><a href="#pingback">pingback</a></code> - - <td><a href="#links1" title="external resource link">External - Resource</a> - - <td><em>not allowed</em> - - <td>Gives the address of the pingback server that handles pingbacks to - the current document. - - <tr> - <td><code title=rel-prefetch><a href="#prefetch">prefetch</a></code> - - <td><a href="#links1" title="external resource link">External - Resource</a> - - <td><em>not allowed</em> - - <td>Specifies that the target resource should be pre-emptively cached. - - <tr> - <td><code title=rel-prev><a href="#prev">prev</a></code></td> - <!-- prev is used more than previous --> - - <td><a href="#hyperlink1" title="hyperlink link">Hyperlink</a> - - <td><a href="#hyperlinks">Hyperlink</a> - - <td>Indicates that the current document is a part of a series, and that - the previous document in the series is the referenced document. - - <tr> - <td><code title=rel-search><a href="#search0">search</a></code></td> - <!-- used quite a bit --> - - <td><a href="#hyperlink1" title="hyperlink link">Hyperlink</a> - - <td><a href="#hyperlinks">Hyperlink</a> - - <td>Gives a link to a resource that can be used to search through the - current document and its related pages. - - <tr> - <td><code title=rel-stylesheet><a - href="#stylesheet">stylesheet</a></code></td> - <!-- most commonly used <link rel> value, variants came in 7th, 8th, 12th, 17th... --> - - <td><a href="#links1" title="external resource link">External - Resource</a> - - <td><em>not allowed</em> - - <td>Imports a stylesheet. - - <tr> - <td><code title=rel-sidebar><a href="#sidebar">sidebar</a></code></td> - <!-- used quite a bit --> - - <td><a href="#hyperlink1" title="hyperlink link">Hyperlink</a> - - <td><a href="#hyperlinks">Hyperlink</a> - - <td>Specifies that the referenced document, if retrieved, is intended to - be shown in the browser's sidebar (if it has one). - - <tr> - <td><code title=rel-tag><a href="#tag">tag</a></code></td> - <!-- second and third most used <a rel> value (third is technically "category tag"). --> - - <td><a href="#hyperlink1" title="hyperlink link">Hyperlink</a> - - <td><a href="#hyperlinks">Hyperlink</a> - - <td>Gives a tag (identified by the given address) that applies to the - current document. - - <tr> - <td><code title=rel-up><a href="#up">up</a></code> - - <td><a href="#hyperlink1" title="hyperlink link">Hyperlink</a> - - <td><a href="#hyperlinks">Hyperlink</a> - - <td>Provides a link to a document giving the context for the current - document. - </table> - - <p>Some of the types described below list synonyms for these values. These - are to be handled as specified by user agents, but must not be used in - documents.</p> - <!--XXX - - issues for rel="", etc: - rel="alternate stylesheet" - rel="script" - rel="related" // see also - which relationship combinations are allowed - what multiple values might mean (multiple <a rel="top"> in the same document) - http://www.euronet.nl/~tekelenb/WWW/LINK/ - http://shift.freezope.org/konq_rellinks/development_html - http://hixie.ch/specs/html/link/001 - http://hixie.ch/specs/html/link/002 - http://www.hixie.ch/specs/html/metadata - what UAs are supposed to do with this - do something about http://microformats.org/wiki/rel-enclosure - -mpt says: -> "As with <a> elements, when <link> elements that use these relationships -> are present, UAs should render them. As with <a> elements, when <link> -> elements that use these relationships do not exist, UAs should not -> render them. UAs should not make <link> rendering any easier to hide -> than <a> rendering." - -for microformats (e.g. to refer to an hcard from an hcalendar): -rel=xref -<a> and <area> only -The href attribute's value must start with a '#' character. -Indicates an in-page cross-reference. For the purposes of data mining tools, the subtree rooted -at the first element with the given ID must be treated as if it was cloned and replaced the <a> element. - - --> - - <h5 id=link-type><span class=secno>4.4.3.1. </span>Link type "<dfn - id=alternate title=rel-alternate><code>alternate</code></dfn>"</h5> - - <p>The <code title=rel-alternate><a href="#alternate">alternate</a></code> - keyword may be used with <code><a href="#link">link</a></code>, <code><a - href="#a">a</a></code>, and <code><a href="#area">area</a></code> - elements. For <code><a href="#link">link</a></code> elements, if the <code - title=attr-link-rel><a href="#rel">rel</a></code> attribute does not also - contain the keyword <code title=rel-stylesheet><a - href="#stylesheet">stylesheet</a></code>, it creates a <a - href="#hyperlink1" title="hyperlink link">hyperlink</a>; but if it - <em>does</em> also contains the keyword <code title=rel-stylesheet><a - href="#stylesheet">stylesheet</a></code>, the <code title=rel-alternate><a - href="#alternate">alternate</a></code> keyword instead modifies the - meaning of the <code title=rel-stylesheet><a - href="#stylesheet">stylesheet</a></code> keyword in the way described for - that keyword, and the rest of this subsection doesn't apply. - - <p>The <code title=rel-alternate><a href="#alternate">alternate</a></code> - keyword indicates that the referenced document is an alternate - representation of the current document. - - <p>The nature of the referenced document is given by the <code - title=attr-hyperlink-media><a href="#media12">media</a></code>, <code - title=attr-hyperlink-hreflang><a href="#hreflang3">hreflang</a></code>, - and <code title=attr-hyperlink-type><a href="#type17">type</a></code> - attributes. - - <p>If the <code title=rel-alternate><a - href="#alternate">alternate</a></code> keyword is used with the <code - title=attr-hyperlink-media><a href="#media12">media</a></code> attribute, - it indicates that the referenced document is intended for use with the - media specified. - - <p>If the <code title=rel-alternate><a - href="#alternate">alternate</a></code> keyword is used with the <code - title=attr-hyperlink-hreflang><a href="#hreflang3">hreflang</a></code> - attribute, and that attribute's value differs from the <a - href="#root-element">root element</a>'s <a href="#language">language</a>, - it indicates that the referenced document is a translation. - - <p>If the <code title=rel-alternate><a - href="#alternate">alternate</a></code> keyword is used with the <code - title=attr-hyperlink-type><a href="#type17">type</a></code> attribute, it - indicates that the referenced document is a reformulation of the current - document in the specified format. - - <p>The <code title=attr-hyperlink-media><a - href="#media12">media</a></code>, <code title=attr-hyperlink-hreflang><a - href="#hreflang3">hreflang</a></code>, and <code - title=attr-hyperlink-type><a href="#type17">type</a></code> attributes can - be combined when specified with the <code title=rel-alternate><a - href="#alternate">alternate</a></code> keyword. - - <div class=example> - <p>For example, the following link is a French translation that uses the - PDF format:</p> - - <pre><link rel=alternate type=application/pdf hreflang=fr href=manual-fr></pre> - </div> - - <p>If the <code title=rel-alternate><a - href="#alternate">alternate</a></code> keyword is used with the <code - title=attr-hyperlink-type><a href="#type17">type</a></code> attribute set - to the value <code title="">application/rss+xml</code> or the value <code - title="">application/atom+xml</code>, then the user agent must treat the - link as it would if it had the <code title=rel-feed><a - href="#feed">feed</a></code> keyword specified as well. - - <p>The <code title=rel-alternate><a href="#alternate">alternate</a></code> - link relationship is transitive — that is, if a document links to - two other documents with the link type "<code title=rel-alternate><a - href="#alternate">alternate</a></code>", then, in addition to implying - that those documents are alternative representations of the first - document, it is also implying that those two documents are alternative - representations of each other. - - <h5 id=link-type0><span class=secno>4.4.3.2. </span>Link type "<dfn - id=archives title=rel-archives><code>archives</code></dfn>"</h5> - - <p>The <code title=rel-archives><a href="#archives">archives</a></code> - keyword may be used with <code><a href="#link">link</a></code>, <code><a - href="#a">a</a></code>, and <code><a href="#area">area</a></code> - elements. For <code><a href="#link">link</a></code> elements, it creates a - <a href="#hyperlink1" title="hyperlink link">hyperlink</a>. - - <p>The <code title=rel-archives><a href="#archives">archives</a></code> - keyword indicates that the referenced document describes a collection of - records, documents, or other materials of historical interest. - - <p class=example>A blog's index page could link to an index of the blog's - past posts with <code title="">rel="archives"</code>. - - <p><strong>Synonyms</strong>: For historical reasons, user agents must also - treat the keyword "<code title="">archive</code>" like the <code - title=rel-archives><a href="#archives">archives</a></code> keyword. - - <h5 id=link-type1><span class=secno>4.4.3.3. </span>Link type "<dfn - id=author title=rel-author><code>author</code></dfn>"</h5> - - <p>The <code title=rel-author><a href="#author">author</a></code> keyword - may be used with <code><a href="#link">link</a></code>, <code><a - href="#a">a</a></code>, and <code><a href="#area">area</a></code> - elements. For <code><a href="#link">link</a></code> elements, it creates a - <a href="#hyperlink1" title="hyperlink link">hyperlink</a>. - - <p>For <code><a href="#a">a</a></code> and <code><a - href="#area">area</a></code> elements, the <code title=rel-author><a - href="#author">author</a></code> keyword indicates that the referenced - document provides further information about the author of the section that - the element defining the hyperlink <a href="#applyToSection">applies</a> - to. - - <p>For <code><a href="#link">link</a></code> elements, the <code - title=rel-author><a href="#author">author</a></code> keyword indicates - that the referenced document provides further information about the author - for the page as a whole. - - <p class=note>The "referenced document" can be, and often is, a <code - title="">mailto:</code> URI giving the e-mail address of the author. <a - href="#refsMAILTO">[MAILTO]</a> - - <p><strong>Synonyms</strong>: For historical reasons, user agents must also - treat <code><a href="#link">link</a></code>, <code><a - href="#a">a</a></code>, and <code><a href="#area">area</a></code> elements - that have a <code title="">rev</code> attribute with the value - "<code>made</code>" as having the <code title=rel-author><a - href="#author">author</a></code> keyword specified as a link relationship. - - <h5 id=link-type2><span class=secno>4.4.3.4. </span>Link type "<dfn - id=bookmark title=rel-bookmark><code>bookmark</code></dfn>"</h5> - - <p>The <code title=rel-bookmark><a href="#bookmark">bookmark</a></code> - keyword may be used with <code><a href="#a">a</a></code> and <code><a - href="#area">area</a></code> elements. - - <p>The <code title=rel-bookmark><a href="#bookmark">bookmark</a></code> - keyword gives a permalink for the nearest ancestor <code><a - href="#article">article</a></code> element of the linking element in - question, or of <a href="#associatedSection">the section the linking - element is most closely associated with</a>, if there are no ancestor - <code><a href="#article">article</a></code> elements. - - <div class=example> - <p>The following snippet has three permalinks. A user agent could - determine which permalink applies to which part of the spec by looking at - where the permalinks are given.</p> - - <pre> ... - <body> - <h1>Example of permalinks</h1> - <div id="a"> - <h2>First example</h2> - <p><a href="a.html" rel="bookmark">This</a> permalink applies to - only the content from the first H2 to the second H2. The DIV isn't - exactly that section, but it roughly corresponds to it.</p> - </div> - <h2>Second example</h2> - <article id="b"> - <p><a href="b.html" rel="bookmark">This</a> permalink applies to - the outer ARTICLE element (which could be, e.g., a blog post).</p> - <article id="c"> - <p><a href="c.html" rel="bookmark">This</a> permalink applies to - the inner ARTICLE element (which could be, e.g., a blog comment).</p> - </article> - </article> - </body> - ...</pre> - </div> - - <h5 id=link-type3><span class=secno>4.4.3.5. </span>Link type "<dfn - id=contact title=rel-contact><code>contact</code></dfn>"</h5> - - <p>The <code title=rel-contact><a href="#contact">contact</a></code> - keyword may be used with <code><a href="#link">link</a></code>, <code><a - href="#a">a</a></code>, and <code><a href="#area">area</a></code> - elements. For <code><a href="#link">link</a></code> elements, it creates a - <a href="#hyperlink1" title="hyperlink link">hyperlink</a>. - - <p>For <code><a href="#a">a</a></code> and <code><a - href="#area">area</a></code> elements, the <code title=rel-contact><a - href="#contact">contact</a></code> keyword indicates that the referenced - document provides further contact information for the section that the - element defining the hyperlink <a href="#applyToSection">applies</a> to. - - <p>User agents must treat any hyperlink in an <code><a - href="#address">address</a></code> element as having the <code - title=rel-contact><a href="#contact">contact</a></code> link type - specified. - - <p>For <code><a href="#link">link</a></code> elements, the <code - title=rel-contact><a href="#contact">contact</a></code> keyword indicates - that the referenced document provides further contact information for the - page as a whole. - - <h5 id=link-type4><span class=secno>4.4.3.6. </span>Link type "<dfn - id=external title=rel-external><code>external</code></dfn>"</h5> - - <p>The <code title=rel-external><a href="#external">external</a></code> - keyword may be used with <code><a href="#a">a</a></code> and <code><a - href="#area">area</a></code> elements. - - <p>The <code title=rel-external><a href="#external">external</a></code> - keyword indicates that the link is leading to a document that is not part - of the site that the current document forms a part of. - - <h5 id=link-type5><span class=secno>4.4.3.7. </span>Link type "<dfn id=feed - title=rel-feed><code>feed</code></dfn>"</h5> - - <p>The <code title=rel-feed><a href="#feed">feed</a></code> keyword may be - used with <code><a href="#link">link</a></code>, <code><a - href="#a">a</a></code>, and <code><a href="#area">area</a></code> - elements. For <code><a href="#link">link</a></code> elements, it creates a - <a href="#hyperlink1" title="hyperlink link">hyperlink</a>. - - <p>The <code title=rel-feed><a href="#feed">feed</a></code> keyword - indicates that the referenced document is a syndication feed. If the <code - title=rel-alternate><a href="#alternate">alternate</a></code> link type is - also specified, then the feed is specifically the feed for the current - document; otherwise, the feed is just a syndication feed, not necessarily - associated with a particular Web page. - - <p>The first <code><a href="#link">link</a></code>, <code><a - href="#a">a</a></code>, or <code><a href="#area">area</a></code> element - in the document (in tree order) that creates a hyperlink with the link - type <code title=rel-feed><a href="#feed">feed</a></code> must be treated - as the default syndication feed for the purposes of feed autodiscovery. - - <p class=note>The <code title=rel-feed><a href="#feed">feed</a></code> - keyword is implied by the <code title=rel-alternate><a - href="#alternate">alternate</a></code> link type in certain cases (q.v.). - - <div class=example> - <p>The following two <code><a href="#link">link</a></code> elements are - equivalent: both give the syndication feed for the current page:</p> - - <pre><link rel="alternate" type="application/atom+xml" href="data.xml"></pre> - - <pre><link rel="feed alternate" href="data.xml"></pre> - - <p>The following extract offers various different syndication feeds:</p> - - <pre> <p>You can access the planets database using Atom feeds:</p> - <ul> - <li><a href="recently-visited-planets.xml" rel="feed">Recently Visited Planets</a></li> - <li><a href="known-bad-planets.xml" rel="feed">Known Bad Planets</a></li> - <li><a href="unexplored-planets.xml" rel="feed">Unexplored Planets</a></li> - </ul></pre> - </div> - - <h5 id=link-type6><span class=secno>4.4.3.8. </span>Link type "<dfn id=help - title=rel-help><code>help</code></dfn>"</h5> - - <p>The <code title=rel-help><a href="#help">help</a></code> keyword may be - used with <code><a href="#link">link</a></code>, <code><a - href="#a">a</a></code>, and <code><a href="#area">area</a></code> - elements. For <code><a href="#link">link</a></code> elements, it creates a - <a href="#hyperlink1" title="hyperlink link">hyperlink</a>. - - <p>For <code><a href="#a">a</a></code> and <code><a - href="#area">area</a></code> elements, the <code title=rel-help><a - href="#help">help</a></code> keyword indicates that the referenced - document provides further help information for the parent of the element - defining the hyperlink, and its children. - - <div class=example> - <p>In the following example, the form control has associated - context-sensitive help. The user agent could use this information, for - example, displaying the referenced document if the user presses the - "Help" or "F1" key.</p> - - <pre> <p><label> Topic: <input name=topic> <a href="help/topic.html" rel="help">(Help)</a></label></p></pre> - </div> - - <p>For <code><a href="#link">link</a></code> elements, the <code - title=rel-help><a href="#help">help</a></code> keyword indicates that the - referenced document provides help for the page as a whole. - - <h5 id=link-type7><span class=secno>4.4.3.9. </span>Link type "<dfn - id=icon3 title=rel-icon><code>icon</code></dfn>"</h5> - - <p>The <code title=rel-icon><a href="#icon3">icon</a></code> keyword may be - used with <code><a href="#link">link</a></code> elements, for which it - creates an <a href="#links1" title="external resource link">external - resource link</a>. - - <p>The specified resource is an icon representing the page or site, and - should be used by the user agent when representing the page in the user - interface. - - <p>Icons could be auditory icons, visual icons, or other kinds of icons. If - multiple icons are provided, the user agent must select the most - appropriate icon according to the <code title=attr-link-media><a - href="#media0">media</a></code> attribute. - - <h5 id=link-type8><span class=secno>4.4.3.10. </span>Link type "<dfn - id=license title=rel-license><code>license</code></dfn>"</h5> - - <p>The <code title=rel-license><a href="#license">license</a></code> - keyword may be used with <code><a href="#link">link</a></code>, <code><a - href="#a">a</a></code>, and <code><a href="#area">area</a></code> - elements. For <code><a href="#link">link</a></code> elements, it creates a - <a href="#hyperlink1" title="hyperlink link">hyperlink</a>. - - <p>The <code title=rel-license><a href="#license">license</a></code> - keyword indicates that the referenced document provides the copyright - license terms under which the current document is provided. - - <p><strong>Synonyms</strong>: For historical reasons, user agents must also - treat the keyword "<code title="">copyright</code>" like the <code - title=rel-license><a href="#license">license</a></code> keyword. - - <h5 id=link-type9><span class=secno>4.4.3.11. </span>Link type "<dfn - id=nofollow title=rel-nofollow><code>nofollow</code></dfn>"</h5> - - <p>The <code title=rel-nofollow><a href="#nofollow">nofollow</a></code> - keyword may be used with <code><a href="#a">a</a></code> and <code><a - href="#area">area</a></code> elements. - - <p>The <code title=rel-nofollow><a href="#nofollow">nofollow</a></code> - keyword indicates that the link is not endorsed by the original author or - publisher of the page. - - <h5 id=link-type10><span class=secno>4.4.3.12. </span>Link type "<dfn - id=pingback title=rel-pingback><code>pingback</code></dfn>"</h5> - - <p>The <code title=rel-pingback><a href="#pingback">pingback</a></code> - keyword may be used with <code><a href="#link">link</a></code> elements, - for which it creates an <a href="#links1" title="external resource - link">external resource link</a>. - - <p>For the semantics of the <code title=rel-pingback><a - href="#pingback">pingback</a></code> keyword, see the Pingback 1.0 - specification. <a href="#refsPINGBACK">[PINGBACK]</a> - - <h5 id=link-type11><span class=secno>4.4.3.13. </span>Link type "<dfn - id=prefetch title=rel-prefetch><code>prefetch</code></dfn>"</h5> - - <p>The <code title=rel-prefetch><a href="#prefetch">prefetch</a></code> - keyword may be used with <code><a href="#link">link</a></code> elements, - for which it creates an <a href="#links1" title="external resource - link">external resource link</a>. - - <p>The <code title=rel-prefetch><a href="#prefetch">prefetch</a></code> - keyword indicates that preemptively fetching and caching the specified - resource is likely to be beneficial, as it is highly likely that the user - will require this resource. - - <h5 id=link-type12><span class=secno>4.4.3.14. </span>Link type "<dfn - id=search0 title=rel-search><code>search</code></dfn>"</h5> - - <p>The <code title=rel-search><a href="#search0">search</a></code> keyword - may be used with <code><a href="#link">link</a></code>, <code><a - href="#a">a</a></code>, and <code><a href="#area">area</a></code> - elements. For <code><a href="#link">link</a></code> elements, it creates a - <a href="#hyperlink1" title="hyperlink link">hyperlink</a>. - - <p>The <code title=rel-search><a href="#search0">search</a></code> keyword - indicates that the referenced document provides an interface specifically - for searching the document and its related resources. - - <p class=note>OpenSearch description documents can be used with <code><a - href="#link">link</a></code> elements and the <code title=rel-search><a - href="#search0">search</a></code> link type to enable user agents to - autodiscover search interfaces. - - <h5 id=link-type13><span class=secno>4.4.3.15. </span>Link type "<dfn - id=stylesheet title=rel-stylesheet><code>stylesheet</code></dfn>"</h5> - - <p>The <code title=rel-stylesheet><a - href="#stylesheet">stylesheet</a></code> keyword may be used with <code><a - href="#link">link</a></code> elements, for which it creates an <a - href="#links1" title="external resource link">external resource link</a> - that contributes to the <a href="#styling0">styling processing model</a>. - - <p>The specified resource is a resource that describes how to present the - document. Exactly how the resource is to be processed depends on the - actual type of the resource. - - <p>If the <code title=rel-alternate><a - href="#alternate">alternate</a></code> keyword is also specified on the - <code><a href="#link">link</a></code> element, then the link is an - alternative stylesheet. - - <h5 id=link-type14><span class=secno>4.4.3.16. </span>Link type "<dfn - id=sidebar title=rel-sidebar><code>sidebar</code></dfn>"</h5> - - <p>The <code title=rel-sidebar><a href="#sidebar">sidebar</a></code> - keyword may be used with <code><a href="#link">link</a></code>, <code><a - href="#a">a</a></code>, and <code><a href="#area">area</a></code> - elements. For <code><a href="#link">link</a></code> elements, it creates a - <a href="#hyperlink1" title="hyperlink link">hyperlink</a>. - - <p>The <code title=rel-sidebar><a href="#sidebar">sidebar</a></code> - keyword indicates that the referenced document, if retrieved, is intended - to be shown in a <a href="#secondary0">secondary browsing context</a> (if - possible), instead of in the current <a href="#browsing0">browsing - context</a>. - - <p>A <a href="#hyperlinks" title=hyperlink>hyperlink element</a> with with - the <code title=rel-sidebar><a href="#sidebar">sidebar</a></code> keyword - specified is a <dfn id=sidebar0 title=rel-sidebar-hyperlink>sidebar - hyperlink</dfn>. - - <h5 id=link-type15><span class=secno>4.4.3.17. </span>Link type "<dfn - id=tag title=rel-tag><code>tag</code></dfn>"</h5> - - <p>The <code title=rel-tag><a href="#tag">tag</a></code> keyword may be - used with <code><a href="#link">link</a></code>, <code><a - href="#a">a</a></code>, and <code><a href="#area">area</a></code> - elements. For <code><a href="#link">link</a></code> elements, it creates a - <a href="#hyperlink1" title="hyperlink link">hyperlink</a>. - - <p>The <code title=rel-tag><a href="#tag">tag</a></code> keyword indicates - that the <em>tag</em> that the referenced document represents applies to - the current document. - - <h5 id=hierarchical><span class=secno>4.4.3.18. </span>Hierarchical link - types</h5> - - <p>Some documents form part of a hierarchical structure of documents. - - <p>A hierarchical structure of documents is one where each document can - have various subdocuments. A subdocument is said to be a <em>child</em> of - the document it is a subdocument of. The document of which it is a - subdocument is said to be its <em>parent</em>. The children of a document - have a relative order; the subdocument that precedes another is its - <em>previous sibling</em>, and the one that follows it is its <em>next - sibling</em>. A document with no parent forms the top of the hierarchy. - - <h6 id=link-type16><span class=secno>4.4.3.18.1. </span>Link type "<dfn - id=first title=rel-first><code>first</code></dfn>"</h6> - - <p>The <code title=rel-first><a href="#first">first</a></code> keyword may - be used with <code><a href="#link">link</a></code>, <code><a - href="#a">a</a></code>, and <code><a href="#area">area</a></code> - elements. For <code><a href="#link">link</a></code> elements, it creates a - <a href="#hyperlink1" title="hyperlink link">hyperlink</a>. - - <p>The <code title=rel-first><a href="#first">first</a></code> keyword - indicates that the document is part of a hierarchical structure, and that - the link is leading to the document that is the first child of the current - document's parent document. - - <p><strong>Synonyms</strong>: For historical reasons, user agents must also - treat the keywords "<code title="">begin</code>" and "<code - title="">start</code>" like the <code title=rel-first><a - href="#first">first</a></code> keyword. - - <h6 id=link-type17><span class=secno>4.4.3.18.2. </span>Link type "<dfn - id=index title=rel-index><code>index</code></dfn>"</h6> - - <p>The <code title=rel-index><a href="#index">index</a></code> keyword may - be used with <code><a href="#link">link</a></code>, <code><a - href="#a">a</a></code>, and <code><a href="#area">area</a></code> - elements. For <code><a href="#link">link</a></code> elements, it creates a - <a href="#hyperlink1" title="hyperlink link">hyperlink</a>. - - <p>The <code title=rel-index><a href="#index">index</a></code> keyword - indicates that the document is part of a hierarchical structure, and that - the link is leading to the document that is the top of the hierarchy. - - <p><strong>Synonyms</strong>: For historical reasons, user agents must also - treat the keywords "<code title="">top</code>", "<code - title="">contents</code>", and "<code title="">toc</code>" like the <code - title=rel-index><a href="#index">index</a></code> keyword. - - <h6 id=link-type18><span class=secno>4.4.3.18.3. </span>Link type "<dfn - id=last title=rel-last><code>last</code></dfn>"</h6> - - <p>The <code title=rel-last><a href="#last">last</a></code> keyword may be - used with <code><a href="#link">link</a></code>, <code><a - href="#a">a</a></code>, and <code><a href="#area">area</a></code> - elements. For <code><a href="#link">link</a></code> elements, it creates a - <a href="#hyperlink1" title="hyperlink link">hyperlink</a>. - - <p>The <code title=rel-last><a href="#last">last</a></code> keyword - indicates that the document is part of a hierarchical structure, and that - the link is leading to the document that is the last child of the current - document's parent document. - - <p><strong>Synonyms</strong>: For historical reasons, user agents must also - treat the keyword "<code title="">end</code>" like the <code - title=rel-last><a href="#last">last</a></code> keyword. - - <h6 id=link-type19><span class=secno>4.4.3.18.4. </span>Link type "<dfn - id=next title=rel-next><code>next</code></dfn>"</h6> - - <p>The <code title=rel-next><a href="#next">next</a></code> keyword may be - used with <code><a href="#link">link</a></code>, <code><a - href="#a">a</a></code>, and <code><a href="#area">area</a></code> - elements. For <code><a href="#link">link</a></code> elements, it creates a - <a href="#hyperlink1" title="hyperlink link">hyperlink</a>. - - <p>The <code title=rel-next><a href="#next">next</a></code> keyword - indicates that the document is part of a hierarchical structure, and that - the link is leading to the document that is the next sibling of the - current document. - - <h6 id=link-type20><span class=secno>4.4.3.18.5. </span>Link type "<dfn - id=prev title=rel-prev><code>prev</code></dfn>"</h6> - - <p>The <code title=rel-prev><a href="#prev">prev</a></code> keyword may be - used with <code><a href="#link">link</a></code>, <code><a - href="#a">a</a></code>, and <code><a href="#area">area</a></code> - elements. For <code><a href="#link">link</a></code> elements, it creates a - <a href="#hyperlink1" title="hyperlink link">hyperlink</a>. - - <p>The <code title=rel-prev><a href="#prev">prev</a></code> keyword - indicates that the document is part of a hierarchical structure, and that - the link is leading to the document that is the previous sibling of the - current document. - - <p><strong>Synonyms</strong>: For historical reasons, user agents must also - treat the keyword "<code title="">previous</code>" like the <code - title=rel-prev><a href="#prev">prev</a></code> keyword. - - <h6 id=link-type21><span class=secno>4.4.3.18.6. </span>Link type "<dfn - id=up title=rel-up><code>up</code></dfn>"</h6> - - <p>The <code title=rel-up><a href="#up">up</a></code> keyword may be used - with <code><a href="#link">link</a></code>, <code><a - href="#a">a</a></code>, and <code><a href="#area">area</a></code> - elements. For <code><a href="#link">link</a></code> elements, it creates a - <a href="#hyperlink1" title="hyperlink link">hyperlink</a>. - - <p>The <code title=rel-up><a href="#up">up</a></code> keyword indicates - that the document is part of a hierarchical structure, and that the link - is leading to the document that is the parent of the current document.</p> - <!-- idea: rel="up" vs rel="up up" vs rel="up up up top" - this would allow you to do breadcrumbs: - <nav> - <p> - <a href="/" rel="top up up up">Main</a> > - <a href="/products/" rel="up up">Products</a> > - <a href="/products/dishwashers" rel="up">Dishwashers</a> > - Second hand - </p> - </nav> - --> - - <h5 id=other0><span class=secno>4.4.3.19. </span>Other link types</h5> - - <p>Other than the types defined above, only types defined as extensions in - the <a href="http://wiki.whatwg.org/wiki/RelExtensions">WHATWG Wiki - RelExtensions page</a> may be used with the <code title="">rel</code> - attribute on <code><a href="#link">link</a></code>, <code><a - href="#a">a</a></code>, and <code><a href="#area">area</a></code> - elements. <a href="#refsWHATWGWIKI">[WHATWGWIKI]</a> - - <p>Anyone is free to edit the WHATWG Wiki RelExtensions page at any time to - add a type. Extension types must be specified with the following - information: - - <dl> - <dt>Keyword - - <dd> - <p>The actual value being defined. The value should not be confusingly - similar to any other defined value (e.g. differing only in case). - - <dt>Effect on... <code><a href="#link">link</a></code> - - <dd> - <p>One of the following:</p> - - <dl> - <dt>not allowed - - <dd>The keyword is not allowed to be specified on <code><a - href="#link">link</a></code> elements. - - <dt>Hyperlink - - <dd>The keyword may be specified on a <code><a - href="#link">link</a></code> element; it creates a <a - href="#hyperlink1" title="hyperlink link">hyperlink link</a>. - - <dt>External Resource - - <dd>The keyword may be specified on a <code><a - href="#link">link</a></code> element; it creates a <a href="#links1" - title="external resource link">external resource link</a>. - </dl> - - <dt>Effect on... <code><a href="#a">a</a></code> and <code><a - href="#area">area</a></code> - - <dd> - <p>One of the following:</p> - - <dl> - <dt>not allowed - - <dd>The keyword is not allowed to be specified on <code><a - href="#a">a</a></code> and <code><a href="#area">area</a></code> - elements. - - <dt>Hyperlink - - <dd>The keyword may be specified on <code><a href="#a">a</a></code> and - <code><a href="#area">area</a></code> elements; it creates a <a - href="#hyperlinks" title=hyperlink>hyperlink</a>. - </dl> - - <dt>Brief description - - <dd> - <p>A short description of what the keyword's meaning is. - - <dt>Link to more details - - <dd> - <p>A link to a more detailed description of the keyword's semantics and - requirements. It could be another page on the Wiki, or a link to an - external page. - - <dt>Synonyms - - <dd> - <p>A list of other keyword values that have exactly the same processing - requirements. Authors must not use the values defined to be synonyms, - they are only intended to allow user agents to support legacy content. - - <dt>Status - - <dd> - <p>One of the following:</p> - - <dl> - <dt>Proposal - - <dd>The keyword has not received wide peer review and approval. It is - included for completeness because pages use the keyword. Pages should - not use the keyword. - - <dt>Accepted - - <dd>The keyword has received wide peer review and approval. It has a - specification that unambiguously defines how to handle pages that use - the keyword, including when they use them in incorrect ways. Pages may - use the keyword. - - <dt>Rejected - - <dd>The keyword has received wide peer review and it has been found to - have significant problems. Pages must not use the keyword. When a - keyword has this status, the "Effect on... <code><a - href="#link">link</a></code>" and "Effect on... <code><a - href="#a">a</a></code> and <code><a href="#area">area</a></code>" - information should be set to "not allowed". - </dl> - - <p>If a keyword is added with the "proposal" status and found to be - redundant with existing values, it should be removed and listed as a - synonym for the existing value. If a keyword is added with the - "proposal" status and found to be harmful, then it should be changed to - "rejected" status, and its "Effect on..." information should be changed - accordingly.</p> - </dl> - - <p>Conformance checkers must use the information given on the WHATWG Wiki - RelExtensions page to establish if a value not explicitly defined in this - specification is allowed or not. When an author uses a new type not - defined by either this specification or the Wiki page, conformance - checkers should offer to add the value to the Wiki, with the details - described above, with the "proposal" status. - - <p>This specification does not define how new values will get approved. It - is expected that the Wiki will have a community that addresses this. - - <h3 id=interfaces><span class=secno>4.5. </span>Interfaces for URI - manipulation</h3> - - <p>An interface that has a complement of <dfn id=uri-decomposition>URI - decomposition attributes</dfn> will have seven attributes with the - following definitions: - - <pre class=idl> - readonly attribute DOMString <a href="#protocol0" title=dom-uda-protocol>protocol</a>; - readonly attribute DOMString <a href="#host0" title=dom-uda-host>host</a>; - readonly attribute DOMString <a href="#hostname0" title=dom-uda-hostname>hostname</a>; - readonly attribute DOMString <a href="#port0" title=dom-uda-port>port</a>; - readonly attribute DOMString <a href="#pathname0" title=dom-uda-pathname>pathname</a>; - readonly attribute DOMString <a href="#search1" title=dom-uda-search>search</a>; - readonly attribute DOMString <a href="#hash0" title=dom-uda-hash>hash</a>; -</pre> - - <p>The attributes defined to be URI decomposition attributes must act as - described for the attributes with the same corresponding names in this - section. - - <p>In addition, an interface with a complement of URI decomposition - attributes will define an <dfn id=input - title=concept-uda-input>input</dfn>, which is a URI that the attributes - act on, and a <dfn id=common3 title=concept-uda-setter>common setter - action</dfn>, which is a set of steps invoked when any of the attributes' - setters are invoked. - - <p>The seven URI decomposition attributes have similar requirements. - - <p>On getting, if the <a href="#input" title=concept-uda-input>input</a> - fulfills the condition given in the "getter condition" column - corresponding to the attribute in the table below, the user agent must - return the part of the <a href="#input" title=concept-uda-input>input</a> - URI given in the "component" column, with any prefixes specified in the - "prefix" column appropriately added to the start of the string and any - suffixes specified in the "suffix" column appropriately added to the end - of the string. Otherwise, the attribute must return the empty string. - - <p>On setting, the new value must first be mutated as described by the - "setter preprocessor" column, then mutated by %-escaping any characters in - the new value that are not valid in the relevant component as given by the - "component" column. Then, if the resulting new value fulfills the - condition given in the "setter condition" column, the user agent must make - a new string <var title="">output</var> by replacing the component of the - URI given by the "component" column in the <a href="#input" - title=concept-uda-input>input</a> URI with the new value; otherwise, the - user agent must let <var title="">output</var> be equal to the <a - href="#input" title=concept-uda-input>input</a>. Finally, the user agent - must invoke the <a href="#common3" title=concept-uda-setter>common setter - action</a> with the value of <var title="">output</var>. - - <p>The rules for parsing and constructing URIs are described in RFC 2396 as - modified by RFC 2732. <a href="#refsRFC2396">[RFC2396]</a> <a - href="#refsRFC2732">[RFC2732]</a> - - <table> - <thead> - <tr> - <th>Attribute - - <th>Component - - <th>Getter Condition - - <th>Prefix - - <th>Suffix - - <th>Setter Preprocessor - - <th>Setter Condition - - <tbody> - <tr> - <td><dfn id=protocol0 title=dom-uda-protocol><code>protocol</code></dfn> - - - <td><scheme> - - <td>— - - <td>— - - <td>U+003A COLON ("<code title="">:</code>") - - <td>Remove all trailing U+003A COLON ("<code title="">:</code>") - characters - - <td>The new value is not the empty string - - <tr> - <td><dfn id=host0 title=dom-uda-host><code>host</code></dfn> - - <td><hostport> - - <td><a href="#input" title=concept-uda-input>input</a> is hierarchical - and uses a server-based naming authority - - <td>— - - <td>— - - <td>— - - <td>— - - <tr> - <td><dfn id=hostname0 title=dom-uda-hostname><code>hostname</code></dfn> - - - <td><host> - - <td><a href="#input" title=concept-uda-input>input</a> is hierarchical - and uses a server-based naming authority - - <td>— - - <td>— - - <td>Remove all leading U+002F SOLIDUS ("<code title="">/</code>") - characters - - <td>— - - <tr> - <td><dfn id=port0 title=dom-uda-port><code>port</code></dfn> - - <td><port> - - <td><a href="#input" title=concept-uda-input>input</a> is hierarchical - and uses a server-based naming authority - - <td>— - - <td>— - - <td>Remove any characters in the new value that are not in the range - U+0030 DIGIT ZERO .. U+0039 DIGIT NINE - - <td>The new value is not the empty string - - <tr> - <td><dfn id=pathname0 title=dom-uda-pathname><code>pathname</code></dfn> - - - <td><abs_path> - - <td><a href="#input" title=concept-uda-input>input</a> is hierarchical - - <td>— - - <td>— - - <td>If it has no leading U+002F SOLIDUS ("<code title="">/</code>") - character, prepend a U+002F SOLIDUS ("<code title="">/</code>") - character to the new value - - <td>— - - <tr> - <td><dfn id=search1 title=dom-uda-search><code>search</code></dfn> - - <td><query> - - <td><a href="#input" title=concept-uda-input>input</a> is hierarchical - - <td>U+003F QUESTION MARK ("<code title="">?</code>") - - <td>— - - <td>Remove one leading U+003F QUESTION MARK ("<code title="">?</code>") - character, if any - - <td>— - - <tr> - <td><dfn id=hash0 title=dom-uda-hash><code>hash</code></dfn> - - <td><fragment> - - <td>Fragment identifier is longer than zero characters - - <td>U+0023 NUMBER SIGN ("<code title="">#</code>") - - <td>— - - <td>Remove one leading U+0023 NUMBER SIGN ("<code title="">#</code>") - character, if any - - <td>— - </table> - <!-- - http://www.hixie.ch/tests/adhoc/dom/level0/location/components/ - http://lxr.mozilla.org/seamonkey/source/dom/src/base/nsLocation.cpp - http://wp.netscape.com/eng/mozilla/3.0/handbook/javascript/ref_h-l.htm#84722 ---> - - <h3 id=navigating><span class=secno>4.6. </span>Navigating across documents</h3> - - <p>Certain actions cause the <a href="#browsing0">browsing context</a> to - <dfn id=navigate>navigate</dfn>. For example, <a href="#following0" - title="following hyperlinks">following a hyperlink</a>, <span - title="">form submission</span>, and the <code - title=dom-window-open>window.open()</code> and <code - title=dom-location-assign><a href="#assign">location.assign()</a></code> - methods can all cause a browsing context to navigate. A user agent may - also provide various ways for the user to explicitly cause a browsing - context to navigate. - - <p>When a browsing context is navigated, the user agent must follow the - following steps: - - <ol> - <li> - <p>Cancel any preexisting attempt to navigate the browsing context. - - <li> - <p>If the new resource is the same as the current resource, but a - fragment identifier has been specified, then <a href="#scrolling0" - title=navigate-fragid>scroll the document to the specified element</a> - and abort these steps. - - <li> - <p>If the new resource is to be handled by displaying some sort of inline - content, e.g. an error message because the specified scheme is not one - of the supported protocols, or an inline prompt to allow the user to - select <a href="#registerprotocolhandler" - title=dom-navigator-registerProtocolHandler>a registered handler</a> for - the given scheme, then <a href="#display" title="display a user agent - page inline">display the inline content</a> and abort these steps. - - <li> - <p>If the new resource is to be handled using a mechanism that does not - affect the browsing context, then abort these steps and proceed with - that mechanism instead. - - <li> - <p>Start fetching the specified resource, as appropriate (e.g. performing - an HTTP GET or POST operation, or reading the file from disk, or - executing script in the case of a <a href="#the-javascript" - title="javascript protocol"><code title="">javascript:</code> URI</a>). - If this results in a redirect, return to step 2 with the new resource. - - <li> - <p>Wait for one or more bytes to be available or for the user agent to - establish that the resource in question is empty. During this time, the - user agent may allow the user to cancel this navigation attempt or start - other navigation attempts. - - <li> - <p>If the document's out-of-band metadata (e.g. HTTP headers), not - counting any <a href="#content-type8" title=Content-Type>type - information</a> (such as the Content-Type HTTP header), requires some - sort of processing that will not affect the browsing context, then - perform that processing and abort these steps.</p> - - <div class=note> - <p>Such processing might be triggered by, amongst other things, the - following:</p> - - <ul class=brief> - <li>HTTP status codes (e.g. 204 No Content or 205 Reset Content) - - <li>HTTP Content-Disposition headers - - <li>Network errors - </ul> - </div> - - <li> - <p>Let <var title="">type</var> be <a href="#sniffed" title="Content-Type - sniffing">the sniffed type of the resource</a>. - - <li> - <p>If the user agent has been configured to process resources of the - given <var title="">type</var> using some mechanism other than rendering - the content in a <a href="#browsing0">browsing context</a>, then skip - this step. Otherwise, if the <var title="">type</var> is one of the - following types, jump to the appropriate entry in the following list, - and process the resource as described there:</p> - - <dl class=switch> - <dt>"text/html" - - <dd>Follow the steps given in the <a href="#page-load" - title=navigate-html>HTML document</a> section, and abort these steps. - - <dt>Any type ending in "+xml" - - <dt>"application/xml" - - <dt>"text/xml" - - <dd>Follow the steps given in the <a href="#page-load0" - title=navigate-xml>XML document</a> section. If that section determines - that the content is <em>not</em> to be displayed as a generic XML - document, then proceed to the next step in this overall set of steps. - Otherwise, abort these steps. - - <dt>"text/plain" - - <dd>Follow the steps given in the <a href="#page-load1" - title=navigate-text>plain text file</a> section, and abort these steps. - - <dt>A supported image type - - <dd>Follow the steps given in the <a href="#page-load2" - title=navigate-image>image</a> section, and abort these steps. - - <dt>A type that will use an external application to render the content - in the <a href="#browsing0">browsing context</a> - - <dd>Follow the steps given in the <a href="#page-load3" - title=navigate-plugin>plugin</a> section, and abort these steps. - </dl> - - <li id=navigate-non-Document> - <p>If, given <var title="">type</var>, the new resource is to be handled - by displaying some sort of inline content, e.g. a native rendering of - the content, an error message because the specified type is not - supported, or an inline prompt to allow the user to select <a - href="#registercontenthandler" - title=dom-navigator-registerContentHandler>a registered handler</a> for - the given type, then <a href="#display" title="display a user agent page - inline">display the inline content</a> and abort these steps. - - <li> - <p>Otherwise, the document's <var title="">type</var> is such that the - resource will not affect the browsing context, e.g. because the resource - is to be handed to an external application. Process the resource - appropriately.</p> - </ol> - - <p>Some of the sections below, to which the above algorithm defers in - certain cases, require the user agent to <dfn id=update>update the session - history with the new page</dfn>. When a user agent is required to do this, - it must follows the set of steps given below that is appropriate for the - situation at hand. From the point of view of any script, these steps must - occur atomically. - - <ol> - <li> - <p class=big-issue>pause for scripts - - <li> - <p class=big-issue>onbeforeunload - - <li> - <p class=big-issue>onunload - - <li> - <dl> - <dt>If the navigation was initiated for <dfn id=entry>entry update</dfn> - of an entry - - <dd> - <ol> - <li> - <p>Replace the entry being updated with a new entry representing the - new resource and its <code>Document</code> object and related state. - The user agent may propagate state from the old entry to the new - entry (e.g. scroll position). - - <li> - <p><a href="#traverse">Traverse the history</a> to the new entry. - </ol> - - <dt>Otherwise - - <dd> - <ol> - <li> - <p>Remove all the entries after the <a href="#current0">current - entry</a> in the <a href="#browsing0">browsing context</a>'s - <code>Document</code> object's <code><a - href="#history1">History</a></code> object.</p> - - <p class=note>This <a href="#history-notes">doesn't necessarily have - to affect</a><!--XXX change to auto-xref?--> the user agent's user - interface.</p> - - <li> - <p>Append a new entry at the end of the <code><a - href="#history1">History</a></code> object representing the new - resource and its <code>Document</code> object and related state. - - <li> - <p><a href="#traverse">Traverse the history</a> to the new entry. - - <li> - <p>If the navigation was initiated with <dfn - id=replacement>replacement enabled</dfn>, remove the entry - immediately before the new <a href="#current0">current entry</a> in - the session history. - </ol> - </dl> - </ol> - - <h4 id=read-html><span class=secno>4.6.1. </span><dfn id=page-load - title=navigate-html>Page load processing model for HTML files</dfn></h4> - - <p>When an HTML document is to be loaded in a <a href="#browsing0">browsing - context</a>, the user agent must create a <code>Document</code> object, - mark it as being an <a href="#html-" title="HTML documents">HTML - document</a>, create an <a href="#html-0">HTML parser</a>, associate it - with the document, and begin to use the bytes provided for the document as - the <a href="#input0">input stream</a> for that parser. - - <p class=note>The <a href="#input0">input stream</a> converts bytes into - characters for use in the <span>tokeniser</span>. This process relies, in - part, on character encoding information found in the real <a - href="#content-type8" title=Content-Type>Content-Type metadata</a> of the - resource; the "sniffed type" is not used for this purpose.</p> - <!-- next two paragraphs are nearly identical to the navigate-text - section, keep them in sync --> - - <p>When no more bytes are available, an EOF character is implied, which - eventually causes a <code title=event-load><a - href="#load0">load</a></code> event to be fired. - - <p>After creating the <code>Document</code> object, but potentially before - the page has finished parsing, the user agent must <a - href="#update">update the session history with the new page</a>. - - <h4 id=read-xml><span class=secno>4.6.2. </span><dfn id=page-load0 - title=navigate-xml>Page load processing model for XML files</dfn></h4> - - <p>When faced with displaying an XML file inline, user agents must first - create a <code>Document</code> object, following the requirements of the - XML and Namespaces in XML recommendations, RFC 3023, DOM3 Core, and other - relevant specifications. <a href="#refsXML">[XML]</a> <a - href="#refsXMLNS">[XMLNS]</a> <a href="#refsRFC3023">[RFC3023]</a> <a - href="#refsDOM3CORE">[DOM3CORE]</a> - - <p>The actual HTTP headers and other metadata, not the headers as mutated - or implied by the algorithms given in this specification, are the ones - that must be used when determining the character encoding according to the - rules given in the above specifications. - - <p>User agents may examine the namespace of the root <code>Element</code> - node of this <code>Document</code> object to perform namespace-based - dispatch to alternative processing tools, e.g. determining that the - content is actually a syndication feed and passing it to a feed handler. - If such processing is to take place, abort the steps in this section, and - jump to <a href="#navigate-non-Document">step 10</a> in the <a - href="#navigate">navigate</a> steps above. - - <p>Otherwise, then, with the newly created <code>Document</code>, the user - agents must <a href="#update">update the session history with the new - page</a>. User agents may do this before the complete document has been - parsed (thus achieving <i>incremental rendering</i>). - - <p>Error messages from the parse process (e.g. namespace well-formedness - errors) may be reported inline by mutating the <code>Document</code>. - - <h4 id=read-text><span class=secno>4.6.3. </span><dfn id=page-load1 - title=navigate-text>Page load processing model for text files</dfn></h4> - - <p>When a plain text document is to be loaded in a <a - href="#browsing0">browsing context</a>, the user agent should create a - <code>Document</code> object, mark it as being an <a href="#html-" - title="HTML documents">HTML document</a>, create an <a href="#html-0">HTML - parser</a>, associate it with the document, act as if the tokeniser had - emitted a start tag token with the tag name "pre", set the <a - href="#tokenisation0">tokenisation</a> stage's <a href="#content2">content - model flag</a> to <i>PLAINTEXT</i>, and begin to pass the stream of - characters in the plain text document to that tokeniser. - - <p>The rules for how to convert the bytes of the plain text document into - actual characters are defined in RFC 2046, RFC 2646, and subsequent - versions thereof. <a href="#refsRFC2046">[RFC2046]</a> <a - href="#refsRFC2046">[RFC2646]</a></p> - <!-- next two paragraphs are nearly identical to the navigate-html - section and similar to the "non-DOM-inline-content" section, and the - next three are similar to the navigate-image and navigate-plugin - sections; keep them all in sync --> - - <p>When no more character are available, an EOF character is implied, which - eventually causes a <code title=event-load><a - href="#load0">load</a></code> event to be fired. - - <p>After creating the <code>Document</code> object, but potentially before - the page has finished parsing, the user agent must <a - href="#update">update the session history with the new page</a>. - - <p>User agents may add content to the <code><a href="#head">head</a></code> - element of the <code>Document</code>, e.g. linking to stylesheet or an XBL - binding, providing script, giving the document a <code><a - href="#title1">title</a></code>, etc. - - <h4 id=read-image><span class=secno>4.6.4. </span><dfn id=page-load2 - title=navigate-image>Page load processing model for images</dfn></h4> - - <p>When an image resource is to be loaded in a <a - href="#browsing0">browsing context</a>, the user agent should create a - <code>Document</code> object, mark it as being an <a href="#html-" - title="HTML documents">HTML document</a>, append an <code><a - href="#html">html</a></code> element to the <code>Document</code>, append - a <code><a href="#head">head</a></code> element and a <code><a - href="#body0">body</a></code> element to the <code><a - href="#html">html</a></code> element, append an <code><a - href="#img">img</a></code> to the <code><a href="#body0">body</a></code> - element, and set the <code title=attr-img-src><a - href="#src">src</a></code> attribute of the <code><a - href="#img">img</a></code> element to the address of the image.</p> - <!-- next three paragraphs are similar to the navigate-text section, - keep them in sync --> - - <p>Then, the user agent must act as if it had <a href="#stops" title="stop - parsing">stopped parsing</a>. - - <p>After creating the <code>Document</code> object, but potentially before - the page has finished fully loading, the user agent must <a - href="#update">update the session history with the new page</a>. - - <p>User agents may add content to the <code><a href="#head">head</a></code> - element of the <code>Document</code>, or attributes to the <code><a - href="#img">img</a></code> element, e.g. to link to stylesheet or an XBL - binding, to provide a script, to give the document a <code><a - href="#title1">title</a></code>, etc. - - <h4 id=read-plugin><span class=secno>4.6.5. </span><dfn id=page-load3 - title=navigate-plugin>Page load processing model for content that uses - plugins</dfn></h4> - - <p>When a resource that requires an external resource to be rendered is to - be loaded in a <a href="#browsing0">browsing context</a>, the user agent - should create a <code>Document</code> object, mark it as being an <a - href="#html-" title="HTML documents">HTML document</a>, append an <code><a - href="#html">html</a></code> element to the <code>Document</code>, append - a <code><a href="#head">head</a></code> element and a <code><a - href="#body0">body</a></code> element to the <code><a - href="#html">html</a></code> element, append an <code><a - href="#embed">embed</a></code> to the <code><a - href="#body0">body</a></code> element, and set the <code - title=attr-img-src><a href="#src">src</a></code> attribute of the <code><a - href="#img">img</a></code> element to the address of the image.</p> - <!-- next three paragraphs are similar to the navigate-text section, - keep them in sync --> - - <p>Then, the user agent must act as if it had <a href="#stops" title="stop - parsing">stopped parsing</a>. - - <p>After creating the <code>Document</code> object, but potentially before - the page has finished fully loading, the user agent must <a - href="#update">update the session history with the new page</a>. - - <p>User agents may add content to the <code><a href="#head">head</a></code> - element of the <code>Document</code>, or attributes to the <code><a - href="#embed">embed</a></code> element, e.g. to link to stylesheet or an - XBL binding, or to give the document a <code><a - href="#title1">title</a></code>. - - <h4 id=non-DOM-inline-content><span class=secno>4.6.6. </span>Page load - processing model for inline content that doesn't have a DOM</h4> - - <p>When the user agent is to <dfn id=display>display a user agent page - inline</dfn> in a <a href="#browsing0">browsing context</a>, the user - agent should create a <code>Document</code> object, mark it as being an <a - href="#html-" title="HTML documents">HTML document</a>, and then either - associate that <code>Document</code> with a custom rendering that is not - rendered using the normal <code>Document</code> rendering rules, or mutate - that <code>Document</code> until it represents the content the user agent - wants to render.</p> - <!-- next two paragraphs are similar to the navigate-text section, - keep them in sync --> - - <p>Once the page has been set up, the user agent must act as if it had <a - href="#stops" title="stop parsing">stopped parsing</a>. - - <p>After creating the <code>Document</code> object, but potentially before - the page has been completely set up, the user agent must <a - href="#update">update the session history with the new page</a>. - - <h4 id=scroll-to-fragid><span class=secno>4.6.7. </span><dfn id=scrolling0 - title=navigate-fragid>Scrolling to a fragment identifier</dfn></h4> - - <p>When a user agent is supposed to scroll to a particular element, it may - change the scrolling position of the document as desired, or perform any - other relevant action. - - <p class=big-issue>how to get a "particular element" from a frag id -- - id="", name="", XPointer, etc; missing IDs (e.g. the infamous "#top") - - <p>Then, the user agent must <a href="#update">update the session history - with the new page</a>, where "the new page" has the same - <code>Document</code> as before, but potentially has a different scroll - position. - - <h3 id=content-type-sniffing><span class=secno>4.7. </span>Determining the - type of a new resource in a browsing context</h3> - - <p class=warning>It is imperative that the rules in this section be - followed exactly. When two user agents use different heuristics for - content type detection, security problems can occur. For example, if a - server believes a contributed file to be an image (and thus benign), but a - Web browser believes the content to be HTML (and thus capable of executing - script), the end user can be exposed to malicious content, making the user - vulnerable to cookie theft attacks and other cross-site scripting attacks. - - <p>The <dfn id=sniffed title="Content-Type sniffing">sniffed type of a - resource</dfn> must be found as follows: - - <ol> - <li> - <p>If the resource was fetched over an HTTP protocol, and there is no - HTTP Content-Encoding header, but there is an HTTP Content-Type header - and it has a value whose bytes exactly match one of the following three - lines:</p> - - <table> - <thead> - <tr> - <th>Bytes in Hexadecimal - - <th>Textual representation - - <tbody> - <tr><!-- Old Apache default --> - - <td>74 65 78 74 2f 70 6c 61 69 6e - - <td><code title="">text/plain</code> - - <tr><!-- Modern Apache default --> - - <td>74 65 78 74 2f 70 6c 61 69 6e 3b 20 63 68 61 72 73 65 74 3d 49 53 - 4f 2d 38 38 35 39 2d 31 - - <td><code title="">text/plain; charset=ISO-8859-1</code> - - <tr><!-- Debian's arbitrarily different Modern Apache default --> - - <td>74 65 78 74 2f 70 6c 61 69 6e 3b 20 63 68 61 72 73 65 74 3d 69 73 - 6f 2d 38 38 35 39 2d 31 - - <td><code title="">text/plain; charset=iso-8859-1</code> - </table> - - <p>...then jump to the <em title="content-type sniffing: text or - binary"><a href="#content-type4">text or binary</a></em> section below.</p> - - <li> - <p>Let <var title="">official type</var> be the type given by the <a - href="#content-type8" title=Content-Type>Content-Type metadata</a> for - the resource (in lowercase<!-- XXX ASCII case folding -->, ignoring any - parameters). If there is no such type, jump to the <em - title="content-type sniffing: unknown type"><a - href="#content-type5">unknown type</a></em> step below. - - <li> - <p>If <var title="">official type</var> ends in "+xml", or if it is - either "text/xml" or "application/xml", then the the sniffed type of the - resource is <var title="">official type</var>; return that and abort - these steps. - </li> - <!-- we don't want - image/svg+xml going through the next step --> - - <li> - <p>If <var title="">official type</var> is an image type supported by the - user agent (e.g. "image/png", "image/gif", "image/jpeg", etc), then jump - to the <em title="content-type sniffing: image"><a - href="#content-type6">images</a></em> section below. - - <li> - <p>If <var title="">official type</var> is "text/html", then jump to the - <em title="content-type sniffing: feed or html"><a - href="#content-type7">feed or HTML</a></em> section below. - - <li> - <p>Otherwise, the sniffed type of the resource is <var title="">official - type</var>. - </ol> - - <h4 id=content-type0><span class=secno>4.7.1. </span><dfn - id=content-type4>Content-Type sniffing: text or binary</dfn></h4> - - <ol> - <li> - <p>The user agent may wait for 512 or more bytes of the resource to be - available. - - <li> - <p>Let <var title="">n</var> be the smaller of either 512 or the number - of bytes already available. - - <li> - <p>If <var title="">n</var> is 4 or more, and the first bytes of the file - match one of the following byte sets:</p> - - <table> - <thead> - <tr> - <th>Bytes in Hexadecimal - - <th>Description - - <tbody> - <tr> - <td>FE FF - - <td>UTF-16BE BOM <!-- followed by a character --> or UTF-32LE BOM - - <tr> - <td>FF FE - - <td>UTF-16LE BOM <!-- followed by a character --> - - <tr> - <td>00 00 FE FF - - <td>UTF-32BE BOM <!-- this one is redundant with the one above - <tr> - <td>FF FE 00 00 - <td>UTF-32LE BOM ---> - - - <tr> - <td>EF BB BF - - <td>UTF-8 BOM - <!-- followed by a character, or the first byte of a multiple character sequence --> - <!-- nobody uses this - <tr> - <td>DD 73 66 73 - <td>UTF-EBCDIC BOM ---> - - </table> - - <p>...then the sniffed type of the resource is "text/plain". - - <li> - <p>Otherwise, if any of the first <var title="">n</var> bytes of the - resource are in one of the following byte ranges:</p> - <!-- This byte list is based on RFC 2046 Section 4.1.2. Characters - in the range 0x00-0X1F, with the exception of 0x09 - 0x0D (ASCII - for TAB, LF, VT, FF, and CR), and character 0x1B (reportedly used - by some encodings as a shift escape), are invalid. Thus, if we see - them, we assume it's not text. --> - - <ul class=brief> - <li> 0x00 - 0x08 - - <li> 0x0E - 0x1A - - <li> 0x1C - 0x1F - </ul> - - <p>...then the sniffed type of the resource is - "application/octet-stream". - - <li> - <p>Otherwise, the sniffed type of the resource is "text/plain". - </ol> - - <h4 id=content-type1><span class=secno>4.7.2. </span><dfn - id=content-type5>Content-Type sniffing: unknown type</dfn></h4> - - <ol> - <li> - <p>The user agent may wait for 512 or more bytes of the resource to be - available. - - <li> - <p>Let <var title="">stream length</var> be the smaller of either 512 or - the number of bytes already available. - - <li> - <p>For each row in the table below:</p> - - <ol> - <li>Let <var title="">pattern length</var> be the length of the pattern - (number of bytes described by the cell in the second column of the - row). - - <li>If <var title="">pattern length</var> is smaller than <var - title="">stream length</var> then skip this row. - - <li>Apply the "and" operator to the first <var title="">pattern - length</var> bytes of the resource and the given mask (the bytes in the - cell of first column of that row), and let the result be the <var - title="">data</var>. - - <li>If the bytes of the <var title="">data</var> matches the given - pattern bytes exactly, then the sniffed type of the resource is the - type given in the cell of the third column in that row; abort these - steps. - </ol> - - <li> - <p>As a last-ditch effort, jump to the <a href="#content-type4" - title="content-type sniffing: text or binary">text or binary</a> - section. - </ol> - - <table> - <thead> - <tr> - <th colspan=2>Bytes in Hexadecimal - - <th rowspan=2>Sniffed type - - <th rowspan=2>Comment - - <tr> - <th>Mask - - <th>Pattern - - <tbody> - <tr> - <td>FF FF DF DF DF DF DF DF DF FF DF DF DF DF - - <td>3C 21 44 4F 43 54 59 50 45 20 48 54 4D 4C <!-- "<!DOCTYPE HTML" --> - - <td>text/html - - <td>The string "<code title=""><!DOCTYPE HTML</code>" in US-ASCII or - compatible encodings, case-insensitively. - - <tr> - <td>FF DF DF DF DF - - <td>3C 48 54 4D 4C <!-- "<HTML" --> - - <td>text/html - - <td>The string "<code title=""><HTML</code>" in US-ASCII or - compatible encodings, case-insensitively. - - <tr> - <td>FF FF FF FF FF - - <td>25 50 44 46 2D - <!-- "%PDF-" (from http://lxr.mozilla.org/seamonkey/source/netwerk/streamconv/converters/nsUnknownDecoder.cpp#321) --> - - - <td>application/pdf - - <td>The string "<code title="">%PDF-</code>", the PDF signature. - - <tr> - <td>FF FF FF FF FF FF FF FF FF FF FF - - <td>25 21 50 53 2D 41 64 6F 62 65 2D - <!-- "%!PS-Adobe-" (from http://lxr.mozilla.org/seamonkey/source/netwerk/streamconv/converters/nsUnknownDecoder.cpp#321) --> - - - <td>application/postscript - - <td>The string "<code title="">%!PS-Adobe-</code>", the PostScript - signature. <!-- copied from the section below --> - - <tbody> - <tr> - <td>FF FF FF FF FF FF - - <td>47 49 46 38 37 61 <!-- GIF87a --> - - <td>image/gif - - <td>The string "<code title="">GIF87a</code>", a GIF signature. - - <tr> - <td>FF FF FF FF FF FF - - <td>47 49 46 38 39 61 <!-- GIF89a --> - - <td>image/gif - - <td>The string "<code title="">GIF89a</code>", a GIF signature. - - <tr> - <td>FF FF FF FF FF FF FF FF - - <td>89 50 4E 47 0D 0A 1A 0A - <!-- [TAB]PNG[CR][LF][EOF][LF]; 137 80 78 71 13 10 26 10 --> - - <td>image/png - - <td>The PNG signature. - - <tr> - <td>FF FF FF - - <td>FF D8 FF - <!-- SOI marker followed by the first byte of another marker --> - - <td>image/jpeg - - <td>A JPEG SOI marker followed by the first byte of another marker. - </table> - - <p>User agents may support further types if desired, by implicitly adding - to the above table. However, user agents should not use any other patterns - for types already mentioned in the table above, as this could then be used - for privilege escalation (where, e.g., a server uses the above table to - determine that content is not HTML and thus safe from XSS attacks, but - then a user agent detects it as HTML anyway and allows script to execute). - - <h4 id=content-type2><span class=secno>4.7.3. </span><dfn - id=content-type6>Content-Type sniffing: image</dfn></h4> - - <p>If the first bytes of the file match one of the byte sequences in the - first columns of the following table, then the sniffed type of the - resource is the type given in the corresponding cell in the second column - on the same row: - - <table> - <thead> - <tr> - <th>Bytes in Hexadecimal - - <th>Sniffed type - - <th>Comment <!-- update the table above if you change this! --> - - <tbody> - <tr> - <td>47 49 46 38 37 61 <!-- GIF87a --> - - <td>image/gif - - <td>The string "<code title="">GIF87a</code>", a GIF signature. - - <tr> - <td>47 49 46 38 39 61 <!-- GIF89a --> - - <td>image/gif - - <td>The string "<code title="">GIF89a</code>", a GIF signature. - - <tr> - <td>89 50 4E 47 0D 0A 1A 0A - <!-- [TAB]PNG[CR][LF][EOF][LF]; 137 80 78 71 13 10 26 10 --> - - <td>image/png - - <td>The PNG signature. - - <tr> - <td>FF D8 FF - <!-- SOI marker followed by the first byte of another marker --> - - <td>image/jpeg - - <td>A JPEG SOI marker followed by the first byte of another marker. - </table> - - <p>User agents must ignore any rows for image types that they do not - support. - - <p>Otherwise, the <i>sniffed type</i> of the resource is the same as its - <var title="">official type</var>. - - <h4 id=content-type3><span class=secno>4.7.4. </span><dfn - id=content-type7>Content-Type sniffing: feed or HTML</dfn></h4> - <!-- mostly based on: - http://blogs.msdn.com/rssteam/articles/PublishersGuide.aspx - http://lxr.mozilla.org/seamonkey/source/browser/components/feeds/src/nsFeedSniffer.cpp#192 - http://lxr.mozilla.org/seamonkey/source/browser/components/feeds/src/nsFeedSniffer.cpp#127 - --> - - <ol> - <li> - <p>The user agent may wait for 512 or more bytes of the resource to be - available. - - <li> - <p>Let <var title="">s</var> be the stream of bytes, and let <span><var - title="">s</var>[<var title="">i</var>]</span> represent the byte in - <var title="">s</var> with position <var title="">i</var>, treating <var - title="">s</var> as zero-indexed (so the first byte is at <span><var - title="">i</var>=0</span>). - - <li> - <p>If at any point this algorithm requires the user agent to determine - the value of a byte in <var title="">s</var> which is not yet available, - or which is past the first 512 bytes of the resource, or which is beyond - the end of the resource, the user agent must stop this algorithm, and - assume that the sniffed type of the resource is "text/html".</p> - - <p class=note>User agents are allowed, by the first step of this - algorithm, to wait until the first 512 bytes of the resource are - available. - - <li> - <p>Initialise <var title="">pos</var> to 0. - - <li> - <p>Examine <span><var title="">s</var>[<var title="">pos</var>]</span>.</p> - - <dl - class=switch><!-- skip whitespace (S token as defined in XML 1.0 section 2.3; production [3] --> - - <dt>If it is 0x09 (ASCII tab), 0x20 (ASCII space), 0x0A (ASCII LF), or - 0x0D (ASCII CR) - - <dd>Increase <var title="">pos</var> by 1 and repeat this step. - - <dt>If it is 0x3C (ASCII "<code title=""><</code>") - - <dd>Increase <var title="">pos</var> by 1 and go to the next step. - - <dt>If it is anything else - - <dd>The sniffed type of the resource is "text/html". Abort these steps. - </dl> - - <li> - <p>If the bytes with positions <var title="">pos</var> to <span><var - title="">pos</var>+2</span> in <var title="">s</var> are exactly equal - to 0x21, 0x2D, 0x2D respectively (ASCII for "<code - title="">!--</code>"), then:</p> - - <ol> - <li>Increase <var title="">pos</var> by 3.</li> - <!-- skips past the " ! - - " --> - - <li>If the bytes with positions <span><var title="">pos</var></span> to - <span><var title="">pos</var>+2</span> in <var title="">s</var> are - exactly equal to 0x2D, 0x2D, 0x3E respectively (ASCII for "<code - title="">--></code>"), then increase <var title="">pos</var> by 3 - and jump back to the previous step (step 5) in the overall algorithm in - this section. - - <li>Otherwise, increase <var title="">pos</var> by 1. - - <li>Otherwise, return to step 2 in these substeps. - </ol> - - <li> - <p>If <span><var title="">s</var>[<var title="">pos</var>]</span> is 0x21 - (ASCII "<code title="">!</code>"):</p> - <!-- this skips past a DOCTYPE if there is one. It is brain-dead - because we don't have to be clever to parse the Atom and RSS x.y - DOCTYPEs, as they don't do anything clever like have internal - subsets of quoted ">" characters. If this fails, then that's ok, - we'll treat it as HTML which is fine since we know it's not a feed - in that case. --> - - <ol> - <li>Increase <var title="">pos</var> by 1. - - <li>If <span><var title="">s</var>[<var title="">pos</var>]</span> equal - 0x3E, then increase <var title="">pos</var> by 1 and jump back to step - 5 in the overall algorithm in this section. - - <li>Otherwise, return to step 1 in these substeps. - </ol> - - <li> - <p>If <span><var title="">s</var>[<var title="">pos</var>]</span> is 0x3F - (ASCII "<code title="">?</code>"):</p> - - <ol> - <li>Increase <var title="">pos</var> by 1. - - <li>If <span><var title="">s</var>[<var title="">pos</var>]</span> and - <span><var title="">s</var>[<var title="">pos</var>+1]</span> equal - 0x3F and 0x3E respectively, then increase <var title="">pos</var> by 1 - and jump back to step 5 in the overall algorithm in this section. - - <li>Otherwise, return to step 1 in these substeps. - </ol> - - <li> - <p>Otherwise, if the bytes in <var title="">s</var> starting at <var - title="">pos</var> match any of the sequences of bytes in the first - column of the following table, then the user agent must follow the steps - given in the corresponding cell in the second column of the same row.</p> - - <table> - <thead> - <tr> - <th>Bytes in Hexadecimal - - <th>Requirement - - <th>Comment - - <tbody> - <tr> - <td>72 73 73 - - <td>The sniffed type of the resource is "application/rss+xml"; abort - these steps - - <td>The three ASCII characters "<code title="">rss</code>" - - <tr> - <td>66 65 65 64 - - <td>The sniffed type of the resource is "application/atom+xml"; abort - these steps - - <td>The four ASCII characters "<code title="">feed</code>" - - <tr> - <td>72 64 66 3A 52 44 46 - - <td>Continue to the next step in this algorithm - - <td>The ASCII characters "<code title="">rdf:RDF</code>" - </table> - - <p>If none of the byte sequences above match the bytes in <var - title="">s</var> starting at <var title="">pos</var>, then the sniffed - type of the resource is "text/html". Abort these steps.</p> - - <li> - <p class=big-issue>If, before the next ">", you find two xmlns* - attributes with http://www.w3.org/1999/02/22-rdf-syntax-ns# and - http://purl.org/rss/1.0/ as the namespaces, then the sniffed type of the - resource is "application/rss+xml", abort these steps. (maybe we only - need to check for http://purl.org/rss/1.0/ actually) - - <li> - <p>Otherwise, the sniffed type of the resource is "text/html". - </ol> - - <p class=note>For efficiency reaons, implementations may wish to implement - this algorithm and the algorithm for detecting the character encoding of - HTML documents in parallel. - - <h4 id=content-type><span class=secno>4.7.5. </span>Content-Type metadata</h4> - - <p>What explicit <dfn id=content-type8 title=Content-Type>Content-Type - metadata</dfn> is associated with the resource (the resource's type - information) depends on the protocol that was used to fetch the resource. - - <p>For HTTP resources, only the Content-Type HTTP header contributes any - data; the explicit type of the resource is then the value of that header, - interpreted as described by the HTTP specifications. <a - href="#refsHTTP">[HTTP]</a> - - <p>For resources fetched from the filesystem, user agents should use - platform-specific conventions, e.g. operating system extension/type - mappings. - - <p>Extensions must not be used for determining resource types for resources - fetched over HTTP. - - <p>For resources fetched over most other protocols, e.g. FTP, there is no - type information. - - <h3 id=user-prompts><span class=secno>4.8. </span>User prompts</h3> - - <p>The <dfn id=alert title=dom-alert><code>alert(<var - title="">message</var>)</code></dfn> method, when invoked, must show the - given <var title="">message</var> to the user. The user agent may make the - method wait for the user to acknowledge the message before returning; if - so, the user agent must <a href="#pause">pause</a> while the method is - waiting. - - <p>The <dfn id=confirm title=dom-confirm><code>confirm(<var - title="">message</var>)</code></dfn> method, when invoked, must show the - given <var title="">message</var> to the user, and ask the user to respond - with a positive or negative response. The user agent must then <a - href="#pause">pause</a> as the the method waits for the user's response. - If the user response positively, the method must return true, and if the - user response negatively, the method must return false. - - <p>The <dfn id=prompt title=dom-prompt><code>prompt(<var - title="">message</var>, <var title="">default</var>)</code></dfn> method, - when invoked, must show the given <var title="">message</var> to the user, - and ask the user to either respond with a string value or abort. The user - agent must then <a href="#pause">pause</a> as the the method waits for the - user's response. The second argument is optional. If the second argument - (<var title="">default</var>) is present, then the response must be - defaulted to the value given by <var title="">default</var>. If the user - aborts, then the method must return null; otherwise, the method must - return the string that the user responded with. - - <p>The <dfn id=print title=dom-print><code>print()</code></dfn> method, - when invoked, should offer the user the opportunity to <a - href="#obtain">obtain a physical form</a> of the document. The user agent - may make the method wait for the user to either accept or decline before - returning; if so, the user agent must <a href="#pause">pause</a> while the - method is waiting. (This does not, of course, preclude the user agent from - <em>always</em> offering the user with the opportunity to convert the - document to whatever media the user might want.) - - <h3 id=scripting><span class=secno>4.9. </span>Scripting</h3> - - <h4 id=running><span class=secno>4.9.1. </span>Running executable code</h4> - - <p>Various mechanisms can cause author-provided executable code to run in - the context of a document. These mechanisms include, but are probably not - limited to: - - <ul> - <li>Processing of <code><a href="#script0">script</a></code> elements. - - <li>Processing of inline <code title="javascript protocol"><a - href="#the-javascript">javascript:</a></code> URIs (e.g. the <code - title=attr-img-src><a href="#src">src</a></code> attribute of <code><a - href="#img">img</a></code> elements, or an <code title="">@import</code> - rule in a CSS <code><a href="#style">style</a></code> element block). - - <li>Event handlers, whether registered through the DOM using <code - title="">addEventListener()</code>, by explicit <a href="#event2">event - handler content attributes</a>, by <a href="#event3">event handler DOM - attributes</a>, or otherwise. - - <li>Processing of technologies like XBL or SVG that have their own - scripting features. - </ul> - - <p>User agents may provide a mechanism to enable or disable the execution - of author-provided code. When the user agent is configured such that - author-provided code does not execute, or if the user agent is implemented - so as to never execute author-provided code, it is said that <dfn - id=scripting1>scripting is disabled</dfn>. When author-provided code - <em>does</em> execute, <dfn id=scripting2>scripting is enabled</dfn>. A - user agent with scripting disabled is a <a href="#non-scripted" - title="User agents with no scripting support">user agent with no scripting - support</a> for the purposes of conformance. - - <h4 id=origin><span class=secno>4.9.2. </span>Origin</h4> - <!-- Hallowed are the Ori --> - <!-- - https://bugzilla.mozilla.org/show_bug.cgi?id=346659 - https://bugzilla.mozilla.org/show_bug.cgi?id=344495 - --> - - <p>Access to certain APIs is granted or denied to scripts based on the <dfn - id=origin0>origin</dfn> of the script and the API being accessed. - - <dl> - <dt>If a script is in a <code><a href="#script0">script</a></code> element - - <dd>The origin of the script is the origin of the <code>Document</code> to - which the <code><a href="#script0">script</a></code> element belongs. - - <dt>If a script is a function or other code reference created by another - script - - <dd>The origin of the script is the origin of the script that created it. - - <dt>If a script is a <a href="#the-javascript" title="javascript - protocol"><code title="">javascript:</code> URI</a> in an attribute - - <dd>The origin is the origin of the <code>Document</code> of the element - on which the attribute is found. - - <dt>If a script is a <a href="#the-javascript" title="javascript - protocol"><code title="">javascript:</code> URI</a> in a style sheet - - <dd>The origin is the origin of the <code>Document</code> to which the - style sheet applies. - - <dt>If a script is a <a href="#the-javascript" title="javascript - protocol"><code title="">javascript:</code> URI</a> to which a <a - href="#browsing0">browsing context</a> is being <a href="#navigate" - title=navigate>navigated</a>, the URI having been provided by the user - (e.g. by using a <i>bookmarklet</i>) - - <dd>The origin is the origin of the <code>Document</code> of the <a - href="#browsing0">browsing context</a>'s <a href="#active">active - document</a>. - - <dt>If a script is a <a href="#the-javascript" title="javascript - protocol"><code title="">javascript:</code> URI</a> to which a <a - href="#browsing0">browsing context</a> is being <a href="#navigate" - title=navigate>navigated</a>, the URI having been declared in markup - - <dd>The origin is the origin of the <code>Document</code> of the element - (e.g. an <code><a href="#a">a</a></code> or <code><a - href="#area">area</a></code> element) that declared the URI. - - <dt>If a script is a <a href="#the-javascript" title="javascript - protocol"><code title="">javascript:</code> URI</a> to which a <a - href="#browsing0">browsing context</a> is being <a href="#navigate" - title=navigate>navigated</a>, the URI having been provided by script - - <dd>The origin is the origin of the script that provided the URI.</dd> - <!-- ... --> - </dl> - - <p>The origin of scripts thus comes down to finding the origin of - <code>Document</code> objects. - - <p>The origin of a <code>Document</code> or image that was served over the - network and whose address uses a URI scheme with a server-based naming - authority is the tuple consisting of the <scheme>, <host>, and - <port> parts of the <code>Document</code>'s full URI. <a - href="#refsRFC2396">[RFC2396]</a> <a href="#refsRFC2732">[RFC2732]</a> - - <p>The origin of a <code>Document</code> or image that was generated from a - <code>data:</code> URI found in another <code>Document</code> or in a - script is the origin of the that <code>Document</code> or script. - - <p>The origin of a <code>Document</code> or image that was generated from a - <code>data:</code> URI from another source is a globally unique identifier - assigned when the document is created. - - <p>The origin of a <code>Document</code> or image that was generated from a - <a href="#the-javascript" title="javascript - protocol"><code>javascript:</code> URI</a> is the same as the origin of - that <code>javascript:</code> URI. - - <p><dfn id=the-string>The string representing the script's domain in IDNA - format</dfn> is obtained as follows: take the domain part of the script's - <a href="#origin0">origin</a> tuple and apply the IDNA ToASCII algorithm - and then the IDNA ToUnicode algorithm to each component of the domain name - (with both the AllowUnassigned and UseSTD3ASCIIRules flags set both - times). <a href="#refsRFC3490">[RFC3490]</a> - - <p>If ToASCII fails to convert one of the components of the string, e.g. - because it is too long or because it contains invalid characters, or if - the origin of the script has no domain part, then the string representing - the script's domain in IDNA format cannot be obtained. (ToUnicode is - defined to never fail.) - - <h4 id=security3><span class=secno>4.9.3. </span>Security exceptions</h4> - - <p class=big-issue>Define <dfn id=security8>security exception</dfn>. - - <h4 id=javascript-protocol><span class=secno>4.9.4. </span><dfn - id=the-javascript title="javascript protocol">The <code - title="">javascript:</code> protocol</dfn></h4> - - <p>A URI using the <code title="">javascript:</code> protocol must, if - evaluated, be evaluated using the in-context evaluation operation defined - for <code title="">javascript:</code> URIs. <a - href="#refsJSURI">[JSURI]</a></p> - <!-- -JSURI: http://ietfreport.isoc.org/all-ids/draft-hoehrmann-javascript-scheme-00.txt and - http://www.websitedev.de/ietf/draft-hoehrmann-javascript-scheme-00.txt should be as stable as it gets, - http://ietfreport.isoc.org/idref/draft-hoehrmann-javascript-scheme/ for the latest version ---> - - <p>When a browsing context is <a href="#navigate" - title=navigate>navigated</a> to a <code>javascript:</code> URI, and the <a - href="#active">active document</a> of that browsing context has the same - <a href="#origin0">origin</a> as the URI, the dereference context must be - the <a href="#browsing0">browsing context</a> being navigated. - - <p>When a browsing context is <a href="#navigate" - title=navigate>navigated</a> to a <code>javascript:</code> URI, and the <a - href="#active">active document</a> of that browsing context has a - <em>different</em> <a href="#origin0">origin</a> than the URI, the - dereference context must be an empty object. - - <p>Otherwise, the dereference context must the <a - href="#browsing0">browsing context</a> of the <code>Document</code> to - which belongs the element for which the URI is being dereferenced, or to - which the style sheet for which the URI is being dereferenced applies, - whichever is appropriate. - - <p>URIs using the <code title="">javascript:</code> protocol should be - evaluated when the resource for that URI is needed, unless <a - href="#scripting1">scripting is disabled</a> or the <code>Document</code> - corresponding to the dereference context (as defined above), if any, has - <code title=dom-document-designMode><a - href="#designMode">designMode</a></code> enabled. - - <p>If the dereference by-product is void (there is no return value), then - the URI must be treated in a manner equivalent to an HTTP resource with an - HTTP 204 No Content response. - - <p>Otherwise, the URI must be treated in a manner equivalent to an HTTP - resource with a 200 OK response whose <a href="#content-type8" - title=Content-Type>Content-Type metadata</a> is <code - title="">text/html</code> and whose response body is the dereference - by-product, converted to a string value. - - <p class=note>Certain contexts, in particular <code><a - href="#img">img</a></code> elements, ignore the <a href="#content-type8" - title=Content-Type>Content-Type metadata</a>. - - <div class=example> - <p>So for example a <code title="">javascript:</code> URI for a <code - title=attr-img-src><a href="#src">src</a></code> attribute of an <code><a - href="#img">img</a></code> element would be evaluated in the context of - the page as soon as the attribute is set; it would then be sniffed to - determine the image type and decoded as an image.</p> - - <p>A <code title="">javascript:</code> URI in an <code - title=attr-a-href>href</code> attribute of an <code><a - href="#a">a</a></code> element would only be evaluated when the link was - <a href="#following0" title="following hyperlinks">followed</a>.</p> - - <p>The <code title=attr-iframe-src><a href="#src1">src</a></code> - attribute of an <code><a href="#iframe">iframe</a></code> element would - be evaluated in the context of the <code><a - href="#iframe">iframe</a></code>'s own <a href="#browsing0">browsing - context</a>; once evaluated, its return value (if it was not void) would - replace that <a href="#browsing0">browsing context</a>'s document, thus - changing the variables visible in that <a href="#browsing0">browsing - context</a>.</p> - </div> - - <h4 id=events><span class=secno>4.9.5. </span>Events</h4> - - <p class=big-issue>We need to define how to handle events that are to be - fired on a Document that is no longer the active document of its browsing - context, and for Documents that have no browsing context. Do the events - fire? Do the handlers in that document not fire? Do we just define - scripting to be disabled when the document isn't active, with events still - running as is? See also the <code><a href="#script0">script</a></code> - element section, which says scripts don't run when the document isn't - active. - - <h5 id=event-handler-attributes><span class=secno>4.9.5.1. </span>Event - handler attributes</h5> - - <p><a href="#html-elements">HTML elements</a> can have <dfn id=event1>event - handler attributes</dfn> specified. These act as bubbling event listeners - for the element on which they are specified. - - <p>Each event handler attribute has two parts, an <a href="#event2" - title="event handler content attributes">event handler content - attribute</a> and an <a href="#event3" title="event handler DOM - attributes">event handler DOM attribute</a>. Event handler attributes must - initially be set to null. When their value changes (through the changing - of their event handler content attribute or their event handler DOM - attribute), they will either be null, or have an - <code>EventListener</code> object assigned to them. - - <p>Objects other than <code>Element</code> objects, in particular <code><a - href="#window">Window</a></code>, only have <a href="#event3" title="event - handler DOM attributes">event handler DOM attribute</a> (since they have - no content attributes). - - <p><dfn id=event2>Event handler content attributes</dfn>, when specified, - must contain valid ECMAScript code matching the ECMAScript <code - title="">FunctionBody</code> production. <a - href="#refsECMA262">[ECMA262]</a> - - <p>When an event handler content attribute is set, its new value must be - interpreted as the body of an anonymous function with a single argument - called <code>event</code>, with the new function's scope chain being - linked from the activation object of the handler, to the element, to the - element's <code>form</code> element if it is a form control, to the - <code>Document</code> object, to the <a href="#browsing0">browsing - context</a> of that <code>Document</code>. The function's - <code>this</code> parameter must be the <code>Element</code> object - representing the element. The resulting function must then be set as the - value of the corresponding event handler attribute, and the new value must - be set as the value of the content attribute. If the given function body - fails to compile, then the corresponding event handler attribute must be - set to null instead (the content attribute must still be updated to the - new value, though). - - <p class=note>See ECMA262 Edition 3, sections 10.1.6 and 10.2.3, for more - details on activation objects. <a href="#refsECMA262">[ECMA262]</a> - - <p class=issue>How do we allow non-JS event handlers? - - <p><dfn id=event3>Event handler DOM attributes</dfn>, on setting, must set - the corresponding event handler attribute to their new value, and on - getting, must return whatever the current value of the corresponding event - handler attribute is (possibly null). - - <p>The following are the event handler attributes that must be supported by - all <a href="#html-elements">HTML elements</a>, as both content attributes - and DOM attributes, and on <code><a href="#window">Window</a></code> - objects, as DOM attributes: - - <dl> - <dt><dfn id=onabort title=handler-onabort><code>onabort</code></dfn> - - <dd> - <p>Must be invoked whenever an <code title=event-abort><a - href="#abort">abort</a></code> event is targeted at or bubbles through - the element. - </dd> - <!-- - <dt><dfn title="handler-onbeforecopy"><code>onbeforecopy</code></dfn></dt> --> - <!-- widely used --> - <!-- - - <dd><p>Must be invoked whenever a <code - title="event-beforecopy">beforecopy</code> event is targeted at or bubbles - through the element.</p></dd> ---> - - <dt><dfn id=onbeforeunload - title=handler-onbeforeunload><code>onbeforeunload</code></dfn> - - <dd> - <p>Must be invoked whenever a <code - title=event-beforeunload>beforeunload</code> event is targeted at or - bubbles through the element. - - <dt><dfn id=onblur title=handler-onblur><code>onblur</code></dfn></dt> - <!-- widely used --> - - <dd> - <p>Must be invoked whenever a <code title=event-blur>blur</code> event is - targeted at or bubbles through the element. - - <dt><dfn id=onchange title=handler-onchange><code>onchange</code></dfn></dt> - <!-- widely used --> - - <dd> - <p>Must be invoked whenever a <code title=event-change>change</code> - event is targeted at or bubbles through the element. - - <dt><dfn id=onclick title=handler-onclick><code>onclick</code></dfn></dt> - <!-- widely used --> - - <dd> - <p>Must be invoked whenever a <code title=event-click>click</code> event - is targeted at or bubbles through the element. - - <dt><dfn id=oncontextmenu - title=handler-oncontextmenu><code>oncontextmenu</code></dfn></dt> - <!-- widely used --> - - <dd> - <p>Must be invoked whenever a <code - title=event-contextmenu>contextmenu</code> event is targeted at or - bubbles through the element. - </dd> - <!-- - <dt><dfn title="handler-oncopy"><code>oncopy</code></dfn></dt> --> - <!-- widely used --> - <!-- - - <dd><p>Must be invoked whenever a <code - title="event-copy">copy</code> event is targeted at or bubbles - through the element.</p></dd> ---> - - <dt><dfn id=ondblclick - title=handler-ondblclick><code>ondblclick</code></dfn></dt> - <!-- widely used --> - - <dd> - <p>Must be invoked whenever a <code title=event-dblclick>dblclick</code> - event is targeted at or bubbles through the element. - - <dt><dfn id=ondrag title=handler-ondrag><code>ondrag</code></dfn> - - <dd> - <p>Must be invoked whenever a <code title=event-drag><a - href="#drag">drag</a></code> event is targeted at or bubbles through the - element. - - <dt><dfn id=ondragend title=handler-ondragend><code>ondragend</code></dfn> - - <dd> - <p>Must be invoked whenever a <code title=event-dragend><a - href="#dragend">dragend</a></code> event is targeted at or bubbles - through the element. - - <dt><dfn id=ondragenter - title=handler-ondragenter><code>ondragenter</code></dfn> - - <dd> - <p>Must be invoked whenever a <code title=event-dragenter><a - href="#dragenter">dragenter</a></code> event is targeted at or bubbles - through the element. - - <dt><dfn id=ondragleave - title=handler-ondragleave><code>ondragleave</code></dfn> - - <dd> - <p>Must be invoked whenever a <code title=event-dragleave><a - href="#dragleave">dragleave</a></code> event is targeted at or bubbles - through the element. - - <dt><dfn id=ondragover - title=handler-ondragover><code>ondragover</code></dfn> - - <dd> - <p>Must be invoked whenever a <code title=event-dragover><a - href="#dragover">dragover</a></code> event is targeted at or bubbles - through the element. - - <dt><dfn id=ondragstart - title=handler-ondragstart><code>ondragstart</code></dfn></dt> - <!-- widely used --> - - <dd> - <p>Must be invoked whenever a <code title=event-dragstart><a - href="#dragstart">dragstart</a></code> event is targeted at or bubbles - through the element. - - <dt><dfn id=ondrop title=handler-ondrop><code>ondrop</code></dfn> - - <dd> - <p>Must be invoked whenever a <code title=event-drop><a - href="#drop">drop</a></code> event is targeted at or bubbles through the - element. - - <dt><dfn id=onerror title=handler-onerror><code>onerror</code></dfn></dt> - <!-- widely used --> - - <dd> - <p>Must be invoked whenever an <code title=event-error><a - href="#error1">error</a></code> event is targeted at or bubbles through - the element.</p> - - <p class=note>The <code title=handler-onerror><a - href="#onerror">onerror</a></code> handler is also used for <a - href="#runtime-script-errors">reporting script errors</a>. - - <dt><dfn id=onfocus title=handler-onfocus><code>onfocus</code></dfn></dt> - <!-- widely used --> - - <dd> - <p>Must be invoked whenever a <code title=event-focus>focus</code> event - is targeted at or bubbles through the element. - - <dt><dfn id=onkeydown title=handler-onkeydown><code>onkeydown</code></dfn></dt> - <!-- widely used --> - - <dd> - <p>Must be invoked whenever a <code title=event-keydown>keydown</code> - event is targeted at or bubbles through the element. - - <dt><dfn id=onkeypress - title=handler-onkeypress><code>onkeypress</code></dfn></dt> - <!-- widely used --> - - <dd> - <p>Must be invoked whenever a <code title=event-keypress>keypress</code> - event is targeted at or bubbles through the element. - - <dt><dfn id=onkeyup title=handler-onkeyup><code>onkeyup</code></dfn></dt> - <!-- widely used --> - - <dd> - <p>Must be invoked whenever a <code title=event-keyup>keyup</code> event - is targeted at or bubbles through the element. - - <dt><dfn id=onload title=handler-onload><code>onload</code></dfn></dt> - <!-- widely used --> - - <dd> - <p>Must be invoked whenever a <code title=event-load><a - href="#load0">load</a></code> event is targeted at or bubbles through - the element. - - <dt><dfn id=onmessage title=handler-onmessage><code>onmessage</code></dfn></dt> - <!-- introduced for <event-source> --> - - <dd> - <p>Must be invoked whenever a <code title=event-message><a - href="#message">message</a></code> event is targeted at or bubbles - through the element. - - <dt><dfn id=onmousedown - title=handler-onmousedown><code>onmousedown</code></dfn></dt> - <!-- widely used --> - - <dd> - <p>Must be invoked whenever a <code - title=event-mousedown>mousedown</code> event is targeted at or bubbles - through the element. - - <dt><dfn id=onmousemove - title=handler-onmousemove><code>onmousemove</code></dfn></dt> - <!-- widely used --> - - <dd> - <p>Must be invoked whenever a <code - title=event-mousemove>mousemove</code> event is targeted at or bubbles - through the element. - - <dt><dfn id=onmouseout - title=handler-onmouseout><code>onmouseout</code></dfn></dt> - <!-- widely used --> - - <dd> - <p>Must be invoked whenever a <code title=event-mouseout>mouseout</code> - event is targeted at or bubbles through the element. - - <dt><dfn id=onmouseover - title=handler-onmouseover><code>onmouseover</code></dfn></dt> - <!-- widely used --> - - <dd> - <p>Must be invoked whenever a <code - title=event-mouseover>mouseover</code> event is targeted at or bubbles - through the element. - - <dt><dfn id=onmouseup title=handler-onmouseup><code>onmouseup</code></dfn></dt> - <!-- widely used --> - - <dd> - <p>Must be invoked whenever a <code title=event-mouseup>mouseup</code> - event is targeted at or bubbles through the element. - - <dt><dfn id=onmousewheel - title=handler-onmousewheel><code>onmousewheel</code></dfn></dt> - <!-- widely used --> - - <dd> - <p>Must be invoked whenever a <code - title=event-mousewheel>mousewheel</code> event is targeted at or bubbles - through the element. - </dd> - <!-- - <dt><dfn title="handler-onpaste"><code>onpaste</code></dfn></dt> --> - <!-- widely used --> - <!-- - - <dd><p>Must be invoked whenever a <code - title="event-paste">paste</code> event is targeted at or bubbles - through the element.</p></dd> ---> - - <dt><dfn id=onresize title=handler-onresize><code>onresize</code></dfn></dt> - <!-- widely used --> - - <dd> - <p>Must be invoked whenever a <code title=event-resize>resize</code> - event is targeted at or bubbles through the element. - </dd> - <!-- XXX should define when it fires --> - - <dt><dfn id=onscroll title=handler-onscroll><code>onscroll</code></dfn></dt> - <!-- widely used --> - - <dd> - <p>Must be invoked whenever a <code title=event-scroll>scroll</code> - event is targeted at or bubbles through the element. - </dd> - <!-- XXX should define when it fires --> - - <dt><dfn id=onselect title=handler-onselect><code>onselect</code></dfn></dt> - <!-- widely used --> - - <dd> - <p>Must be invoked whenever a <code title=event-select><a - href="#select">select</a></code> event is targeted at or bubbles through - the element. - </dd> - <!-- XXX should define when it fires --> - <!--XXX - <dt><dfn title="handler-onselectstart"><code>onselectstart</code></dfn></dt> --> - <!-- widely used --> - <!-- - - <dd><p>Must be invoked whenever a <code - title="event-selectstart">selectstart</code> event is targeted at or bubbles - through the element.</p></dd> ---> - <!-- XXX should define when it fires --> - - <dt><dfn id=onsubmit title=handler-onsubmit><code>onsubmit</code></dfn></dt> - <!-- widely used --> - - <dd> - <p>Must be invoked whenever a <code title=event-submit>submit</code> - event is targeted at or bubbles through the element. - - <dt><dfn id=onunload title=handler-onunload><code>onunload</code></dfn></dt> - <!-- widely used --> - - <dd> - <p>Must be invoked whenever an <code title=event-unload>unload</code> - event is targeted at or bubbles through the element. - </dd> - <!-- XXX need to fire this --> - </dl> - - <p>When an event handler attribute is invoked, its argument must be set to - the <code>Event</code> object of the event in question. If the function - returns the exact boolean value false, the event's - <code>preventDefault()</code> method must then invoked. Exception: for - historical reasons, for the HTML <code>mouseover</code> event, the - <code>preventDefault()</code> method must be called when the function - returns true instead.</p> - <!-- IE actually uncancels the event if the function returns true --> - - <p>When <a href="#scripting1">scripting is disabled</a>, event handler - attributes must do nothing. - - <p>When <a href="#scripting2">scripting is enabled</a>, all event handler - attributes on an element, whether set to null or to a function, must be - registered as event listeners on the element, as if the <code - title=dom-EventTarget-addEventListenerNS>addEventListenerNS()</code> - method on the <code>Element</code> object's <code>EventTarget</code> - interface had been invoked when the element was created, with the event - type (<code title=dom-event-type>type</code> argument) equal to the type - described for the event handler attribute in the list above, the namespace - (<code title=dom-event-namespaceURI>namespaceURI</code> argument) set to - null, the listener set to be a target and bubbling phase listener (<code - title=dom-event-useCapture>useCapture</code> argument set to false), the - event group set to the default group (<code - title=dom-event-evtGroup>evtGroup</code> argument set to null), and the - event listener itself (<code title=dom-event-listener>listener</code> - argument) set to do nothing while the event handler attribute is null, and - set to invoke the function associated with the event handler attribute - otherwise. - - <h5 id=event><span class=secno>4.9.5.2. </span>Event firing</h5> - - <p class=big-issue>maybe this should be moved higher up (terminology? - conformance? DOM?) - - <p>Certain operations and methods are defined as firing events on elements. - For example, the <code title=dom-click><a href="#click">click()</a></code> - method on the <code><a href="#htmlelement">HTMLElement</a></code> - interface is defined as firing a <code title=event-click>click</code> - event on the element. <a href="#refsDOM3EVENTS">[DOM3EVENTS]</a> - - <p><dfn id=firing title="fire a click event">Firing a <code - title=event-click>click</code> event</dfn> means that a <a - href="http://www.w3.org/TR/DOM-Level-3-Events/events.html#event-click"><code>click</code></a> - event with no namespace, which bubbles and is cancelable, and which uses - the <code>MouseEvent</code> interface, must be dispatched at the given - element. The event object must have its <code title="">screenX</code>, - <code title="">screenY</code>, <code title="">clientX</code>, <code - title="">clientY</code>, and <code title="">button</code> attributes set - to 0, its <code title="">ctrlKey</code>, <code title="">shiftKey</code>, - <code title="">altKey</code>, and <code title="">metaKey</code> attributes - set according to the current state of the key input device, if any (false - for any keys that are not available), its <code title="">detail</code> - attribute set to 1, and its <code title="">relatedTarget</code> attribute - set to null. The <code title="">getModifierState()</code> method on the - object must return values appropriately describing the state of the key - input device at the time the event is created. - - <p><dfn id=firing0 title="fire a change event">Firing a <code - title=event-change>change</code> event</dfn> means that a <a - href="http://www.w3.org/TR/DOM-Level-3-Events/events.html#event-change"><code>change</code></a> - event with no namespace, which bubbles but is not cancelable, and which - uses the <code>Event</code> interface, must be dispatched at the given - element. The event object must have its <code title="">detail</code> - attribute set to 0. - - <p><dfn id=firing1 title="fire a contextmenu event">Firing a <code - title=event-contextmenu>contextmenu</code> event</dfn> means that a <code - title=event-contextmenu>contextmenu</code> event with no namespace, which - bubbles and is cancelable, and which uses the <code>Event</code> - interface, must be dispatched at the given element. The event object must - have its <code title="">detail</code> attribute set to 0. - - <p><dfn id=firing2 title="fire a simple event">Firing a simple event called - <var title="">e</var></dfn> means that an event with the name <var - title="">e</var>, with no namespace, which does not bubble but is - cancelable, and which uses the <code>Event</code> interface, must be - dispatched at the given element. - - <p><dfn id=firing3 title="fire a show event">Firing a <code - title=event-show>show</code> event</dfn> means <a href="#firing2" - title="fire a simple event">firing a simple event called <code - title=event-show>show</code></a>. <dfn id=firing4 title="fire a load - event">Firing a <code title=event-load>load</code> event</dfn> means <a - href="#firing2" title="fire a simple event">firing a simple event called - <code title=event-load>load</code></a>. <!--<dfn title="fire a - DOMContentLoaded event">Firing a <code - title="event-DOMContentLoaded">DOMContentLoaded</code> event</dfn> - means <span title="fire a simple event">firing a simple event called - <code - title="event-DOMContentLoaded">DOMContentLoaded</code></span>.--> - <dfn id=firing5 title="fire an error event">Firing an <code - title=event-error>error</code> event</dfn> means <a href="#firing2" - title="fire a simple event">firing a simple event called <code - title=event-error>error</code></a>.</p> - <!-- XXX need to define the dispatching of DOMActivate --> - - <p class=big-issue><dfn id=firing6 title="fire a progress event">Firing a - progress event called <var title="">e</var></dfn> means something that - hasn't yet been defined, in the <a href="#refsPROGRESS">[PROGRESS]</a> - spec. - - <p>The default action of these event is to do nothing unless otherwise - stated. - - <p class=big-issue>If you dispatch a custom "click" event at an element - that would normally have default actions, should they get triggered? If - so, we need to go through the entire spec and make sure that any default - actions are defined in terms of <em>any</em> event of the right type on - that element, not those that are dispatched in expected ways. - - <h5 id=events0><span class=secno>4.9.5.3. </span>Events and the <code><a - href="#window">Window</a></code> object</h5> - - <p>When an event is dispatched at a DOM node in a <code>Document</code> in - a <a href="#browsing0">browsing context</a>, if the event is not a <code - title=event-load><a href="#load0">load</a></code> event, the user agent - must also dispatch the event to the <code><a - href="#window">Window</a></code>, as follows: - - <ol> - <li>In the capture phase, the event must be dispatched to the <code><a - href="#window">Window</a></code> object before being dispatched to any of - the nodes. - - <li>In the bubble phase, the event must be dispatched to the <code><a - href="#window">Window</a></code> object at the end of the phase, unless - bubbling has been prevented. - </ol> - - <h5 id=runtime-script-errors><span class=secno>4.9.5.4. </span>Runtime - script errors</h5> - - <p><em>This section only applies to user agents that support scripting in - general and ECMAScript in particular.</em> - - <p>Whenever a runtime script error occurs in one of the scripts associated - with the document, the value of the <code title=handler-onerror><a - href="#onerror">onerror</a></code> <span>event handler DOM - attribute</span> of the <code><a href="#window">Window</a></code> object - must be processed, as follows: - - <dl class=switch> - <dt>If the value is a function - - <dd> - <p>The function referenced by the <code title=handler-onerror><a - href="#onerror">onerror</a></code> attribute must be invoked with three - arguments, before notifying the user of the error.</p> - - <p>The three arguments passed to the function are all - <code>DOMString</code>s; the first must give the message that the UA is - considering reporting, the second must give the URI to the resource in - which the error occured, and the third must give the line number in that - resource on which the error occured.</p> - - <p>If the function returns false, then the error should not be reported - to the user. Otherwise, if the function returns another value (or does - not return at all), the error should be reported to the user.</p> - - <p>Any exceptions thrown or errors caused by this function must be - reported to the user immediately after the error that the function was - called for, without calling the function again.</p> - - <dt>If the value is <code>null</code> - - <dd> - <p>The error should not reported to the user.</p> - - <dt>If the value is anything else - - <dd> - <p>The error should be reported to the user.</p> - </dl> - - <p>The initial value of <code title=handler-onerror><a - href="#onerror">onerror</a></code> must be <code>undefined</code>. - - <h3 id=browser><span class=secno>4.10. </span>Browser state</h3> - - <p>The <dfn id=navigator title=dom-navigator><code>navigator</code></dfn> - attribute of the <code><a href="#window">Window</a></code> interface must - return an instance of the <code><a - href="#clientinformation">ClientInformation</a></code> interface, which - represents the identity and state of the user agent (the client), and - allows Web pages to register themselves as potential protocol and content - handlers: - - <pre - class=idl>interface <dfn id=clientinformation>ClientInformation</dfn> { - readonly attribute boolean <a href="#navigator.online" title=dom-navigator-onLine>onLine</a>; - void <a href="#registerprotocolhandler" title=dom-navigator-registerProtocolHandler>registerProtocolHandler</a>(in DOMString protocol, in DOMString uri, in DOMString title); - void <a href="#registercontenthandler" title=dom-navigator-registerContentHandler>registerContentHandler</a>(in DOMString mimeType, in DOMString uri, in DOMString title); -<!-- XXX there are other attributes! -->};</pre> - <!-- also, see window.external.AddSearchProvider() and similar DOM APIs from IE --> - - <h4 id=offline><span class=secno>4.10.1. </span>Offline Web applications</h4> - - <p>The <dfn id=navigator.online - title=dom-navigator-onLine><code>navigator.onLine</code></dfn> attribute - must return false if the user agent will not contact the network when the - user follows links or when a script requests a remote page (or knows that - such an attempt would fail), and must return true otherwise. - - <p>The <dfn id=offline0 title=event-offline><code>offline</code></dfn> - event must be fired when the value of the <code - title=dom-navigator-onLine><a - href="#navigator.online">navigator.onLine</a></code> attribute of the - <code><a href="#window">Window</a></code> changes from true to false. - - <p>The <dfn id=online title=event-online><code>online</code></dfn> event - must be fired when the value of the <code title=dom-navigator-onLine><a - href="#navigator.online">navigator.onLine</a></code> attribute of the - <code><a href="#window">Window</a></code> changes from false to true. - - <p>These events are in no namespace, do bubble, are not cancelable, have no - default action, and use the normal <code>Event</code> interface. They must - be fired on <a href="#the-body0">the body element</a>. (As the events - bubble, they will reach the <code><a href="#window">Window</a></code> - object.)</p> - <!-- XXX ononline onoffline need to be defined --> - - <h4 id=custom-handlers><span class=secno>4.10.2. </span>Custom protocol and - content handlers</h4> - - <p>The <dfn id=registerprotocolhandler - title=dom-navigator-registerProtocolHandler><code>registerProtocolHandler()</code></dfn> - method allows Web sites to register themselves as possible handlers for - particular protocols. For example, an online fax service could register - itself as a handler of the <code>fax:</code> protocol (<a - href="#refsRFC2806">[RFC2806]</a>), so that if the user clicks on such a - link, he is given the opportunity to use that Web site. Analogously, the - <dfn id=registercontenthandler - title=dom-navigator-registerContentHandler><code>registerContentHandler()</code></dfn> - method allows Web sites to register themselves as possible handlers for - content in a particular MIME type. For example, the same online fax - service could register itself as a handler for <code>image/g3fax</code> - files (<a href="#refsRFC1494">[RFC1494]</a>), so that if the user has no - native application capable of handling G3 Facsimile byte streams, his Web - browser can instead suggest he use that site to view the image. - - <p>User agents may, within the constraints described in this section, do - whatever they like when the methods are called. A UA could, for instance, - prompt the user and offer the user the opportunity to add the site to a - shortlist of handlers, or make the handlers his default, or cancel the - request. UAs could provide such a UI through modal UI or through a - non-modal transient notification interface. UAs could also simply silently - collect the information, providing it only when relevant to the user. - - <p>There is <a href="#sample-handler-impl">an example of how these methods - could be presented to the user</a> below. - - <p>The arguments to the methods have the following meanings: - - <dl> - <dt><var title="">protocol</var> (<code - title=dom-navigator-registerProtocolHandler><a - href="#registerprotocolhandler">registerProtocolHandler()</a></code> - only) - - <dd> - <p>A scheme, such as <code>ftp</code> or <code>fax</code>. The scheme - must be treated case-insensitively by user agents for the purposes of - comparing with the scheme part of URIs that they consider against the - list of registered handlers.</p> - - <p>The <var title="">protocol</var> value, if it contains a colon (as in - "<code>ftp:</code>"), will never match anything, since schemes don't - contain colons.</p> - - <dt><var title="">mimeType</var> (<code - title=dom-navigator-registerContentHandler><a - href="#registercontenthandler">registerContentHandler()</a></code> only) - - <dd> - <p>A MIME type, such as <code>model/vrml</code> or - <code>text/richtext</code>. The MIME type must be treated - case-insensitively by user agents for the purposes of comparing with - MIME types of documents that they consider against the list of - registered handlers.</p> - - <p>User agents must compare the given values only to the MIME - type/subtype parts of content types, not to the complete type including - parameters. Thus, if <var title="">mimeType</var> values passed to this - method include characters such as commas or whitespace, or include MIME - parameters, then the handler being registered will never be used.</p> - - <dt><var title="">uri</var> - - <dd> - <p>The URI of the page that will handle the requests. When the user agent - uses this URI, it must replace the first occurrence of the exact literal - string "<code>%s</code>" with an escaped version of the URI of the - content in question (as defined below), and then fetch the resulting URI - using the GET method (or equivalent for non-HTTP URIs).</p> - - <p>To get the escaped version of the URI, first, the domain part of the - URI (if any) must be converted to its punycode representation, and then, - every character in the URI that is not in the ranges given in the next - paragraph must be replaced by its UTF-8 byte representation, each byte - being represented by a U+0025 (%) character and two digits in the range - U+0030 (0) to U+0039 (9) and U+0041 (A) to U+0046 (F) giving the - hexadecimal representation of the byte.</p> - - <p>The ranges of characters that must not be escaped are: U+002D (-), - U+002E (.), U+0030 (0) to U+0039 (9), U+0041 (A) to U+005A (Z), U+005F - (_), U+0061 (a) to U+007A (z), and U+007E (~).</p> - <!-- XXX move that to a common algorithms section if any other - part of the spec needs it --> - - <div class=example> - <p>If the user had visited a site that made the following call:</p> - - <pre>navigator.registerContentHandler('application/x-soup', 'http://example.com/soup?url=%s', 'SoupWeb™')</pre> - - <p>...and then clicked on a link such as:</p> - - <pre><a href="http://www.example.net/chickenkïwi.soup">Download our Chicken Kiwi soup!</a></pre> - - <p>...then, assuming this <code>chickenkiwi.soup</code> file was served - with the MIME type <code>application/x-soup</code>, the UA might - instead navigate to the following URI:</p> - - <pre>http://example.com/soup?url=http%3A%2F%2Fwww.example.net%2Fchickenk%C3%AFwi.soup</pre> - - <p>This site could then fetch the <code>chickenkiwi.soup</code> file and - do whatever it is that it does with soup (synthesise it and ship it to - the user, or whatever).</p> - </div> - - <dt><var title="">title</var> - - <dd> - <p>A descriptive title of the handler, which the UA might use to remind - the user what the site in question is.</p> - </dl> - - <p>User agents should raise <a href="#security8" title="security - exception">security exceptions</a> if the methods are called with <var - title="">protocol</var> or <var title="">mimeType</var> values that the UA - deems to be "privileged". For example, a site attempting to register a - handler for <code>http</code> URIs or <code>text/html</code> content in a - Web browser would likely cause an exception to be raised. - - <p>User agents must raise a <code>SYNTAX_ERR</code> exception if the <var - title="">uri</var> argument passed to one of these methods does not - contain the exact literal string "<code>%s</code>". - - <p>User agents must not raise any other exceptions (other than - binding-specific exceptions, such as for an incorrect number of arguments - in an ECMAScript implementation). - - <p>This section does not define how the pages registered by these methods - are used, beyond the requirements on how to process the <var - title="">uri</var> value (see above). To some extent, the <span - title="navigating across documents">processing model for navigating across - documents</span> defines some cases where these methods are relevant, but - in general UAs may use this information wherever they would otherwise - consider handing content to native plugins or helper applications. - - <p>UAs must not use registered content handlers to handle content that was - returned as part of a non-GET transaction (or rather, as part of any - non-idempotent transaction), as the remote site would not be able to fetch - the same data. - - <h5 id=security4><span class=secno>4.10.2.1. </span>Security and privacy</h5> - - <p>These mechanisms can introduce a number of concerns, in particular - privacy concerns. - - <p><strong>Hijacking all Web usage.</strong> User agents should not allow - protocols that are key to its normal operation, such as <code>http</code> - or <code>https</code>, to be rerouted through third-party sites. This - would allow a user's activities to be trivially tracked, and would allow - user information, even in secure connections, to be collected. - - <p><strong>Hijacking defaults.</strong> It is strongly recommended that - user agents do not automatically change any defaults, as this could lead - the user to send data to remote hosts that the user is not expecting. New - handlers registering themselves should never automatically cause those - sites to be used. - - <p><strong>Registration spamming.</strong> User agents should consider the - possibility that a site will attempt to register a large number of - handlers, possibly from multiple domains (e.g. by redirecting through a - series of pages each on a different domain, and each registering a handler - for <code>video/mpeg</code> — analogous practices abusing other Web - browser features have been used by pornography Web sites for many years). - User agents should gracefully handle such hostile attempts, protecting the - user. - - <p><strong>Misleading titles.</strong> User agents should not rely wholy on - the <var title="">title</var> argument to the methods when presenting the - registered handlers to the user, since sites could easily lie. For - example, a site <code>hostile.example.net</code> could claim that it was - registering the "Cuddly Bear Happy Content Handler". User agents should - therefore use the handler's domain in any UI along with any title. - - <p><strong>Hostile handler metadata.</strong> User agents should protect - against typical attacks against strings embedded in their interface, for - example ensuring that markup or escape characters in such strings are not - executed, that null bytes are properly handled, that over-long strings do - not cause crashes or buffer overruns, and so forth. - - <p><strong>Leaking Intranet URIs.</strong> The mechanism described in this - section can result in secret Intranet URIs being leaked, in the following - manner: - - <ol> - <li>The user registers a third-party content handler as the default - handler for a content type. - - <li>The user then browses his corporate Intranet site and accesses a - document that uses that content type. - - <li>The user agent contacts the third party and hands the third party the - URI to the Intranet content. - </ol> - - <p>No actual confidential file data is leaked in this manner, but the URIs - themselves could contain confidential information. For example, the URI - could be - <code>https://www.corp.example.com/upcoming-aquisitions/samples.egf</code>, - which might tell the third party that Example Corporation is intending to - merge with Samples LLC. Implementors might wish to consider allowing - administrators to disable this feature for certain subdomains, content - types, or protocols. - - <p><strong>Leaking secure URIs.</strong> User agents should not send HTTPS - URIs to third-party sites registered as content handlers, in the same way - that user agents do not send <code>Referer</code> headers from secure - sites to third-party sites. - - <p><strong>Leaking credentials.</strong> User agents must never send - username or password information in the URIs that are escaped and included - sent to the handler sites. User agents may even avoid attempting to pass - to Web-based handlers the URIs of resources that are known to require - authentication to access, as such sites would be unable to access the - resources in question without prompting the user for credentials - themselves (a practice that would require the user to know whether to - trust the third-party handler, a decision many users are unable to make or - even understand). - - <h5 id=sample-handler-impl><span class=secno>4.10.2.2. </span>Sample user - interface</h5> - - <p><em>This section is non-normative.</em> - - <p>A simple implementation of this feature for a desktop Web browser might - work as follows. - - <p>The <code title=dom-navigator-registerProtocolHandler><a - href="#registerprotocolhandler">registerProtocolHandler()</a></code> - method could display a modal dialog box: - - <pre>||[ Protocol Handler Registration ]||||||||||||||||||||||||||| -| | -| This Web page: | -| | -| Kittens at work | -| http://kittens.example.org/ | -| | -| ...would like permission to handle the protocol "x-meow:" | -| using the following Web-based application: | -| | -| Kittens-at-work displayer | -| http://kittens.example.org/?show=%s | -| | -| Do you trust the administrators of the "kittens.example. | -| org" domain? | -| | -| ( Trust kittens.example.org ) (( Cancel )) | -|____________________________________________________________|</pre> - - <p>...where "Kittens at work" is the title of the page that invoked the - method, "http://kittens.example.org/" is the URI of that page, "x-meow" is - the string that was passed to the <code - title=dom-navigator-registerProtocolHandler><a - href="#registerprotocolhandler">registerProtocolHandler()</a></code> - method as its first argument (<var title="">protocol</var>), - "http://kittens.example.org/?show=%s" was the second argument (<var - title="">uri</var>), and "Kittens-at-work displayer" was the third - argument (<var title="">title</var>). - - <p>If the user clicks the Cancel button, then nothing further happens. If - the user clicks the "Trust" button, then the handler is remembered. - - <p>When the user then attempts to fetch a URI that uses the "x-meow:" - scheme, then it might display a dialog as follows: - - <pre>||[ Unknown Protocol ]|||||||||||||||||||||||||||||||||||||||| -| | -| You have attempted to access: | -| | -| x-meow:S2l0dGVucyBhcmUgdGhlIGN1dGVzdCE%3D | -| | -| How would you like FerretBrowser to handle this resource? | -| | -| (o) Contact the FerretBrowser plugin registry to see if | -| there is an official way to handle this resource. | -| | -| ( ) Pass this URI to a local application: | -| [ /no application selected/ ] ( Choose ) | -| | -| ( ) Pass this URI to the "Kittens-at-work displayer" | -| application at "kittens.example.org". | -| | -| [ ] Always do this for resources using the "x-meow" | -| protocol in future. | -| | -| ( Ok ) (( Cancel )) | -|____________________________________________________________|</pre> - - <p>...where the third option is the one that was primed by the site - registering itself earlier. - - <p>If the user does select that option, then the browser, in accordance - with the requirements described in the previous two sections, will - redirect the user to - "http://kittens.example.org/?show=x-meow%3AS2l0dGVucyBhcmUgdGhlIGN1dGVzdCE%253D". - - <p>The <code title=dom-navigator-registerContentHandler><a - href="#registercontenthandler">registerContentHandler()</a></code> method - would work equivalently, but for unknown MIME types instead of unknown - protocols. - - <h3 id=storage><span class=secno>4.11. </span>Client-side session and - persistent storage of name/value pairs</h3> - - <h4 id=introduction0><span class=secno>4.11.1. </span>Introduction</h4> - - <p><em>This section is non-normative.</em> - - <p>This specification introduces two related mechanisms, similar to HTTP - session cookies <a href="#refsRFC2965">[RFC2965]</a>, for storing - structured data on the client side. - - <p>The first is designed for scenarios where the user is carrying out a - single transaction, but could be carrying out multiple transactions in - different windows at the same time. - - <p>Cookies don't really handle this case well. For example, a user could be - buying plane tickets in two different windows, using the same site. If the - site used cookies to keep track of which ticket the user was buying, then - as the user clicked from page to page in both windows, the ticket - currently being purchased would "leak" from one window to the other, - potentially causing the user to buy two tickets for the same flight - without really noticing. - - <p>To address this, this specification introduces the <code - title=dom-sessionStorage><a - href="#sessionstorage">sessionStorage</a></code> DOM attribute. Sites can - add data to the session storage, and it will be accessible to any page - from that domain opened in that window. - - <div class=example> - <p>For example, a page could have a checkbox that the user ticks to - indicate that he wants insurance:</p> - - <pre><label> - <input type="checkbox" onchange="sessionStorage.insurance = checked"> - I want insurance on this trip. -</label></pre> - - <p>A later page could then check, from script, whether the user had - checked the checkbox or not:</p> - - <pre>if (sessionStorage.insurance) { ... }</pre> - - <p>If the user had multiple windows opened on the site, each one would - have its own individual copy of the session storage object.</p> - </div> - <!-- - - sessionStorage.flightDeparture = 'OSL'; - sessionStorage.flightArrival = 'NYC'; - - for (var i in forms[0].elements) - sessionStorage["data_" + i.name] = i.value; - - if (!sessionStorage[documents]) - sessionStorage[documents] = {}; - sessionStorage[documents][filename] = <document/>; - - --> - - <p>The second storage mechanism is designed for storage that spans multiple - windows, and lasts beyond the current session. In particular, Web - applications may wish to store megabytes of user data, such as entire - user-authored documents or a user's mailbox, on the clientside for - performance reasons. - - <p>Again, cookies do not handle this case well, because they are - transmitted with every request. - - <p>The <code title=dom-globalStorage><a - href="#globalstorage">globalStorage</a></code> DOM attribute is used to - access the global storage areas. - - <div class=example> - <p>The site at example.com can display a count of how many times the user - has loaded its page by putting the following at the bottom of its page:</p> - - <pre><p> - You have viewed this page - <span id="count">an untold number of</span> - time(s). -</p> -<script> - var storage = globalStorage['example.com']; - if (!storage.pageLoadCount) - storage.pageLoadCount = 0; - storage.pageLoadCount = parseInt(storage.pageLoadCount, 10) + 1; - document.getElementById('count').textContent = storage.pageLoadCount; -</script></pre> - </div> - - <p>Each domain and each subdomain has its own separate storage area. - Subdomains can access the storage areas of parent domains, and domains can - access the storage areas of subdomains. - - <ul class=brief> - <li><code>globalStorage['']</code> is accessible to all domains. - - <li><code>globalStorage['com']</code> is accessible to all .com domains - - <li><code>globalStorage['example.com']</code> is accessible to example.com - and any of its subdomains - - <li><code>globalStorage['www.example.com']</code> is accessible to - www.example.com and example.com, but not www2.example.com. - </ul> - - <p>Storage areas (both session storage and global storage) store strings. - To store structured data in a storage area, you must first convert it to a - string. - - <h4 id=the-storage><span class=secno>4.11.2. </span>The <code><a - href="#storage2">Storage</a></code> interface</h4> - - <pre class=idl> -interface <dfn id=storage2>Storage</dfn> { - readonly attribute unsigned long <a href="#length7" title=dom-Storage-length>length</a>; - DOMString <a href="#keyn" title=dom-Storage-key>key</a>(in unsigned long index); - <a href="#storageitem">StorageItem</a> <a href="#getitem" title=dom-Storage-getItem>getItem</a>(in DOMString key); - void <a href="#setitem" title=dom-Storage-setItem>setItem</a>(in DOMString key, in DOMString data); - void <a href="#removeitem" title=dom-Storage-removeItem>removeItem</a>(in DOMString key); -};</pre> - - <p>Each <code><a href="#storage2">Storage</a></code> object provides access - to a list of key/value pairs, which are sometimes called items. Keys are - strings, and any string (including the empty string) is a valid key. - Values are strings with associated metadata, represented by <code><a - href="#storageitem">StorageItem</a></code> objects. - - <p>Each <code><a href="#storage2">Storage</a></code> object is associated - with a list of key/value pairs when it is created, as defined in the - sections on the <code title=dom-sessionStorage><a - href="#sessionstorage">sessionStorage</a></code> and <code - title=dom-globalStorage><a href="#globalstorage">globalStorage</a></code> - attributes. Multiple separate objects implementing the <code><a - href="#storage2">Storage</a></code> interface can all be associated with - the same list of key/value pairs simultaneously. - - <p>Key/value pairs have associated metadata. In particular, a key/value - pair can be marked as either "safe only for secure content", or as "safe - for both secure and insecure content". - - <p>A key/value pair is <dfn id=accessible title="accessible - keys">accessible</dfn> if either it is marked as "safe for both secure and - insecure content", or it is marked as "safe only for secure content" and - the script in question is running in a <span>secure browsing - context</span><!-- XXX xref -->. - - <p>The <dfn id=length7 title=dom-Storage-length><code>length</code></dfn> - attribute must return the number of key/value pairs currently present and - <a href="#accessible" title="accessible keys">accessible</a> in the list - associated with the object. - - <p>The <dfn id=keyn title=dom-Storage-key><code>key(<var - title="">n</var>)</code></dfn> method must return the name of the <var - title="">n</var>th <span>accessible</span> key in the list. The order of - keys is user-agent defined, but must be consistent within an object - between changes to the number of keys. (Thus, <a href="#setitem" - title=dom-Storage-setItem>adding</a> or <a href="#removeitem" - title=dom-Storage-removeItem>removing</a> a key may change the order of - the keys, but merely changing the value of an existing key must not.) - <!--The order of keys may differ between instances of the - <code>Storage</code> interface accessing the same list. [removed for - now for clarity, but if people ask, put it back. this is part of the - spec.]--> - If <var title="">n</var> is less than zero or greater than or equal to the - number of key/value pairs in the object, then this method must raise an - <code>INDEX_SIZE_ERR</code> exception. - - <p>The <dfn id=getitem title=dom-Storage-getItem><code>getItem(<var - title="">key</var>)</code></dfn> method must return the <code><a - href="#storageitem">StorageItem</a></code> object representing the - key/value pair with the given <var title="">key</var>. If the given <var - title="">key</var> does not exist in the list associated with the object, - or is not <span>accessible</span>, then this method must return null. - Subsequent calls to this method with the same key from scripts running in - the same <span>security context</span> must return the same instance of - the <code><a href="#storageitem">StorageItem</a></code> interface. (Such - instances must not be shared across security contexts, though.)</p> - <!-- XXX define security context --> - - <p>The <dfn id=setitem title=dom-Storage-setItem><code>setItem(<var - title="">key</var>, <var title="">value</var>)</code></dfn> method must - first check if a key/value pair with the given <var title="">key</var> - already exists in the list associated with the object. - - <p>If it does not, then a new key/value pair must be added to the list, - with the given <var title="">key</var> and <var title="">value</var>, such - that any current or future <code><a - href="#storageitem">StorageItem</a></code> objects referring to this - key/value pair will return the value given in the <var - title="">value</var> argument. If the script setting the value is running - in a <span>secure browsing context</span>, then the key/value pair must be - marked as "safe only for secure content", otherwise it must be marked as - "safe for both secure and insecure content". - - <p>If the given <var title="">key</var> <em>does</em> exist in the list, - then, if the key/value pair with the given <var title="">key</var> is - <span>accessible</span>, it must have its value updated so that any - current or future <code><a href="#storageitem">StorageItem</a></code> - objects referring to this key/value pair will return the value given in - the <var title="">value</var> argument. If it is <em>not</em> - <span>accessible</span>, the method must raise a <a - href="#security8">security exception</a>. - - <p>When the <code title=dom-Storage-setItem><a - href="#setitem">setItem()</a></code> method is successfully invoked (i.e. - when it doesn't raise an exception), events are fired on other <code><a - href="#htmldocument">HTMLDocument</a></code> objects that can access the - newly stored data, as defined in the sections on the <code - title=dom-sessionStorage><a - href="#sessionstorage">sessionStorage</a></code> and <code - title=dom-globalStorage><a href="#globalstorage">globalStorage</a></code> - attributes.</p> - <!-- - not normative, see the sections below for the normative statement - --> - - <p>The <dfn id=removeitem - title=dom-Storage-removeItem><code>removeItem(<var - title="">key</var>)</code></dfn> method must cause the key/value pair with - the given <var title="">key</var> to be removed from the list associated - with the object, if it exists and is <span>accessible</span>. If no item - with that key exists, the method must do nothing. If an item with that key - exists but is not <span>accessible</span>, the method must raise a <a - href="#security8">security exception</a>. - - <p>The <code title=dom-Storage-setItem><a - href="#setitem">setItem()</a></code> and <code - title=dom-Storage-removeItem><a href="#removeitem">removeItem()</a></code> - methods must be atomic with respect to failure. That is, changes to the - data storage area must either be successful, or the data storage area must - not be changed at all. - - <p>In the ECMAScript DOM binding, enumerating a <code><a - href="#storage2">Storage</a></code> object must enumerate through the - currently stored and <span>accessible</span> keys in the list the object - is associated with. (It must not enumerate the values or the actual - members of the interface). In the ECMAScript DOM binding, <code><a - href="#storage2">Storage</a></code> objects must support dereferencing - such that getting a property that is not a member of the object (i.e. is - neither a member of the <code><a href="#storage2">Storage</a></code> - interface nor of <code title=dom-Object>Object</code>) must invoke the - <code title=dom-Storage-getItem><a href="#getitem">getItem()</a></code> - method with the property's name as the argument, and setting such a - property must invoke the <code title=dom-Storage-setItem><a - href="#setitem">setItem()</a></code> method with the property's name as - the first argument and the given value as the second argument. - - <h4 id=the-storageitem><span class=secno>4.11.3. </span>The <code><a - href="#storageitem">StorageItem</a></code> interface</h4> - - <p>Items in <code><a href="#storage2">Storage</a></code> objects are - represented by objects implementing the <code><a - href="#storageitem">StorageItem</a></code> interface. - - <pre class=idl> -interface <dfn id=storageitem>StorageItem</dfn> { - attribute boolean <a href="#secure" title=dom-StorageItem-secure>secure</a>; - attribute DOMString <a href="#value7" title=dom-StorageItem-value>value</a>; -};</pre> - - <p>In the ECMAScript DOM binding, <code><a - href="#storageitem">StorageItem</a></code> objects must stringify to their - <code title=dom-StorageItem-value><a href="#value7">value</a></code> - attribute's value. - - <p>The <dfn id=value7 title=dom-StorageItem-value><code>value</code></dfn> - attribute must return the current value of the key/value pair represented - by the object. When the attribute is set, the user agent must invoke the - <code title=dom-Storage-setItem><a href="#setitem">setItem()</a></code> - method of the <code><a href="#storage2">Storage</a></code> object that the - <code><a href="#storageitem">StorageItem</a></code> object is associated - with, with the key that the <code><a - href="#storageitem">StorageItem</a></code> object is associated with as - the first argument, and the new given value of the attribute as the second - argument. - - <p><code><a href="#storageitem">StorageItem</a></code> objects must be - <em><a href="#live">live</a></em>, meaning that as the underlying <code><a - href="#storage2">Storage</a></code> object has its key/value pairs - updated, the <code><a href="#storageitem">StorageItem</a></code> objects - must always return the actual value of the key/value pair they represent. - - <p>If the key/value pair has been deleted, the <code><a - href="#storageitem">StorageItem</a></code> object must act as if its value - was the empty string. On setting, the key/value pair will be recreated. - - <p>The <dfn id=secure - title=dom-StorageItem-secure><code>secure</code></dfn> attribute must - raise an <code>INVALID_ACCESS_ERR</code> exception when accessed or set - from a script whose browsing context is not <span title="secure browsing - context">considered secure</span><!-- - XXX xref -->. (Basically, if the - page is not an SSL page.) - - <p>If the browsing context <em>is</em> secure, then the <code - title=dom-StorageItem-secure><a href="#secure">secure</a></code> attribute - must return true if the key/value pair is considered "safe only for secure - content", and false if it is considered "safe for both secure and insecure - content". If it is set to true, then the key/value pair must be flagged as - "safe only for secure content". If it is set to false, then the key/value - pair must be flagged as "safe for both secure and insecure content". - - <p>If a <code><a href="#storageitem">StorageItem</a></code> object is - obtained by a script that is not running in a <span>secure browsing - context</span>, and the item is then marked with the "safe only for secure - content" flag by a script that <em>is</em> running in a secure context, - the <code><a href="#storageitem">StorageItem</a></code> object must - continue to be available to the first script, who will be able to read the - value of the object. However, any attempt to <em>set</em> the value would - then start raising exceptions as described in the previous section, and - the key/value pair would no longer appear in the appropriate <code><a - href="#storage2">Storage</a></code> object. - - <h4 id=the-sessionstorage><span class=secno>4.11.4. </span>The <code - title=dom-sessionStorage><a - href="#sessionstorage">sessionStorage</a></code> attribute</h4> - - <p>The <dfn id=sessionstorage - title=dom-sessionStorage><code>sessionStorage</code></dfn> attribute - represents the storage area specific to the current <a - href="#top-level">top-level browsing context</a>. - - <p>Each <a href="#top-level">top-level browsing context</a> has a unique - set of session storage areas, one for each domain. - - <p>User agents should not expire data from a browsing context's session - storage areas, but may do so when the user requests that such data be - deleted, or when the UA detects that it has limited storage space, or for - security reasons. User agents should always avoid deleting data while a - script that could access that data is running. When a top-level browsing - context is destroyed (and therefore permanently inaccessible to the user) - the data stored in its session storage areas can be discarded with it, as - the API described in this specification provides no way for that data to - ever be subsequently retrieved. - - <p class=note>The lifetime of a browsing context can be unrelated to the - lifetime of the actual user agent process itself, as the user agent may - support resuming sessions after a restart. - - <p>When a new <code><a href="#htmldocument">HTMLDocument</a></code> is - created, the user agent must check to see if the document's <a - href="#top-level">top-level browsing context</a> has allocated a session - storage area for that <a href="#domain0">document's domain</a>. If it has - not, a new storage area for that document's domain must be created. - - <p>The <code><a href="#storage2">Storage</a></code> object for the - document's associated <code><a href="#window">Window</a></code> object's - <code title=dom-sessionStorage><a - href="#sessionstorage">sessionStorage</a></code> attribute must then be - associated with the domain's session storage area. - - <p>When a new <a href="#top-level">top-level browsing context</a> is - created by cloning an existing <a href="#browsing0">browsing context</a>, - the new browsing context must start with the same session storage areas as - the original, but the two sets must from that point on be considered - separate, not affecting each other in any way. - - <p>When a new <a href="#top-level">top-level browsing context</a> is - created by a script in an existing <a href="#browsing0">browsing - context</a>, or by the user following a link in an existing browsing - context, or in some other way related to a specific <code><a - href="#htmldocument">HTMLDocument</a></code>, then, if the new context's - first <code><a href="#htmldocument">HTMLDocument</a></code> has the same - <a href="#domain0" title="document's domain">domain</a> as the <code><a - href="#htmldocument">HTMLDocument</a></code> from which the new context - was created, the new browsing context must start with a single session - storage area. That storage area must be a copy of that domain's session - storage area in the original browsing context, which from that point on - must be considered separate, with the two storage areas not affecting each - other in any way.</p> - <!-- XXX define the case for window.open() --> - - <p id=sessionStorageEvent>When the <code title=dom-Storage-setItem><a - href="#setitem">setItem()</a></code> method is called on a <code><a - href="#storage2">Storage</a></code> object <var title="">x</var> that is - associated with a session storage area, then, if the method does not raise - a <a href="#security8">security exception</a>, in every <code><a - href="#htmldocument">HTMLDocument</a></code> object whose <code><a - href="#window">Window</a></code> object's <code - title=dom-sessionStorage><a - href="#sessionstorage">sessionStorage</a></code> attribute's <code><a - href="#storage2">Storage</a></code> object is associated with the same - storage area, other than <var title="">x</var>, a <code - title=event-storage><a href="#storage3">storage</a></code> event must be - fired, as <a href="#storage3" title=event-storage>described below</a>. - - <h4 id=the-globalstorage><span class=secno>4.11.5. </span>The <code - title=dom-globalStorage><a href="#globalstorage">globalStorage</a></code> - attribute</h4> - - <pre class=idl>interface <dfn id=storagelist>StorageList</dfn> { - <a href="#storage2">Storage</a> <a href="#nameditem2" title=dom-Storagelist-namedItem>namedItem</a>(in DOMString domain); -};</pre> - - <p>The <dfn id=globalstorage - title=dom-globalStorage><code>globalStorage</code></dfn> object provides a - <code><a href="#storage2">Storage</a></code> object for each domain. - - <p>In the ECMAScript DOM binding, <code><a - href="#storagelist">StorageList</a></code> objects must support - dereferencing such that getting a property that is not a member of the - object (i.e. is neither a member of the <code><a - href="#storagelist">StorageList</a></code> interface nor of <code - title=dom-Object>Object</code>) must invoke the <code - title=dom-Storagelist-namedItem><a - href="#nameditem2">namedItem()</a></code> method with the property's name - as the argument. - - <p>User agents must have a set of global storage areas, one for each - domain. - - <p>User agents should only expire data from the global storage areas for - security reasons or when requested to do so by the user. User agents - should always avoid deleting data while a script that could access that - data is running. Data stored in global storage areas should be considered - potentially user-critical. It is expected that Web applications will use - the global storage areas for storing user-written documents. - - <p>The <dfn id=nameditem2 - title=dom-Storagelist-namedItem><code>namedItem(<var - title="">domain</var>)</code></dfn> method tries to returns a <code><a - href="#storage2">Storage</a></code> object associated with the given - domain, according to the rules that follow. - - <div id=splitDomain> - <p>The <var title="">domain</var> must first be split into an array of - strings, by splitting the string at "." characters (U+002E FULL STOP). If - the <var title="">domain</var> argument is the empty string, then the - array is empty as well. If the <var title="">domain</var> argument is not - empty but has no dots, then the array has one item, which is equal to the - <var title="">domain</var> argument. If the <var title="">domain</var> - argument contains consecutive dots, there will be empty strings in the - array (e.g. the string "hello..world" becomes split into the three - strings "hello", "", and "world", with the middle one being the empty - string).</p> - - <p>Each component of the array must then have the IDNA ToASCII algorithm - applied to it, with both the AllowUnassigned and UseSTD3ASCIIRules flags - set. <a href="#refsRFC3490">[RFC3490]</a> If ToASCII fails to convert one - of the components of the string, e.g. because it is too long or because - it contains invalid characters, then the user agent must raise a - <code>SYNTAX_ERR</code> exception. <a href="#refsDOM3CORE">[DOM3CORE]</a> - The components after this step consist of only US-ASCII characters.</p> - - <p>The components of the array must then be converted to lowercase. Since - only US-ASCII is involved at this step, this only requires converting - characters in the range A-Z to the corresponding characters in the range - a-z.</p> - </div> - - <p>The resulting array is used in a comparison with another array, as - described below. In addition, its components are concatenated together, - each part separated by a dot (U+002E), to form the <dfn - id=normalised0>normalised requested domain</dfn>. - - <p class=example>If the original <var title="">domain</var> was - "Åsgård.Example.Com", then the resulting array would have the - three items "xn--sgrd-poac", "example", and "com", and the normalised - requested domain would be "xn--sgrd-poac.example.com". - - <p>Next, the domain part of the tuple forming the calling script's <a - href="#origin0">origin</a> is processed to find if it is allowed to access - the requested domain. - - <p>If the script's origin has no domain part, e.g. if only the server's IP - address is known, and the <a href="#normalised0">normalised requested - domain</a> is not the empty string, then the user agent must raise a <a - href="#security8">security exception</a>. - - <p class=note>If the <a href="#normalised0">normalised requested domain</a> - is the empty string, then the rest of this algorithm can be skipped. This - is because in that situation, the comparison of the two arrays below will - always find them to be the same — the first array in such a - situation is also empty and so permission to access that storage area will - always be given. - - <p>If the domain part of the script's origin contains no dots (U+002E) then - the string "<code>.localdomain</code>" must be appended to the script's - domain. - - <p>Then, the domain part of the script's origin must be turned into an - array, being split, converted to ASCII, and lowercased as described for - the <var title="">domain</var> argument <a href="#splitDomain">above</a>. - - <p>Of the two arrays, the longest one must then be shortened to the length - of the shorter one, by dropping items from the start of the array. - - <div class=example> - <p>If the <var title="">domain</var> argument is "www.example.com" and the - script origin's domain part is "example.com" then the first array will be - a three item array ("www", "example", "com"), and the second will be a - two item array ("example", "com"). The first array is therefore - shortened, dropping the leading parts, making both into the same array - ("example", "com").</p> - </div> - - <p>If the two arrays are not component-for-component identical in literal - string comparisons, then the user agent must then raise a <a - href="#security8">security exception</a>. - - <p>Otherwise, the user agent must check to see if it has allocated global - storage area for the <a href="#normalised0">normalised requested - domain</a>. If it has not, a new storage area for that domain must be - created. - - <p>The user agent must then create a <code><a - href="#storage2">Storage</a></code> object associated with that domain's - global storage area, and return it. - - <p>When the requested <var title="">domain</var> is a top level domain, or - the empty string, or a country-specific sub-domain like "co.uk" or - "ca.us", the associated global storage area is known as <dfn - id=public0>public storage area</dfn> - - <div id=globalStorageEvent> - <p>The <code title=dom-Storage-setItem><a - href="#setitem">setItem()</a></code> method might be called on a <code><a - href="#storage2">Storage</a></code> object that is associated with a - global storage area for a domain <var title="">d</var>, created by a - <code><a href="#storagelist">StorageList</a></code> object associated - with a <code><a href="#window">Window</a></code> object <var - title="">x</var>. Whenever this occurs, if the method didn't raise an - exception, a <code title=event-storage><a - href="#storage3">storage</a></code> event must be fired, as described - below, in every <code><a href="#htmldocument">HTMLDocument</a></code> - object that matches the following conditions:</p> - - <ul> - <li>Its <code><a href="#window">Window</a></code> object is not <var - title="">x</var>, and - - <li>Its <code><a href="#window">Window</a></code> object's <code - title=dom-sessionStorage><a - href="#sessionstorage">globalStorage</a></code> attribute's <code><a - href="#storagelist">StorageList</a></code> object's <code - title=dom-Storagelist-namedItem><a - href="#nameditem2">namedItem()</a></code> method would not raise a <a - href="#security8">security exception</a> according to the rules above if - it was invoked with the domain <var title="">d</var>. - </ul> - - <p>In other words, every other document that has access to that domain's - global storage area is notified of the change.</p> - </div> - - <h4 id=the-storage0><span class=secno>4.11.6. </span>The <code - title=event-storage><a href="#storage3">storage</a></code> event</h4> - - <p>The <dfn id=storage3 title=event-storage><code>storage</code></dfn> - event is fired in an <code><a href="#htmldocument">HTMLDocument</a></code> - when a storage area changes, as described in the previous two sections (<a - href="#sessionStorageEvent">for session storage</a>, <a - href="#globalStorageEvent">for global storage</a>). - - <p>When this happens, a <code><a href="#storage2">storage</a></code> event - in no namespace, which bubbles, is not cancelable, has no default action, - and which uses the <code><a href="#storageevent">StorageEvent</a></code> - interface described below, must be fired on <a href="#the-body0">the body - element</a>. - - <p>However, it is possible (indeed, for session storage areas, likely) that - the target <code><a href="#htmldocument">HTMLDocument</a></code> object is - not active at that time. For example, it might not be the <a - href="#current0">current entry</a> in the session history; user agents - typically stop scripts from running in pages that are in the history. In - such cases, the user agent must instead delay the firing of the event - until such time as the <code><a - href="#htmldocument">HTMLDocument</a></code> object in question becomes - active again. - - <p>When there are multiple delayed <code><a - href="#storage2">storage</a></code> events for the same <code><a - href="#htmldocument">HTMLDocument</a></code> object, user agents should - coalesce events with the same <code title=dom-Storageevent-domain><a - href="#domain1">domain</a></code> value (dropping duplicates). - - <p>If the DOM of a page that has delayed <code><a - href="#storage2">storage</a></code> events queued up is <a href="#discard" - title=discard>discarded</a>, then the delayed events are dropped as well. - - <pre class=idl>interface <dfn id=storageevent>StorageEvent</dfn> : Event { - readonly attribute DOMString <a href="#domain1" title=dom-StorageEvent-domain>domain</a>; - void <a href="#initstorageevent" title=dom-StorageEvent-initStorageEvent>initStorageEvent</a>(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString domainArg); - void <a href="#initstorageeventns" title=dom-StorageEvent-initStorageEventNS>initStorageEventNS</a>(in DOMString namespaceURIArg, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString domainArg); -};</pre> - - <p>The <dfn id=initstorageevent - title=dom-StorageEvent-initStorageEvent><code>initStorageEvent()</code></dfn> - and <dfn id=initstorageeventns - title=dom-StorageEvent-initStorageEventNS><code>initStorageEventNS()</code></dfn> - methods must initialise the event in a manner analogous to the - similarly-named methods in the DOM3 Events interfaces. <a - href="#refsDOM3EVENTS">[DOM3EVENTS]</a> - - <p>The <dfn id=domain1 - title=dom-StorageEvent-domain><code>domain</code></dfn> attribute of the - <code><a href="#storageevent">StorageEvent</a></code> event object must be - set to the name of the domain associated with the storage area that - changed if that storage area is a global storage area, or the string - "<code>#session</code>" if it was a session storage area.</p> - <!-- XXX onstorage should be defined --> - - <h4 id=miscellaneous0><span class=secno>4.11.7. </span>Miscellaneous - implementation requirements for storage areas</h4> - - <h5 id=disk-space><span class=secno>4.11.7.1. </span>Disk space</h5> - - <p>User agents should limit the total amount of space allowed for a domain - based on the domain of the page setting the value. - - <p>User agents should not limit the total amount of space allowed on a - per-storage-area basis, otherwise a site could just store data in any - number of subdomains, e.g. storing up to the limit in a1.example.com, - a2.example.com, a3.example.com, etc, circumventing per-domain limits. - - <p>User agents should consider additional quota mechanisms (for example - limiting the amount of space provided to a domain's subdomains as a group) - so that hostile authors can't run scripts from multiple subdomains all - adding data to the global storage area in an attempted denial-of-service - attack. - - <p>User agents may prompt the user when per-domain space quotas are - reached, allowing the user to grant a site more space. This enables sites - to store many user-created documents on the user's computer, for instance. - - <p>User agents should allow users to see how much space each domain is - using. - - <p>If the storage area space limit is reached during a <code - title=dom-Storage-setItem><a href="#setitem">setItem()</a></code> call, - the user agent should raise an exception.</p> - <!-- XXX which one? --> - - <p>A mostly arbitrary limit of five megabytes per domain is recommended. - Implementation feedback is welcome and will be used to update this - suggestion in future. - - <h5 id=threads0><span class=secno>4.11.7.2. </span>Threads</h5> - - <p>Multiple browsing contexts must be able to access the global storage - areas simultaneously in a predictable manner. Scripts must not be able to - detect any concurrent script execution. - - <p>This is required to guarentee that the <code title=dom-Storage-length><a - href="#length7">length</a></code> attribute of a <code><a - href="#storage2">Storage</a></code> object never changes while a script is - executing, other than in a way that is predictable by the script itself. - - <p>There are various ways of implementing this requirement. One is that if - a script running in one browsing context accesses a global storage area, - the UA blocks scripts in other browsing contexts when they try to access - <em>any</em> global storage area until the first script has executed to - completion. (Similarly, when a script in one browsing context accesses its - session storage area, any scripts that have the same top level browsing - context and the same domain would block when accessing their session - storage area until the first script has executed to completion.) Another - (potentially more efficient but probably more complex) implementation - strategy is to use optimistic transactional script execution. This - specification does not require any particular implementation strategy, so - long as the requirement above is met. - - <h4 id=security5><span class=secno>4.11.8. </span>Security and privacy</h4> - - <h5 id=user-tracking><span class=secno>4.11.8.1. </span>User tracking</h5> - - <p>A third-party advertiser (or any entity capable of getting content - distributed to multiple sites) could use a unique identifier stored in its - domain's global storage area to track a user across multiple sessions, - building a profile of the user's interests to allow for highly targeted - advertising. In conjunction with a site that is aware of the user's real - identity (for example an e-commerce site that requires authenticated - credentials), this could allow oppressive groups to target individuals - with greater accuracy than in a world with purely anonymous Web usage. - - <p>The <code title=dom-globalStorage><a - href="#globalstorage">globalStorage</a></code> object also introduces a - way for sites to cooperate to track users over multiple domains, by - storing identifying data in "<a href="#public0" title="public storage - area">public</a>" top-level domain storage area, accessible by any domain. - - <p>There are a number of techniques that can be used to mitigate the risk - of user tracking: - - <ul> - <li> - <p>Blocking third-party storage: user agents may restrict access to the - <code title=dom-globalStorage><a - href="#globalstorage">globalStorage</a></code> object to scripts - originating at the domain of the top-level document of the <a - href="#browsing0">browsing context</a>.</p> - - <p>This blocks a third-party site from using its private storage area for - tracking a user, but top-level sites could still cooperate with third - parties to perferm user tracking by using the "<a href="#public0" - title="public storage area">public</a>" storage area.</p> - - <li> - <p>Expiring stored data: user agents may automatically delete stored data - after a period of time.</p> - - <p>For example, a user agent could treat the global storage area as - session-only storage, deleting the data once the user had closed all the - <span>browsing contexts</span> that could access it.</p> - - <p>This can restrict the ability of a site to track a user, as the site - would then only be able to track the user across multiple sessions when - he authenticates with the site itself (e.g. by making a purchase or - logging in to a service).</p> - <!-- XXX should there be an explicit way for sites to state when - data should expire? as in - globalStorage['example.com'].expireData(365); ? --> - - - <li> - <p>Blocking access to the top-level domain ("<a href="#public0" - title="public storage area">public</a>") storage areas: user agents may - prevent domains from storing data in and reading data from the top-level - domain entries in the <code title=dom-globalStorage><a - href="#globalstorage">globalStorage</a></code> object.</p> - - <p>In practice this requires a detailed list of all the "public" - second-level (and third-level) domains. For example, content at the - domain <code>www.example.com</code> would be allowed to access - <code>example.com</code> data but not <code>com</code> data; content at - the domain <code>example.co.uk</code> would be allowed access to - <code>example.co.uk</code> but not <code>co.uk</code> or - <code>uk</code>; and content at <code>example.chiyoda.tokyo.jp</code> - would be allowed access to <code>example.chiyoda.tokyo.jp</code> but not - <code>chiyoda.tokyo.jp</code>, <code>tokyo.jp</code>, or - <code>jp</code>, while content at <code>example.metro.tokyo.jp</code> - would be allowed access to both <code>example.metro.tokyo.jp</code> and - <code>metro.tokyo.jp</code> but not <code>tokyo.jp</code> or - <code>jp</code>. The problem is even more convoluted when one considers - private domains with third-party subdomains such as - <code>dyndns.org</code> or <code>uk.com</code>.</p> - - <p>Blocking access to the "<a href="#public0" title="public storage - area">public</a>" storage areas can also prevent innocent sites from - cooperating to provide services beneficial to the user.</p> - - <li> - <p>Treating persistent storage as cookies: user agents may present the - persistent storage feature to the user in a way that does not - distinguish it from HTTP session cookies. <a - href="#refsRFC2965">[RFC2965]</a></p> - - <p>This might encourage users to view persistent storage with healthy - suspicion.</p> - - <li> - <p>Site-specific white-listing of access to "<a href="#public0" - title="public storage area">public</a>" storage area: user agents may - allow sites to access persistent storage for their own domain and - subdomains in an unrestricted manner, but require the user to authorise - access to the storage area of higher-level domains.</p> - - <p>For example, code at <code>example.com</code> would be always allowed - to read and write data for <code>www.example.com</code> and - <code>example.com</code>, but if it tried to access <code>com</code>, - the user agent could display a non-modal message informing the user that - the page requested access to <code>com</code> and offering to allow it.</p> - - <li> - <p>Origin-tracking of persistent storage data: user agents may record the - domain of the script that caused data to be stored.</p> - - <p>If this information is then used to present the view of data currently - in persistent storage, it would allow the user to make informed - decisions about which parts of the persistent storage to prune. Combined - with a blacklist ("delete this data and prevent this domain from ever - storing data again"), the user can restrict the use of persistent - storage to sites that he trusts.</p> - - <li> - <p>Shared blacklists: user agents may allow users to share their - persistent storage domain blacklists.</p> - - <p>This would allow communities to act together to protect their privacy.</p> - </ul> - - <p>While these suggestions prevent trivial use of this API for user - tracking, they do not block it altogether. Within a single domain, a site - can continue to track the user across multiple sessions, and can then pass - all this information to the third party along with any identifying - information (names, credit card numbers, addresses) obtained by the site. - If a third party cooperates with multiple sites to obtain such - information, a profile can still be created. - - <p>However, user tracking is to some extent possible even with no - cooperation from the user agent whatsoever, for instance by using session - identifiers in URIs, a technique already commonly used for innocuous - purposes but easily repurposed for user tracking (even retroactively). - This information can then be shared with other sites, using using - visitors' IP addresses and other user-specific data (e.g. user-agent - headers and configuration settings) to combine separate sessions into - coherent user profiles. - - <h5 id=cookie><span class=secno>4.11.8.2. </span>Cookie resurrection</h5> - - <p>If the user interface for persistent storage presents data in the - persistent storage feature separately from data in HTTP session cookies, - then users are likely to delete data in one and not the other. This would - allow sites to use the two features as redundant backup for each other, - defeating a user's attempts to protect his privacy. - - <h5 id=integrity><span class=secno>4.11.8.3. </span>Integrity of "public" - storage areas</h5> - - <p>Since the "<a href="#public0" title="public storage area">public</a>" - global storage areas are accessible by content from many different - parties, it is possible for third-party sites to delete or change - information stored in those areas in ways that the originating sites may - not expect. - - <p>Authors must not use the "<a href="#public0" title="public storage - area">public</a>" global storage areas for storing sensitive data. Authors - must not trust information stored in "<a href="#public0" title="public - storage area">public</a>" global storage areas. - - <h5 id=cross-protocol><span class=secno>4.11.8.4. </span>Cross-protocol and - cross-port attacks</h5> - - <p>This API makes no distinction between content served over HTTP, FTP, or - other host-based protocols, and does not distinguish between content - served from different ports at the same host. - - <p>Thus, for example, data stored in the global persistent storage for - domain "www.example.com" by a page served from HTTP port 80 will be - available to a page served in <code>http://example.com:18080/</code>, even - if the latter is an experimental server under the control of a different - user. - - <p>Since the data is not sent over the wire by the user agent, this is not - a security risk in its own right. However, authors must take proper steps - to ensure that all hosts that have fully qualified host names that are - subsets of hosts dealing with sensitive information are as secure as the - originating hosts themselves. - - <p>Similarly, authors must ensure that all Web servers on a host, - regardless of the port, are equally trusted if any of them are to use - persistent storage. For instance, if a Web server runs a production - service that makes use of the persistent storage feature, then other users - that have access to that machine and that can run a Web server on another - port will be able to access the persistent storage added by the production - service (assuming they can trick a user into visiting their page). - - <p>However, if one is able to trick users into visiting a Web server with - the same host name but on a different port as a production service used by - these users, then one could just as easily fake the look of the site and - thus trick users into authenticating with the fake site directly, - forwarding the request to the real site and stealing the credentials in - the process. Thus, the persistent storage feature is considered to only - minimally increase the risk involved. - - <p class=big-issue>What about if someone is able to get a server up on a - port, and can then send people to that URI? They could steal all the data - with no further interaction. How about putting the port number at the end - of the string being compared? (Implicitly.) - - <h5 id=dns-spoofing><span class=secno>4.11.8.5. </span>DNS spoofing attacks</h5> - - <p>Because of the potential for DNS spoofing attacks, one cannot guarentee - that a host claiming to be in a certain domain really is from that domain. - The <code title=dom-StorageItem-secure><a href="#secure">secure</a></code> - attribute is provided to mark certain key/value pairs as only being - accessible to pages that have been authenticated using secure certificates - (or similar mechanisms). - - <p>Authors must ensure that they do not mark sensitive items as "safe for - both secure and insecure content". (To prevent the risk of a race - condition, data stored by scripts in secure contexts default to being - marked as "safe only for secure content".) - - <h5 id=cross-directory><span class=secno>4.11.8.6. </span>Cross-directory - attacks</h5> - - <p>Different authors sharing one host name, for example users hosting - content on <code>geocities.com</code>, all share one persistent storage - object. There is no feature to restrict the access by pathname. Authors on - shared hosts are therefore recommended to avoid using the persistent - storage feature, as it would be trivial for other authors to read from and - write to the same storage area. - - <p class=note>Even if a path-restriction feature was made available, the - usual DOM scripting security model would make it trivial to bypass this - protection and access the data from any path. - - <h5 id=public><span class=secno>4.11.8.7. </span>Public storage areas - corresponding to hosts</h5> - - <p>If a "<a href="#public0" title="public storage area">public</a>" global - storage area corresponds to a host, as it typically does if for private - domains with third-party subdomains such as dyndns.org or uk.com, the host - corresponding to the "public" domain has access to all the storage areas - of its third-party subdomains. In general, authors are discouraged from - using the <code title=dom-globalStorage><a - href="#globalstorage">globalStorage</a></code> API for sensitive data - unless the operators of all the domains involved are trusted. - - <p>User agents may mitigate this problem by preventing hosts corresponding - to "<a href="#public0" title="public storage area">public</a>" global - storage areas from accessing any storage areas other than their own. - - <h5 id=storage0><span class=secno>4.11.8.8. </span>Storage areas in the - face of untrusted higher-level domains that do not correspond to public - storage areas</h5> - - <p>Authors should not store sensitive data using the global storage APIs if - there are hosts with fully-qualified domain names that are subsets of - their own which they do not trust. For example, an author at - <code>finance.members.example.net</code> should not store sensitive - financial user data in the <code>finance.members.example.net</code> - storage area if he does not trust the host that runs - <code>example.net</code>. - - <h5 id=storage1><span class=secno>4.11.8.9. </span>Storage areas in the - face of untrusted subdomains</h5> - - <p>If an author publishing content on one host, e.g. - <code>example.com</code>, wishes to use the <code - title=dom-globalStorage><a href="#globalstorage">globalStorage</a></code> - API but does not wish any content on the host's subdomains to access the - data, the author should use an otherwise non-existent subdomain name, - e.g., <code>private.example.com</code>, to store the data. This will be - accessible only to that host (and its parent domains), and not to any of - the real subdomains (e.g. <code>upload.example.com</code>). - - <h5 id=implementation><span class=secno>4.11.8.10. </span>Implementation - risks</h5> - - <p>The two primary risks when implementing this persistent storage feature - are letting hostile sites read information from other domains, and letting - hostile sites write information that is then read from other domains. - - <p>Letting third-party sites read data that is not supposed to be read from - their domain causes <em>information leakage</em>, For example, a user's - shopping wishlist on one domain could be used by another domain for - targeted advertising; or a user's work-in-progress confidential documents - stored by a word-processing site could be examined by the site of a - competing company. - - <p>Letting third-party sites write data to the storage areas of other - domains can result in <em>information spoofing</em>, which is equally - dangerous. For example, a hostile site could add items to a user's - wishlist; or a hostile site could set a user's session identifier to a - known ID that the hostile site can then use to track the user's actions on - the victim site. - - <p>A risk is also presented by servers on local domains having host names - matching top-level domain names, for instance having a host called "com" - or "net". Such hosts might, if implementations fail to correctly implement - the <code>.localdomain</code> suffixing, <!-- XXX cross ref --> have full - access to all the data stored in a UA's persistent storage for that top - level domain. - - <p>Thus, strictly following the model described in this specification is - important for user security. - - <p>In addition, a number of optional restrictions related to the "<a - href="#public0" title="public storage area">public</a>" global storage - areas are suggested in the previous sections. The design of this API is - intended to be such that not supporting these restrictions, or supporting - them less than perfectly, does not result in critical security problems. - However, implementations are still encouraged to create and maintain a - list of "<a href="#public0" title="public storage area">public</a>" - domains, and apply the restrictions described above. - - <h3 id=sql><span class=secno>4.12. </span>Client-side database storage</h3> - - <h4 id=introduction1><span class=secno>4.12.1. </span>Introduction</h4> - - <p class=big-issue>... - - <h4 id=executing><span class=secno>4.12.2. </span>Executing SQL statements</h4> - - <p>Each <a href="#origin0">origin</a> must have an associated database - unique to that origin. An author can interact with the database using the - <code title=dom-executeSql><a href="#executesql">executeSql()</a></code> - method. - - <p>When the <dfn id=executesql title=dom-executeSql><code>executeSql(<var - title="">sqlStatement</var>, <var - title="">arguments...</var>)</code></dfn> method is invoked, the user - agent must first interpret the first argument to the method (<var - title="">sqlStatement</var>) as an SQL statement, replacing any <code - title="">?</code> placeholders in the statement with the values given in - the subsequent arguments (<var title="">arguments...</var>), and must then - evaluate the statement as an SQL statement in the context of the database - associated with the <a href="#origin0">origin</a> of the <a - href="#active">active document</a> of the <a href="#browsing0">browsing - context</a> of the <code><a href="#window">Window</a></code> object on - which the method was called. <a href="#refsSQL">[SQL]</a> - - <p>If the <code title=dom-executeSql><a - href="#executesql">executeSql()</a></code> method is called with a - different number of arguments after the statement than there are - placeholder <code title="">?</code> characters in the statement, then the - method must raise a <code>SYNTAX_ERR</code> exception. - - <p>Otherwise, the method must return a <code><a - href="#resultset">ResultSet</a></code> object representing the result of - the operation. - - <p>The user agent must act as if the database was hosted in an otherwise - completely empty environment with no resources. For example, attempts to - read from or write to the filesystem will fail. - - <p>User agents should limit the total amount of space allowed for each - origin, but may prompt the user and extend the limit if a database is - reaching its quota. User agents should allow users to see how much space - each database is using. - - <p>A mostly arbitrary limit of five megabytes per origin is recommended. - Implementation feedback is welcome and will be used to update this - suggestion in future. - - <p>SQL inherently supports multiple concurrent connections. Authors should - make use of SQL's transaction features if multiple scripts are expected to - interact with the same database simultaneously (as could happen if the - same page was opened in two different <a href="#browsing0" title="browsing - context">browsing contexts</a>). - - <p class=note>A future version of this specification may define the exact - SQL subset required in more detail. - - <h4 id=database><span class=secno>4.12.3. </span>Database query results</h4> - - <p>Calls to the <code title=dom-executeSql><a - href="#executesql">executeSql()</a></code> method return <code><a - href="#resultset">ResultSet</a></code> objects. - - <pre class=idl>interface <dfn id=resultset>ResultSet</dfn> { - // cursor - readonly attribute boolean <a href="#validrow" title=dom-ResultSet-validRow>validRow</a>; - void <a href="#next0" title=dom-ResultSet-next>next</a>(); - - // current row accessors - readonly attribute unsigned int <a href="#length8" title=dom-ResultSet-length>length</a>; - DOMString <a href="#getname" title=dom-ResultSet-getName>getName</a>(in unsigned int field); - Object <a href="#itemfield" title=dom-ResultSet-item>item</a>(in unsigned int field); - Object <a href="#nameditem3" title=dom-ResultSet-namedItem>namedItem</a>(in DOMString field); - - // general result accessors - readonly attribute int <a href="#insertid" title=dom-ResultSet-insertId>insertId</a>; -};</pre> - - <p>A <code><a href="#resultset">ResultSet</a></code> object has a cursor - which visits the results of a SQL statement, in the order returned. - Initially, the cursor must point at the first row returned by the - statement, if any. Once a row has been visited, it cannot be visited again - (the cursor cannot go backwards). - - <p>The <dfn id=validrow - title=dom-ResultSet-validRow><code>validRow</code></dfn> attribute must - return return true if the <code><a href="#resultset">ResultSet</a></code> - object's cursor is at a row with data. If the cursor has been moved beyond - the last row of the results, or if there were no results for the SQL - statement in question, then the method must return false. - - <p>The <dfn id=next0 title=dom-ResultSet-next><code>next()</code></dfn> - method must advance the cursor to the next row. If there are no more rows - it must advance the cursor past the end of the results, so that <code - title=dom-ResultSet-validRow><a href="#validrow">validRow</a></code> will - return false. - - <p>Each row of the results consists of a set of fields. Each field has a - name and a value. The fields are ordered. The names of the fields, and - their order, must be the same for every row in the results. - - <p>The <dfn id=length8 title=dom-ResultSet-length><code>length</code></dfn> - attribute must return the number of fields in each row. If the <code><a - href="#resultset">ResultSet</a></code> object has no results rows (i.e. if - the SQL statement executed did not return any results) then the attribute - must return zero. - - <p>The <dfn id=getname title=dom-ResultSet-getName><code>getName(<var - title="">field</var>)</code></dfn> method must return the name of the - field with index <var title="">field</var>. - - <p>The <dfn id=itemfield title=dom-ResultSet-item><code>item(<var - title="">field</var>)</code></dfn> method must return the value of the - field with index <var title="">field</var>. In the ECMAScript binding, the - object's [[Get]] method, when invoked with a numeric argument, must have - the same effect as calling the <code title=dom-ResultSet-item><a - href="#itemfield">item()</a></code> method. - - <p>If the <var title="">field</var> argument of either the <code - title=dom-ResultSet-getName><a href="#getname">getName()</a></code> or - <code title=dom-ResultSet-item><a href="#itemfield">item()</a></code> - methods is ever less than zero or greater than or equal to the number of - fields in each row, or if those methods are called when the <code><a - href="#resultset">ResultSet</a></code> object has no results rows, the - methods must instead raise an <code>INDEX_SIZE_ERR</code> exception. - - <p>The <dfn id=nameditem3 - title=dom-ResultSet-namedItem><code>namedItem(<var - title="">field</var>)</code></dfn> method must return the value of the - field with the name <var title="">field</var>. If there is no field with - that name, the method must instead raise a <code>SYNTAX_ERR</code> - exception. In the ECMAScript binding, the object's [[Get]] method, when - invoked with a non-numeric argument, must have the same effect as calling - the <code title=dom-ResultSet-namedItem><a - href="#nameditem3">namedItem()</a></code> method. - - <p>The <dfn id=insertid - title=dom-ResultSet-insertId><code>insertId</code></dfn> attribute must - return the row ID of the row that the <code><a - href="#resultset">ResultSet</a></code> object's SQL statement inserted - into the database, if the statement inserted a row. If the statement - inserted multiple rows, the ID of the last row must be the one returned. - If the statement did not insert a row, then the attribute must instead - raise an <code>INVALID_ACCESS_ERR</code> exception. - - <h4 id=privacy><span class=secno>4.12.4. </span>Privacy</h4> - - <p>In contrast with the <code title=dom-globalStorage><a - href="#globalstorage">globalStorage</a></code> feature, which - intentionally allows data to be accessed across multiple domains, - protocols, and ports (albeit in a controlled fashion), this database - feature is limited to scripts running with the same <a - href="#origin0">origin</a> as the database. Thus, it is expected that the - privacy implications be equivalent to those already present in allowing - scripts to communicate with their originating host. - - <p>User agents are encouraged to treat data stored in databases in the same - way as cookies for the purposes of user interfaces, to reduce the risk of - using this feature for cookie resurrection. - - <h4 id=security6><span class=secno>4.12.5. </span>Security</h4> - - <h5 id=user-agents><span class=secno>4.12.5.1. </span>User agents</h5> - - <p>User agent implementors are strongly encouraged to audit all their - supported SQL statements for security implications. For example, <code - title="">LOAD DATA INFILE</code> is likely to pose security risks and - there is little reason to support it. - - <p>In general, it is recommended that user agents not support features that - control how databases are stored on disk. For example, there is little - reason to allow Web authors to control the character encoding used in the - disk representation of the data, as all data in ECMAScript is implicitly - UTF-16. - - <h5 id=sql-injection><span class=secno>4.12.5.2. </span>SQL injection</h5> - - <p>Authors are strongly recommended to make use of the <code - title="">?</code> placeholder feature of the <code title=dom-executeSql><a - href="#executesql">executeSql()</a></code> method, and to never construct - SQL statements on the fly. - - <h2 id=editing><span class=secno>5. </span><dfn id=editing0>Editing</dfn></h2> - - <p>This section describes various features that allow authors to enable - users to edit documents and parts of documents interactively. - - <h3 id=editing-intro><span class=secno>5.1. </span>Introduction</h3> - - <p><em>This section is non-normative.</em> - - <p class=big-issue>Would be nice to explain how these features work - together. - - <h3 id=contenteditable><span class=secno>5.2. </span>The <code - title=attr-contenteditable><a - href="#contenteditable0">contenteditable</a></code> attribute</h3> - - <p>The <dfn id=contenteditable0 - title=attr-contenteditable><code>contenteditable</code></dfn> attribute is - a common attribute. User agents must support this attribute on all <a - href="#html-elements">HTML elements</a>. - - <p>The <code title=attr-contenteditable><a - href="#contenteditable0">contenteditable</a></code> attribute is an <a - href="#enumerated">enumerated attribute</a> whose keywords are the empty - string, <code title="">true</code>, and <code title="">false</code>. The - empty string and the <code title="">true</code> keyword map to the - <em>true</em> state. The <code title="">false</code> keyword maps to the - <em>false</em> state, which is also the <em>invalid value default</em>. - There is no <em>missing value default</em>. - - <p>If an HTML element has a <code title=attr-contenteditable><a - href="#contenteditable0">contenteditable</a></code> attribute set to the - true state, or if its nearest ancestor with the <code - title=attr-contenteditable><a - href="#contenteditable0">contenteditable</a></code> attribute set has its - attribute set to the true state, or if it has no ancestors with the <code - title=attr-contenteditable><a - href="#contenteditable0">contenteditable</a></code> attribute set but the - <code>Document</code> has <code title=dom-document-designMode><a - href="#designMode">designMode</a></code> enabled, then the UA must treat - the element as <dfn id=editable0>editable</dfn> (as described below). - - <p>Otherwise, either the HTML element has a <code - title=attr-contenteditable><a - href="#contenteditable0">contenteditable</a></code> attribute set to the - false state, or its nearest ancestor with the <code - title=attr-contenteditable><a - href="#contenteditable0">contenteditable</a></code> attribute set is not - <em><a href="#editable0">editable</a></em>, or it has no ancestor with the - <code title=attr-contenteditable><a - href="#contenteditable0">contenteditable</a></code> attribute set and the - <code>Document</code> itself has <code title=dom-document-designMode><a - href="#designMode">designMode</a></code> disabled, and the element is thus - not editable. - - <p>The <dfn id=contenteditable1 - title=dom-contentEditable><code>contentEditable</code></dfn> DOM - attribute, on getting, must return the string "<code - title="">inherit</code>" if the content attribute isn't set, "<code - title="">true</code>" if the attribute is set and has the true state, and - "<code title="">false</code>" otherwise. On setting, if the new value is - case-insensitively<!-- XXX ascii --> equal to the string "<code - title="">inherit</code>" then the content attribute must be removed, if - the new value is case-insensitively<!-- XXX - ascii --> equal to the - string "<code title="">true</code> then the content attribute must be set - to the string "<code title="">true</code>, if the new value is - case-insensitively<!-- XXX - ascii --> equal to the string "<code - title="">false</code> then the content attribute must be set to the string - "<code title="">false</code>, and otherwise the attribute setter must - raise a <code>SYNTAX_ERR</code> exception. - - <p>If an element is <a href="#editable0">editable</a> and its parent - element is not, or if an element is <a href="#editable0">editable</a> and - it has no parent element, then the element is an <dfn id=editing1>editing - host</dfn>. Editable elements can be nested. User agents must make editing - hosts focusable (which typicially means they enter the <span - title=tabindex>tab order</span>). An editing host can contain non-editable - sections, these are handled as described below. An editing host can - contain non-editable sections that contain further editing hosts. - - <p>When an editing host has focus, it must have a <dfn id=caret>caret - position</dfn> that specifies where the current editing position is. It - may also have a <a href="#a-selection" title="the - selection">selection</a>.</p> - <!--- XXX xref to later section --> - - <p class=note>How the caret and selection are represented depends entirely - on the UA.</p> - <!-- XXX rendering requirement: The current caret should affect the - line-height (i.e. it acts at least like an empty inline element) --> - <!-- XXX document.designMode attribute --> - - <h4 id=user-editing><span class=secno>5.2.1. </span>User editing actions</h4> - - <p>There are several actions that the user agent should allow the user to - perform while the user is interacting with an editing host. How exactly - each action is triggered is not defined for every action, but when it is - not defined, suggested key bindings are provided to guide implementors. - - <dl> - <dt>Move the caret - - <dd> - <p>User agents must allow users to move the caret to any position within - an editing host, even into nested editable elements. This could be - triggered as the default action of <code - title=event-keydown>keydown</code> events with various key identifiers - and as the default action of <code - title=event-mousedown>mouseydown</code> events. - - <dt>Change the selection - - <dd> - <p>User agents must allow users to change <a href="#a-selection">the - selection</a> within an editing host, even into nested editable - elements. This could be triggered as the default action of <code - title=event-keydown>keydown</code> events with various key identifiers - and as the default action of <code - title=event-mousedown>mouseydown</code> events. - - <dt id=contenteditable-insertText>Insert text - - <dd> - <p>This action must be triggered as the default action of a <code - title=event-textInput>textInput</code> event, and may be triggered by - other commands as well. It must cause the user agent to insert the - specified text (given by the event object's <code title="">data</code> - attribute in the case of the <code - title=event-textInput>textInput</code> event) at the caret.</p> - - <p>If the caret is positioned somewhere where <a - href="#inline-level0">inline-level content</a> is not allowed (e.g. - because the element accepts "both block-level and inline-level content - but not both", and the element already contains block-level content), - then the user agent must not insert the text directly at the caret - position. In such cases the behaviour is UA-dependent, but user agents - must not, in response to a request to insert text, generate a DOM that - is less conformant than the DOM prior to the request.</p> - - <p>User agents should allow users to insert new paragraphs into elements - that only contain block-level content.</p> - - <div class=example> - <p>For example, given the markup:</p> - - <pre><section> - <dl> - <dt> Ben </dt> - <dd> Goat </dd> - </dl> -</section></pre> - - <p>...the user agent should allow the user to insert <code><a - href="#p">p</a></code> elements before and after the <code><a - href="#dl">dl</a></code> element, as children of the <code><a - href="#section">section</a></code> element.</p> - </div> - - <dt id=contenteditable-breakBlock>Break block - - <dd> - <p>UAs should offer a way for the user to request that the current block - be broken at the caret, e.g. as the default action of a <code - title=event-keydown>keydown</code> event whose identifier is the "Enter" - key and that has no modifiers set.</p> - - <p>The exact behaviour is UA-dependent, but user agents must not, in - response to a request to break a block, generate a DOM that is less - conformant than the DOM prior to the request. - - <dt id=contenteditable-br>Insert a line separator - - <dd> - <p>UAs should offer a way for the user to request an explicit line break - at the caret position without breaking the block, e.g. as the default - action of a <code title=event-keydown>keydown</code> event whose - identifier is the "Enter" key and that has a shift modifier set. Line - separators are typically found within a poem verse or an address. To - insert a line break, the user agent must insert a <code><a - href="#br">br</a></code> element.</p> - - <p>If the caret is positioned somewhere where <a - href="#inline-level0">inline-level content</a> is not allowed (e.g. - because the element accepts "both block-level and inline-level content - but not both", and the element already contains block-level content), - then the user agent must not insert the <code><a - href="#br">br</a></code> element directly at the caret position. In such - cases the behaviour is UA-dependent, but user agents must not, in - response to a request to insert a line separator, generate a DOM that is - less conformant than the DOM prior to the request. - - <dt id=contenteditable-delete>Delete - - <dd> - <p>UAs should offer a way for the user to delete text and elements, e.g. - as the default action of <code title=event-keydown>keydown</code> events - whose identifiers are "U+0008" or "U+007F".</p> - - <p>Five edge cases in particular need to be considered carefully when - implementing this feature: backspacing at the start of an element, - backspacing when the caret is immediately after an element, - forward-deleting at the end of an element, forward-deleting when the - caret is immediately before an element, and deleting a <a - href="#a-selection" title="the selection">selection</a> whose start and - end points do not share a common parent node.</p> - - <p>In any case, the exact behaviour is UA-dependent, but user agents must - not, in response to a request to delete text or an element, generate a - DOM that is less conformant than the DOM prior to the request. - - <dt id=contenteditable-wrapSemantic>Insert, and wrap text in, semantic - elements - - <dd> - <p>UAs should offer a way for the user to mark text as having <a - href="#em" title=em>stress emphasis</a> and as being <a href="#strong" - title=strong>important</a>, and may offer the user the ability to mark - text and blocks with other semantics.</p> - - <p>UAs should similarly offer a way for the user to insert empty semantic - elements (such as, again, <code><a href="#em">em</a></code>, <code><a - href="#strong">strong</a></code>, and others) to subsequently fill by - entering text manually.</p> - - <p>UAs should also offer a way to remove those semantics from marked up - text, and to remove empty semantic element that have been inserted.</p> - - <p>The exact behaviour is UA-dependent, but user agents must not, in - response to a request to wrap semantics around some text or to insert or - remove a semantic element, generate a DOM that is less conformant than - the DOM prior to the request. - - <dt>Select and move non-editable elements nested inside editing hosts - - <dd> - <p>UAs should offer a way for the user to move images and other - non-editable parts around the content within an editing host. This may - be done using the <a href="#drag-and">drag and drop</a> mechanism. User - agents must not, in response to a request to move non-editable elements - nested inside editing hosts, generate a DOM that is less conformant than - the DOM prior to the request. - - <dt>Edit form controls nested inside editing hosts - - <dd> - <p>When an <a href="#editable0">editable</a> form control is edited, the - changes must be reflected in both its current value <em>and</em> its - default value. For <code>input</code> elements this means updating the - <code title=dom-input-defaultValue>defaultValue</code> DOM attribute as - well as the <code title=dom-input-value>value</code> DOM attribute; for - <code>select</code> elements it means updating the <code>option</code> - elements' <code title=dom-option-defaultSelected>defaultSelected</code> - DOM attribute as well as the <code - title=dom-option-selected>selected</code> DOM attribute; for - <code>textarea</code> elements this means updating the <code - title=dom-textarea-defaultValue>defaultValue</code> DOM attribute as - well as the <code title=dom-textarea-value>value</code> DOM attribute. - (Updating the <code title="">default*</code> DOM attributes causes - content attributes to be updated as well.) - </dd> - <!-- XXX something about not supporting resizing? --> - </dl> - <!-- XXX each action performed should be added to the undo history --> - - <p>User agents may perform several commands per user request; for example - if the user selects a block of text and hits <kbd><kbd>Enter</kbd></kbd>, - the UA might interpret that as a request to delete the content of <a - href="#a-selection">the selection</a> followed by a request to break the - block at that position. - - <h4 id=making><span class=secno>5.2.2. </span>Making entire documents - editable</h4> - - <p>Documents have a <dfn id=designMode - title=dom-document-designMode><code>designMode</code></dfn>, which can be - either enabled or disabled. - - <p>The <code title=dom-document-designMode><a - href="#designMode">designMode</a></code> DOM attribute on the - <code>Document</code> object takes takes two values, "<code - title="">on</code>" and "<code title="">off</code>". When it is set, the - new value must be case-insensitively <!-- XXX ASCII case-folding --> - compared to these two values. If it matches the "<code title="">on</code>" - value, then <code title=dom-document-designMode><a - href="#designMode">designMode</a></code> must be enabled, and if it - matches the "<code title="">off</code>" value, then <code - title=dom-document-designMode><a href="#designMode">designMode</a></code> - must be disabled. Other values must be ignored. - - <p>When <code title=dom-document-designMode><a - href="#designMode">designMode</a></code> is enabled, the DOM attribute - must return the value "<code title="">on</code>", and when it is disabled, - it must return the value "<code title="">off</code>". - - <p>The last state set must persist until the document is destroyed or the - state is changed. Initially, documents must have their <code - title=dom-document-designMode><a href="#designMode">designMode</a></code> - disabled. - - <p>Enabling <code title=dom-document-designMode><a - href="#designMode">designMode</a></code> causes scripts in general to be - disabled and the document to become editable. - - <p>When the <code>Document</code> has <code - title=dom-document-designMode><a href="#designMode">designMode</a></code> - enabled, event listeners registered on the document or any elements owned - by the document must do nothing. - - <h3 id=dnd><span class=secno>5.3. </span><dfn id=drag-and>Drag and - drop</dfn></h3> - <!--XXX - -http://msdn.microsoft.com/workshop/author/datatransfer/overview.asp -http://msdn.microsoft.com/workshop/author/dhtml/reference/objects/clipboarddata.asp - -> To implement this with simple interface I've proposed, events should be -> handled either by existing elements (like list items that compare their size -> and position of dragged element to decide whether element should be dropped -> before or after) or handled by container that would probably need to calculate -> positions of it's children and create new element to show drop target. Smooth -> Mac-like drag'n'drop can be implemented by animating drop target's -> padding/margin. So that's quite a bit of code that's going to be reinvented -> each time someone implements reordering. - -<hyatt> :droptarget -<hyatt> or something -<hyatt> we don't support a pseudo-class for the drop target but that's a great idea -<Hixie_> yeah, thinking about that too -<Hixie_> :drop-target, :drop-target(above), :drop-target(below) and having ondragover be able to say "not on me, but next to me maybe" - -http://msdn.microsoft.com/workshop/author/dhtml/reference/events/ondragstart.asp -http://msdn.microsoft.com/workshop/author/dhtml/reference/events/ondrag.asp -http://msdn.microsoft.com/workshop/author/dhtml/reference/events/ondragend.asp -http://msdn.microsoft.com/workshop/author/dhtml/reference/objects/obj_datatransfer.asp -http://developer.apple.com/documentation/AppleApplications/Conceptual/SafariJSProgTopics/Tasks/DragAndDrop.html ---> - - <p>This section defines an event-based drag-and-drop mechanism. - - <p>This specification does not define exactly what a <em>drag-and-drop - operation</em> actually is. - - <p>On a visual medium with a pointing device, a drag operation could be the - default action of a <code title=event-mousedown>mousedown</code> event - that is followed by a series of <code - title=event-mousemove>mousemove</code> events, and the drop could be - triggered by the mouse being released. - - <p>On media without a pointing device, the user would probably have to - explicitly indicate his intention to perform a drag-and-drop operation, - stating what he wishes to drag and what he wishes to drop, respectively. - - <p>However it is implemented, drag-and-drop operations must have a starting - point (e.g. where the mouse was clicked, or the start of <a - href="#a-selection">the selection</a> or element that was selected for the - drag), may have any number of intermediate steps (elements that the mouse - moves over during a drag, or elements that the user picks as possible drop - points as he cycles through possibilities), and must either have an end - point (the element above which the mouse button was released, or the - element that was finally selected), or be canceled. The end point must be - the last element selected as a possible drop point before the drop occurs - (so if the operation is not canceled, there must be at least one element - in the middle step). - - <h4 id=the-dragevent><span class=secno>5.3.1. </span>The <code><a - href="#dragevent">DragEvent</a></code> and <code><a - href="#datatransfer0">DataTransfer</a></code> interfaces</h4> - - <p>The drag-and-drop processing model involves several events. They all use - the <code><a href="#dragevent">DragEvent</a></code> interface. - - <pre class=idl>interface <dfn id=dragevent>DragEvent</dfn> : Event { - readonly attribute <a href="#datatransfer0">DataTransfer</a> <a href="#datatransfer" title=dom-DragEvent-dataTransfer>dataTransfer</a>; - void <a href="#initdragevent" title=dom-DragEvent-initDragEvent>initDragEvent</a>(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg); - void <a href="#initdrageventns" title=dom-DragEvent-initDragEventNS>initDragEventNS</a>(in DOMString namespaceURIArg, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg); -};</pre> - - <p>The <dfn id=initdragevent - title=dom-DragEvent-initDragEvent><code>initDragEvent()</code></dfn> and - <dfn id=initdrageventns - title=dom-DragEvent-initDragEventNS><code>initDragEventNS()</code></dfn> - methods must initialise the event in a manner analogous to the - similarly-named methods in the DOM3 Events interfaces. <a - href="#refsDOM3EVENTS">[DOM3EVENTS]</a> - - <p>The <dfn id=datatransfer - title=dom-DragEvent-dataTransfer><code>dataTransfer</code></dfn> attribute - of the <code><a href="#dragevent">DragEvent</a></code> interface - represents the context information for the event. - - <p>When a <code><a href="#dragevent">DragEvent</a></code> object is - created, a new <code><a href="#datatransfer0">DataTransfer</a></code> - object must be created and assigned to the <code - title=dom-DragEvent-dataTransfer><a - href="#datatransfer">dataTransfer</a></code> context information field of - the event object. - - <pre class=idl>interface <dfn id=datatransfer0>DataTransfer</dfn> { - attribute DOMString <a href="#dropeffect" title=dom-DataTransfer-dropEffect>dropEffect</a>; - attribute DOMString <a href="#effectallowed" title=dom-DataTransfer-effectAllowed>effectAllowed</a>; - void <a href="#cleardata" title=dom-DataTransfer-clearData>clearData</a>(in DOMString format); - void <a href="#setdata" title=dom-DataTransfer-setData>setData</a>(in DOMString format, in DOMString data); - DOMString <a href="#getdata" title=dom-DataTransfer-getData>getData</a>(in DOMString format); - void <a href="#setdragimage" title=dom-DataTransfer-setDragImage>setDragImage</a>(in Element image, in long x, in long y); - void <a href="#addelement" title=dom-DataTransfer-addElement>addElement</a>(in Element element); -}; -</pre> - - <p><code><a href="#datatransfer0">DataTransfer</a></code> objects can - conceptually contain various kinds of data. - - <p>When a <code><a href="#dragevent">DragEvent</a></code> event object is - initialised, the <code><a href="#datatransfer0">DataTransfer</a></code> - object created for the event's <code title=dom-DragEvent-dataTransfer><a - href="#datatransfer">dataTransfer</a></code> member must be initialised as - follows: - - <ul> - <li>The <code><a href="#datatransfer0">DataTransfer</a></code> object must - initially contain no data, no elements, and have no associated image. - - <li>The <code><a href="#datatransfer0">DataTransfer</a></code> object's - <code title=dom-DataTransfer-effectAllowed><a - href="#effectallowed">effectAllowed</a></code> attribute must be set to - "<code title="">uninitialized</code>". - - <li>The <code title=dom-DataTransfer-dropEffect><a - href="#dropeffect">dropEffect</a></code> attribute must be set to "<code - title="">none</code>". - </ul> - - <p>The <dfn id=dropeffect - title=dom-DataTransfer-dropEffect><code>dropEffect</code></dfn> attribute - controls the drag-and-drop feedback that the user is given during a - drag-and-drop operation. - - <p>The attribute must ignore any attempts to set it to a value other than - <code title="">none</code>, <code title="">copy</code>, <code - title="">link</code>, and <code title="">move</code>. On getting, the - attribute must return the last of those four values that it was set to. - - <p>The <dfn id=effectallowed - title=dom-DataTransfer-effectAllowed><code>effectAllowed</code></dfn> - attribute is used in the drag-and-drop processing model to initialise the - <code title=dom-DataTransfer-dropEffect><a - href="#dropeffect">dropEffect</a></code> attribute during the <code - title=event-dragenter><a href="#dragenter">dragenter</a></code> and <code - title=event-dragover><a href="#dragover">dragover</a></code> events. - - <p>The attribute must ignore any attempts to set it to a value other than - <code title="">none</code>, <code title="">copy</code>, <code - title="">copyLink</code>, <code title="">copyMove</code>, <code - title="">link</code>, <code title="">linkMove</code>, <code - title="">move</code>, <code title="">all</code>, and <code - title="">uninitialized</code>. On getting, the attribute must return the - last of those values that it was set to. - - <p><code><a href="#datatransfer0">DataTransfer</a></code> objects can hold - pieces of data, each associated with a unique format. Formats are - generally given by MIME types, with some values special-cased for legacy - reasons. - - <p>The <dfn id=cleardata - title=dom-DataTransfer-clearData><code>clearData(<var - title="">format</var>)</code></dfn> method must clear the <code><a - href="#datatransfer0">DataTransfer</a></code> object of any data - associated with the given <var title="">format</var>. If <var - title="">format</var> is the value "<code title="">Text</code>", then it - must be treated as "<code title="">text/plain</code>". If the <var - title="">format</var> is "<code title="">URL</code>", then it must be - treated as "<code title="">text/uri-list</code>". - - <p>The <dfn id=setdata title=dom-DataTransfer-setData><code>setData(<var - title="">format</var>, <var title="">data</var>)</code></dfn> method must - add <var title="">data</var> to the data stored in the <code><a - href="#datatransfer0">DataTransfer</a></code> object, labelled as being of - the type <var title="">format</var>. This must replace any previous data - that had been set for that format. If <var title="">format</var> is the - value "<code title="">Text</code>", then it must be treated as "<code - title="">text/plain</code>". If the <var title="">format</var> is "<code - title="">URL</code>", then it must be treated as "<code - title="">text/uri-list</code>". - - <p>The <dfn id=getdata title=dom-DataTransfer-getData><code>getData(<var - title="">format</var>)</code></dfn> method must return the data that is - associated with the type <var title="">format</var>, if any, and must - return the empty string otherwise. If <var title="">format</var> is the - value "<code title="">Text</code>", then it must be treated as "<code - title="">text/plain</code>". If the <var title="">format</var> is "<code - title="">URL</code>", then the data associated with the "<code - title="">text/uri-list</code>" format must be parsed as appropriate for - <code title="">text/uri-list</code> data, and the first URI from the list - must be returned. If there is no data with that format, or if there is but - it has no URIs, then the method must return the empty string. <a - href="#refsRFC2483">[RFC2483]</a> - - <p>The <dfn id=setdragimage - title=dom-DataTransfer-setDragImage><code>setDragImage(<var - title="">element</var>, <var title="">x</var>, <var - title="">y</var>)</code></dfn> method sets which element to use <a - href="#base-dnd-feedback">to generate the drag feedback</a>. The <var - title="">element</var> argument can be any <code>Element</code>; if it is - an <code><a href="#img">img</a></code> element, then the user agent should - use the element's image (at its intrinsic size) to generate the feedback, - otherwise the user agent should base the feedback on the given element - (but the exact mechanism for doing so is not specified). - - <p>The <dfn id=addelement - title=dom-DataTransfer-addElement><code>addElement(<var - title="">element</var>)</code></dfn> method is an alternative way of - specifying how the user agent is to <a href="#base-dnd-feedback">render - the drag feedback</a>. It adds an element to the <code><a - href="#datatransfer0">DataTransfer</a></code> object. - - <h4 id=events1><span class=secno>5.3.2. </span>Events fired during a - drag-and-drop action</h4> - - <p>The following events are involved in the drag-and-drop model. Whenever - the processing model described below causes one of these events to be - fired, the event fired must use the <code><a - href="#dragevent">DragEvent</a></code> interface defined above, must have - the bubbling and cancelable behaviours given in the table below, and must - have the context information set up as described after the table. - - <table> - <thead> - <tr> - <th> Event Name - - <th> Target - - <th> Bubbles? - - <th> Cancelable? - - <th> <code title=dom-DataTransfer-addElement><a - href="#addelement">dataTransfer</a></code> - - <th> <code title=dom-DataTransfer-effectAllowed><a - href="#effectallowed">effectAllowed</a></code> - - <th> <code title=dom-DataTransfer-dropEffect><a - href="#dropeffect">dropEffect</a></code> - - <th> Default Action - - <tbody> - <tr> - <td><dfn id=dragstart title=event-dragstart><code>dragstart</code></dfn> - - <td><a href="#source0">Source node</a> - - <td>✓ Bubbles - - <td>✓ Cancelable - - <td>Contains <a href="#source0">source node</a> unless a selection is - being dragged, in which case it is empty - - <td><code title="">uninitialized</code> - - <td><code title="">none</code> - - <td>Initiate the drag-and-drop operation - - <tr> - <td><dfn id=drag title=event-drag><code>drag</code></dfn> - - <td><a href="#source0">Source node</a> - - <td>✓ Bubbles - - <td>✓ Cancelable - - <td>Empty - - <td><a href="#effectAllowed-initialisation">Same as last event</a> - - <td><code title="">none</code> - - <td>Continue the drag-and-drop operation - - <tr> - <td><dfn id=dragenter title=event-dragenter><code>dragenter</code></dfn> - - <td><a href="#immediate">Immediate user selection</a> or <a - href="#the-body0">the body element</a> - - <td>✓ Bubbles - - <td>✓ Cancelable - - <td>Empty - - <td><a href="#effectAllowed-initialisation">Same as last event</a> - - <td><a href="#dropEffect-initialisation">Based on - <code>effectAllowed</code> value</a> - - <td>Reject <a href="#immediate">immediate user selection</a> as - potential <a href="#current1" title="current target element">target - element</a> - - <tr> - <td><dfn id=dragleave title=event-dragleave><code>dragleave</code></dfn> - - <td><a href="#current1" title="current target element">Previous target - element</a> - - <td>✓ Bubbles - - <td>— - - <td>Empty - - <td><a href="#effectAllowed-initialisation">Same as last event</a> - - <td><code title="">none</code> - - <td>None - - <tr> - <td><dfn id=dragover title=event-dragover><code>dragover</code></dfn> - - <td><a href="#current1">Current target element</a> - - <td>✓ Bubbles - - <td>✓ Cancelable - - <td>Empty - - <td><a href="#effectAllowed-initialisation">Same as last event</a> - - <td><a href="#dropEffect-initialisation">Based on - <code>effectAllowed</code> value</a> - - <td>Reset the <a href="#current2">current drag operation</a> to "none" - - <tr> - <td><dfn id=drop title=event-drop><code>drop</code></dfn> - - <td><a href="#current1">Current target element</a> - - <td>✓ Bubbles - - <td>✓ Cancelable - - <td><code>getData()</code> returns data set in <code - title=dom-dragstart>dragstart</code> event - - <td><a href="#effectAllowed-initialisation">Same as last event</a> - - <td><a href="#current2">Current drag operation</a> - - <td>Varies - - <tr> - <td><dfn id=dragend title=event-dragend><code>dragend</code></dfn> - - <td><a href="#source0">Source node</a> - - <td>✓ Bubbles - - <td>— - - <td>Empty - - <td><a href="#effectAllowed-initialisation">Same as last event</a> - - <td><a href="#current2">Current drag operation</a> - - <td>Varies - </table> - - <p>The <code title=dom-DragEvent-dataTransfer><a - href="#datatransfer">dataTransfer</a></code> object's contents are empty - except for <code title=event-dragstart><a - href="#dragstart">dragstart</a></code> events and <code - title=event-drop><a href="#drop">drop</a></code> events, for which the - contents are set as described in the processing model, below. - - <p id=effectAllowed-initialisation>The <code - title=dom-DataTransfer-effectAllowed><a - href="#effectallowed">effectAllowed</a></code> attribute must be set to - "<code title="">uninitialized</code>" for <code title=event-dragstart><a - href="#dragstart">dragstart</a></code> events, and to whatever value the - field had after the last drag-and-drop event was fired for all other - events (only counting events fired by the user agent for the purposes of - the drag-and-drop model described below). - - <p id=dropEffect-initialisation>The <code - title=dom-DataTransfer-dropEffect><a - href="#dropeffect">dropEffect</a></code> attribute must be set to "<code - title="">none</code>" for <code title=event-dragstart><a - href="#dragstart">dragstart</a></code>, <code title=event-drag><a - href="#drag">drag</a></code>, <code title=event-dragleave><a - href="#dragleave">dragleave</a></code>, and <code title=event-dragend><a - href="#dragend">dragend</a></code> events (except when stated otherwise in - the algorithms given in the sections below), to the value corresponding to - the <a href="#current2">current drag operation</a> for <code - title=event-drop><a href="#drop">drop</a></code> events, and to a value - based on the <code title=dom-DataTransfer-effectAllowed><a - href="#effectallowed">effectAllowed</a></code> attribute's value and to - the drag-and-drop source, as given by the following table, for the - remaining events (<code title=event-dragenter><a - href="#dragenter">dragenter</a></code> and <code title=event-dragover><a - href="#dragover">dragover</a></code>): - - <table> - <thead> - <tr> - <th><code title=dom-DataTransfer-effectAllowed><a - href="#effectallowed">effectAllowed</a></code> - - <th><code title=dom-DataTransfer-dropEffect><a - href="#dropeffect">dropEffect</a></code> - - <tbody> - <tr> - <td><code title="">none</code> - - <td><code title="">none</code> - - <tr> - <td><code title="">copy</code>, <code title="">copyLink</code>, <code - title="">copyMove</code>, <code title="">all</code> - - <td><code title="">copy</code> - - <tr> - <td><code title="">link</code>, <code title="">linkMove</code> - - <td><code title="">link</code> - - <tr> - <td><code title="">move</code> - - <td><code title="">move</code> - - <tr> - <td><code title="">uninitialized</code> when what is being dragged is a - selection from a text field - - <td><code title="">move</code> - - <tr> - <td><code title="">uninitialized</code> when what is being dragged is a - selection - - <td><code title="">copy</code> - - <tr> - <td><code title="">uninitialized</code> when what is being dragged is an - <code><a href="#a">a</a></code> element with an <code>href</code> - attribute - - <td><code title="">link</code> - - <tr> - <td>Any other case - - <td><code title="">copy</code> - </table> - - <h4 id=drag-and-drop><span class=secno>5.3.3. </span>Drag-and-drop - processing model</h4> - - <p>When the user attempts to begin a drag operation, the user agent must - first determine what is being dragged. If the drag operation was invoked - on a selection, then it is the selection that is being dragged. Otherwise, - it is the first element, going up the ancestor chain, starting at the node - that the user tried to drag, that has the DOM attribute <code - title=dom-draggable><a href="#draggable0">draggable</a></code> set to - true. If there is no such element, then nothing is being dragged, the - drag-and-drop operation is never started, and the user agent must not - continue with this algorithm. - - <p class=note><code><a href="#img">img</a></code> elements and <code><a - href="#a">a</a></code> elements with an <code title=attr-hyperlink-href><a - href="#href6">href</a></code> attribute have their <code - title=dom-draggable><a href="#draggable0">draggable</a></code> attribute - set to true by default. - - <p>If the user agent determines that something can be dragged, a <code - title=event-dragstart><a href="#dragstart">dragstart</a></code> event must - then be fired. - - <p>If it is a selection that is being dragged, then this event must be - fired on the node that the user started the drag on (typically the text - node that the user originally clicked). If the user did not specify a - particular node, for example if the user just told the user agent to begin - a drag of "the selection", then the event must be fired on the deepest - node that is a common ancestor of all parts of the selection. - - <p>If it is not a selection that is being dragged, then the event must be - fired on the element that is being dragged. - - <p>The node on which the event is fired is the <dfn id=source0>source - node</dfn>. Multiple events are fired on this node during the course of - the drag-and-drop operation. - - <p>If it is a selection that is being dragged, the <code - title=dom-DragEvent-dataTransfer><a - href="#datatransfer">dataTransfer</a></code> member of the event must be - created with no nodes. Otherwise, it must be created containing just the - <a href="#source0">source node</a>. Script can use the <code - title=dom-DataTransfer-addElement><a - href="#addelement">addElement()</a></code> method to add further elements - to the list of what is being dragged. - - <p>If it is a selection that is being dragged, the <code - title=dom-DragEvent-dataTransfer><a - href="#datatransfer">dataTransfer</a></code> member of the event must have - the text of the selection added to it as the data associated with the - <code title="">text/plain</code> format. Otherwise, if it is an <code><a - href="#img">img</a></code> element being dragged, then the value of the - element's <code title=dom-img-src><a href="#src0">src</a></code> DOM - attribute must be added, associated with the <code - title="">text/uri-list</code> format. Otherwise, if it is an <code><a - href="#a">a</a></code> element being dragged, then the value of the - element's <code title=dom-a-href><a href="#href3">href</a></code> DOM - attribute must be added, associated with the <code - title="">text/uri-list</code> format. Otherwise, no data is added to the - object by the user agent. - - <p>If the event is canceled, then the drag-and-drop operation must not - occur; the user agent must not continue with this algorithm. - - <p>If it is not canceled, then the drag-and-drop operation must be - initiated. - - <p class=note>Since events with no event handlers registered are, almost by - definition, never canceled, drag-and-drop is always available to the user - if the author does not specifically prevent it. - - <p id=base-dnd-feedback>The drag-and-drop feedback must be generated from - the first of the following sources that is available: - - <ol> - <li>The element specified in the last call to the <code - title=dom-DataTransfer-setDragImage><a - href="#setdragimage">setDragImage()</a></code> method of the <code - title=dom-DragEvent-dataTransfer><a - href="#datatransfer">dataTransfer</a></code> object of the <code - title=event-dragstart><a href="#dragstart">dragstart</a></code> event, if - the method was called. In visual media, if this is used, the <var - title="">x</var> and <var title="">y</var> arguments that were passed to - that method should be used as hints for where to put the cursor relative - to the resulting image. The values are expressed as distances in CSS - pixels from the left side and from the top side of the image - respectively. <a href="#refsCSS21">[CSS21]</a></li> - <!-- - CSS3 UNITS would be better --> - - <li>The elements that were added to the <code - title=dom-DragEvent-dataTransfer><a - href="#datatransfer">dataTransfer</a></code> object, both before the - event was fired, and during the handling of the event using the <code - title=dom-DataTransfer-addElement><a - href="#addelement">addElement()</a></code> method, if any such elements - were indeed added. - - <li>The selection that the user is dragging. - </ol> - <!-- XXX xref also link to the section that explains how to - render drag-and-drop, :drag, :drop, etc. Safari has a pseudo-class - that it uses to render an element off-screen to use as the drag - feedback. --> - - <p>The user agent must take a note of <a href="#setdata" - title=dom-DataTransfer-setData>the data that was placed</a> in the <code - title=dom-DragEvent-dataTransfer><a - href="#datatransfer">dataTransfer</a></code> object. This data will be - made available again when the <code title=event-drop><a - href="#drop">drop</a></code> event is fired. - - <p>From this point until the end of the drag-and-drop operation, device - input events (e.g. mouse and keyboard events) must be suppressed. In - addition, the user agent must track all DOM changes made during the - drag-and-drop operation, and add them to its <a href="#undo">undo - history</a> as one atomic operation once the drag-and-drop operation has - ended. - - <p>During the drag operation, the element directly indicated by the user as - the drop target is called the <dfn id=immediate>immediate user - selection</dfn>. (Only elements can be selected by the user; other nodes - must not be made available as drop targets.) However, the <a - href="#immediate">immediate user selection</a> is not necessarily the <dfn - id=current1>current target element</dfn>, which is the element currently - selected for the drop part of the drag-and-drop operation. The <a - href="#immediate">immediate user selection</a> changes as the user selects - different elements (either by pointing at them with a pointing device, or - by selecting them in some other way). The <a href="#current1">current - target element</a> changes when the <a href="#immediate">immediate user - selection</a> changes, based on the results of event handlers in the - document, as described below. - - <p>Both the <a href="#current1">current target element</a> and the <a - href="#immediate">immediate user selection</a> can be null, which means no - target element is selected. They can also both be elements in other - (DOM-based) documents, or other (non-Web) programs altogether. (For - example, a user could drag text to a word-processor.) The <a - href="#current1">current target element</a> is initially null. - - <p>In addition, there is also a <dfn id=current2>current drag - operation</dfn>, which can take on the values "none", "copy", "link", and - "move". Initially it has the value "none". It is updated by the user agent - as described in the steps below. - - <p>User agents must, every 350ms (±200ms), perform the following steps - in sequence. (If the user agent is still performing the previous iteration - of the sequence when the next iteration becomes due, the user agent must - not execute the overdue iteration, effectively "skipping missed frames" of - the drag-and-drop operation.) - - <ol> - <li> - <p>First, the user agent must fire a <code title=event-drag><a - href="#drag">drag</a></code> event at the <a href="#source0">source - node</a>. If this event is canceled, the user agent must set the <a - href="#current2">current drag operation</a> to none (no drag operation).</p> - - <li> - <p>Next, if the <code title=event-drag><a href="#drag">drag</a></code> - event was not canceled and the user has not ended the drag-and-drop - operation, the user agent must check the state of the drag-and-drop - operation, as follows:</p> - - <ol> - <li> - <p>First, if the user is indicating a different <a - href="#immediate">immediate user selection</a> than during the last - iteration (or if this is the first iteration), and if this <a - href="#immediate">immediate user selection</a> is not the same as the - <a href="#current1">current target element</a>, then the <a - href="#current1">current target element</a> must be updated, as - follows:</p> - - <ol> - <li> - <p>If the new <a href="#immediate">immediate user selection</a> is - null, or is in a non-DOM document or application, then set the <a - href="#current1">current target element</a> to the same value.</p> - - <li> - <p>Otherwise, the user agent must fire a <code - title=event-dragenter><a href="#dragenter">dragenter</a></code> - event at the <a href="#immediate">immediate user selection</a>.</p> - - <li> - <p>If the event is canceled, then the <a href="#current1">current - target element</a> must be set to the <a href="#immediate">immediate - user selection</a>.</p> - - <li> - <p>Otherwise, if the <a href="#current1">current target element</a> - is not <a href="#the-body0">the body element</a>, the user agent - must fire a <code title=event-dragenter><a - href="#dragenter">dragenter</a></code> event at <a - href="#the-body0">the body element</a>, and the <a - href="#current1">current target element</a> must be set to <a - href="#the-body0">the body element</a>, regardless of whether that - event was canceled or not. (If <a href="#the-body0">the body - element</a> is null, then the <a href="#current1">current target - element</a> would be set to null too in this case, it wouldn't be - set to the <code>Document</code> object.)</p> - </ol> - - <li> - <p>If the previous step caused the <a href="#current1">current target - element</a> to change, and if the previous target element was not null - or a part of a non-DOM document, the user agent must fire a <code - title=event-dragleave><a href="#dragleave">dragleave</a></code> event - at the previous target element.</p> - - <li> - <p>If the <a href="#current1">current target element</a> is a DOM - element, the user agent must fire a <code title=event-dragover><a - href="#dragover">dragover</a></code> event at this <a - href="#current1">current target element</a>.</p> - - <p>If the <code title=event-dragover><a - href="#dragover">dragover</a></code> event is canceled, the <a - href="#current2">current drag operation</a> must be reset to "none".</p> - - <p>Otherwise, the <a href="#current2">current drag operation</a> must - be set based on the values the <code - title=dom-DataTransfer-effectAllowed><a - href="#effectallowed">effectAllowed</a></code> and <code - title=dom-DataTransfer-dropEffect><a - href="#dropeffect">dropEffect</a></code> attributes of the <code - title=dom-DragEvent-dataTransfer><a - href="#datatransfer">dataTransfer</a></code> object had after the - event was handled, as per the following table:</p> - - <table> - <thead> - <tr> - <th><code title=dom-DataTransfer-effectAllowed><a - href="#effectallowed">effectAllowed</a></code> - - <th><code title=dom-DataTransfer-dropEffect><a - href="#dropeffect">dropEffect</a></code> - - <th>Drag operation - - <tbody> - <tr> - <td><code title="">uninitialized</code>, <code title="">copy</code>, - <code title="">copyLink</code>, <code title="">copyMove</code>, or - <code title="">all</code> - - <td><code title="">copy</code> - - <td>"copy" - - <tr> - <td><code title="">uninitialized</code>, <code title="">link</code>, - <code title="">copyLink</code>, <code title="">linkMove</code>, or - <code title="">all</code> - - <td><code title="">link</code> - - <td>"link" - - <tr> - <td><code title="">uninitialized</code>, <code title="">move</code>, - <code title="">copyMove</code>, <code title="">linkMove</code>, or - <code title="">all</code> - - <td><code title="">move</code> - - <td>"move" - - <tr> - <td colspan=2>Any other case - - <td>"none" - </table> - - <p>Then, regardless of whether the <code title=event-dragover><a - href="#dragover">dragover</a></code> event was canceled or not, the - drag feedback (e.g. the mouse cursor) must be updated to match the <a - href="#current2">current drag operation</a>, as follows:</p> - - <table> - <thead> - <tr> - <th>Drag operation - - <th>Feedback - - <tbody> - <tr> - <td>"copy" - - <td>Data will be copied if dropped here. - - <tr> - <td>"link" - - <td>Data will be linked if dropped here. - - <tr> - <td>"move" - - <td>Data will be moved if dropped here. - - <tr> - <td>"none" - - <td>No operation allowed, dropping here will cancel the - drag-and-drop operation. - </table> - - <li> - <p>Otherwise, if the <a href="#current1">current target element</a> is - not a DOM element, the user agent must use platform-specific - mechanisms to determine what drag operation is being performed (none, - copy, link, or move). This sets the <em><a href="#current2">current - drag operation</a></em>.</p> - </ol> - - <li> - <p>Otherwise, if the user ended the drag-and-drop operation (e.g. by - releasing the mouse button in a mouse-driven drag-and-drop interface), - or if the <code title=event-drag><a href="#drag">drag</a></code> event - was canceled, then this will be the last iteration. The user agent must - follow the following steps, then stop looping.</p> - - <ol> - <li> - <p>If the <a href="#current2">current drag operation</a> is none (no - drag operation), or, if the user ended the drag-and-drop operation by - canceling it (e.g. by hitting the <kbd>Escape</kbd> key), or if the <a - href="#current1">current target element</a> is null, then the drag - operation failed. If the <a href="#current1">current target - element</a> is a DOM element, the user agent must fire a <code - title=event-dragleave><a href="#dragleave">dragleave</a></code> event - at it; otherwise, if it is not null, it must use platform-specific - conventions for drag cancellation.</p> - - <li> - <p>Otherwise, the drag operation was as success. If the <a - href="#current1">current target element</a> is a DOM element, the user - agent must fire a <code title=event-drop><a - href="#drop">drop</a></code> event at it; otherwise, it must use - platform-specific conventions for indicating a drop.</p> - - <p>When the target is a DOM element, the <code - title=dom-DataTransfer-dropEffect><a - href="#dropeffect">dropEffect</a></code> attribute of the event's - <code title=dom-DragEvent-dataTransfer><a - href="#datatransfer">dataTransfer</a></code> object must be given the - value representing the <a href="#current2">current drag operation</a> - (<code title="">copy</code>, <code title="">link</code>, or <code - title="">move</code>), and the object must be set up so that the <code - title=dom-DataTransfer-getData><a href="#getdata">getData()</a></code> - method will return the data that was added during the <code - title=event-dragstart><a href="#dragstart">dragstart</a></code> event.</p> - - <p>If the event is canceled, the <a href="#current2">current drag - operation</a> must be set to the value of the <code - title=dom-DataTransfer-dropEffect><a - href="#dropeffect">dropEffect</a></code> attribute of the event's - <code title=dom-DragEvent-dataTransfer><a - href="#datatransfer">dataTransfer</a></code> object as it stood after - the event was handled.</p> - - <p>Otherwise, the event is not canceled, and the user agent must - perform the event's default action, which depends on the exact target - as follows:</p> - - <dl class=switch> - <dt>If the <a href="#current1">current target element</a> is a text - field (e.g. <code>textarea</code>, or an <code>input</code> element - with <code title="">type="text"</code><!--XXX xref-->) - - <dd>The user agent must insert the data associated with the - <code>text/plain</code> format, if any, into the text field in a - manner consistent with platform-specific conventions (e.g. inserting - it at the current mouse cursor position, or inserting it at the end - of the field). - - <dt>Otherwise - - <dd>Reset the <a href="#current2">current drag operation</a> to - "none". - </dl> - - <li> - <p>Finally, the user agent must fire a <code title=event-dragend><a - href="#dragend">dragend</a></code> event at the <a - href="#source0">source node</a>, with the <code - title=dom-DataTransfer-dropEffect><a - href="#dropeffect">dropEffect</a></code> attribute of the event's - <code title=dom-DragEvent-dataTransfer><a - href="#datatransfer">dataTransfer</a></code> object being set to the - value corresponding to the <a href="#current2">current drag - operation</a>.</p> - - <p class=note>The <a href="#current2">current drag operation</a> can - change during the processing of the <code title=event-drop><a - href="#drop">drop</a></code> event, if one was fired.</p> - - <p>The event is not cancelable. After the event has been handled, the - user agent must act as follows:</p> - - <dl class=switch> - <dt>If the <a href="#current1">current target element</a> is a text - field (e.g. <code>textarea</code>, or an <code>input</code> element - with <code title="">type="text"</code><!--XXX xref-->), and a <code - title=event-drop><a href="#drop">drop</a></code> event was fired in - the previous step, and the <a href="#current2">current drag - operation</a> is "move", and the source of the drag-and-drop - operation is a selection in the DOM - - <dd>The user agent should delete the range representing the dragged - selection from the DOM. - - <dt>If the <a href="#current1">current target element</a> is a text - field (e.g. <code>textarea</code>, or an <code>input</code> element - with <code title="">type="text"</code><!--XXX xref-->), and a <code - title=event-drop><a href="#drop">drop</a></code> event was fired in - the previous step, and the <a href="#current2">current drag - operation</a> is "move", and the source of the drag-and-drop - operation is a selection in a text field - - <dd>The user agent should delete the dragged selection from the - relevant text field. - - <dt>Otherwise - - <dd>The event has no default action. - </dl> - </ol> - </ol> - - <h5 id=when-the><span class=secno>5.3.3.1. </span>When the drag-and-drop - operation starts or ends in another document</h5> - - <p>The model described above is independent of which <code>Document</code> - object the nodes involved are from; the events must be fired as described - above and the rest of the processing model must be followed as described - above, irrespective of how many documents are involved in the operation. - - <h5 id=when-the0><span class=secno>5.3.3.2. </span>When the drag-and-drop - operation starts or ends in another application</h5> - - <p>If the drag is initiated in another application, the <a - href="#source0">source node</a> is not a DOM node, and the user agent must - use platform-specific conventions instead when the requirements above - involve the source node. User agents in this situation must act as if the - dragged data had been added to the <code><a - href="#datatransfer0">DataTransfer</a></code> object when the drag - started, even though no <code title=event-dragstart><a - href="#dragstart">dragstart</a></code> event was actually fired; user - agents must similarly use platform-specific conventions when deciding on - what drag feedback to use. - - <p>If a drag is started in a document but ends in another application, then - the user agent must instead replace the parts of the processing model - relating to handling the <em>target</em> according to platform-specific - conventions. - - <p>In any case, scripts running in the context of the document must not be - able to distinguish the case of a drag-and-drop operation being started or - ended in another application from the case of a drag-and-drop operation - being started or ended in another document from another domain. - - <h4 id=the-draggable><span class=secno>5.3.4. </span>The <dfn id=draggable - title=attr-draggable><code>draggable</code></dfn> attribute</h4> - - <p>All elements may have the <code title=attr-draggable><a - href="#draggable">draggable</a></code> content attribute set. The <code - title=attr-draggable><a href="#draggable">draggable</a></code> attribute - is an <a href="#enumerated">enumerated attribute</a>. It has three states. - The first state is <em>true</em> and it has the keyword <code - title="">true</code>. The second state is <em>false</em> and it has the - keyword <code title="">false</code>. The third state is <em>auto</em>; it - has no keywords but it is the <em>missing value default</em>. - - <p>The <dfn id=draggable0 title=dom-draggable><code>draggable</code></dfn> - DOM attribute, whose value depends on the content attribute's in the way - described below, controls whether or not the element is draggable. - Generally, only text selections are draggable, but elements whose <code - title=dom-draggable><a href="#draggable0">draggable</a></code> DOM - attribute is true become draggable as well. - - <p>If an element's <code title=attr-draggable><a - href="#draggable">draggable</a></code> content attribute has the state - <em>true</em>, the <code title=dom-draggable><a - href="#draggable0">draggable</a></code> DOM attribute must return true. - - <p>Otherwise, if the element's <code title=attr-draggable><a - href="#draggable">draggable</a></code> content attribute has the state - <em>false</em>, the <code title=dom-draggable><a - href="#draggable0">draggable</a></code> DOM attribute must return false. - - <p>Otherwise, the element's <code title=attr-draggable><a - href="#draggable">draggable</a></code> content attribute has the state - <em>auto</em>. If the element is an <code><a href="#img">img</a></code> - element, or, if the element is an <code><a href="#a">a</a></code> element - with an <code title=attr-hyperlink-href><a href="#href6">href</a></code> - content attribute, the <code title=dom-draggable><a - href="#draggable0">draggable</a></code> DOM attribute must return true. - - <p>Otherwise, the <code title=dom-draggable><a - href="#draggable0">draggable</a></code> DOM must return false. - - <p>If the <code title=dom-draggable><a - href="#draggable0">draggable</a></code> DOM attribute is set to the value - false, the <code title=attr-draggable><a - href="#draggable">draggable</a></code> content attribute must be set to - the literal value <code title="">false</code>. If the <code - title=dom-draggable><a href="#draggable0">draggable</a></code> DOM - attribute is set to the value true, the <code title=attr-draggable><a - href="#draggable">draggable</a></code> content attribute must be set to - the literal value <code title="">true</code>. - - <h4 id=copy-and><span class=secno>5.3.5. </span>Copy and paste</h4> - - <p>Copy-and-paste is a form of drag-and-drop: the "copy" part is equivalent - to dragging content to another application (the "clipboard"), and the - "paste" part is equivalent to dragging content <em>from</em> another - application. - - <p>Select-and-paste (a model used by mouse operations in the X Window - System) is equivalent to a drag-and-drop operation where the source is the - selection. - - <h5 id=copy-to><span class=secno>5.3.5.1. </span>Copy to clipboard</h5> - - <p>When the user invokes a copy operation, the user agent must act as if - the user had invoked a drag on the current selection. If the drag-and-drop - operation initiates, then the user agent must act as if the user had - indicated (as the <a href="#immediate">immediate user selection</a>) a - hypothetical application representing the clipbroad. Then, the user agent - must act as if the user had ended the drag-and-drop operation without - canceling it. If the drag-and-drop operation didn't get canceled, the user - agent should then follow the relevant platform-specific conventions for - copy operations (e.g. updating the clipboard). - - <h5 id=cut-to><span class=secno>5.3.5.2. </span>Cut to clipboard</h5> - - <p>When the user invokes a cut operation, the user agent must act as if the - user had invoked a copy operation (see the previous section), followed, if - the copy was completed successfully, by <a - href="#contenteditable-delete">a selection delete operation</a>. - - <h5 id=paste><span class=secno>5.3.5.3. </span>Paste from clipboard</h5> - - <p>When the user invokes a clipboard paste operation, the user agent must - act as if the user had invoked a drag on a hypothetical application - representing the clipboard, setting the data associated with the drag as - the text from the keyboard (either as <code title="">text/plain</code> or - <code>text/uri-list</code>). If the contents of the clipboard cannot be - represented as text or URIs, then the paste operation must not have any - effect. - - <p>Then, the user agent must act as if the user had indicated (as the <a - href="#immediate">immediate user selection</a>) the element with the - keyboard focus, and then ended the drag-and-drop operation without - canceling it. - - <h5 id=paste0><span class=secno>5.3.5.4. </span>Paste from selection</h5> - - <p>When the user invokes a selection paste operation, the user agent must - act as if the user had invoked a drag on the current selection, then - indicated (as the <a href="#immediate">immediate user selection</a>) the - element with the keyboard focus, and then ended the drag-and-drop - operation without canceling it. - - <p>If the contents of the selection cannot be represented as text or URIs, - then the paste operation must not have any effect. - - <h4 id=security7><span class=secno>5.3.6. </span>Security risks in the - drag-and-drop model</h4> - - <p>User agents must not make the data added to the <code><a - href="#datatransfer0">DataTransfer</a></code> object during the <code - title=event-dragstart><a href="#dragstart">dragstart</a></code> event - available to scripts until the <code title=event-drop><a - href="#drop">drop</a></code> event, because otherwise, if a user were to - drag sensitive information from one document to a second document, - crossing a hostile third document in the process, the hostile document - could intercept the data. - - <p>For the same reason, user agents must only consider a drop to be - successful if the user specifically ended the drag operation — if - any scripts end the drag operation, it must be considered unsuccessful - (canceled) and the <code title=event-drop><a href="#drop">drop</a></code> - event must not be fired. - - <p>User agents should take care to not start drag-and-drop operations in - response to script actions. For example, in a mouse-and-window - environment, if a script moves a window while the user has his mouse - button depressed, the UA would not consider that to start a drag. This is - important because otherwise UAs could cause data to be dragged from - sensitive sources and dropped into hostile documents without the user's - consent. - - <h3 id=undo><span class=secno>5.4. </span><dfn id=undo-history>Undo - history</dfn></h3> - - <p class=big-issue>There has got to be a better way of doing this, surely. - - <p>The user agent must associate an <dfn id=undo-transaction>undo - transaction history</dfn> with each <code><a - href="#htmldocument">HTMLDocument</a></code> object. - - <p>The <a href="#undo-transaction">undo transaction history</a> is a list - of entries. The entries are of two type: <a href="#dom-changes">DOM - changes</a> and <a href="#undo-object" title="undo object">undo - objects</a>. - - <p>Each <dfn id=dom-changes>DOM changes</dfn> entry in the <a - href="#undo-transaction">undo transaction history</a> consists of batches - of one or more of the following: - - <ul> - <li>Changes to the <a href="#content">content attributes</a> of an - <code>Element</code> node. - - <li>Changes to the <a href="#dom-attributes">DOM attributes</a> of a - <code>Node</code>.</li> - <!-- XXX uh, these change on their own, so - clearly this isn't going to fly. Which DOM attributes, exactly? --> - - <li>Changes to the DOM hierarchy of nodes that are descendants of the - <code><a href="#htmldocument">HTMLDocument</a></code> object - (<code>parentNode</code>, <code>childNodes</code>). - </ul> - - <p><dfn id=undo-object>Undo object</dfn> entries consist of objects - representing state that scripts running in the document are managing. For - example, a Web mail application could use an <a href="#undo-object">undo - object</a> to keep track of the fact that a user has moved an e-mail to a - particular folder, so that the user can undo the action and have the - e-mail return to its former location. - - <p>Broadly speaking, <a href="#dom-changes">DOM changes</a> entries are - handled by the UA in response to user edits of form controls and - <span>editing hosts</span> on the page, and <a href="#undo-object">undo - object</a> entries are handled by script in response to higher-level user - actions (such as interactions with server-side state, or in the - implementation of a drawing tool). - - <h4 id=the-undomanager><span class=secno>5.4.1. </span>The <code><a - href="#undomanager">UndoManager</a></code> interface</h4> - - <div class=big-issue> - <p>This API sucks. Seriously. It's a terrible API. Really bad. I hate it. - Here are the requirements:</p> - - <ul> - <li>Has to cope with cases where the server has undo state already when - the page is loaded, that can be stuffed into the undo buffer onload. - - <li>Has to support undo/redo. - - <li>Has to cope with the "undo" action being "contact the server and tell - it to undo", rather than it being the opposite of the "redo" action. - - <li>Has to cope with some undo states expiring from the undo history - (e.g. server can only remember one undelete action) but other states not - expiring (e.g. client can undo arbitrary amounts of local edits). - </ul> - </div> - - <p>To manage <a href="#undo-object">undo object</a> entries in the <a - href="#undo-transaction">undo transaction history</a>, the <code><a - href="#undomanager">UndoManager</a></code> interface can be used: - - <pre class=idl>interface <dfn id=undomanager>UndoManager</dfn> { - unsigned long <a href="#adddata" title=dom-UndoManager-add>add</a>(in DOMObject data, in DOMStrong title); - void <a href="#remove1" title=dom-UndoManager-remove>remove</a>(in unsigned long index); - void <a href="#clearundo" title=dom-UndoManager-clearUndo>clearUndo</a>(); - void <a href="#clearredo" title=dom-UndoManager-clearRedo>clearRedo</a>(); - DOMObject <a href="#itemn" title=dom-UndoManager-item>item</a>(in unsigned long index); - readonly attribute unsigned long <a href="#length9" title=dom-UndoManager-length>length</a>; - readonly attribute unsigned long <a href="#position0" title=dom-UndoManager-position>position</a>; -};</pre> - - <p>The <dfn id=undomanager0 - title=dom-undoManager><code>undoManager</code></dfn> attribute of the - <code><a href="#window">Window</a></code> interface must return the object - implementing the <code><a href="#undomanager">UndoManager</a></code> - interface for that <code><a href="#window">Window</a></code> object's - associated <code><a href="#htmldocument">HTMLDocument</a></code> object. - - <p>In the ECMAScript DOM binding, objects implementing this interface must - also support being dereferenced using the square bracket notation, such - that dereferencing with an integer index is equivalent to invoking the - <code title=dom-UndoManager-item><a href="#itemn">item()</a></code> method - with that index (e.g. <code title="">undoManager[1]</code> returns the - same as <code title="">undoManager.item(1)</code>). - - <p><code><a href="#undomanager">UndoManager</a></code> objects represent - their document's <a href="#undo-transaction">undo transaction history</a>. - Only <a href="#undo-object">undo object</a> entries are visible with this - API, but this does not mean that <a href="#dom-changes">DOM changes</a> - entries are absent from the <a href="#undo-transaction">undo transaction - history</a>. - - <p>The <dfn id=length9 - title=dom-UndoManager-length><code>length</code></dfn> attribute must - return the number of <a href="#undo-object">undo object</a> entries in the - <a href="#undo-transaction">undo transaction history</a>. - - <p>The <dfn id=itemn title=dom-UndoManager-item><code>item(<var - title="">n</var>)</code></dfn> method must return the <var - title="">n</var>th <a href="#undo-object">undo object</a> entry in the <a - href="#undo-transaction">undo transaction history</a>. - - <p>The <a href="#undo-transaction">undo transaction history</a> has a <dfn - id=current3 title="undo position">current position</dfn>. This is the - position between two entries in the <a href="#undo-transaction">undo - transaction history</a>'s list where the previous entry represents what - needs to happen if the user invokes the "undo" command (the "undo" side, - lower numbers), and the next entry represents what needs to happen if the - user invokes the "redo" command (the "redo" side, higher numbers). - - <p>The <dfn id=position0 - title=dom-UndoManager-position><code>position</code></dfn> attribute must - return the index of the <a href="#undo-object">undo object</a> entry - nearest to the <a href="#current3">undo position</a>, on the "redo" side. - If there are no <a href="#undo-object">undo object</a> entries on the - "redo" side, then the attribute must return the same as the <code - title=dom-UndoManager-length><a href="#length9">length</a></code> - attribute. If there are no <a href="#undo-object">undo object</a> entries - on the "undo" side of the <a href="#current3">undo position</a>, the <code - title=dom-UndoManager-position><a href="#position0">position</a></code> - attribute returns zero. - - <p class=note>Since the <a href="#undo-transaction">undo transaction - history</a> contains both <a href="#undo-object">undo object</a> entries - and <a href="#dom-changes">DOM changes</a> entries, but the <code - title=dom-UndoManager-position><a href="#position0">position</a></code> - attribute only returns indices relative to <a href="#undo-object">undo - object</a> entries, it is possible for several "undo" or "redo" actions to - be performed without the value of the <code - title=dom-UndoManager-position><a href="#position0">position</a></code> - attribute changing. - - <p>The <dfn id=adddata title=dom-UndoManager-add><code>add(<var - title="">data</var>, <var title="">title</var>)</code></dfn> method's - behaviour depends on the current state. Normally, it must insert the <var - title="">data</var> object passed as an argument into the <a - href="#undo-transaction">undo transaction history</a> immediately before - the <a href="#current3">undo position</a>, optionally remembering the - given <var title="">title</var> to use in the UI. If the method is called - <a href="#undo-moving0" title=do-undo>during an undo operation</a>, - however, the object must instead be added immediately <em>after</em> the - <a href="#current3">undo position</a>. - - <p>If the method is called and there is neither <a href="#undo-moving0" - title=do-undo>an undo operation in progress</a> nor <a - href="#redo-moving0" title=do-redo>a redo operation in progress</a> then - any entries in the <a href="#undo-transaction">undo transaction - history</a> after the <a href="#current3">undo position</a> must be - removed (as if <code title=dom-UndoManager-clearRedo><a - href="#clearredo">clearRedo()</a></code> had been called). - - <p class=big-issue>We could fire events when someone adds something to the - undo history -- one event per undo object entry before the position (or - after, during redo addition), allowing the script to decide if that entry - should remain or not. Or something. Would make it potentially easier to - expire server-held state when the server limitations come into play.</p> - <!-- XXX note on expiring undo in case server can only do one level undo --> - - <p>The <dfn id=remove1 title=dom-UndoManager-remove><code>remove(<var - title="">index</var>)</code></dfn> method must remove the <a - href="#undo-object">undo object</a> entry with the specified <var - title="">index</var>. If the index is less than zero or greater than or - equal to <code title=dom-UndoManager-length><a - href="#length9">length</a></code> then the method must raise an - <code>INDEX_SIZE_ERR</code> exception. <a href="#dom-changes">DOM - changes</a> entries are unaffected by this method. - - <p>The <dfn id=clearundo - title=dom-UndoManager-clearUndo><code>clearUndo()</code></dfn> method must - remove all entries in the <a href="#undo-transaction">undo transaction - history</a> before the <a href="#current3">undo position</a>, be they <a - href="#dom-changes">DOM changes</a> entries or <a href="#undo-object">undo - object</a> entries. - - <p>The <dfn id=clearredo - title=dom-UndoManager-clearRedo><code>clearRedo()</code></dfn> method must - remove all entries in the <a href="#undo-transaction">undo transaction - history</a> after the <a href="#current3">undo position</a>, be they <a - href="#dom-changes">DOM changes</a> entries or <a href="#undo-object">undo - object</a> entries. - - <p class=big-issue>Another idea is to have a way for scripts to say - "startBatchingDOMChangesForUndo()" and after that the changes to the DOM - go in as if the user had done them. - - <h4 id=undo-moving><span class=secno>5.4.2. </span><dfn id=undo-moving0 - title=do-undo>Undo: moving back in the undo transaction history</dfn></h4> - - <p>When the user invokes an undo operation, or when the <code - title=dom-document-execCommand><a - href="#execCommand">execCommand()</a></code> method is called with the - <code title=command-undo><a href="#undo1">undo</a></code> command, the - user agent must perform an undo operation. - - <p>If the <a href="#current3">undo position</a> is at the start of the <a - href="#undo-transaction">undo transaction history</a>, then the user agent - must do nothing. - - <p>If the entry immediately before the <a href="#current3">undo - position</a> is a <a href="#dom-changes">DOM changes</a> entry, then the - user agent must remove that <a href="#dom-changes">DOM changes</a> entry, - reverse the DOM changes that were listed in that entry, and, if the - changes were reversed with no problems, add a new <a - href="#dom-changes">DOM changes</a> entry (consisting of the opposite of - those DOM changes) to the <a href="#undo-transaction">undo transaction - history</a> on the other side of the <a href="#current3">undo - position</a>. - - <p>If the DOM changes cannot be undone (e.g. because the DOM state is no - longer consistent with the changes represented in the entry), then the - user agent must simply remove the <a href="#dom-changes">DOM changes</a> - entry, without doing anything else. - - <p>If the entry immediately before the <a href="#current3">undo - position</a> is an <a href="#undo-object">undo object</a> entry, then the - user agent must first remove that <a href="#undo-object">undo object</a> - entry from the <a href="#undo-transaction">undo transaction history</a>, - and then must fire an <code title=event-undo><a - href="#undo0">undo</a></code> event on the <code>Document</code> object, - using the <a href="#undo-object">undo object</a> entry's associated undo - object as the event's data. - - <p>Any calls to <code title=dom-undoManager-add><a - href="#adddata">add()</a></code> while the event is being handled will be - used to populate the redo history, and will then be used if the user - invokes the "redo" command to undo his undo. - - <h4 id=redo-moving><span class=secno>5.4.3. </span><dfn id=redo-moving0 - title=do-redo>Redo: moving forward in the undo transaction history</dfn></h4> - - <p>When the user invokes a redo operation, or when the <code - title=dom-document-execCommand><a - href="#execCommand">execCommand()</a></code> method is called with the - <code title=command-redo><a href="#redo0">redo</a></code> command, the - user agent must perform a redo operation. - - <p>This is mostly the opposite of an <a href="#undo-moving0" - title=do-undo>undo operation</a>, but the full definition is included here - for completeness. - - <p>If the <a href="#current3">undo position</a> is at the end of the <a - href="#undo-transaction">undo transaction history</a>, then the user agent - must do nothing. - - <p>If the entry immediately after the <a href="#current3">undo position</a> - is a <a href="#dom-changes">DOM changes</a> entry, then the user agent - must remove that <a href="#dom-changes">DOM changes</a> entry, reverse the - DOM changes that were listed in that entry, and, if the changes were - reversed with no problems, add a new <a href="#dom-changes">DOM - changes</a> entry (consisting of the opposite of those DOM changes) to the - <a href="#undo-transaction">undo transaction history</a> on the other side - of the <a href="#current3">undo position</a>. - - <p>If the DOM changes cannot be redone (e.g. because the DOM state is no - longer consistent with the changes represented in the entry), then the - user agent must simply remove the <a href="#dom-changes">DOM changes</a> - entry, without doing anything else. - - <p>If the entry immediately after the <a href="#current3">undo position</a> - is an <a href="#undo-object">undo object</a> entry, then the user agent - must first remove that <a href="#undo-object">undo object</a> entry from - the <a href="#undo-transaction">undo transaction history</a>, and then - must fire a <code title=event-undo><a href="#undo0">redo</a></code> event - on the <code>Document</code> object, using the <a href="#undo-object">undo - object</a> entry's associated undo object as the event's data. - - <h4 id=the-undomanagerevent><span class=secno>5.4.4. </span>The <code><a - href="#undomanagerevent">UndoManagerEvent</a></code> interface and the - <code title=event-undo><a href="#undo0">undo</a></code> and <code - title=event-redo><a href="#redo">redo</a></code> events</h4> - - <pre - class=idl>interface <dfn id=undomanagerevent>UndoManagerEvent</dfn> : Event { - readonly attribute DOMObject <a href="#data3" title=dom-UndoManagerEvent-data>data</a>; - void <a href="#initundomanagerevent" title=dom-UndoManagerEvent-initUndoManagerEvent>initUndoManagerEvent</a>(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMObject dataArg); - void <span title=dom-UndoManagerEvent-initUndoManagerEventNS>initUndoManagerEventNS</span>(in DOMString namespaceURIArg, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMObject dataArg); -};</pre> - - <p>The <dfn id=initundomanagerevent - title=dom-UndoManagerEvent-initUndoManagerEvent><code>initUndoManagerEvent()</code></dfn> - and <dfn id=initundomanagereventns><code - title=dom-UndoManagerEvent-initUndoManagerEventNS>initUndoManagerEventNS()</code></dfn> - methods must initialise the event in a manner analogous to the - similarly-named methods in the DOM3 Events interfaces. <a - href="#refsDOM3EVENTS">[DOM3EVENTS]</a> - - <p>The <dfn id=data3 - title=dom-UndoManagerEvent-data><code>data</code></dfn> attribute - represents the <a href="#undo-object">undo object</a> for the event. - - <p>The <dfn id=undo0 title=event-undo><code>undo</code></dfn> and <dfn - id=redo title=event-redo><code>redo</code></dfn> events do not bubble, - cannot be canceled, and have no default action. When the user agent fires - one of these events it must use the <code><a - href="#undomanagerevent">UndoManagerEvent</a></code> interface, with the - <code title=dom-UndoManagerEvent-data><a href="#data3">data</a></code> - field containing the relevant <a href="#undo-object">undo object</a>. - - <h4 id=implementation0><span class=secno>5.4.5. </span>Implementation notes</h4> - - <p>How user agents present the above conceptual model to the user is not - defined. The undo interface could be a filtered view of the <a - href="#undo-transaction">undo transaction history</a>, it could manipulate - the <a href="#undo-transaction">undo transaction history</a> in ways not - described above, and so forth. For example, it is possible to design a UA - that appears to have separate <a href="#undo-transaction" title="undo - transaction history">undo transaction histories</a> for each form control; - similarly, it is possible to design systems where the user has access to - more undo information than is present in the offical (as described above) - <a href="#undo-transaction">undo transaction history</a> (such as - providing a tree-based approach to document state). Such UI models should - be based upon the single <a href="#undo-transaction">undo transaction - history</a> described in this section, however, such that to a script - there is no detectable difference. - - <h3 id=command><span class=secno>5.5. </span>Command APIs</h3> - - <p>The <dfn id=execCommand - title=dom-document-execCommand><code>execCommand(<var - title="">commandId</var>, <var title="">doShowUI</var>, <var - title="">value</var>)</code></dfn> method on the <code><a - href="#htmldocument">HTMLDocument</a></code> interface allows scripts to - perform actions on the <a href="#a-selection" title="the - selection">current selection</a> or at the current caret position. - Generally, these commands would be used to implement editor UI, for - example having a "delete" button on a toolbar. - - <p>There are three variants to this method, with one, two, and three - arguments respectively. The <var title="">doShowUI</var> and <var - title="">value</var> parameters, even if specified, are ignored unless - otherwise stated. - - <p class=note>In this specification, in fact, the <var - title="">doShowUI</var> parameter is always ignored, regardless of its - value. It is included for historical reasons only. - - <p>When any of these methods are invoked, user agents must act as described - in the list below. - - <p>For actions marked "<dfn id=editing2>editing hosts only</dfn>", if the - selection is not entirely within an <a href="#editing1">editing host</a>, - of if there is no selection and the caret is not inside an <a - href="#editing1">editing host</a>, then the user agent must do nothing. - - <dl> - <dt>If the <var title="">commandId</var> is <dfn id=undo1 - title=command-undo><code>undo</code></dfn> - - <dd>The user agent must <a href="#undo-moving0" title=do-undo>move back - one step</a> in its <a href="#undo-transaction">undo transaction - history</a>, restoring the associated state. If there is no further undo - information the user agent must do nothing. See the <a - href="#undo-history">undo history</a>. - - <dt>If the <var title="">commandId</var> is <dfn id=redo0 - title=command-redo><code>redo</code></dfn> - - <dd>The user agent must <a href="#redo-moving0" title=do-redo>move forward - one step</a> in its <a href="#undo-transaction">undo transaction - history</a>, restoring the associated state. If there is no further undo - (well, "redo") information the user agent must do nothing. See the <a - href="#undo-history">undo history</a>. - - <dt>If the <var title="">commandId</var> is <dfn id=selectall0 - title=command-selectAll><code>selectAll</code></dfn> - - <dd>The user agent must change the selection so that all the content in - the currently focused <a href="#editing1">editing host</a> is selected. - If no <a href="#editing1">editing host</a> is focused, then the content - of the entire document must be selected. - - <dt>If the <var title="">commandId</var> is <dfn id=unselect - title=command-unselect><code>unselect</code></dfn> - - <dd> - <p>The user agent must change the selection so that nothing is selected.</p> - - <p class=big-issue>We need some sort of way in which the user can make a - selection without risk of script clobbering it. - - <dt>If the <var title="">commandId</var> is <dfn id=superscript - title=command-superscript><code>superscript</code></dfn> - - <dd><em><a href="#editing2">Editing hosts only.</a></em> The user agent - must act as if the user had requested that the selection <a - href="#contenteditable-wrapSemantic">be wrapped in the semantics</a> of - the <code><a href="#sup">sup</a></code> element (or unwrapped, or, if - there is no selection, have that semantic inserted or removed — the - exact behaviour is UA-defined). - - <dt>If the <var title="">commandId</var> is <dfn id=subscript - title=command-subscript><code>subscript</code></dfn> - - <dd><em><a href="#editing2">Editing hosts only.</a></em> The user agent - must act as if the user had requested that the selection <a - href="#contenteditable-wrapSemantic">be wrapped in the semantics</a> of - the <em title=""><code><a href="#sub">sub</a></code></em> element (or, - again, unwrapped, or have that semantic inserted or removed, as defined - by the UA). - - <dt>If the <var title="">commandId</var> is <dfn id=formatblock - title=command-formatBlock><code>formatBlock</code></dfn> - - <dd> - <p><em><a href="#editing2">Editing hosts only.</a></em> This command - changes the semantics of the blocks containing the selection.</p> - - <p>If there is no selection, then, where in the description below refers - to the selection, the user agent must act as if the selection was an - empty range at the caret position.</p> - - <p>If the <var title="">value</var> parameter is not specified or has a - value other than one of the following literal strings:</p> - - <ul class=brief> - <li><code title=""><address></code> - - <li><code title=""><aside></code> - - <li><code title=""><h1></code> - - <li><code title=""><h2></code> - - <li><code title=""><h3></code> - - <li><code title=""><h4></code> - - <li><code title=""><h5></code> - - <li><code title=""><h6></code> - - <li><code title=""><nav></code> - - <li><code title=""><p></code> - - <li><code title=""><pre></code> - </ul> - - <p>...then the user agent must do nothing.</p> - - <p>Otherwise, the user agent must, for every position in the selection, - take the furthest <a href="#block-level0" title="block-level - elements">block-level element</a> ancestor of that position that - contains only <a href="#inline-level0">inline-level content</a> and is - not being used as a <a href="#structured" title="structured inline-level - elements">structured inline-level element</a>, and, if that element is a - descendant of the editing host, rename it (as if the <code - title="">Element.renameNode()</code> method had been used) according to - the <var title="">value</var>, by stripping the leading - <code><</code> character and the trailing <code>></code> character - and using the rest as the new tag name, using the HTML namespace. - - <dt>If the <var title="">commandId</var> is <dfn id=delete - title=command-delete><code>delete</code></dfn> - - <dd><em><a href="#editing2">Editing hosts only.</a></em> The user agent - must act as if the user had performed <a href="#contenteditable-delete">a - backspace operation</a>. - - <dt>If the <var title="">commandId</var> is <dfn id=forwarddelete - title=command-forwardDelete><code>forwardDelete</code></dfn> - - <dd><em><a href="#editing2">Editing hosts only.</a></em> The user agent - must act as if the user had performed <a href="#contenteditable-delete">a - forward delete operation</a>. - - <dt>If the <var title="">commandId</var> is <dfn id=insertlinebreak - title=command-insertLineBreak><code>insertLineBreak</code></dfn> - - <dd><em><a href="#editing2">Editing hosts only.</a></em> The user agent - must act as if the user had <a href="#contenteditable-br">requested a - line separator</a>. - - <dt>If the <var title="">commandId</var> is <dfn id=insertparagraph - title=command-insertParagraph><code>insertParagraph</code></dfn> - - <dd><em><a href="#editing2">Editing hosts only.</a></em> The user agent - must act as if the user had performed a <a - href="#contenteditable-breakBlock">break block</a> editing action. - - <dt>If the <var title="">commandId</var> is <dfn id=inserttext - title=command-insertText><code>insertText</code></dfn> - - <dd><em><a href="#editing2">Editing hosts only.</a></em> The user agent - must act as if the user had <a - href="#contenteditable-insertText">inserted text</a> corresponding to the - <var title="">value</var> parameter. - - <dt>If the <var title="">commandId</var> is <code><var - title="">vendorID</var>-<var title="">customCommandID</var></code> - - <dd>User agents may implement vendor-specific extensions to this API. - Vendor-specific extensions to the list of commands should use the syntax - <code><var title="">vendorID</var>-<var - title="">customCommandID</var></code> so as to prevent clashes between - extensions from different vendors and future additions to this - specification. - - <dt>If the <var title="">commandId</var> is something else - - <dd>User agents must do nothing. - </dl> - - <h3 id=selection><span class=secno>5.6. </span>The text selection APIs</h3> - - <p>Every <a href="#browsing0">browsing context</a> has <dfn id=a-selection - title="the selection">a selection</dfn>. The selection may be empty, and - the selection may have more than one range (a disjointed selection). The - user should be able to change the selection. User agents are not required - to let the user select more than one range, and may collapse multiple - ranges in the selection to a single range when the user interacts with the - selection. (But, of course, the user agent may let the user create - selections with multiple ranges.) - - <p>This one selection must be shared by all the content of the browsing - context (though not by nested <a href="#browsing0" title="browsing - context">browsing contexts</a>), including any editing hosts in the - document. (Editing hosts that are not inside a document cannot have a - selection.) - - <p>If the selection is empty (collapsed, so that it has only one segment - and that segment's start and end points are the same) then the selection's - position should equal the caret position. When the selection is not empty, - this specification does not define the caret position; user agents should - follow platform conventions in deciding whether the caret is at the start - of the selection, the end of the selection, or somewhere else. - - <p>On some platforms (such as those using Wordstar editing conventions), - the caret position is totally independent of the start and end of the - selection, even when the selection is empty. On such platforms, user - agents may ignore the requirement that the cursor position be linked to - the position of the selection altogether. - - <p>Mostly for historical reasons, in addition to the <a - href="#browsing0">browsing context</a>'s <a href="#a-selection" title="the - selection">selection</a>, each <code>textarea</code> and - <code>input</code> element has an independent selection. These are the - <dfn id=text-field title="text field selection">text field - selections</dfn>. - - <p>The <code><a href="#datagrid0">datagrid</a></code> and - <code>select</code> elements also have selections, indicating which items - have been picked by the user. These are not discussed in this section. - - <p class=note>This specification does not specify how selections are - presented to the user. The Selectors specification, in conjunction with - CSS, can be used to style text selections using the <code><a - href="#selection1">::selection</a></code> pseudo-element. <a - href="#refsSELECTORS">[SELECTORS]</a> <a href="#refsCSS21">[CSS21]</a> - - <h4 id=documentSelection><span class=secno>5.6.1. </span>APIs for the - browsing context selection</h4> - - <p>The <dfn id=getselection - title=dom-getSelection><code>getSelection()</code></dfn> method on the - <code><a href="#window">Window</a></code> interface must return the - <code><a href="#selection1">Selection</a></code> object representing <a - href="#a-selection">the selection</a> of that <code><a - href="#window">Window</a></code> object's <a href="#browsing0">browsing - context</a>. - - <p>For historical reasons, the <dfn id=getselection0 - title=dom-document-getSelection><code>getSelection()</code></dfn> method - on the <code><a href="#htmldocument">HTMLDocument</a></code> interface - must return the same <code><a href="#selection1">Selection</a></code> - object. - - <pre class=idl>interface <dfn id=selection1>Selection</dfn> { - readonly attribute Node <a href="#anchornode" title=dom-selection-anchorNode>anchorNode</a>; - readonly attribute long <a href="#anchoroffset" title=dom-selection-anchorOffset>anchorOffset</a>; - readonly attribute Node <a href="#focusnode" title=dom-selection-focusNode>focusNode</a>; - readonly attribute long <a href="#focusoffset" title=dom-selection-focusOffset>focusOffset</a>; - readonly attribute boolean <a href="#iscollapsed" title=dom-selection-isCollapsed>isCollapsed</a>; - void <a href="#collapse" title=dom-selection-collapse>collapse</a>(in Node parentNode, in long offset); - void <a href="#collapsetostart" title=dom-selection-collapseToStart>collapseToStart</a>(); - void <a href="#collapsetoend" title=dom-selection-collapseToEnd>collapseToEnd</a>(); - void <a href="#selectallchildren" title=dom-selection-selectAllChildren>selectAllChildren</a>(in Node parentNode); - void <a href="#deletefromdocument" title=dom-selection-deleteFromDocument>deleteFromDocument</a>(); - readonly attribute long <a href="#rangecount" title=dom-selection-rangeCount>rangeCount</a>; - Range <a href="#getrangeat" title=dom-selection-getRangeAt>getRangeAt</a>(in long index); - void <a href="#addrange" title=dom-selection-addRange>addRange</a>(in Range range); - void <a href="#removerange" title=dom-selection-removeRange>removeRange</a>(in Range range); - void <a href="#removeallranges" title=dom-selection-removeAllRanges>removeAllRanges</a>(); - DOMString <a href="#tostring" title=dom-selection-toString>toString</a>(); -};</pre> - <!-- - See also: - http://lxr.mozilla.org/mozilla/source/content/base/public/nsISelection.idl - This spec doesn't have everything from there yet, in particular - selectionLanguageChange() and containsNode() are missing. They are missing - because I couldn't work out how to define them in terms of Ranges. - - I also haven't included extend(): - - void <span title="dom-selection-extend">extend</span>(in Node parentNode, in long offset); - // raise if no range - // raise WRONG_DOCUMENT_ERR if parentNode not in document - // do something - - ...mostly because I can't work out how to describe what it does quickly. ---> - - <p>The <code><a href="#selection1">Selection</a></code> interface is - represents a list of <code>Range</code> objects. The first item in the - list has index 0, and the last item has index <var title="">count</var>-1, - where <var title="">count</var> is the number of ranges in the list. <a - href="#refsDOM2RANGE">[DOM2RANGE]</a> - - <p>All of the members of the <code><a - href="#selection1">Selection</a></code> interface are defined in terms of - operations on the <code>Range</code> objects represented by this object. - These operations can raise exceptions, as defined for the - <code>Range</code> interface; this can therefore result in the members of - the <code><a href="#selection1">Selection</a></code> interface raising - exceptions as well, in addition to any explicitly called out below.</p> - <!--- XXX example --> - - <p>The <dfn id=anchornode - title=dom-selection-anchorNode><code>anchorNode</code></dfn> attribute - must return the value returned by the <code title="">startContainer</code> - attribute of the last <code>Range</code> object in the list, or null if - the list is empty. - - <p>The <dfn id=anchoroffset - title=dom-selection-anchorOffset><code>anchorOffset</code></dfn> attribute - must return the value returned by the <code title="">startOffset</code> - attribute of the last <code>Range</code> object in the list, or 0 if the - list is empty. - - <p>The <dfn id=focusnode - title=dom-selection-focusNode><code>focusNode</code></dfn> attribute must - return the value returned by the <code title="">endContainer</code> - attribute of the last <code>Range</code> object in the list, or null if - the list is empty. - - <p>The <dfn id=focusoffset - title=dom-selection-focusOffset><code>focusOffset</code></dfn> attribute - must return the value returned by the <code title="">endOffset</code> - attribute of the last <code>Range</code> object in the list, or 0 if the - list is empty. - - <p>The <dfn id=iscollapsed - title=dom-selection-isCollapsed><code>isCollapsed</code></dfn> attribute - must return true if there are zero ranges, or if there is exactly one - range and its <code title="">collapsed</code> attribute is itself true. - Otherwise it must return false. - - <p>The <dfn id=collapse title=dom-selection-collapse><code>collapse(<var - title="">parentNode</var>, <var title="">offset</var>)</code></dfn> method - must raise a <code>WRONG_DOCUMENT_ERR</code> DOM exception if <var - title="">parentNode</var>'s <code title="">ownerDocument</code> is not the - <code><a href="#htmldocument">HTMLDocument</a></code> object with which - the <code><a href="#selection1">Selection</a></code> object is associated. - Otherwise it is, and the method must remove all the ranges in the <code><a - href="#selection1">Selection</a></code> list, then create a new - <code>Range</code> object, add it to the list, and invoke its <code - title="">setStart()</code> and <code title="">setEnd()</code> methods with - the <var title="">parentNode</var> and <var title="">offset</var> values - as their arguments. - - <p>The <dfn id=collapsetostart - title=dom-selection-collapseToStart><code>collapseToStart()</code></dfn> - method must raise an <code>INVALID_STATE_ERR</code> DOM exception if there - are no ranges in the list. Otherwise, it must invoke the <code - title=dom-selection-collapse><a href="#collapse">collapse()</a></code> - method with the <code title="">startContainer</code> and <code - title="">startOffset</code> values of the first <code>Range</code> object - in the list as the arguments. - - <p>The <dfn id=collapsetoend - title=dom-selection-collapseToEnd><code>collapseToEnd()</code></dfn> - method must raise an <code>INVALID_STATE_ERR</code> DOM exception if there - are no ranges in the list. Otherwise, it must invoke the <code - title=dom-selection-collapse><a href="#collapse">collapse()</a></code> - method with the <code title="">endContainer</code> and <code - title="">endOffset</code> values of the last <code>Range</code> object in - the list as the arguments. - - <p>The <dfn id=selectallchildren - title=dom-selection-selectAllChildren><code>selectAllChildren(<var - title="">parentNode</var>)</code></dfn> method must invoke the <code - title=dom-selection-collapse><a href="#collapse">collapse()</a></code> - method with the <var title="">parentNode</var> value as the first argument - and 0 as the second argument, and must then invoke the <code - title="">selectNodeContents()</code> method on the first (and only) range - in the list with the <var title="">parentNode</var> value as the argument. - - <p>The <dfn id=deletefromdocument - title=dom-selection-deleteFromDocument><code>deleteFromDocument()</code></dfn> - method must invoke the <code title="">deleteContents()</code> method on - each range in the list, if any, from first to last. - - <p>The <dfn id=rangecount - title=dom-selection-rangeCount><code>rangeCount</code></dfn> attribute - must return the number of ranges in the list. - - <p>The <dfn id=getrangeat - title=dom-selection-getRangeAt><code>getRangeAt(<var - title="">index</var>)</code></dfn> method must return the <var - title="">index</var>th range in the list. If <var title="">index</var> is - less than zero or greater or equal to the value returned by the <code - title=dom-selection-rangeCount><a href="#rangecount">rangeCount</a></code> - attribute, then the method must raise an <code>INDEX_SIZE_ERR</code> DOM - exception. - - <p>The <dfn id=addrange title=dom-selection-addRange><code>addRange(<var - title="">range</var>)</code></dfn> method must add the given <var - title="">range</var> Range object to the list of selections, at the end - (so the newly added range is the new last range). Duplicates are not - prevented; a range may be added more than once in which case it appears in - the list more than once, which (for example) will cause <code - title=dom-selection-toString><a href="#tostring">toString()</a></code> to - return the range's text twice.</p> - <!-- XXX how does this interact with - deleteFromDocument() which acts on all ranges? --> - - <p>The <dfn id=removerange - title=dom-selection-removeRange><code>removeRange(<var - title="">range</var>)</code></dfn> method must remove the first occurrence - of <var title="">range</var> in the list of ranges, if it appears at all. - - <p>The <dfn id=removeallranges - title=dom-selection-removeAllRanges><code>removeAllRanges()</code></dfn> - method must remove all the ranges from the list of ranges, such that the - <code title=dom-selection-rangeCount><a - href="#rangecount">rangeCount</a></code> attribute returns 0 after the - <code title=dom-selection-removeAllRanges><a - href="#removeallranges">removeAllRanges()</a></code> method is invoked - (and until a new range is added to the list, either through this interface - or via user interaction). - - <p>The <dfn id=tostring - title=dom-selection-toString><code>toString()</code></dfn> method must - return a concatenation of the results of invoking the <code - title="">toString()</code> method of the <code>Range</code> object on each - of the ranges of the selection, in the order they appear in the list - (first to last). - - <p>In language bindings where this is supported, objects implementing the - <code><a href="#selection1">Selection</a></code> interface must stringify - to the value returned by the object's <code - title=dom-selection-toString><a href="#tostring">toString()</a></code> - method. - - <div class=example> - <p>In the following document fragment, the emphasised parts indicate the - selection.</p> - - <pre><p>The cute girl likes <em>the </em><cite><em>Oxford English</em> Dictionary</cite>.</p></pre> - - <p>If a script invoked <code - title="">window.getSelection().toString()</code>, the return value would - be "<code>the Oxford English</code>".</p> - </div> - - <p class=note>The <code><a href="#selection1">Selection</a></code> - interface has no relation to the <code><a - href="#datagridselection">DataGridSelection</a></code> interface. - - <h4 id=textFieldSelection><span class=secno>5.6.2. </span>APIs for the text - field selections</h4> - - <p class=big-issue>When we define HTMLTextAreaElement and HTMLInputElement - we will have to add the IDL given below to both of their IDLs. - - <p>The <code>input</code> and <code>textarea</code> elements define four - members in their DOM interfaces for handling their text selection: - - <pre - class=idl> void <a href="#select0" title="dom-textarea/input-select">select</a>(); - attribute unsigned long <a href="#selectionstart" title="dom-textarea/input-selectionStart">selectionStart</a>; - attribute unsigned long <a href="#selectionend" title="dom-textarea/input-selectionEnd">selectionEnd</a>; - void <a href="#setselectionrange" title="dom-textarea/input-setSelectionRange">setSelectionRange</a>(in unsigned long start, in unsigned long end);</pre> - <!-- XXX also add textLength? it seems to be widely used --> - - <p>These methods and attributes expose and control the selection of - <code>input</code> and <code>textarea</code> text fields. - - <p>The <dfn id=select0 - title="dom-textarea/input-select"><code>select()</code></dfn> method must - cause the contents of the text field to be fully selected. - - <p>The <dfn id=selectionstart - title="dom-textarea/input-selectionStart"><code>selectionStart</code></dfn> - attribute must, on getting, return the offset (in logical order) to the - character that immediately follows the start of the selection. If there is - no selection, then it must return the offset (in logical order) to the - character that immediately follows the text entry cursor. - - <p>On setting, it must act as if the <code - title="dom-textarea/input-setSelectionRange"><a - href="#setselectionrange">setSelectionRange()</a></code> method had been - called, with the new value as the first argument, and the current value of - the <code title="dom-textarea/input-selectionEnd"><a - href="#selectionend">selectionEnd</a></code> attribute as the second - argument, unless the current value of the <code - title="dom-textarea/input-selectionEnd"><a - href="#selectionend">selectionEnd</a></code> is less than the new value, - in which case the second argument must also be the new value. - - <p>The <dfn id=selectionend - title="dom-textarea/input-selectionEnd"><code>selectionEnd</code></dfn> - attribute must, on getting, return the offset (in logical order) to the - character that immediately follows the end of the selection. If there is - no selection, then it must return the offset (in logical order) to the - character that immediately follows the text entry cursor. - - <p>On setting, it must act as if the <code - title="dom-textarea/input-setSelectionRange"><a - href="#setselectionrange">setSelectionRange()</a></code> method had been - called, with the current value of the <code - title="dom-textarea/input-selectionStart"><a - href="#selectionstart">selectionStart</a></code> attribute as the first - argument, and new value as the second argument. - - <p>The <dfn id=setselectionrange - title="dom-textarea/input-setSelectionRange"><code>setSelectionRange(<var - title="">start</var>, <var title="">end</var>)</code></dfn> method must - set the selection of the text field to the sequence of characters starting - with the character at the <var title="">start</var>th position (in logical - order) and ending with the character at the <span>(<var - title="">end</var>-1)</span>th position. Arguments greater than the length - of the value in the text field must be treated as pointing at the end of - the text field. If <var title="">end</var> is less than or equal to <var - title="">start</var> then the start of the selection and the end of the - selection must both be placed immediately before the character with offset - <var title="">end</var>. In UAs where there is no concept of an empty - selection, this must set the cursor to be just before the character with - offset <var title="">end</var>. - - <div class=example> - <p>To obtain the currently selected text, the following JavaScript - suffices:</p> - - <pre>var selectionText = control.value.substring(control.selectionStart, control.selectionEnd);</pre> - - <p>...where <var title="">control</var> is the <code>input</code> or - <code>textarea</code> element.</p> - </div> - - <p>Characters with no visible rendering, such as U+200D ZERO WIDTH JOINER, - still count as characters. Thus, for instance, the selection can include - just an invisible character, and the text insertion cursor can be placed - to one side or another of such a character. - - <p>When these methods and attributes are used with <code>input</code> - elements that are not displaying simple text fields, they must raise an - <code>INVALID_STATE_ERR</code> exception. - - <h2 id=comms><span class=secno>6. </span>Communication</h2> - - <h3 id=event0><span class=secno>6.1. </span>Event definitions</h3> - - <p>Messages in <a href="#cross-document">cross-document messaging</a> and, - by default, in <a href="#server-sent">server-sent DOM events</a>, use the - <dfn id=message title=event-message><code>message</code></dfn> event. - - <p>The following interface is defined for this event: - - <pre class=idl>interface <dfn id=messageevent>MessageEvent</dfn> : Event { - readonly attribute DOMString <a href="#data4" title=dom-MessageEvent-data>data</a>; - readonly attribute DOMString <a href="#domain2" title=dom-MessageEvent-domain>domain</a>; - readonly attribute DOMString <a href="#uri" title=dom-MessageEvent-uri>uri</a>; - readonly attribute Document <a href="#source1" title=dom-MessageEvent-source>source</a>; - void <a href="#initmessageevent" title=dom-MessageEvent-initMessageEvent>initMessageEvent</a>(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString dataArg, in DOMString domainArg, in DOMString uriArg, in Document documentArg); - void <a href="#initmessageeventns" title=dom-MessageEvent-initMessageEventNS>initMessageEventNS</a>(in DOMString namespaceURI, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString dataArg, in DOMString domainArg, in DOMString uriArg, in Document documentArg); -};</pre> - - <p>The <dfn id=initmessageevent - title=dom-MessageEvent-initMessageEvent><code>initMessageEvent()</code></dfn> - and <dfn id=initmessageeventns - title=dom-MessageEvent-initMessageEventNS><code>initMessageEventNS()</code></dfn> - methods must initialise the event in a manner analogous to the - similarly-named methods in the DOM3 Events interfaces. <a - href="#refsDOM3EVENTS">[DOM3EVENTS]</a> - - <p>The <dfn id=data4 title=dom-MessageEvent-data><code>data</code></dfn> - attribute represents the message being sent. - - <p>The <dfn id=domain2 - title=dom-MessageEvent-domain><code>domain</code></dfn> attribute - represents, in <a href="#cross-document">cross-document messaging</a>, the - domain of the document from which the message came. - - <p>The <dfn id=uri title=dom-MessageEvent-uri><code>uri</code></dfn> - attribute represents, in <a href="#cross-document">cross-document - messaging</a>, the address of the document from which the message came. - - <p>The <dfn id=source1 - title=dom-MessageEvent-source><code>source</code></dfn> attribute - represents, in <a href="#cross-document">cross-document messaging</a>, the - <code>Document</code> from which the message came. - - <h3 id=server-sent-events><span class=secno>6.2. </span><dfn - id=server-sent>Server-sent DOM events</dfn></h3> - <!-- event-source --> - - <p>This section describes a mechanism for allowing servers to dispatch DOM - events into documents that expect it. The <code><a - href="#event-source">event-source</a></code> element provides a simple - interface to this mechanism. - - <h4 id=the-remoteeventtarget><span class=secno>6.2.1. </span>The <dfn - id=remoteeventtarget><code>RemoteEventTarget</code></dfn> interface</h4> - - <p>Any object that implements the <code>EventTarget</code> interface must - also implement the <code><a - href="#remoteeventtarget0">RemoteEventTarget</a></code> interface. - - <pre - class=idl>interface <dfn id=remoteeventtarget0>RemoteEventTarget</dfn> { - void <a href="#addeventsource" title=dom-RemoteEventTarget-addEventSource>addEventSource</a>(in DOMString src); - void <a href="#removeeventsource" title=dom-RemoteEventTarget-removeEventSource>removeEventSource</a>(in DOMString src); -};</pre> - - <p>When the <dfn id=addeventsource - title=dom-RemoteEventTarget-addEventSource><code>addEventSource(<var - title="">src</var>)</code></dfn> method is invoked, the user agent must - add the URI specified in <var title="">src</var> to the <a - href="#list-of3" title=concept-event-source-list>list of event sources</a> - for that object. The same URI can be registered multiple times. - - <p>When the <dfn id=removeeventsource - title=dom-RemoteEventTarget-removeEventSource><code>removeEventSource(<var - title="">src</var>)</code></dfn> method is invoked, the user agent must - remove the URI specified in <var title="">src</var> from the <a - href="#list-of3" title=concept-event-source-list>list of event sources</a> - for that object. If the same URI has been registered multiple times, - removing it must only remove one instance of that URI for each invocation - of the <code title=removeEventSource>removeEventSource()</code> method. - - <p>Relative URIs must be resolved relative to <span - class=big-issue>...</span>. - - <h4 id=connecting><span class=secno>6.2.2. </span>Connecting to an event - stream</h4> - - <p>Each object implementing the <code>EventTarget</code> and <code><a - href="#remoteeventtarget0">RemoteEventTarget</a></code> interfaces has a - <dfn id=list-of3 title=concept-event-source-list>list of event - sources</dfn> that are registered for that object. - - <p>When a new URI is added to this list, the user agent should, as soon as - all currently executing scripts (if any) have finished executing, and if - the specified URI isn't removed from the list before they do so, fetch the - resource identified by that URI. - - <p>When an event source is removed from the list of event sources for an - object, if that resource is still being fetched, then the relevant - connection must be closed. - - <p>Since connections established to remote servers for such resources are - expected to be long-lived, UAs should ensure that appropriate buffering is - used. In particular, while line buffering may be safe if lines are defined - to end with a single U+000A LINE FEED character, block buffering or line - buffering with different expected line endings can cause delays in event - dispatch. - - <p>In general, the semantics of the transport protocol specified by the - URIs for the event sources must be followed, including HTTP caching rules. - - <p>For HTTP connections, the <code title="">Accept</code> header may be - included; if included, it must only contain formats of event framing that - are supported by the user agent (one of which must be - <code>application/x-dom-event-stream</code>, as described below). - - <p>Other formats of event framing may also be supported in addition to - <code>application/x-dom-event-stream</code>, but this specification does - not define how they are to be parsed or processed. - - <p class=note>Such formats could include systems like SMS-push; for example - servers could use <code title="">Accept</code> headers and HTTP redirects - to an SMS-push mechanism as a kind of protocol negotiation to reduce - network load in GSM environments. - - <p>User agents should use the <code>Cache-Control: no-cache</code> header - in requests to bypass any caches for requests of event sources. - - <p>For connections to domains other than the <a href="#domain0">document's - domain</a>, the semantics of the Access-Control HTTP header must be - followed. <a href="#refsACCESSCONTROL">[ACCESSCONTROL]</a> - - <p>HTTP 200 OK responses with a <a href="#content-type8">Content-Type</a> - header specifying the type <code>application/x-dom-event-stream</code> - that are either from the <a href="#domain0">document's domain</a> or - explicitly allowed by the Access-Control HTTP headers must be processed - line by line <a href="#event-stream-interpretation">as described - below</a>. - - <p>For the purposes of such successfully opened event streams only, user - agents should ignore HTTP cache headers, and instead assume that the - resource indicates that it does not wish to be cached. - - <p>If such a resource completes loading (i.e. the entire HTTP response body - is received or the connection itself closes), the user agent should - request the event source resource again after a delay of approximately - five seconds. - - <p>HTTP 200 OK responses that have a <a - href="#content-type8">Content-Type</a> other than - <code>application/x-dom-event-stream</code> (or some other supported - type), and HTTP responses whose Access-Control headers indicate that the - resource are not to be used, must be ignored and must prevent the user - agent from refetching the resource for that event source. - - <p>HTTP 201 Created, 202 Accepted, 203 Non-Authoritative Information, and - 206 Partial Content responses must be treated like HTTP 200 OK responses - for the purposes of reopening event source resources. They are, however, - likely to indicate an error has occurred somewhere and may cause the user - agent to emit a warning. - - <p>HTTP 204 No Content, and 205 Reset Content responses must be treated as - if they were 200 OK responses with the right MIME type but no content, and - should therefore cause the user agent to refetch the resource after a - short delay. - - <p>HTTP 300 Multiple Choices responses should be handled automatically if - possible (treating the responses as if they were 302 Found responses - pointing to the appropriate resource), and otherwise must be treated as - HTTP 404 responses. - - <p>HTTP 301 Moved Permanently responses must cause the user agent to - reconnect using the new server specified URI instead of the previously - specified URI for all subsequent requests for this event source. (It - doesn't affect other event sources with the same URI unless they also - receive 301 responses, and it doesn't affect future sessions, e.g. if the - page is reloaded.) - - <p>HTTP 302 Found, 303 See Other, and 307 Temporary Redirect responses must - cause the user agent to connect to the new server-specified URI, but if - the user agent needs to again request the resource at a later point, it - must return to the previously specified URI for this event source. - - <p>HTTP 304 Not Modified responses should be handled like HTTP 200 OK - responses, with the content coming from the user agent cache. A new - request should then be made after a short delay of approximately five - seconds. - - <p>HTTP 305 Use Proxy, HTTP 401 Unauthorized, and 407 Proxy Authentication - Required should be treated transparently as for any other subresource. - - <p>Any other HTTP response code not listed here should cause the user agent - to stop trying to process this event source.</p> - <!-- - including: HTTP 400 Bad Request, 403 Forbidden, 404 Not Found, 405 - Method Not Allowed, 406 Not Acceptable, 408 Request Timeout, 409 - Conflict, 410 Gone, 411 Length Required, 412 Precondition Failed, - 413 Request Entity Too Large, 414 Request-URI Too Long, 415 - Unsupported Media Type, 416 Requested Range Not Satisfiable, 417 - Expectation Failed, 500 Internal Server Error, 501 Not Implemented, - 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout, and - 505 HTTP Version Not Supported responses --> - - <p>DNS errors must be considered fatal, and cause the user agent to not - open any connection for that event source. - - <p>For non-HTTP protocols, UAs should act in equivalent ways. - - <h4 id=parsing0><span class=secno>6.2.3. </span>Parsing an event stream</h4> - - <p>This event stream format's MIME type is - <code>application/x-dom-event-stream</code>. - - <p>The event stream format is (in pseudo-BNF): - - <pre><stream> ::= <bom>? <event>* -<event> ::= [ <comment> | <command> | <field> ]* <newline> -<comment> ::= ';' <any-char>* <newline> -<command> ::= ':' <any-char>* <newline> -<field> ::= <name> [ ':' <space>? <any-char>* ]? <newline> -<name> ::= <name-start-char> <name-char>* - -# characters: -<bom> ::= a single U+FEFF BYTE ORDER MARK character -<space> ::= a single U+0020 SPACE character (' ') -<newline> ::= a U+000D CARRIAGE RETURN character - followed by a U+000A LINE FEED character - | a single U+000D CARRIAGE RETURN character - | a single U+000A LINE FEED character - | the end of the file -<name-start-char> ::= a single Unicode character other than - ':', ';', U+000D CARRIAGE RETURN and U+000A LINE FEED -<name-char> ::= a single Unicode character other than - ':', U+000D CARRIAGE RETURN and U+000A LINE FEED -<any-char> ::= a single Unicode character other than - U+000D CARRIAGE RETURN and U+000A LINE FEED -</pre> - - <p>Event streams in this format must always be encoded as UTF-8. Lines must - be separated by either a U+000D CARRIAGE RETURN U+000A LINE FEED (CRLF) - character pair, a single U+000A LINE FEED (LF) character, or a single - U+000D CARRIAGE RETURN (CR) character. User agents must treat those three - variants as equivalent line terminators. - - <p>Bytes that are not valid UTF-8 sequences must be interpreted as the - U+FFFD REPLACEMENT CHARACTER. - - <p>A leading U+FEFF BYTE ORDER MARK character must be ignored if present. - - <p>The stream must then be parsed by reading everything line by line, in - blocks separated by blank lines. Comment lines (those starting with the - character ';') and command lines (those starting with the character ':') - must be ignored. - - <p>Command lines are reserved for future extensions.</p> - <!--XXX Lachlan says: - For the next version of server sent events, it might be useful if - authors could specify the retry interval for connections. - - e.g. In cases where it is known that content is only updated at - specified intervals (e.g. once per minute), having the browser retry - the connection every 5 seconds and fire the event with the same - content may be excessive. - - This could possibly be done using the :command syntax. - - e.g. - Event: click - :retry 60000 - - The browser would then retry the connection in 60,000 milliseconds (1 - minute). - --> - - <p>For each non-blank, non-comment, non-command line, the field name must - first be taken. This is everything on the line up to but not including the - first colon (':') or the line terminator, whichever comes first. Then, if - there was a colon, the data for that line must be taken. This is - everything after the colon, ignoring a single space after the colon if - there is one, up to the end of the line. If there was no colon the data is - the empty string. - - <div class=example> - <p>Examples:</p> - - <pre>Field name: Field data</pre> - - <pre>This is a blank field</pre> - - <pre>1. These two lines: have the same data -2. These two lines:have the same data</pre> - - <pre>1. But these two lines: do not -2. But these two lines: do not</pre> - </div> - - <p>If a field name occurs multiple times in a block, the value for that - field in that black must consist of the data parts for each of those - lines, concatenated with U+000A LINE FEED characters between them - (regardless of what the line terminators used in the stream actually are). - - <div class=example> - <p>For example, the following block:</p> - - <pre>Test: Line 1 -Foo: Bar -Test: Line 2</pre> - - <p>...is treated as having two fields, one called <code>Test</code> with - the value "<code>Line 1\nLine 2</code>" (where <code>\n</code> represents - a newline), and one called <code>Foo</code> with the value - "<code> Bar</code>" (note the leading space character).</p> - </div> - - <p>A block thus consists of all the name-value pairs for its fields. - Command lines have no effect on blocks and are not considered part of a - block. - - <p class=note>Since any random stream of characters matches the above - format, there is no need to define any error handling. - - <h4 id=event-stream-interpretation><span class=secno>6.2.4. - </span>Interpreting an event stream</h4> - - <p>Once the fields have been parsed, they are interpreted as follows (these - are case-sensitive exact comparisons): - - <dl> - <dt><code title="">Event</code> field - - <dd> - <p>This field gives the name of the event. For example, <code - title="">load</code>, <code title="">DOMActivate</code>, <code - title="">updateTicker</code>. If there is no field with this name, the - name <code title=event-message><a href="#message">message</a></code> - must be used. - - <dt><code title="">Namespace</code> field - - <dd> - <p>This field gives the DOM3 namespace for the event. (For normal DOM - events this would be null.) If it isn't specified the event namespace is - null. - - <dt><code title="">Class</code> field - - <dd> - <p>This field gives is the interface used for the event, for instance - <code>Event</code>, <code>UIEvent</code>, <code>MutationEvent</code>, - <code>KeyboardEvent</code>, etc. For compatibility with DOM3 Events, the - values <code title="">UIEvents</code>, <code - title="">MouseEvents</code>, <code title="">MutationEvents</code>, and - <code title="">HTMLEvents</code> are valid values and must be treated - respectively as meaning the interfaces <code>UIEvent</code>, - <code>MouseEvent</code>, <code>MutationEvent</code>, and - <code>Event</code>. (This value can therefore be used as the argument to - <code title="">createEvent()</code>.)</p> - - <p>If the value is not specified but the <code title="">Namespace</code> - is null and the <code title="">Event</code> field exactly matches one of - the events specified by DOM3 Events in <a - href="http://www.w3.org/TR/DOM-Level-3-Events/events.html#Events-EventTypes-complete">section - 1.4.2 "Complete list of event types"</a>, then the interface used must - default to the interface relevant for that event type. <a - href="#refsDOM3EVENTS">[DOM3EVENTS]</a></p> - - <div class=example> - <p>For example:</p> - - <pre>Event: click</pre> - - <p>...would cause <code title="">Class</code> to be treated as - <code>MouseEvent</code>.</p> - </div> - - <p>If the <code title="">Namespace</code> is null and the <code - title="">Event</code> field is <code title=event-message><a - href="#message">message</a></code> (including if it was not specified - explicitly), then the <code><a - href="#messageevent">MessageEvent</a></code> interface must be used.</p> - - <p>Otherwise, the <code>Event</code> interface must be used.</p> - - <p>It is quite possible to give the wrong class for an event. This is - equivalent to creating an event in the DOM using the DOM Event APIs, but - using the wrong interface for it.</p> - - <dt><code title="">Bubbles</code> field - - <dd> - <p>This field specifies whether the event is to bubble. If it is - specified and has the value <code title="">No</code>, the event must not - bubble. If it is specified and has any other value (including <code - title="">no</code> or <code title="">NO</code>) then the event must - bubble.</p> - - <p>If it is not specified but the <code title="">Namespace</code> field - is null and the <code title="">Event</code> field exactly matches one of - the events specified by DOM3 Events in <a - href="http://www.w3.org/TR/DOM-Level-3-Events/events.html#Events-EventTypes-complete">section - 1.4.2 "Complete list of event types"</a>, then the event must bubble if - the DOM3 Events spec specifies that that event bubbles, and musn't - bubble if it specifies it does not. <a - href="#refsDOM3EVENTS">[DOM3EVENTS]</a></p> - - <div class=example> - <p>For example:</p> - - <pre>Event: load</pre> - - <p>...would cause <code title="">Bubbles</code> to be treated as <code - title="">No</code>.</p> - </div> - - <p>Otherwise, the event must bubble.</p> - - <dt><code title="">Cancelable</code> field - - <dd> - <p>This field specifies whether the event can have its default action - prevented. If it is specified and has the value <code - title="">No</code>, the event must not be cancelable. If it is specified - and has any other value (including <code title="">no</code> or <code - title="">NO</code>) then the event must be cancelable.</p> - - <p>If it is not specified, but the <code title="">Namespace</code> field - is null and the <code title="">Event</code> field exactly matches one of - the events specified by DOM3 Events in <a - href="http://www.w3.org/TR/DOM-Level-3-Events/events.html#Events-EventTypes-complete">section - 1.4.2 "Complete list of event types"</a>, then the event must be - cancelable if the DOM3 Events specification specifies that it is, and - must not be cancelable otherwise. <a - href="#refsDOM3EVENTS">[DOM3EVENTS]</a></p> - - <div class=example> - <p>For example:</p> - - <pre>Event: load</pre> - - <p>...would cause <code title="">Cancelable</code> to be treated as - <code title="">No</code>.</p> - </div> - - <p>Otherwise, the event must be cancelable.</p> - - <dt><code title="">Target</code> field - - <dd> - <p>This field gives the node that the event is to be dispatched on.</p> - - <p>If the object for which the event source is being processed is not a - Node, but the <code title="">Target</code> field is nonetheless - specified, then the event must be dropped.</p> - - <p>Otherwise, if field is specified and its value starts with a <code - title="">#</code> character, then the remainder of the value represents - an ID, and the event must be dispatched on the same node as would be - obtained by the <code title="">getElementById()</code> method on the - <code title="">ownerDocument</code> of the node whose event source is - being processed.</p> - - <div class=example> - <p>For example,</p> - - <pre>Target: #test</pre> - - <p>...would target the element with ID <code title="">test</code>.</p> - </div> - - <p>Otherwise, if the field is specified and its value is the literal - string "<code title="">Document</code>", then the event must be - dispatched at the <code title="">ownerDocument</code> of the node whose - event source is being processed.</p> - - <p>Otherwise, the field (whether specified or not) is ignored and the - event must be dispatched at the object itself.</p> - </dl> - - <p>Other fields depend on the interface specified (or possibly implied) by - the <code title="">Class</code> field. If the specified interface has an - attribute that exactly matches the name of the field, and the value of the - field can be converted (using the type conversions defined in ECMAScript) - to the type of the attribute, then it must be used. Any attributes (other - than the <code>Event</code> interface attributes) that do not have - matching fields are initialised to zero, null, false, or the empty string. - - <div class=example> - <p>For example:</p> - - <pre>Event: click -Class: MouseEvent -button: 2</pre> - - <p>...would result in a 'click' event using the <code>MouseEvent</code> - interface that has <code>button</code> set to <code title="">2</code> but - <code>screenX</code>, <code>screenY</code>, etc, set to 0, false, or null - as appropriate.</p> - </div> - - <p>If a field does not match any of the attributes on the event, it must be - ignored. - - <div class=example> - <p>For example:</p> - - <pre>Event: keypress -Class: MouseEvent -keyIdentifier: 0</pre> - - <p>...would result in a <code>MouseEvent</code> event with its fields all - at their default values, with the event name being <code - title="">keypress</code>. The <code title="">keyIdentifier</code> field - would be ignored. (If the author had not included the <code - title="">Class</code> field explicitly, it would have just worked, since - the class would have defaulted as described above.)</p> - </div> - - <p>Once a blank line or the end of the file is reached, an event of the - type and namespace given by the <code title="">Event</code> and - <code>Namespace</code> fields respectively must be synthesized and - dispatched to the appropriate node as described by the fields above. No - event must be dispatched until a blank line has been received or the end - of the file reached. - - <p>The event must be dispatched as if using the DOM <code - title="">dispatchEvent()</code> method. Thus, if the <code - title="">Event</code> field was omitted, leaving the name as the empty - string, or if the name had invalid characters, then the dispatching of the - event fails. - - <p>Events fired from event sources do not have user-agent default actions. - - <div class=example> - <p>The following event stream, once followed by a blank line:</p> - - <pre>data: YHOO -data: -2 -data: 10</pre> - - <p>...would cause an event <code title=event-message><a - href="#message">message</a></code> with the interface <code><a - href="#messageevent">MessageEvent</a></code> to be dispatched on the - <code><a href="#event-source">event-source</a></code> element, which - would then bubble up the DOM, and whose <code - title=dom-MessageEvent-data><a href="#data4">data</a></code> attribute - would contain the string <code>YHOO\n-2\n10</code> (where <code>\n</code> - again represents a newline).</p> - - <p>This could be used as follows: - - <pre><event-source src="http://stocks.example.com/ticker.php" - onmessage="var data = event.data.split('\n'); updateStocks(data[0], data[1], data[2]);"></pre> - - <p>...where <code title="">updateStocks()</code> is a function defined as:</p> - - <pre>function updateStocks(symbol, delta, value) { ... }</pre> - - <p>...or some such.</p> - </div> - - <div class=example> - <p>The following stream contains four blocks and therefore fires four - events. The first block has just a comment, and will fire a <code - title=event-message><a href="#message">message</a></code> event with all - the fields set to the empty string or null. The second block has two - fields with names "load" and "Target" respectively; since there is no - "<code title="">load</code>" member on the <code><a - href="#messageevent">MessageEvent</a></code> object that field is - ignored, leaving the event as a second <code title=event-message><a - href="#message">message</a></code> event with all the fields set to the - empty string or null, but this time the event is targetted at an element - with ID "image1". The third block is empty (no lines between two blank - lines), and the fourth block has only two comments, so they both yet - again fire <code title=event-message><a - href="#message">message</a></code> events with all the fields set to the - empty string or null.</p> - - <pre>; test - -load -Target: #image1 - - -; if any more events follow this block, they will not be affected by -; the "Target" and "load" fields above. -</pre> - </div> - - <h4 id=notes><span class=secno>6.2.5. </span>Notes</h4> - - <p>Legacy proxy servers are known to, in certain cases, drop HTTP - connections after a short timeout. To protect against such proxy servers, - authors can include a comment line (one starting with a ';' character) - every 15 seconds or so. - - <p>Authors wishing to relate event source connections to each other or to - specific documents previously served might find that relying on IP - addresses doesn't work, as individual clients can have multiple IP - addresses (due to having multiple proxy servers) and individual IP - addresses can have multiple clients (due to sharing a proxy server). It is - better to include a unique identifier in the document when it is served - and then pass that identifier as part of the URI in the <code - title=attr-event-source-src><a href="#src11">src</a></code> attribute of - the <code><a href="#event-source">event-source</a></code> element. - - <p>Implementations that support HTTP's per-server connection limitation - might run into trouble when opening multiple pages from a site if each - page has an <code><a href="#event-source">event-source</a></code> to the - same domain. Authors can avoid this using the relatively complex mechanism - of using unique domain names per connection, or by allowing the user to - enable or disable the <code><a - href="#event-source">event-source</a></code> functionality on a per-page - basis. - - <h3 id=network><span class=secno>6.3. </span>Network connections</h3> - - <p>To enable Web applications to communicate with each other in local area - networks, and to maintain bidirectional communications with their - originating server, this specification introduces the <code><a - href="#connection0">Connection</a></code> interface. - - <p>The <code><a href="#window">Window</a></code> interface provides three - constructors for creating <code><a - href="#connection0">Connection</a></code> objects: <code - title=dom-TCPConnection><a - href="#tcpconnection">TCPConnection()</a></code>, for creating a direct - (possibly encrypted) link to another node on the Internet using TCP/IP; - <code title=dom-LocalBroadcastConnection><a - href="#localbroadcastconnection">LocalBroadcastConnection()</a></code>, - for creating a connection to any listening peer on a local network (which - could be a local TCP/IP subnet using UDP, a Bluetooth PAN, or another kind - of network infrastructure); and <code title=dom-PeerToPeerConnection><a - href="#peertopeerconnection">PeerToPeerConnection()</a></code>, for a - direct peer-to-peer connection (which could again be over TCP/IP, - Bluetooth, IrDA, or some other type of network). - - <p class=note>This interface does not allow for raw access to the - underlying network. For example, this interface could not be used to - implement an IRC client without proxying messages through a custom server. - - <h4 id=network-intro><span class=secno>6.3.1. </span>Introduction</h4> - - <p><em>This section is non-normative.</em> - - <p class=big-issue>An introduction to the client-side and server-side of - using the direct connection APIs. - - <p class=big-issue>An example of a party-line implementation of a broadcast - service, and direct peer-to-peer chat for direct local connections.</p> - <!-- - <div class="example"> - <p>The following script creates a connection to a local party - line:</p> - <pre>var a = new LocalBroadcastConnection(); - a.onread = function(e) { alert(e.source + ' wrote ' + e.data); } - a.send('hello');</pre> - </div> ---> - <!--XXX - Explain why we don't use HTTP instead of our own protocol: wouldn't - work for peer-to-peer, too much work to implement server if you - have to implement a compliant HTTP server as well, etc - --> - - <h4 id=the-connection><span class=secno>6.3.2. </span>The <code><a - href="#connection0">Connection</a></code> interface</h4> - - <pre class=idl>interface <dfn id=connection0>Connection</dfn> { - readonly attribute DOMString <a href="#network1" title=dom-Connection-network>network</a>; - readonly attribute DOMString <a href="#peer" title=dom-Connection-peer>peer</a>; - readonly attribute int <a href="#readystate0" title=dom-Connection-readyState>readyState</a>; - attribute EventListener <a href="#onopen" title=dom-Connection-onopen>onopen</a>; - attribute EventListener <a href="#onread" title=dom-Connection-onread>onread</a>; - attribute EventListener <a href="#onclose" title=dom-Connection-onclose>onclose</a>; - void <a href="#send" title=dom-Connection-send>send</a>(in DOMString data); - void <a href="#disconnect" title=dom-Connection-disconnect>disconnect</a>(); -};</pre> - - <p><code><a href="#connection0">Connection</a></code> objects must also - implement the <code>EventTarget</code> interface. <a - href="#refsDOM3EVENTS">[DOM3EVENTS]</a> - - <p>When a <code><a href="#connection0">Connection</a></code> object is - created, the UA must try to establish a connection, as described in the - sections below describing each connection type. - - <p>The <dfn id=network1 - title=dom-Connection-network><code>network</code></dfn> attribute - represents the name of the network connection (the value depends on the - kind of connection being established). The <dfn id=peer - title=dom-Connection-peer><code>peer</code></dfn> attribute identifies the - remote host for direct (non-broadcast) connections. - - <p>The <code title=dom-Connection-network><a - href="#network1">network</a></code> attribute must be set as soon as the - <code><a href="#connection0">Connection</a></code> object is created, and - keeps the same value for the lifetime of the object. The <code - title=dom-Connection-peer><a href="#peer">peer</a></code> attribute must - initially be set to the empty string and must be updated once, when the - connection is established, after which point it must keep the same value - for the lifetime of the object. - - <p>The <dfn id=readystate0 - title=dom-Connection-readyState><code>readyState</code></dfn> attribute - represents the state of the connection. When the object is created it must - be set to 0. It can have the following values: - - <dl> - <dt>0 Connecting - - <dd>The connection has not yet been established. - - <dt>1 Connected - - <dd>The connection is established and communication is possible. - - <dt>2 Closed - - <dd>The connection has been closed. - </dl> - - <p id=openConnection>Once a connection is established, the <code - title=dom-Connection-readyState><a - href="#readystate0">readyState</a></code> attribute's value must be - changed to 1, and the <code title=event-connection-open><a - href="#open3">open</a></code> event must be fired on the <code><a - href="#connection0">Connection</a></code> object. - - <p>When data is received, the <code title=event-connection-read><a - href="#read">read</a></code> event will be fired on the <code><a - href="#connection0">Connection</a></code> object.</p> - <!-- conf crit for this - statement is in the various protocol-specific sections below. --> - - <p id=closeConnection>When the connection is closed, the <code - title=dom-Connection-readyState><a - href="#readystate0">readyState</a></code> attribute's value must be - changed to 2, and the <code title=event-connection-close><a - href="#close0">close</a></code> event must be fired on the <code><a - href="#connection0">Connection</a></code> object. - - <p>The <dfn id=onopen - title=dom-Connection-onopen><code>onopen</code></dfn>, <dfn id=onread - title=dom-Connection-onread><code>onread</code></dfn>, and <dfn id=onclose - title=dom-Connection-onclose><code>onclose</code></dfn> attributes must, - when set, register their new value as an event listener for their - respective events (namely <code title=event-connection-open><a - href="#open3">open</a></code>, <code title=event-connection-read><a - href="#read">read</a></code>, and <code title=event-connection-close><a - href="#close0">close</a></code>), and unregister their previous value if - any. - - <p>The <dfn id=send title=dom-Connection-send><code>send()</code></dfn> - method transmits data using the connection. If the connection is not yet - established, it must raise an <code>INVALID_STATE_ERR</code> exception. If - the connection <em>is</em> established, then the behaviour depends on the - connection type, as described below. - - <p>The <dfn id=disconnect - title=dom-Connection-disconnect><code>disconnect()</code></dfn> method - must close the connection, if it is open. If the connection is already - closed, it must do nothing. Closing the connection causes a <code - title=event-connection-close><a href="#close0">close</a></code> event to - be fired and the <code title=dom-Connection-readyState><a - href="#readystate0">readyState</a></code> attribute's value to change, as - <a href="#closeConnection">described above</a>. - - <h4 id=connection><span class=secno>6.3.3. </span>Connection Events</h4> - - <p>All the events described in this section are events in no namespace, - which do not bubble, are not cancelable, and have no default action. - - <p>The <dfn id=open3 title=event-connection-open><code>open</code></dfn> - event is fired when the connection is established. UAs must use the normal - <code>Event</code> interface when firing this event. - - <p>The <dfn id=close0 title=event-connection-close><code>close</code></dfn> - event is fired when the connection is closed (whether by the author, - calling the <code title=dom-Connection-disconnect><a - href="#disconnect">disconnect()</a></code> method, or by the server, or by - a network error). UAs must use the normal <code>Event</code> interface - when firing this event as well. - - <p class=note>No information regarding why the connection was closed is - passed to the application in this version of this specification. - - <p>The <dfn id=read title=event-connection-read><code>read</code></dfn> - event is fired when when data is received for a connection. UAs must use - the <code><a href="#connectionreadevent">ConnectionReadEvent</a></code> - interface for this event. - - <pre - class=idl>interface <dfn id=connectionreadevent>ConnectionReadEvent</dfn> : Event { - readonly attribute DOMString <a href="#data5" title=dom-ConnectionReadEvent-data>data</a>; - readonly attribute DOMString <a href="#source2" title=dom-ConnectionReadEvent-source>source</a>; - void <a href="#initconnectionreadevent" title=dom-ConnectionReadEvent-initConnectionReadEvent>initConnectionReadEvent</a>(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString dataArg); - void <a href="#initconnectionreadeventns" title=dom-ConnectionReadEvent-initConnectionReadEventNS>initConnectionReadEventNS</a>(in DOMString namespaceURI, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString dataArg); -}; -</pre> - - <p>The <dfn id=initconnectionreadevent - title=dom-ConnectionReadEvent-initConnectionReadEvent><code>initConnectionReadEvent()</code></dfn> - and <dfn id=initconnectionreadeventns - title=dom-ConnectionReadEvent-initConnectionReadEventNS><code>initConnectionReadEventNS()</code></dfn> - methods must initialise the event in a manner analogous to the - similarly-named methods in the DOM3 Events interfaces. <a - href="#refsDOM3EVENTS">[DOM3EVENTS]</a> - - <p>The <dfn id=data5 - title=dom-ConnectionReadEvent-data><code>data</code></dfn> attribute - represents the data that was transmitted from the peer. - - <p>The <dfn id=source2 - title=dom-ConnectionReadEvent-source><code>source</code></dfn> attribute - represents the name of the peer. This is primarily useful on broadcast - connections; on direct connections it is equal to the <code - title=dom-Connection-peer><a href="#peer">peer</a></code> attribute on the - <code><a href="#connection0">Connection</a></code> object.</p> - <!-- XXX check that the following three sections define "the data - that was transmitted" and "the name of the peer" in terms that mean - they fit into the above definitions ("for the purposes of the - ConnectionReadEvent"), and check they say that they MUST be set - correctly. --> - <!-- XXX should we have a Connection attribute on the event? --> - - <p>Events that would be fired during script execution (e.g. between the - connection object being created — and thus the connection being - established — and the current script completing; or, during the - execution of a <code title=event-connection-read><a - href="#read">read</a></code> event handler) must be buffered, and those - events queued up and each one individually fired after the script has - completed.</p> - <!-- XXX make this more generic --> - - <h4 id=tcp-connections><span class=secno>6.3.4. </span>TCP connections</h4> - - <p>The <dfn id=tcpconnection - title=dom-TCPConnection><code>TCPConnection(<var title="">subdomain</var>, - <var title="">port</var>, <var title="">secure</var>)</code></dfn> - constructor on the <code><a href="#window">Window</a></code> interface - returns a new object implementing the <code><a - href="#connection0">Connection</a></code> interface, set up for a direct - connection to a specified host on the page's domain. - - <p>When this constructor is invoked, the following steps must be followed. - - <p>First, if the domain part of the script's <a href="#origin0">origin</a> - is not a host name (e.g. it is an IP address) then the UA must raise a <a - href="#security8">security exception</a>. <span class=issue>We currently - don't allow connections to be set up back to an originating IP address, - but we could, if the subdomain is the empty string.</span> - - <p>Then, if the <var title="">subdomain</var> argument is null or the empty - string, the target host is the domain part of the script's <a - href="#origin0">origin</a>. Otherwise, the <var title="">subdomain</var> - argument is prepended to the domain part of the script's origin with a dot - separating the two strings, and that is the target host. - - <p>If either: - - <ul> - <li>the target host is not a valid host name, or - - <li>the <var title="">port</var> argument is neither equal to 80, nor - equal to 443, nor greater than or equal to 1024 and less than or equal to - 65535, - </ul> - - <p>...then the UA must raise a <a href="#security8">security exception</a>.</p> - <!-- XXX we should have our own port for this too, e.g. 980 --> - - <p>Otherwise, the user agent must verify that the <a href="#the-string">the - string representing the script's domain in IDNA format</a> can be obtained - without errors. If it cannot, then the user agent must raise a <a - href="#security8">security exception</a>. - - <p>The user agent may also raise a <a href="#security8">security - exception</a> at this time if, for some reason, permission to create a - direct TCP connection to the relevant host is denied. Reasons could - include the UA being instructed by the user to not allow direct - connections, or the UA establishing (for instance using UPnP) that the - network topology will cause connections on the specified port to be - directed at the wrong host. - - <p>If no exceptions are raised by the previous steps, then a new <code><a - href="#connection0">Connection</a></code> object must be created, its - <code title=dom-Connection-peer><a href="#peer">peer</a></code> attribute - must be set to a string consisting of the name of the target host, a colon - (U+003A COLON), and the port number as decimal digits, and its <code - title=dom-Connection-network><a href="#network1">network</a></code> - attribute must be set to the same value as the <code - title=dom-Connection-peer><a href="#peer">peer</a></code> attribute. - - <p>This object must then be returned. - - <p>The user agent must then begin trying to establish a connection with the - target host and specified port. (This typically would begin in the - backgound, while the script continues to execute.) - - <p>If the <var title="">secure</var> boolean argument is set to true, then - the user agent must establish a secure connection with the target host and - specified port using TLS or another protocol, negotiated with the server. - <a href="#refsRFC2246">[RFC2246]</a> If this fails the user agent must act - as if it had <a href="#closeConnection">closed the connection</a>. - - <p>Once a secure connection is established, or if the <var - title="">secure</var> boolean argument is not set to true, then the user - agent must continue to connect to the server using the protocol described - in the section entitled <a href="#clients0">clients connecting over - TCP</a>. All data on connections made using TLS must be sent as - "application data". - - <p>Once the connection is established, the UA must act as described in the - section entitled <a href="#sending0">sending and receiving data over - TCP</a>. - - <p>User agents should allow multiple TCP connections to be established per - host. In particular, user agents should not apply per-host HTTP connection - limits to connections established with the <code - title=dom-TCPConnection><a href="#tcpconnection">TCPConnection</a></code> - constructor. - - <h4 id=broadcast><span class=secno>6.3.5. </span>Broadcast connections</h4> - - <p>The <dfn id=localbroadcastconnection - title=dom-LocalBroadcastConnection><code>LocalBroadcastConnection()</code></dfn> - constructor on the <code><a href="#window">Window</a></code> interface - returns a new object implementing the <code><a - href="#connection0">Connection</a></code> interface, set up to broadcast - on the local network. - - <p>When this constructor is invoked, a new <code><a - href="#connection0">Connection</a></code> object must be created. - - <p>The <code title=dom-Connection-network><a - href="#network1">network</a></code> attribute of the object must be set to - <a href="#the-string">the string representing the script's domain in IDNA - format</a>. If this string cannot be obtained, then the user agent must - raise a <a href="#security8">security exception</a> exception when the - constructor is called. - - <p>The <code title=dom-Connection-peer><a href="#peer">peer</a></code> - attribute must be set to the empty string. - - <p>The object must then be returned, unless, for some reason, permission to - broadcast on the local network is to be denied. In the latter case, a <a - href="#security8">security exception</a> must be raised instead. User - agents may deny such permission for any reason, for example a user - preference. - - <p>If the object is returned (i.e. if no exception is raised), the user - agent must the begin broadcasting and listening on the local network, in - the background, as described below. The user agent may define "the local - network" in any way it considers appropriate and safe; for instance the - user agent may ask the user which network (e.g. Bluetooth, IrDA, Ethernet, - etc) the user would like to broadcast on before beginning broadcasting. - - <p>UAs may broadcast and listen on multiple networks at once. For example, - the UA could broadcast on both Bluetooth and Wifi at the same time.</p> - <!-- XXX bridging? how do we handle one UA not seeing - the same hosts as another UA? --> - - <p>As soon as the object is returned, the connection <a - href="#openConnection">has been established</a>, which implies that the - <code title=event-connection-open><a href="#open3">open</a></code> event - must be fired. Broadcast connections are never closed. - - <h5 id=broadcasting><span class=secno>6.3.5.1. </span>Broadcasting over - TCP/IP</h5> - - <p class=big-issue>Should we drop this altogether? Letting people fill the - local network with garbage seems unwise. - - <p class=big-issue>We need to register a UDP port for this. For now this - spec refers to port 18080/udp. - - <p class=note>Since this feature requires that the user agent listen to a - particular port, some platforms might prevent more than one user agent per - IP address from using this feature at any one time. - - <p>On TCP/IP networks, broadcast connections transmit data using UDP over - port 18080. - - <p>When the <code title=dom-Connection-send><a href="#send">send(<var - title="">data</var>)</a></code> method is invoked on a <code><a - href="#connection0">Connection</a></code> object that was created by the - <code title=dom-LocalBroadcastConnection><a - href="#localbroadcastconnection">LocalBroadcastConnection()</a></code> - constructor, the user agent must follow these steps: - - <ol> - <li>Create a string consisting of the value of the <code - title=dom-Connection-network><a href="#network1">network</a></code> - attribute of the <code><a href="#connection0">Connection</a></code> - object, a U+0020 SPACE character, a U+0002 START OF TEXT character, and - the <var title="">data</var> argument. - - <li>Encode the string as UTF-8. - - <li>If the resulting byte stream is longer than 65487 bytes, raise an - <code>INDEX_SIZE_ERR</code> DOM exception and stop. - - <li>Create a UDP packet whose data is the byte stream, with the source and - destination ports being 18080, and with appropriate length and checksum - fields. Transmit this packet to IPv4 address 255.255.255.255 or IPv6 - address ff02::1, as appropriate. <span class=note>IPv6 applications will - also have to enable reception from this address.</span> - </ol> - - <p>When a broadcast connection is opened on a TCP/IP network, the user - agent should listen for UDP packets on port 18080. - - <p>When the user agent receives a packet on port 18080, the user agent must - attempt to decode that packet's data as UTF-8. If the data is not fully - correct UTF-8 (i.e. if there are decoding errors) then the packet must be - ignored. Otherwise, the user agent must check to see if the decoded string - contains a U+0020 SPACE character. If it does not, then the packet must - again be ignored (it might be a peer discovery packet from a <code - title=dom-PeerToPeerConnection><a - href="#peertopeerconnection">PeerToPeerConnection()</a></code> - constructor). If it does then the user agent must split the string at the - first space character. All the characters before the space are then known - as <var title="">d</var>, and all the characters after the space are known - as <var title="">s</var>. If <var title="">s</var> is not at least one - character long, or if the first character of <var title="">s</var> is not - a U+0002 START OF TEXT character, then the packet must be ignored. (This - allows for future extension of this protocol.) - - <p>Otherwise, for each <code><a href="#connection0">Connection</a></code> - object that was created by the <code title=dom-LocalBroadcastConnection><a - href="#localbroadcastconnection">LocalBroadcastConnection()</a></code> - constructor and whose <code title=dom-Connection-network><a - href="#network1">network</a></code> attribute exactly matches <var - title="">d</var>, a <code title=event-connection-read><a - href="#read">read</a></code> event must be fired on the <code><a - href="#connection0">Connection</a></code> object. The string <var - title="">s</var>, with the first character removed, must be used as the - <code title=dom-ConnectionReadEvent-data><a href="#data5">data</a></code>, - and the source IP address of the packet as the <code - title=dom-ConnectionReadEvent-source><a href="#source2">source</a></code>. - - <p class=big-issue>Making the source IP available means that if two or more - machines in a private network can be made to go to a hostile page - simultaneously, the hostile page can determine the IP addresses used - locally (i.e. on the other side of any NAT router). Is there some way we - can keep link-local IP addresses secret while still allowing for - applications to distinguish between multiple participants? - - <h5 id=bluetooth-broadcast><span class=secno>6.3.5.2. </span>Broadcasting - over Bluetooth</h5> - - <p class=big-issue>Does anyone know enough about Bluetooth to write this - section? - - <h5 id=irda-broadcast><span class=secno>6.3.5.3. </span>Broadcasting over - IrDA</h5> - - <p class=big-issue>Does anyone know enough about IrDA to write this - section? - - <h4 id=peer-to-peer><span class=secno>6.3.6. </span>Peer-to-peer - connections</h4> - - <p>The <dfn id=peertopeerconnection - title=dom-PeerToPeerConnection><code>PeerToPeerConnection()</code></dfn> - constructor on the <code><a href="#window">Window</a></code> interface - returns a new object implementing the <code><a - href="#connection0">Connection</a></code> interface, set up for a direct - connection to a user-specified host. - - <p>When this constructor is invoked, a new <code><a - href="#connection0">Connection</a></code> object must be created. - - <p>The <code title=dom-Connection-network><a - href="#network1">network</a></code> attribute of the object must be set to - <a href="#the-string">the string representing the script's domain in IDNA - format</a>. If this string cannot be obtained, then the user agent must - raise a <a href="#security8">security exception</a> exception when the - constructor is called. - - <p>The <code title=dom-Connection-peer><a href="#peer">peer</a></code> - attribute must be set to the empty string. - - <p>The object must then be returned, unless, for some reason, permission to - establish peer-to-peer connections is generally disallowed, for example - due to administrator settings. In the latter case, a <a - href="#security8">security exception</a> must be raised instead. - - <p>The user agent must then, typically while the script resumes execution, - find a remote host to establish a connection to. To do this it must start - broadcasting and listening for peer discovery messages and listening for - incoming connection requests on all the supported networks. How this is - performed depends on the type of network and is described below. - - <p>The UA should inform the user of the clients that are detected, and - allow the user to select one to connect to. UAs may also allow users to - explicit specify hosts that were not detected, e.g. by having the user - enter an IP address. - - <p>If an incoming connection is detected before the user specifies a target - host, the user agent should ask the user to confirm that this is the host - they wish to connect to. If it is, the connection should be accepted and - the UA will act as the <em>server</em> in this connection. (Which UA acts - as the server and which acts as the client is not discernible at the DOM - API level.) - - <p>If no incoming connection is detected and if the user specifies a - particular target host, a connection should be established to that host, - with the UA acting as the <em>client</em> in the connection. - - <p>No more than one connection must be established per <code><a - href="#connection0">Connection</a></code> object, so once a connection has - been established, the user agent must stop listening for further - connections (unless, or until such time as, another <code><a - href="#connection0">Connection</a></code> object is being created). - - <p>If at any point the user cancels the connection process or the remote - host refuses the connection, then the user agent must act as if it had <a - href="#closeConnection">closed the connection</a>, and stop trying to - connect. - - <h5 id=peer-to-peer0><span class=secno>6.3.6.1. </span>Peer-to-peer - connections over TCP/IP</h5> - - <p class=big-issue>Should we replace this section with something that uses - Rendez-vous/zeroconf or equivalent? - - <p class=big-issue>We need to register ports for this. For now this spec - refers to port 18080/udp and 18080/tcp. - - <p class=note>Since this feature requires that the user agent listen to a - particular port, some platforms might prevent more than one user agent per - IP address from using this feature at any one time. - - <p>When using TCP/IP, broadcasting peer discovery messages must be done by - creating UDP packets every few seconds containing as their data the value - of the connection's <code title=dom-Connection-network><a - href="#network1">network</a></code> attribute, encoded as UTF-8, with the - source and destination ports being set to 18080 and appropriate length and - checksum fields, and sending these packets to address (in IPv4) - 255.255.255.255 or (in IPv6) ff02::1, as appropriate. - - <p>Listening for peer discovery messages must be done by examining incoming - UDP packets on port 18080. <span class=note>IPv6 applications will also - have to enable reception from the ff02::1 address.</span> If their payload - is exactly byte-for-byte equal to a UTF-8 encoded version of the value of - the connection's <code title=dom-Connection-network><a - href="#network1">network</a></code> attribute, then the source address of - that packet represents the address of a host that is ready to accept a - peer-to-peer connection, and it should therefore be offered to the user. - - <p>Incoming connection requests must be listened for on TCP port 18080. If - an incoming connection is received, the UA must act as a <em>server</em>, - as described in the section entitled <a href="#servers0">servers accepting - connections over TCP</a>. - - <p>If no incoming connection requests are accepted and the user instead - specifies a target host to connect to, the UA acts as a <em>client</em>: - the user agent must attempt to connect to the user-specified host on port - 18080, as described in the section entitled <a href="#clients0">clients - connecting over TCP</a>. - - <p>Once the connection is established, the UA must act as described in the - section entitled <a href="#sending0">sending and receiving data over - TCP</a>. - - <p class=note>This specification does not include a way to establish - <em>secure</em> (encrypted) peer-to-peer connections at this time. <span - class=big-issue>If you can see a good way to do this, let me know.</span> - - <h5 id=bluetooth-peer><span class=secno>6.3.6.2. </span>Peer-to-peer - connections over Bluetooth</h5> - - <p class=big-issue>Does anyone know enough about Bluetooth to write this - section? - - <h5 id=irda-peer><span class=secno>6.3.6.3. </span>Peer-to-peer connections - over IrDA</h5> - - <p class=big-issue>Does anyone know enough about IrDA to write this - section?</p> - <!--XXX - <p>Prompts the user to select a connection to make, which could - look like this:</p> - -<pre>|:: New Connection :::::::::::::::::::::::::::::::::::::::::| -| | -| Select the peer to connect to: | -| | -| JohnSmith_Series60 via Bluetooth (( Connect )) | -| Patrick's Phone via Bluetooth ( Connect ) | -| John Smith via UDP ( Connect ) | -| | -| ( Cancel ) | -|___________________________________________________________| -</pre> - - <p>While the prompt is displayed, the UA should broadcast on all - supported networks, as described <span title="announcing peer - connections">below</span>.</p> - - <p>Returns null if the prompt was canceled. Otherwise, returns a - <code>Connection</code> object with its <code>network</code> - attribute set to <var title="">topic</var> and its <code>peer</code> - attribute set to a string uniquely identifying the selected peer, - and opens a connection to that peer. (See: <span>peer connection - formats</span>.)</p> - - - |:: New Connection :::::::::::::::::::::::::::::::::::::::::| - | | - | Would you like to open a connection called "Chess" for | - | this Web site?: | - | | - | example.org | - | | - | Select connection to use: [ Bluetooth | v ] | - | | - | (( Open connection )) ( Cancel ) | - |___________________________________________________________| - - c = new LocalBroadcastConnection("Chess"); - c.onread = function(s, f) { alert("got message " + s + " from " + f); } - c.send("hello, anybody there?"); - - - |:: New Connection :::::::::::::::::::::::::::::::::::::::::| - | | - | Select the peer to connect to: | - | | - | JohnSmith_Series60 via Bluetooth (( Connect )) | - | Patrick's Phone via Bluetooth ( Connect ) | - | John Smith via UDP ( Connect ) | - | | - | ( Cancel ) | - |___________________________________________________________| - - c = new LocalPeerConnection("Chess"); - // c.peer contains peer's name - c.onread = function(s) { alert("got message " + s); } // second argument is c.peer - c.send("hello"); - - c = new TCPConnection("chess.example.com", 8089, false); - // c.peer contains 'chess.example.com:8089' - c.onread = function(s) { alert("got message " + s); } // second argument is c.peer - c.send("hello"); - -> > Again, what else should we support? Should this have an HTML Element -> > backing it for more declarative authoring? What error handling do we need? -> > Should it automatically use bluetooth, TCP/IP broadcast, infrared, or -> > should it be under the control of the author or user? ---> - - <h4 id=the-common><span class=secno>6.3.7. </span>The common protocol for - TCP-based connections</h4> - - <p>The same protocol is used for <code title=dom-TCPConnection><a - href="#tcpconnection">TCPConnection</a></code> and <code - title=dom-PeerToPeerConnection><a - href="#peertopeerconnection">PeerToPeerConnection</a></code> connection - types. This section describes how such connections are established from - the client and server sides, and then describes how data is sent and - received over such connections (which is the same for both clients and - servers). - - <h5 id=clients><span class=secno>6.3.7.1. </span><dfn id=clients0>Clients - connecting over TCP</dfn></h5> - - <p>This section defines the client-side requirements of the protocol used - by the <code title=dom-TCPConnection><a - href="#tcpconnection">TCPConnection</a></code> and <code - title=dom-PeerToPeerConnection><a - href="#peertopeerconnection">PeerToPeerConnection</a></code> connection - types. - - <p>If a TCP connection to the specified target host and port cannot be - established, for example because the target host is a domain name that - cannot be resolved to an IP address, or because packets cannot be routed - to the host, the user agent should retry creating the connection. If the - user agent gives up trying to connect, the user agent must act as if it - had <a href="#closeConnection">closed the connection</a>. - - <p class=note>No information regarding the state of the connection is - passed to the application while the connection is being established in - this version of this specification. - - <p>Once a TCP/IP connection to the remote host is established, the user - agent must transmit the following sequence of bytes, represented here in - hexadecimal form: - - <pre>0x48 0x65 0x6C 0x6C 0x6F 0x0A</pre> - - <p class=note>This represents the string "Hello" followed by a newline, - encoded in UTF-8. - - <p>The user agent must then read all the bytes sent from the remote host, - up to the first 0x0A byte (inclusive). That string of bytes is then - compared byte-for-byte to the following string of bytes: - - <pre>0x57 0x65 0x6C 0x63 0x6F 0x6E 0x65 0x0A</pre> - - <p class=note>This says "Welcome". - - <p>If the server sent back a string in any way different to this, then the - user agent must <a href="#closeConnection">close the connection</a> and - give up trying to connect. - - <p>Otherwise, the user agent must then take <a href="#the-string">the - string representing the script's domain in IDNA format</a>, encode it as - UTF-8, and send that to the remote host, followed by a 0x0A byte (a U+000A - LINE FEED in UTF-8). - - <p>The user agent must then read all the bytes sent from the remote host, - up to the first 0x0A byte (inclusive). That string of bytes must then be - compared byte-for-byte to the string that was just sent to the server (the - one with the IDNA domain name and ending with a newline character). If the - server sent back a string in any way different to this, then the user - agent must <a href="#closeConnection">close the connection</a> and give up - trying to connect. - - <p>Otherwise, the connection <a href="#openConnection">has been - established</a> (and events and so forth get fired, as described above). - - <p>If at any point during this process the connection is closed - prematurely, then the user agent must <a href="#closeConnection">close the - connection</a> and give up trying to connect.</p> - <!-- XXX we should support automatic reconnect --> - - <h5 id=servers><span class=secno>6.3.7.2. </span><dfn id=servers0>Servers - accepting connections over TCP</dfn></h5> - - <p>This section defines the server side of the protocol described in the - previous section. For authors, it should be used as a guide for how to - implement servers that can communicate with Web pages over TCP. For UAs - these are the requirements for the server part of <code - title=dom-PeerToPeerConnection><a - href="#peertopeerconnection">PeerToPeerConnection</a></code>s. - - <p>Once a TCP/IP connection from a remote host is established, the user - agent must transmit the following sequence of bytes, represented here in - hexadecimal form: - - <pre>0x57 0x65 0x6C 0x63 0x6F 0x6E 0x65 0x0A</pre> - - <p class=note>This says "Welcome" and a newline in UTF-8. - - <p>The user agent must then read all the bytes sent from the remote host, - up to the first 0x0A byte (inclusive). That string of bytes is then - compared byte-for-byte to the following string of bytes: - - <pre>0x48 0x65 0x6C 0x6C 0x6F 0x0A</pre> - - <p class=note>"Hello" and a newline. - - <p>If the remote host sent back a string in any way different to this, then - the user agent must <a href="#closeConnection">close the connection</a> - and give up trying to connect. - - <p>Otherwise, the user agent must then take <a href="#the-string">the - string representing the script's domain in IDNA format</a>, encode it as - UTF-8, and send that to the remote host, followed by a 0x0A byte (a U+000A - LINE FEED in UTF-8). - - <p>The user agent must then read all the bytes sent from the remote host, - up to the first 0x0A byte (inclusive). That string of bytes must then be - compared byte-for-byte to the string that was just sent to that host (the - one with the IDNA domain name and ending with a newline character). If the - remote host sent back a string in any way different to this, then the user - agent must <a href="#closeConnection">close the connection</a> and give up - trying to connect. - - <p>Otherwise, the connection <a href="#openConnection">has been - established</a> (and events and so forth get fired, as described above). - - <p class=note>For author-written servers (as opposed to the server side of - a peer-to-peer connection), the script's domain would be replaced by the - hostname of the server. Alternatively, such servers might instead wait for - the client to send its domain string, and then simply echo it back. This - would allow connections from pages on any domain, instead of just pages - originating from the same host. The client compares the two strings to - ensure they are the same before allowing the connection to be used by - author script. - - <p>If at any point during this process the connection is closed - prematurely, then the user agent must <a href="#closeConnection">close the - connection</a> and give up trying to connect.</p> - <!-- XXX we should support automatic reconnect --> - - <h5 id=sending><span class=secno>6.3.7.3. </span><dfn id=sending0>Sending - and receiving data over TCP</dfn></h5> - - <p>When the <code title=dom-Connection-send><a href="#send">send(<var - title="">data</var>)</a></code> method is invoked on the connection's - corresponding <code><a href="#connection0">Connection</a></code> object, - the user agent must take the <var title="">data</var> argument, replace - any U+0000 NULL and U+0017 END OF TRANSMISSION BLOCK characters in it with - U+FFFD REPLACEMENT CHARACTER characters, then transmit a U+0002 START OF - TEXT character, this new <var title="">data</var> string and a single - U+0017 END OF TRANSMISSION BLOCK character (in that order) to the remote - host, all encoded as UTF-8. - - <p>When the user agent receives bytes on the connection, the user agent - must buffer received bytes until it receives a 0x17 byte (a U+0017 END OF - TRANSMISSION BLOCK character). If the first buffered byte is not a 0x02 - byte (a U+0002 START OF TEXT character encoded as UTF-8) then all the data - up to the 0x17 byte, inclusive, must be dropped. (This allows for future - extension of this protocol.) Otherwise, all the data from (but not - including) the 0x02 byte and up to (but not including) the 0x17 byte must - be taken, interpreted as a UTF-8 string, and a <code - title=event-connection-read><a href="#read">read</a></code> event must be - fired on the <code><a href="#connection0">Connection</a></code> object - with that string as the <code title=dom-ConnectionReadEvent-data><a - href="#data5">data</a></code>. If that string cannot be decoded as UTF-8 - without errors, the packet should be ignored. - - <p class=note>This protocol does not yet allow binary data (e.g. an image - or <a href="#media7">media data</a>) to be efficiently transmitted. A - future version of this protocol might allow this by using the prefix - character U+001F INFORMATION SEPARATOR ONE, followed by binary data which - uses a particular byte (e.g. 0xFF) to encode byte 0x17 somehow (since - otherwise 0x17 would be treated as transmission end by down-level UAs).</p> - <!-- - Specifically, replace all occurrences of 0xFF with 0xFF 0xFF and - all occurrences of 0x17 with 0xFF 0x00, or similar. - --> - - <h4 id=network-security><span class=secno>6.3.8. </span>Security</h4> - - <p class=big-issue>Need to write this section. - - <p class=big-issue>If you have an unencrypted page that is (through a - man-in-the-middle attack) changed, it can access a secure service that is - using IP authentication and then send that data back to the attacker. Ergo - we should probably stop unencrypted pages from accessing encrypted - services, on the principle that the actual level of security is zero. Then - again, if we do that, we prevent insecure sites from using SSL as a - tunneling mechanism. - - <p class=big-issue>Should consider dropping the subdomain-only restriction. - It doesn't seem to add anything, and prevents cross-domain chatter. - - <h4 id=network-other-specs><span class=secno>6.3.9. </span>Relationship to - other standards</h4> - - <p class=big-issue>Should have a section talking about the fact that we - blithely ignoring IANA's port assignments here. - - <p class=big-issue>Should explain why we are not reusing HTTP for this. - (HTTP is too heavy-weight for such a simple need; requiring authors to - implement an HTTP server just to have a party line is too much of a - barrier to entry; cannot rely on prebuilt components; having a simple - protocol makes it much easier to do RAD; HTTP doesn't fit the needs and - doesn't have the security model needed; etc) - - <h3 id=crossDocumentMessages><span class=secno>6.4. </span><dfn - id=cross-document>Cross-document messaging</dfn></h3> - - <p>Web browsers, for security and privacy reasons, prevent documents in - different domains from affecting each other; that is, cross-site scripting - is disallowed. - - <p>While this is an important security feature, it prevents pages from - different domains from communicating even when those pages are not - hostile. This section introduces a messaging system that allows documents - to communicate with each other regardless of their source domain, in a way - designed to not enable cross-site scripting attacks. - - <p class=big-issue>We may want to just put postMessage on Window instead of - Document, as that reduces the XSS risk. - - <h4 id=processing1><span class=secno>6.4.1. </span>Processing model</h4> - - <p>When a script invokes the <dfn id=postmessage - title=dom-document-postMessage><code>postMessage(<var - title="">message</var>)</code></dfn> method on a <code>Document</code> - object, the user agent must create an event that uses the <code><a - href="#messageevent">MessageEvent</a></code> interface, with the event - name <code title=event-message><a href="#message">message</a></code>, - which bubbles, is cancelable, and has no default action. The <code - title=dom-MessageEvent-data><a href="#data4">data</a></code> attribute - must be set to the value passed as the <var title="">message</var> - argument to the <code title=dom-document-postMessage><a - href="#postmessage">postMessage()</a></code> method, the <code - title=dom-MessageEvent-domain><a href="#domain2">domain</a></code> - attribute must be set to the domain of the document that the script that - invoked the methods is associated with, the <code - title=dom-MessageEvent-uri><a href="#uri">uri</a></code> attribute must be - set to the URI of that document, and the <code - title=dom-MessageEvent-source><a href="#source1">source</a></code> - attribute must be set to the <code>Document</code> object representing - that document. - - <p>The event must then be dispatched at the <code>Document</code> object - itself.</p> - <!-- XXX must ensure that postMessage() is accessible on - cross-domain Document objects but that the dispatchEvent() method is - not. --> - - <p class=warning>Authors should check the <code - title=dom-MessageEvent-domain><a href="#domain2">domain</a></code> - attribute to ensure that messages are only accepted from domains that they - expect to receive messages from. Otherwise, bugs in the author's message - handling code could be exploited by hostile sites. - - <div class=example> - <p>For example, if document A contains an <code><a - href="#object">object</a></code> element that contains document B, and - script in document A calls <code title=dom-document-postMessage><a - href="#postmessage">postMessage()</a></code> on document B, then a - message event will be fired on that element, marked as originating from - document A. The script in document A might look like:</p> - - <pre>var o = document.getElementsByTagName('object')[0]; -o.<span title="">contentDocument</span>.<a href="#postmessage" title=dom-document-postMessage>postMessage</a>('Hello world'); -</pre> - - <p>To register an event handler for incoming events, the script would use - <code title="">addEventListener()</code> (or similar mechanisms). For - example, the script in document B might look like:</p> - - <pre>document.addEventListener('message', receiver, false); -function receiver(e) { - if (e.domain == 'example.com') { - if (e.data == 'Hello world') { - e.source.postMessage('Hello'); - } else { - alert(e.data); - } - } -}</pre> - - <p>This script first checks the domain is the expected domain, and then - looks at the message, which it either displays to the user, or responds - to by sending a message back to the document which sent the message in - the first place.</p> - </div> - - <p class=note>Implementors are urged to take extra care in the - implementation of this feature. It allows authors to transmit information - from one domain to another domain, which is normally disallowed for - security reasons. It also requires that UAs be careful to allow access to - certain properties but not others. - - <h2 id=repetition><span class=secno>7. </span>Repetition templates</h2> - - <p class=big-issue>See <a - href="http://www.whatwg.org/specs/web-forms/current-work/#repeatingFormControls">WF2</a> - for now - - <h2 id=syntax><span class=secno>8. </span>The HTML syntax</h2> - - <h3 id=writing><span class=secno>8.1. </span>Writing HTML documents</h3> - - <p><em>This section only applies to documents, authoring tools, and markup - generators. In particular, it does not apply to conformance checkers; - conformance checkers must use the requirements given in the next section - ("parsing HTML documents").</em> - - <p>Documents must consist of the following parts, in the given order: - - <ol> - <li>Optionally, a single U+FEFF BYTE ORDER MARK (BOM) character. - - <li>Any number of <a href="#comments0" title=syntax-comments>comments</a> - and <a href="#space" title="space character">space characters</a>. - - <li>A <a href="#doctype" title=syntax-doctype>DOCTYPE</a>. - - <li>Any number of <a href="#comments0" title=syntax-comments>comments</a> - and <a href="#space" title="space character">space characters</a>. - - <li>The root element, in the form of an <code><a - href="#html">html</a></code> <a href="#elements2" - title=syntax-elements>element</a>. - - <li>Any number of <a href="#comments0" title=syntax-comments>comments</a> - and <a href="#space" title="space character">space characters</a>. - </ol> - - <p>The various types of content mentioned above are described in the next - few sections. - - <p>In addition, there are some restrictions on how <a href="#charset0" - title=attr-meta-charset>character encoding declarations</a> are to be - serialised, as discussed in the section on that topic. - - <h4 id=the-doctype><span class=secno>8.1.1. </span>The DOCTYPE</h4> - - <p>A <dfn id=doctype title=syntax-doctype>DOCTYPE</dfn> is a mostly - useless, but required, header. - - <p class=note>DOCTYPEs are required for legacy reasons. When omitted, - browsers tend to use a different rendering mode that is incompatible with - some specifications. Including the DOCTYPE in a document ensures that the - browser makes a best-effort attempt at following the relevant - specifications. - - <p>A DOCTYPE must consist of the following characters, in this order: - - <ol class=brief> - <li>A U+003C LESS-THAN SIGN (<code><</code>) character. - - <li>A U+0021 EXCLAMATION MARK (<code>!</code>) character. - - <li>A U+0044 LATIN CAPITAL LETTER D or U+0064 LATIN SMALL LETTER D - character. - - <li>A U+004F LATIN CAPITAL LETTER O or U+006F LATIN SMALL LETTER O - character. - - <li>A U+0043 LATIN CAPITAL LETTER C or U+0063 LATIN SMALL LETTER C - character. - - <li>A U+0054 LATIN CAPITAL LETTER T or U+0074 LATIN SMALL LETTER T - character. - - <li>A U+0059 LATIN CAPITAL LETTER Y or U+0079 LATIN SMALL LETTER Y - character. - - <li>A U+0050 LATIN CAPITAL LETTER P or U+0070 LATIN SMALL LETTER P - character. - - <li>A U+0045 LATIN CAPITAL LETTER E or U+0065 LATIN SMALL LETTER E - character. - - <li>One or more <a href="#space" title="space character">space - characters</a>. - - <li>A U+0048 LATIN CAPITAL LETTER H or U+0068 LATIN SMALL LETTER H - character. - - <li>A U+0054 LATIN CAPITAL LETTER T or U+0074 LATIN SMALL LETTER T - character. - - <li>A U+004D LATIN CAPITAL LETTER M or U+006D LATIN SMALL LETTER M - character. - - <li>A U+004C LATIN CAPITAL LETTER L or U+006C LATIN SMALL LETTER L - character. - - <li>Zero or more <a href="#space" title="space character">space - characters</a>. - - <li>A U+003E GREATER-THAN SIGN (<code>></code>) character. - </ol> - - <p class=note>In other words, <code><!DOCTYPE HTML></code>, - case-insensitively. - - <h4 id=elements0><span class=secno>8.1.2. </span>Elements</h4> - - <p>There are four different kinds of <dfn id=elements2 - title=syntax-elements>elements</dfn>: void elements, CDATA elements, - RCDATA elements, and normal elements. - - <dl> - <dt>Void elements - - <dd><code><a href="#base">base</a></code>, <code><a - href="#link">link</a></code>, <code><a href="#meta0">meta</a></code>, - <code><a href="#hr">hr</a></code>, <code><a href="#br">br</a></code>, - <code><a href="#img">img</a></code>, <code><a - href="#embed">embed</a></code>, <code><a href="#param">param</a></code>, - <code><a href="#area">area</a></code>, <code><a - href="#col">col</a></code>, <code>input</code><!-- XXX add: , - <code>command</code>, <code>event-source</code> --></dd> - <!-- XXX - keep this synchronised with the list of "permitted slash" elements - --> - - <dt>CDATA elements - - <dd><code><a href="#style">style</a></code>, <code><a - href="#script0">script</a></code></dd> - <!-- iframe and - noscript don't count as CDATA for syntax purposes --> - - <dt>RCDATA elements - - <dd><code><a href="#title1">title</a></code>, <code>textarea</code> - - <dt>Normal elements - - <dd>All other allowed HTML elements are normal elements. - </dl> - - <p><dfn id=tags title=syntax-tags>Tags</dfn> are used to delimit the start - and end of elements in the markup. CDATA, RCDATA, and normal elements have - a <a href="#start5" title=syntax-start-tags>start tag</a> to indicate - where they begin, and an <a href="#end-tags0" title=syntax-end-tags>end - tag</a> to indicate where they end. The start and end tags of certain - normal elements can be <a href="#omitted" - title=syntax-tag-omission>omitted</a>, as described later. Those that - cannot be omitted must not be omitted. Void elements only have a start - tag; end tags must not be specified for void elements. - - <p>The contents of the element must be placed between just after the start - tag (which <a href="#omitted" title=syntax-tag-omission>might be implied, - in certain cases</a>) and just before the end tag (which again, <a - href="#omitted" title=syntax-tag-omission>might be implied in certain - cases</a>). The exact allowed contents of each individual element depends - on the content model of that element, as described earlier in this - specification. Elements must not contain content that their content model - disallows. In addition to the restrictions placed on the contents by those - content models, however, the four types of elements have additional - <em>syntactic</em> requirements. - - <p>Void elements can't have any contents (since there's no end tag, no - content can be put between the start tag and the end tag.) - - <p>CDATA elements can have <a href="#text1" title=syntax-text>text</a>, - but: - - <ul> - <li>The text must not contain the two character sequence "<code - title=""></</code>" (U+003C LESS-THAN SIGN, U+002F SOLIDUS). - - <li>For every occurrence of the four character sequence "<code - title=""><!--</code>" (U+003C LESS-THAN SIGN, U+0021 EXCLAMATION MARK, - U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS), there must be a corresponding - three-character sequence "<code title="">--></code>" (U+002D - HYPHEN-MINUS, U+002D HYPHEN-MINUS, U+003E GREATER-THAN SIGN) whose U+003E - GREATER-THAN SIGN (>) character occurs later in the text than the - U+003C LESS-THAN SIGN (<) character of the first sequence. (This means - the hyphens from the "<code title=""><!--</code>" part can overlap - those in the "<code title="">--></code>" part, as in "<code - title=""><!--></code>".) - </ul> - - <p>RCDATA elements can have <a href="#text1" title=syntax-text>text</a> and - <a href="#character0" title=syntax-entities>character entity - references</a>, but the text must not contain the character U+003C - LESS-THAN SIGN (<code><</code>) or the character U+0026 AMPERSAND - (<code>&</code>). - - <p>Normal elements can have <a href="#text1" title=syntax-text>text</a>, <a - href="#character0" title=syntax-entities>character entity references</a>, - other <a href="#elements2" title=syntax-elements>elements</a>, and <a - href="#comments0" title=syntax-comments>comments</a>, but the text must - not contain the character U+003C LESS-THAN SIGN (<code><</code>) or the - character U+0026 AMPERSAND (<code>&</code>). Some normal elements also - have <a href="#have-extra" title=syntax-element-restrictions>yet more - restrictions</a> on what content they are allowed to hold, beyond the - restrictions imposed by the content model and those described in this - paragraph. Those restrictions are described below. - - <p>Tags contain a <dfn id=tag-name title=syntax-tag-name>tag name</dfn>, - giving the element's name. HTML elements all have names that only use - characters in the range U+0061 LATIN SMALL LETTER A .. U+007A LATIN SMALL - LETTER Z, or, in uppercase, U+0041 LATIN CAPITAL LETTER A .. U+005A LATIN - CAPITAL LETTER Z, and U+002D HYPHEN-MINUS (<code>-</code>). In the HTML - syntax, tag names may be written with any mix of lower- and uppercase - letters that, when converted to all-lowercase, matches the element's tag - name; tag names are case-insensitive. - - <h5 id=start><span class=secno>8.1.2.1. </span>Start tags</h5> - - <p><dfn id=start5 title=syntax-start-tags>Start tags</dfn> must have the - following format: - - <ol> - <li>The first character of a start tag must be a U+003C LESS-THAN SIGN - (<code><</code>). - - <li>The next few characters of a start tag must be the element's <a - href="#tag-name" title=syntax-tag-name>tag name</a>. - - <li>If there are to be any attributes in the next step, there must first - be one or more <a href="#space" title="space character">space - characters</a>. - - <li>Then, the start tag may have a number of attributes, the <a - href="#attributes1" title=syntax-attributes>syntax for which</a> is - described below. Attributes may be separated from each other by one or - more <a href="#space" title="space character">space characters</a>. - - <li>After the attributes, there may be one or more <a href="#space" - title="space character">space characters</a>. (Some attributes are - required to be followed by a space. See the <a href="#attributes1" - title=syntax-attributes>attributes section</a> below.) - - <li>Then, if the element is one of the void elements, then there may be a - single U+002F SOLIDUS (<code>/</code>) character. This character has no - effect except to appease the markup gods. As this character is therefore - just a symbol of faith, atheists should omit it. - - <li>Finally, start tags must be closed by a U+003E GREATER-THAN SIGN - (<code>></code>) character. - </ol> - - <h5 id=end-tags><span class=secno>8.1.2.2. </span>End tags</h5> - - <p><dfn id=end-tags0 title=syntax-end-tags>End tags</dfn> must have the - following format: - - <ol> - <li>The first character of an end tag must be a U+003C LESS-THAN SIGN - (<code><</code>). - - <li>The second character of an end tag must be a U+002F SOLIDUS - (<code>/</code>). - - <li>The next few characters of an end tag must be the element's <a - href="#tag-name" title=syntax-tag-name>tag name</a>. - - <li>After the tag name, there may be one or more <a href="#space" - title="space character">space characters</a>. - - <li>Finally, end tags must be closed by a U+003E GREATER-THAN SIGN - (<code>></code>) character. - </ol> - - <h5 id=attributes0><span class=secno>8.1.2.3. </span>Attributes</h5> - - <p><dfn id=attributes1 title=syntax-attributes>Attributes</dfn> for an - element are expressed inside the element's start tag. - - <p>Attributes have a name and a value. <dfn id=attribute - title=syntax-attribute-name>Attribute names</dfn> use characters in the - range U+0061 LATIN SMALL LETTER A .. U+007A LATIN SMALL LETTER Z, or, in - uppercase, U+0041 LATIN CAPITAL LETTER A .. U+005A LATIN CAPITAL LETTER Z, - and U+002D HYPHEN-MINUS (<code>-</code>). In the HTML syntax, attribute - names may be written with any mix of lower- and uppercase letters that, - when converted to all-lowercase, matches the attribute's name; attribute - names are case-insensitive. - - <p><dfn id=attribute0 title=syntax-attribute-value>Attribute values</dfn> - are a mixture of <a href="#text1" title=syntax-text>text</a> and <a - href="#character0" title=syntax-entities>character entity references</a>, - except with the additional restriction that the text cannot contain a - U+0026 AMPERSAND (<code>&</code>) character. - - <p>Attributes can be specified in four different ways: - - <dl> - <dt>Empty attribute syntax - - <dd> - <p>Just the <a href="#attribute" title=syntax-attribute-name>attribute - name</a>.</p> - - <div class=example> - <p>In the following example, the <code - title=attr-input-disabled>disabled</code> attribute is given with the - empty attribute syntax:</p> - - <pre><input <em>disabled</em>></pre> - </div> - - <p>If an attribute using the empty attribute syntax is to be followed by - another attribute, then there must be a <a href="#space">space - character</a> separating the two.</p> - - <dt>Unquoted attribute value syntax - - <dd> - <p>The <a href="#attribute" title=syntax-attribute-name>attribute - name</a>, followed by zero or more <a href="#space" title="space - character">space characters</a>, followed by a single U+003D EQUALS SIGN - character, followed by zero or more <a href="#space" title="space - character">space characters</a>, followed by the <a href="#attribute0" - title=syntax-attribute-value>attribute value</a>, which, in addition to - the requirements given above for attribute values, must not contain any - literal <a href="#space" title="space character">space characters</a>, - U+003E GREATER-THAN SIGN (<code>></code>) characters, or U+003C - LESS-THAN SIGN (<code><</code>) characters, and must not, - furthermore, start with either a literal U+0022 QUOTATION MARK - (<code>"</code>) character or a literal U+0027 APOSTROPHE - (<code>'</code>) character.</p> - - <div class=example> - <p>In the following example, the <code - title=attr-input-value>value</code> attribute is given with the - unquoted attribute value syntax:</p> - - <pre><input <em>value=yes</em>></pre> - </div> - - <p>If an attribute using the unquoted attribute syntax is to be followed - by another attribute or by one of the optional U+002F SOLIDUS - (<code>/</code>) characters allowed in step 6 of the <span - title=syntax-start-tag>start tag</span> syntax above, then there must be - a <a href="#space">space character</a> separating the two.</p> - - <dt>Single-quoted attribute value syntax - - <dd> - <p>The <a href="#attribute" title=syntax-attribute-name>attribute - name</a>, followed by zero or more <a href="#space" title="space - character">space characters</a>, followed by a single U+003D EQUALS SIGN - character, followed by zero or more <a href="#space" title="space - character">space characters</a>, followed by a single U+0027 APOSTROPHE - (<code>'</code>) character, followed by the <a href="#attribute0" - title=syntax-attribute-value>attribute value</a>, which, in addition to - the requirements given above for attribute values, must not contain any - literal U+0027 APOSTROPHE (<code>'</code>) characters, and finally - followed by a second single U+0027 APOSTROPHE (<code>'</code>) - character.</p> - - <div class=example> - <p>In the following example, the <code title=attr-input-type>type</code> - attribute is given with the single-quoted attribute value syntax:</p> - - <pre><input <em>type='checkbox'</em>></pre> - </div> - - <dt>Double-quoted attribute value syntax - - <dd> - <p>The <a href="#attribute" title=syntax-attribute-name>attribute - name</a>, followed by zero or more <a href="#space" title="space - character">space characters</a>, followed by a single U+003D EQUALS SIGN - character, followed by zero or more <a href="#space" title="space - character">space characters</a>, followed by a single U+0022 QUOTATION - MARK (<code>"</code>) character, followed by the <a href="#attribute0" - title=syntax-attribute-value>attribute value</a>, which, in addition to - the requirements given above for attribute values, must not contain any - literal U+0022 QUOTATION MARK (<code>"</code>) characters, and finally - followed by a second single U+0022 QUOTATION MARK (<code>"</code>) - character.</p> - - <div class=example> - <p>In the following example, the <code title=attr-input-name>name</code> - attribute is given with the double-quoted attribute value syntax:</p> - - <pre><input <em>name="be evil"</em>></pre> - </div> - </dl> - - <h5 id=optional><span class=secno>8.1.2.4. </span>Optional tags</h5> - - <p>Certain tags can be <dfn id=omitted - title=syntax-tag-omission>omitted</dfn>.</p> - <!-- <html> --> - - <p>An <code><a href="#html">html</a></code> element's <span - title=syntax-start-tag>start tag</span> may be omitted if the first thing - inside the <code><a href="#html">html</a></code> element is not a <a - href="#space">space character</a> or a <a href="#comments0" - title=syntax-comments>comment</a>.</p> - <!-- </html> --> - - <p>An <code><a href="#html">html</a></code> element's <span - title=syntax-end-tag>end tag</span> may be omitted if the <code><a - href="#html">html</a></code> element is not immediately followed by a <a - href="#space">space character</a> or a <a href="#comments0" - title=syntax-comments>comment</a>.</p> - <!-- <head> --> - - <p>A <code><a href="#head">head</a></code> element's <span - title=syntax-start-tag>start tag</span> may be omitted if the first thing - inside the <code><a href="#head">head</a></code> element is an element.</p> - <!-- </head> --> - - <p>A <code><a href="#head">head</a></code> element's <span - title=syntax-end-tag>end tag</span> may be omitted if the <code><a - href="#head">head</a></code> element is not immediately followed by a <a - href="#space">space character</a> or a <a href="#comments0" - title=syntax-comments>comment</a>.</p> - <!-- <body> --> - - <p>A <code><a href="#body0">body</a></code> element's <span - title=syntax-start-tag>start tag</span> may be omitted if the first thing - inside the <code><a href="#body0">body</a></code> element is not a <a - href="#space">space character</a> or a <a href="#comments0" - title=syntax-comments>comment</a>, except if the first thing inside the - <code><a href="#body0">body</a></code> element is a <code><a - href="#script0">script</a></code> or <code><a - href="#style">style</a></code> element and the node immediately preceding - the <code><a href="#body0">body</a></code> element is a <code><a - href="#head">head</a></code> element whose end tag has been omitted.</p> - <!-- </body> --> - - <p>A <code><a href="#body0">body</a></code> element's <span - title=syntax-end-tag>end tag</span> may be omitted if the <code><a - href="#body0">body</a></code> element is not immediately followed by a <a - href="#space">space character</a> or a <a href="#comments0" - title=syntax-comments>comment</a>. <!-- </li> --> - - <p>A <code><a href="#li">li</a></code> element's <span - title=syntax-end-tag>end tag</span> may be omitted if the <code><a - href="#li">li</a></code> element is immediately followed by another - <code><a href="#li">li</a></code> element or if there is no more content - in the parent element.</p> - <!-- </dt> --> - - <p>A <code><a href="#dt">dt</a></code> element's <span - title=syntax-end-tag>end tag</span> may be omitted if the <code><a - href="#dt">dt</a></code> element is immediately followed by another - <code><a href="#dt">dt</a></code> element or a <code><a - href="#dd">dd</a></code> element.</p> - <!-- </dd> --> - - <p>A <code><a href="#dd">dd</a></code> element's <span - title=syntax-end-tag>end tag</span> may be omitted if the <code><a - href="#dd">dd</a></code> element is immediately followed by another - <code><a href="#dd">dd</a></code> element or a <code><a - href="#dt">dt</a></code> element, or if there is no more content in the - parent element.</p> - <!-- </p> --> - - <p>A <code><a href="#p">p</a></code> element's <span - title=syntax-end-tag>end tag</span> may be omitted if the <code><a - href="#p">p</a></code> element is immediately followed by an <code><a - href="#address">address</a></code>, <code><a - href="#blockquote">blockquote</a></code>, <code><a - href="#dl">dl</a></code>, <code>fieldset</code>, <code>form</code>, - <code><a href="#h1">h1</a></code>, <code><a href="#h2">h2</a></code>, - <code><a href="#h3">h3</a></code>, <code><a href="#h4">h4</a></code>, - <code><a href="#h5">h5</a></code>, <code><a href="#h6">h6</a></code>, - <code><a href="#hr">hr</a></code>, <code><a href="#menu">menu</a></code>, - <code><a href="#ol">ol</a></code>, <code><a href="#p">p</a></code>, - <code><a href="#pre">pre</a></code>, <code><a - href="#table">table</a></code>, or <code><a href="#ul">ul</a></code> - element, or if there is no more content in the parent element.</p> - <!-- </optgroup> --> - - <p>An <code>optgroup</code> element's <span title=syntax-end-tag>end - tag</span> may be omitted if the <code>optgroup</code> element is - immediately followed by another <code>optgroup</code> element, or if there - is no more content in the parent element.</p> - <!-- </option> --> - - <p>An <code>option</code> element's <span title=syntax-end-tag>end - tag</span> may be omitted if the <code>option</code> element is - immediately followed by another <code>option</code> element, or if there - is no more content in the parent element.</p> - <!-- <colgroup> --> - - <p>A <code><a href="#colgroup">colgroup</a></code> element's <span - title=syntax-start-tag>start tag</span> may be omitted if the first thing - inside the <code><a href="#colgroup">colgroup</a></code> element is a - <code><a href="#col">col</a></code> element, and if the element is not - immediately preceeded by another <code><a - href="#colgroup">colgroup</a></code> element whose <span - title=syntax-end-tag>end tag</span> has been omitted.</p> - <!-- </colgroup> --> - - <p>A <code><a href="#colgroup">colgroup</a></code> element's <span - title=syntax-end-tag>end tag</span> may be omitted if the <code><a - href="#colgroup">colgroup</a></code> element is not immediately followed - by a <a href="#space">space character</a> or a <a href="#comments0" - title=syntax-comments>comment</a>.</p> - <!-- </thead> --> - - <p>A <code><a href="#thead0">thead</a></code> element's <span - title=syntax-end-tag>end tag</span> may be omitted if the <code><a - href="#thead0">thead</a></code> element is immediately followed by a - <code><a href="#tbody">tbody</a></code> or <code><a - href="#tfoot0">tfoot</a></code> element.</p> - <!-- <tbody> --> - - <p>A <code><a href="#tbody">tbody</a></code> element's <span - title=syntax-start-tag>start tag</span> may be omitted if the first thing - inside the <code><a href="#tbody">tbody</a></code> element is a <code><a - href="#tr">tr</a></code> element, and if the element is not immediately - preceeded by a <code><a href="#tbody">tbody</a></code>, <code><a - href="#thead0">thead</a></code>, or <code><a - href="#tfoot0">tfoot</a></code> element whose <span - title=syntax-end-tag>end tag</span> has been omitted.</p> - <!-- </tbody> --> - - <p>A <code><a href="#tbody">tbody</a></code> element's <span - title=syntax-end-tag>end tag</span> may be omitted if the <code><a - href="#tbody">tbody</a></code> element is immediately followed by a - <code><a href="#tbody">tbody</a></code> or <code><a - href="#tfoot0">tfoot</a></code> element, or if there is no more content in - the parent element.</p> - <!-- </tfoot> --> - - <p>A <code><a href="#tfoot0">tfoot</a></code> element's <span - title=syntax-end-tag>end tag</span> may be omitted if the <code><a - href="#tfoot0">tfoot</a></code> element is immediately followed by a - <code><a href="#tbody">tbody</a></code> element, or if there is no more - content in the parent element.</p> - <!-- </tr> --> - - <p>A <code><a href="#tr">tr</a></code> element's <span - title=syntax-end-tag>end tag</span> may be omitted if the <code><a - href="#tr">tr</a></code> element is immediately followed by another - <code><a href="#tr">tr</a></code> element, or if there is no more content - in the parent element.</p> - <!-- </td> --> - - <p>A <code><a href="#td">td</a></code> element's <span - title=syntax-end-tag>end tag</span> may be omitted if the <code><a - href="#td">td</a></code> element is immediately followed by a <code><a - href="#td">td</a></code> or <code><a href="#th">th</a></code> element, or - if there is no more content in the parent element.</p> - <!-- </th> --> - - <p>A <code><a href="#th">th</a></code> element's <span - title=syntax-end-tag>end tag</span> may be omitted if the <code><a - href="#th">th</a></code> element is immediately followed by a <code><a - href="#td">td</a></code> or <code><a href="#th">th</a></code> element, or - if there is no more content in the parent element. - - <p><strong>However</strong>, a <span title=syntax-start-tag>start - tag</span> must never be omitted if it has any attributes. - - <h5 id=restrictions><span class=secno>8.1.2.5. </span>Restrictions on - content models</h5> - - <p>For historical reasons, certain elements <dfn id=have-extra - title=syntax-element-restrictions>have extra restrictions</dfn> beyond - even the restrictions given by their content model. - - <p>A <code><a href="#p">p</a></code> element must not contain <code><a - href="#blockquote">blockquote</a></code>, <code><a - href="#dl">dl</a></code>, <code><a href="#menu">menu</a></code>, <code><a - href="#ol">ol</a></code>, <code><a href="#pre">pre</a></code>, <code><a - href="#table">table</a></code>, or <code><a href="#ul">ul</a></code> - elements, even though these elements are technically allowed inside - <code><a href="#p">p</a></code> elements according to the content models - described in this specification. (In fact, if one of those elements is put - inside a <code><a href="#p">p</a></code> element in the markup, it will - instead imply a <code><a href="#p">p</a></code> element end tag before - it.) - - <p>An <code>optgroup</code> element must not contain <code>optgroup</code> - elements, even though these elements are technically allowed to be nested - according to the content models described in this specification. (If an - <code>optgroup</code> element is put inside another in the markup, it will - in fact imply an <code>optgroup</code> end tag before it.) - - <p>A <code><a href="#table">table</a></code> element must not contain - <code><a href="#tr">tr</a></code> elements, even though these elements are - technically allowed inside <code><a href="#table">table</a></code> - elements according to the content models described in this specification. - (If a <code><a href="#tr">tr</a></code> element is put inside a <code><a - href="#table">table</a></code> in the markup, it will in fact imply a - <code><a href="#tbody">tbody</a></code> start tag before it.) - - <p>A single U+000A LINE FEED (LF) character may be placed immediately after - the <span title=syntax-start-tag>start tag</span> of <code><a - href="#pre">pre</a></code> and <code>textarea</code> elements. This does - not affect the processing of the element. The otherwise optional U+000A - LINE FEED (LF) character <em>must</em> be included if the element's - contents start with that character (because otherwise the leading newline - in the contents would be treated like the optional newline, and ignored). - - <div class=example> - <p>The following two <code><a href="#pre">pre</a></code> blocks are - equivalent:</p> - - <pre><pre>Hello</pre></pre> - - <pre><pre><br>Hello</pre></pre> - </div> - - <h4 id=text><span class=secno>8.1.3. </span>Text</h4> - - <p><dfn id=text1 title=syntax-text>Text</dfn> is allowed inside elements, - attributes, and comments. Text must consist of valid Unicode characters - other than U+0000. Text should not contain control characters other than - <a href="#space" title="space character">space characters</a>. Extra - constraints are placed on what is and what is not allowed in text based on - where the text is to be put, as described in the other sections. - - <h5 id=newlines><span class=secno>8.1.3.1. </span>Newlines</h5> - - <p><dfn id=newlines0 title=syntax-newlines>Newlines</dfn> in HTML may be - represented either as U+000D CARRIAGE RETURN (CR) characters, U+000A LINE - FEED (LF) characters, or pairs of U+000D CARRIAGE RETURN (CR), U+000A LINE - FEED (LF) characters in that order. - - <h4 id=character><span class=secno>8.1.4. </span>Character entity - references</h4> - - <p>In certain cases described in other sections, <a href="#text1" - title=syntax-text>text</a> may be mixed with <dfn id=character0 - title=syntax-entities>character entity references</dfn>. These can be used - to escape characters that couldn't otherwise legally be included in <a - href="#text1" title=syntax-text>text</a>. - - <p>Character entity references must start with a U+0026 AMPERSAND - (<code>&</code>). Following this, there are three possible kinds of - character entity references: - - <dl> - <dt>Named entities - - <dd>The ampersand must be followed by one of the names given in the <a - href="#entities0">entities</a> section, using the same case. Finally, - after the name, the entity must be terminated by a U+003B SEMICOLON - character (<code title="">;</code>). - - <dt>Decimal numeric entities - - <dd>The ampersand must be followed by a U+0023 NUMBER SIGN - (<code>#</code>) character, followed by one or more digits in the range - U+0030 DIGIT ZERO .. U+0039 DIGIT NINE, representing a base-ten integer - that itself is a valid Unicode code point that is neither U+0000 nor a - character in the range U+0080 .. U+009F. The digits must then be followed - by a U+003B SEMICOLON character (<code title="">;</code>). - - <dt>Hexadecimal numeric entities - - <dd>The ampersand must be followed by a U+0023 NUMBER SIGN - (<code>#</code>) character, which must be followed by either a U+0078 - LATIN SMALL LETTER X or a U+0058 LATIN CAPITAL LETTER X character, which - must then be followed by one or more digits in the range U+0030 DIGIT - ZERO .. U+0039 DIGIT NINE, U+0061 LATIN SMALL LETTER A .. U+0066 LATIN - SMALL LETTER F, and U+0041 LATIN CAPITAL LETTER A .. U+0046 LATIN CAPITAL - LETTER F, representing a base-sixteen integer that itself is a valid - Unicode code point that is neither U+0000 nor a character in the range - U+0080 .. U+009F. The digits must then be followed by a U+003B SEMICOLON - character (<code title="">;</code>). - </dl> - - <h4 id=comments><span class=secno>8.1.5. </span>Comments</h4> - - <p><dfn id=comments0 title=syntax-comments>Comments</dfn> must start with - the four character sequence U+003C LESS-THAN SIGN, U+0021 EXCLAMATION - MARK, U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS (<code - title=""><!--</code>). Following this sequence, the comment may have <a - href="#text1" title=syntax-text>text</a>, with the additional restriction - that the text must not contain two consecutive U+002D HYPHEN-MINUS (<code - title="">-</code>) characters, nor end with a U+002D HYPHEN-MINUS (<code - title="">-</code>) character. Finally, the comment must be ended by the - three character sequence U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS, U+003E - GREATER-THAN SIGN (<code title="">--></code>). - - <h3 id=parsing><span class=secno>8.2. </span>Parsing HTML documents</h3> - - <p><em>This section only applies to user agents, data mining tools, and - conformance checkers.</em> - - <p>The rules for parsing <a href="#xml-documents">XML documents</a> (and - thus <a href="#xhtml5">XHTML</a> documents) into DOM trees are covered by - the XML and Namespaces in XML specifications, and are out of scope of this - specification. <a href="#refsXML">[XML]</a> <a - href="#refsXMLNS">[XMLNS]</a> <!-- XXX refs --> - - <p>For <a href="#html-">HTML documents</a>, user agents must use the - parsing rules described in this section to generate the DOM trees. - Together, these rules define what is referred to as the <dfn - id=html-0>HTML parser</dfn>.</p> - <!-- XXX should probably remove that "must" since - it'll be redundant with something in the navigating processing model - eventually --> - - <div class=note> - <p>While the HTML form of HTML5 bears a close resemblance to SGML and XML, - it is a separate language with its own parsing rules.</p> - - <p>Some earlier versions of HTML (in particular from HTML2 to HTML4) were - based on SGML and used SGML parsing rules. However, few (if any) web - browsers ever implemented true SGML parsing for HTML documents; the only - user agents to strictly handle HTML as an SGML application have - historically been validators. The resulting confusion — with - validators claiming documents to have one representation while widely - deployed Web browsers interoperably implemented a different - representation — has wasted decades of productivity. This version - of HTML thus returns to a non-SGML basis.</p> - - <p>Authors interested in using SGML tools in their authoring pipeline are - encouraged to use XML tools and the XML serialisation of HTML5.</p> - </div> - - <p>This specification defines the parsing rules for HTML documents, whether - they are syntactically valid or not. Certain points in the parsing - algorithm are said to be <dfn id=parse title="parse error">parse - errors</dfn>. The error handling for parse errors is well-defined: user - agents must either act as described below when encountering such problems, - or must abort processing at the first error that they encounter for which - they do not wish to apply the rules described below. - - <p>Conformance checkers must report at least one parse error condition to - the user if one or more parse error conditions exist in the document and - must not report parse error conditions if none exist in the document. - Conformance checkers may report more than one parse error condition if - more than one parse error conditions exist in the document. Conformance - checkers are not required to recover from parse errors. - - <p class=note>Parse errors are only errors with the <em>syntax</em> of - HTML. In addition to checking for parse errors, conformance checkers will - also verify that the document obeys all the other conformance requirements - described in this specification. - - <h4 id=overview><span class=secno>8.2.1. </span>Overview of the parsing - model</h4> - - <p>The input to the HTML parsing process consists of a stream of Unicode - characters, which is passed through a <a - href="#tokenisation0">tokenisation</a> stage (lexical analysis) followed - by a <a href="#tree-construction0">tree construction</a> stage (semantic - analysis). The output is a <code>Document</code> object. - - <p class=note>Implementations that <a href="#non-scripted">do not support - scripting</a> do not have to actually create a DOM <code>Document</code> - object, but the DOM tree in such cases is still used as the model for the - rest of the specification. - - <p>In the common case, the data handled by the tokenisation stage comes - from the network, but <a href="#dynamic2" title="dynamic markup - insertion">it can also come from script</a>, e.g. using the <code - title=dom-document-write-HTML><a - href="#document.write0">document.write()</a></code> API. - - <p><img alt="" src="images/parsing-model-overview.png"> - - <p id=nestedParsing>There is only one set of state for the tokeniser stage - and the tree construction stage, but the tree construction stage is - reentrant, meaning that while the tree construction stage is handling one - token, the tokeniser might be resumed, causing further tokens to be - emitted and processed before the first token's processing is complete. - - <div class=example> - <p>In the following example, the tree construction stage will be called - upon to handle a "p" start tag token while handling the "script" start - tag token:</p> - - <pre>... -<script> - document.write('<p>'); -</script> -...</pre> - </div> - - <h4 id=the-input0><span class=secno>8.2.2. </span>The <dfn id=input0>input - stream</dfn></h4> - - <p>The stream of Unicode characters that consists the input to the - tokenisation stage will be initially seen by the user agent as a stream of - bytes (typically coming over the network or from the local file system). - The bytes encode the actual characters according to a particular - <em>character encoding</em>, which the user agent must use to decode the - bytes into characters. - - <p id=documentEncoding>For HTML, user agents must use the following - algorithm in determining the character encoding of a document: - - <ol> - <li> - <p>If the transport layer specifies an encoding, use that, and abort - these steps. - - <li> - <p>The user agent may wait for 512 or more bytes of the resource to be - available. - - <li> - <p>Let <var title="">n</var> be the smaller of either 512 or the number - of bytes already available. - - <li> - <p>For each of the rows in the following table, starting with the first - one and going down, if <var title="">n</var> is equal to or greater than - the number of bytes in the first column, and the first bytes of the file - match the bytes given in the first column, then use the encoding given - in the cell in the second column of that row, and abort these steps:</p> - - <table> - <thead> - <tr> - <th>Bytes in Hexadecimal - - <th>Description - - <tbody> - <tr> - <td>00 00 FE FF - - <td>UTF-32BE BOM - - <tr> - <td>FF FE 00 00 - - <td>UTF-32LE BOM - - <tr> - <td>FE FF - - <td>UTF-16BE BOM - - <tr> - <td>FF FE - - <td>UTF-16LE BOM - - <tr> - <td>EF BB BF - - <td>UTF-8 BOM <!-- nobody uses this - <tr> - <td>DD 73 66 73 - <td>UTF-EBCDIC ---> - - </table> - - <li> - <p>Otherwise, the user agent will have to search for explicit character - encoding information in the file itself. This must proceed as follows: - - <p>Let <var title="">position</var> be a pointer to a byte in the input - stream, initially pointing at the first byte. If at any point during - these steps the <var title="">position</var> pointer points beyond the - <var title="">n</var>th byte of the input stream, then skip to the next - step of the overall character encoding detection algorithm (the step - which mentions frequency analysis below).</p> - - <p>Now, repeat the following "two" steps until the algorithm aborts - (either because <var title="">position</var> reaches beyond the <var - title="">n</var>th byte, or because a character encoding is found):</p> - - <ol> - <li> - <p>If <var title="">position</var> points to:</p> - - <dl class=switch> - <dt>A sequence of bytes starting with: 0x3C 0x21 0x2D 0x2D (ASCII - '<!--') - - <dd> - <p>Advance the <var title="">position</var> pointer so that it points - at the first 0x3E byte which is preceeded by two 0x2D bytes (i.e. at - the end of an ASCII '-->' sequence) and comes after the second 0x2D - byte that was found. (The two 0x2D bytes cannot be the same as the - those in the '<!--' sequence.) If no such byte is found before - the <var title="">n</var>th byte, abort this "two step" algorithm.</p> - - <dt>A sequence of bytes starting with: 0x3C, 0x4D or 0x6D, 0x45 or - 0x65, 0x54 or 0x74, 0x41 or 0x61, and finally one of 0x09, 0x0A, - 0x0B, 0x0C, 0x0D, 0x20 (case-insensitive ASCII '<meta' followed by - a space) - - <dd> - <ol> - <li> - <p>Advance the <var title="">position</var> pointer so that it - points at the next 0x09, 0x0A, 0x0B, 0x0C, 0x0D, or 0x20 byte (the - one in sequence of characters matched above), if there is one - before the <var title="">n</var>th byte. If there isn't, abort the - "two step" algorithm. - - <li> - <p><a href="#get-an" title=concept-get-attributes-when-sniffing>Get - an attribute</a> and its value. If no attribute was sniffed, then - skip this inner set of steps, and jump to the second step in the - overall "two step" algorithm.</p> - - <p class=note>As required above, if the <var - title="">position</var> pointer points beyond the <var - title="">n</var>th byte after the "get an attribute" step, the - "two step" algorithm will abort. - - <li> - <p>Examine the attribute's name:</p> - - <dl class=switch> - <dt>If it is 'charset' - - <dd> - <p>If the attribute's value is a supported character encoding, - then use the given encoding, and abort all these steps. - Otherwise, do nothing with this attribute. - - <dt>If it is 'content' - - <dd> - <p>The attribute's value is now parsed.</p> - - <ol> - <li> - <p>Skip characters in the attribute's value up to and including - the first U+003B SEMICOLON (<code title="">;</code>) - character. - - <li> - <p>Skip any U+0009, U+000A, U+000B, U+000C, U+000D, or U+0020 - characters (i.e. spaces) that immediately follow the - semicolon. - - <li> - <p>If the next six characters are not 'charset', abort this - very inner set of steps (parsing the attribute's value), and - continue looking for other attributes. - - <li> - <p>Skip any U+0009, U+000A, U+000B, U+000C, U+000D, or U+0020 - characters that immediately follow the word 'charset' (there - might not be any). - - <li> - <p>If the next character is not a U+003D EQUALS SIGN ('='), - abort this very inner set of steps (parsing the attribute's - value), and continue looking for other attributes. - - <li> - <p>Skip any U+0009, U+000A, U+000B, U+000C, U+000D, or U+0020 - characters that immediately follow the word equals sign (there - might not be any). - - <li> - <p>Process the next character as follows:</p> - - <dl class=switch> - <dt>If it is a U+0022 QUOTATION MARK ('"') and there is a - later U+0022 QUOTATION MARK ('"') in the attribute's value - - <dd> - <p>Let <var title="">tentative encoding</var> be the string - between the two quotation marks. - - <dt>If it is a U+0027 APOSTROPHE ("'") and there is a later - U+0027 APOSTROPHE ("'") in the attribute's value - - <dd> - <p>Let <var title="">tentative encoding</var> be the string - between the two apostrophes. - - <dt>If it is an unmatched U+0022 QUOTATION MARK ('"') - - <dt>If it is an unmatched U+0027 APOSTROPHE ("'") - - <dd> - <p>There is no <var title="">tentative encoding</var>. - - <dt>Otherwise - - <dd> - <p>Let <var title="">tentative encoding</var> be the string - from this character to the first U+0009, U+000A, U+000B, - U+000C, U+000D, or U+0020 character or the end of the - attribute's value, whichever comes first. - </dl> - - <li>If there is a <var title="">tentative encoding</var> and it - is the name of a supported character encoding, then use that - encoding; abort all these steps. - - <li>Otherwise, skip this 'content' attribute and continue on - with any other attributes. - </ol> - - <dd> - - <dt>Any other name - - <dd> - <p>Do nothing with that attribute. - </dl> - - <li> - <p>Return to step 1 in these inner steps. - </ol> - - <dt>A sequence of bytes starting with a 0x3C byte (ASCII '<'), - optionally a 0x2F byte (ASCII '/'), and finally a byte in the range - 0x41-0x5A or 0x61-0x7A (an ASCII letter) - - <dd> - <ol> - <li> - <p>Advance the <var title="">position</var> pointer so that it - points at the next 0x09 (ASCII TAB), 0x0A (ASCII LF), 0x0B (ASCII - VT), 0x0C (ASCII FF), 0x0D (ASCII CR), 0x20 (ASCII space), 0x3E - (ASCII '>'), 0x3C (ASCII '<') byte, if there is one before the - <var title="">n</var>th byte. If there isn't, abort the "two step" - algorithm. - - <li> - <p>If the pointer points to a 0x3C (ASCII '<') byte, then return to - the first step in the overall "two step" algorithm. - - <li> - <p>Repeatedly <a href="#get-an" - title=concept-get-attributes-when-sniffing>get an attribute</a> - until no further attributes can be found, then jump to the second - step in the overall "two step" algorithm. - </ol> - - <dt>A sequence of bytes starting with: 0x3C 0x2D (ASCII '<!') - - <dt>A sequence of bytes starting with: 0x3C 0x2F (ASCII '</') - - <dt>A sequence of bytes starting with: 0x3C 0x3F (ASCII '<?') - - <dd> - <p>Advance the <var title="">position</var> pointer so that it points - at the first 0x3E byte (ASCII '>') that comes after the 0x3C byte - that was found. If no such byte is found before the <var - title="">n</var>th byte, abort this "two step" algorithm.</p> - - <dt>Any other byte - - <dd> - <p>Do nothing with that byte.</p> - </dl> - - <li>Move <var title="">position</var> so it points at the next byte in - the input stream, and return to the first step of this "two step" - algorithm. - </ol> - - <p>When the above "two step" algorithm says to <dfn id=get-an - title=concept-get-attributes-when-sniffing>get an attribute</dfn>, it - means doing this:</p> - - <ol> - <li> - <p>If the byte at <var title="">position</var> is one of 0x09 (ASCII - TAB), 0x0A (ASCII LF), 0x0B (ASCII VT), 0x0C (ASCII FF), 0x0D (ASCII - CR), 0x20 (ASCII space), or 0x2F (ASCII '/') then advance <var - title="">position</var> to the next byte and start over. - - <li> - <p>If the byte at <var title="">position</var> is 0x3C (ASCII '<'), - then move <var title="">position</var> back to the previous byte, and - stop looking for an attribute. There isn't one. - - <li> - <p>If the byte at <var title="">position</var> is 0x3E (ASCII '>'), - then stop looking for an attribute. There isn't one. - - <li> - <p>Otherwise, the byte at <var title="">position</var> is the start of - the attribute name. Let <var title="">attribute name</var> and <var - title="">attribute value</var> be the empty string. - - <li> - <p><em>Attribute name</em>: Process the byte at <var - title="">position</var> as follows:</p> - - <dl class=switch> - <dt>If it is 0x3D (ASCII '='), and the <var title="">attribute - name</var> is longer than the empty string - - <dd>Advance <var title="">position</var> to the next byte and jump to - the step below labelled <em>value</em>. - - <dt>If it is 0x09 (ASCII TAB), 0x0A (ASCII LF), 0x0B (ASCII VT), 0x0C - (ASCII FF), 0x0D (ASCII CR), or 0x20 (ASCII space) - - <dd>Jump to the step below labelled <em>spaces</em>. - - <dt>If it is 0x2F (ASCII '/'), 0x3C (ASCII '<'), or 0x3E (ASCII - '>') - - <dd>Stop looking for an attribute. The attribute's name is the value - of <var title="">attribute name</var>, its value is the empty string. - - <dt>If it is in the range 0x41 (ASCII 'A') to 0x5A (ASCII 'Z') - - <dd>Append the Unicode character with codepoint <span><var - title="">b</var>+0x20</span> to <var title="">attribute name</var> - (where <var title="">b</var> is the value of the byte at <var - title="">position</var>). - - <dt>Anything else - - <dd>Append the Unicode character with the same codepoint as the value - of the byte at <var title="">position</var>) to <var - title="">attribute name</var>. (It doesn't actually matter how bytes - outside the ASCII range are handled here, since only ASCII characters - can contribute to the detection of a character encoding.) - </dl> - - <li> - <p>Advance <var title="">position</var> to the next byte and return to - the previous step. - - <li> - <p><em>Spaces.</em> If the byte at <var title="">position</var> is one - of 0x09 (ASCII TAB), 0x0A (ASCII LF), 0x0B (ASCII VT), 0x0C (ASCII - FF), 0x0D (ASCII CR), or 0x20 (ASCII space) then advance <var - title="">position</var> to the next byte, then, repeat this step. - - <li> - <p>If the byte at <var title="">position</var> is <em>not</em> 0x3D - (ASCII '='), stop looking for an attribute. Move <var - title="">position</var> back to the previous byte. The attribute's - name is the value of <var title="">attribute name</var>, its value is - the empty string. - - <li> - <p>Advance <var title="">position</var> past the 0x3D (ASCII '=') byte. - - <li> - <p><em>Value.</em> If the byte at <var title="">position</var> is one - of 0x09 (ASCII TAB), 0x0A (ASCII LF), 0x0B (ASCII VT), 0x0C (ASCII - FF), 0x0D (ASCII CR), or 0x20 (ASCII space) then advance <var - title="">position</var> to the next byte, then, repeat this step. - - <li> - <p>Process the byte at <var title="">position</var> as follows:</p> - - <dl class=switch> - <dt>If it is 0x22 (ASCII '"') or 0x27 ("'") - - <dd> - <ol> - <li>Let <var title="">b</var> be the value of the byte at <var - title="">position</var>. - - <li>Advance <var title="">position</var> to the next byte. - - <li>If the value of the byte at <var title="">position</var> is the - value of <var title="">b</var>, then stop looking for an attribute. - The attribute's name is the value of <var title="">attribute - name</var>, and its value is the value of <var title="">attribute - value</var>. - - <li>Otherwise, if the value of the byte at <var - title="">position</var> is in the range 0x41 (ASCII 'A') to 0x5A - (ASCII 'Z'), then append a Unicode character to <var - title="">attribute value</var> whose codepoint is 0x20 more than - the value of the byte at <var title="">position</var>. - - <li>Otherwise, append a Unicode character to <var title="">attribute - value</var> whose codepoint is the same as the value of the byte at - <var title="">position</var>. - - <li>Return to the second step in these substeps. - </ol> - - <dt>If it is 0x3C (ASCII '<'), or 0x3E (ASCII '>') - - <dd>Stop looking for an attribute. The attribute's name is the value - of <var title="">attribute name</var>, its value is the empty string. - - <dt>If it is in the range 0x41 (ASCII 'A') to 0x5A (ASCII 'Z') - - <dd>Append the Unicode character with codepoint <span><var - title="">b</var>+0x20</span> to <var title="">attribute value</var> - (where <var title="">b</var> is the value of the byte at <var - title="">position</var>). - - <dt>Anything else - - <dd>Append the Unicode character with the same codepoint as the value - of the byte at <var title="">position</var>) to <var - title="">attribute value</var>. - </dl> - - <li> - <p>Process the byte at <var title="">position</var> as follows:</p> - - <dl class=switch> - <dt>If it is 0x09 (ASCII TAB), 0x0A (ASCII LF), 0x0B (ASCII VT), 0x0C - (ASCII FF), 0x0D (ASCII CR), 0x20 (ASCII space), 0x3C (ASCII '<'), - or 0x3E (ASCII '>') - - <dd>Stop looking for an attribute. The attribute's name is the value - of <var title="">attribute name</var> and its value is the value of - <var title="">attribute value</var>. - - <dt>If it is in the range 0x41 (ASCII 'A') to 0x5A (ASCII 'Z') - - <dd>Append the Unicode character with codepoint <span><var - title="">b</var>+0x20</span> to <var title="">attribute value</var> - (where <var title="">b</var> is the value of the byte at <var - title="">position</var>). - - <dt>Anything else - - <dd>Append the Unicode character with the same codepoint as the value - of the byte at <var title="">position</var>) to <var - title="">attribute value</var>. - </dl> - - <li> - <p>Advance <var title="">position</var> to the next byte and return to - the previous step. - </ol> - - <li> - <p>The user agent may attempt to autodetect the character encoding from - applying frequency analysis or other algorithms to the data stream. If - autodetection succeeds in determining a character encoding, then use - that; abort these steps. <a href="#refsUNIVCHARDET">[UNIVCHARDET]</a> - </li> - <!-- - http://www.mozilla.org/projects/intl/UniversalCharsetDetection.html - --> - - <li> - <p>Otherwise, use an implementation-defined or user-specified default - character encoding. Due to its use in legacy content, <code - title="">windows-1252</code> is recommended as a default in - predominantly Western demographics. In non-legacy environments, the more - comprehensive <code title="">UTF-8</code> encoding is recommended - instead. Since these encodings can in many cases be distinguished by - inspection, a user agent may heuristically decide which to use as a - default. - </ol> - - <p class=note>For XML documents, the algorithm user agents must use to - determine the character encoding is given by the XML specification. This - section does not apply to XML documents. <a href="#refsXML">[XML]</a> - - <p>When a user agent would otherwise use the ISO-8859-1 encoding, it must - instead use the Windows-1252 encoding. User agents must not support the - CESU-8, UTF-7, BOCU-1 and SCSU encodings. <a href="#refsCESU8">[CESU8]</a> - <a href="#refsUTF7">[UTF7]</a> <a href="#refsBOCU1">[BOCU1]</a> <a - href="#refsSCSU">[SCSU]</a> - - <p>Bytes or sequences of bytes in the original byte stream that could not - be converted to Unicode characters must be converted to U+FFFD REPLACEMENT - CHARACTER code points. - - <p>A leading U+FEFF BYTE ORDER MARK (BOM) must be dropped if present. - - <p>All U+0000 NULL characters in the input must be replaced by U+FFFD - REPLACEMENT CHARACTERs. Any occurrences of such characters is a <a - href="#parse">parse error</a>. - - <p>U+000D CARRIAGE RETURN (CR) characters, and U+000A LINE FEED (LF) - characters, are treated specially. Any CR characters that are followed by - LF characters must be removed, and any CR characters not followed by LF - characters must be converted to LF characters. Thus, newlines in HTML DOMs - are represented by LF characters, and there are never any CR characters in - the input to the <a href="#tokenisation0">tokenisation</a> stage. - - <p>The <dfn id=next-input>next input character</dfn> is the first character - in the input stream that has not yet been <dfn id=consumed>consumed</dfn>. - Initially, the <em><a href="#next-input">next input character</a></em> is - the first character in the input. - - <p>The <dfn id=insertion>insertion point</dfn> is the position (just before - a character or just before the end of the input stream) where content - inserted using <code title=dom-document-write-HTML><a - href="#document.write0">document.write()</a></code> is actually inserted. - The insertion point is relative to the position of the character - immediately after it, it is not an absolute offset into the input stream. - Initially, the insertion point is uninitialised. - - <p>The "EOF" character in the tables below is a conceptual character - representing the end of the <a href="#input0">input stream</a>. If the - parser is a <a href="#script-created">script-created parser</a>, then the - end of the <a href="#input0">input stream</a> is reached when an <dfn - id=explicit>explicit "EOF" character</dfn> (inserted by the <code - title=dom-document-close><a href="#close">document.close()</a></code> - method) is consumed. Otherwise, the "EOF" character is not a real - character in the stream, but rather the lack of any further characters. - - <h4 id=tokenisation><span class=secno>8.2.3. </span><dfn - id=tokenisation0>Tokenisation</dfn></h4> - - <p>Implementations must act as if they used the following state machine to - tokenise HTML. The state machine must start in the <a - href="#data-state">data state</a>. Most states consume a single character, - which may have various side-effects, and either switches the state machine - to a new state to <em>reconsume</em> the same character, or switches it to - a new state (to consume the next character), or repeats the same state (to - consume the next character). Some states have more complicated behaviour - and can consume several characters before switching to another state. - - <p>The exact behaviour of certain states depends on a <dfn - id=content2>content model flag</dfn> that is set after certain tokens are - emitted. The flag has several states: <em title="">PCDATA</em>, <em - title="">RCDATA</em>, <em title="">CDATA</em>, and <em - title="">PLAINTEXT</em>. Initially it must be in the PCDATA state. In the - RCDATA and CDATA states, a further <dfn id=escape>escape flag</dfn> is - used to control the behaviour of the tokeniser. It is either true or - false, and initially must be set to the false state. - - <p>The output of the tokenisation step is a series of zero or more of the - following tokens: DOCTYPE, start tag, end tag, comment, character, - end-of-file. DOCTYPE tokens have names and can be either correct or in - error. Start and end tag tokens have a tag name and a list of attributes, - each of which has a name and a value. Comment and character tokens have - data. - - <p>When a token is emitted, it must immediately be handled by the <a - href="#tree-construction0">tree construction</a> stage. The tree - construction stage can affect the state of the <a href="#content2">content - model flag</a>, and can insert additional characters into the stream. (For - example, the <code><a href="#script0">script</a></code> element can result - in scripts executing and using the <a href="#dynamic2">dynamic markup - insertion</a> APIs to insert characters into the stream being tokenised.) - - <p>When an end tag token is emitted, the <a href="#content2">content model - flag</a> must be switched to the PCDATA state. - - <p>When an end tag token is emitted with attributes, that is a <a - href="#parse">parse error</a>. - - <p>Before each step of the tokeniser, the user agent may check to see if - either one of the scripts in the <a href="#list-of1">list of scripts that - will execute as soon as possible</a> or the first script in the <a - href="#list-of0">list of scripts that will execute asynchronously</a>, has - <span>completed loading</span><!-- XXX xref -->. If one has, then it must - be <a href="#executing0" title="executing a script block">executed</a> and - removed from its list. - - <p>The tokeniser state machine is as follows: - - <dl> - <dt><dfn id=data-state>Data state</dfn> - - <dd> - <p>Consume the <a href="#next-input">next input character</a>:</p> - - <dl class=switch> - <dt>U+0026 AMPERSAND (&) - - <dd>When the <a href="#content2">content model flag</a> is set to one of - the PCDATA or RCDATA states: switch to the <a href="#entity">entity - data state</a>. - - <dd>Otherwise: treat it as per the "anything else" entry below. - - <dt>U+002D HYPHEN-MINUS (-) - - <dd> - <p>If the <a href="#content2">content model flag</a> is set to either - the RCDATA state or the CDATA state, and the <a href="#escape">escape - flag</a> is false, and there are at least three characters before this - one in the input stream, and the last four characters in the input - stream, including this one, are U+003C LESS-THAN SIGN, U+0021 - EXCLAMATION MARK, U+002D HYPHEN-MINUS, and U+002D HYPHEN-MINUS - ("<!--"), then set the <a href="#escape">escape flag</a> to true.</p> - - <p>In any case, emit the input character as a character token. Stay in - the <a href="#data-state">data state</a>.</p> - - <dt>U+003C LESS-THAN SIGN (<) - - <dd>When the <a href="#content2">content model flag</a> is set to the - PCDATA state: switch to the <a href="#tag-open">tag open state</a>. - - <dd>When the <a href="#content2">content model flag</a> is set to either - the RCDATA state or the CDATA state and the <a href="#escape">escape - flag</a> is false: switch to the <a href="#tag-open">tag open - state</a>. - - <dd>Otherwise: treat it as per the "anything else" entry below. - - <dt>U+003E GREATER-THAN SIGN (>) - - <dd> - <p>If the <a href="#content2">content model flag</a> is set to either - the RCDATA state or the CDATA state, and the <a href="#escape">escape - flag</a> is true, and the last three characters in the input stream - including this one are U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS, - U+003E GREATER-THAN SIGN ("-->"), set the <a href="#escape">escape - flag</a> to false.</p> - <!-- no need to check - that there are enough characters, since you can only run into - this if the flag is true in the first place, which requires four - characters. --> - - <p>In any case, emit the input character as a character token. Stay in - the <a href="#data-state">data state</a>.</p> - - <dt>EOF - - <dd>Emit an end-of-file token. - - <dt>Anything else - - <dd>Emit the input character as a character token. Stay in the <a - href="#data-state">data state</a>. - </dl> - - <dt><dfn id=entity>Entity data state</dfn> - - <dd> - <p><em>(This cannot happen if the <a href="#content2">content model - flag</a> is set to the CDATA state.)</em></p> - - <p>Attempt to <a href="#consume">consume an entity</a>.</p> - - <p>If nothing is returned, emit a U+0026 AMPERSAND character token.</p> - - <p>Otherwise, emit the character token that was returned.</p> - - <p>Finally, switch to the <a href="#data-state">data state</a>.</p> - - <dt><dfn id=tag-open>Tag open state</dfn> - - <dd> - <p>The behaviour of this state depends on the <a href="#content2">content - model flag</a>.</p> - - <dl> - <dt>If the <a href="#content2">content model flag</a> is set to the - RCDATA or CDATA states - - <dd> - <p>If the <a href="#next-input">next input character</a> is a U+002F - SOLIDUS (/) character, consume it and switch to the <a - href="#close1">close tag open state</a>. If the <a - href="#next-input">next input character</a> is not a U+002F SOLIDUS - (/) character, emit a U+003C LESS-THAN SIGN character token and switch - to the <a href="#data-state">data state</a> to process the <a - href="#next-input">next input character</a>.</p> - - <dt>If the <a href="#content2">content model flag</a> is set to the - PCDATA state - - <dd> - <p>Consume the <a href="#next-input">next input character</a>:</p> - - <dl class=switch> - <dt>U+0021 EXCLAMATION MARK (!) - - <dd>Switch to the <a href="#markup">markup declaration open state</a>. - - <dt>U+002F SOLIDUS (/) - - <dd>Switch to the <a href="#close1">close tag open state</a>. - - <dt>U+0041 LATIN CAPITAL LETTER A through to U+005A LATIN CAPITAL - LETTER Z - - <dd>Create a new start tag token, set its tag name to the lowercase - version of the input character (add 0x0020 to the character's code - point), then switch to the <a href="#tag-name0">tag name state</a>. - (Don't emit the token yet; further details will be filled in before - it is emitted.) - - <dt>U+0061 LATIN SMALL LETTER A through to U+007A LATIN SMALL LETTER Z - - <dd>Create a new start tag token, set its tag name to the input - character, then switch to the <a href="#tag-name0">tag name - state</a>. (Don't emit the token yet; further details will be filled - in before it is emitted.) - - <dt>U+003E GREATER-THAN SIGN (>) - - <dd><a href="#parse">Parse error</a>. Emit a U+003C LESS-THAN SIGN - character token and a U+003E GREATER-THAN SIGN character token. - Switch to the <a href="#data-state">data state</a>. - - <dt>U+003F QUESTION MARK (?) - - <dd><a href="#parse">Parse error</a>. Switch to the <a - href="#bogus">bogus comment state</a>. - - <dt>Anything else - - <dd><a href="#parse">Parse error</a>. Emit a U+003C LESS-THAN SIGN - character token and reconsume the current input character in the <a - href="#data-state">data state</a>. - </dl> - </dl> - - <dt><dfn id=close1>Close tag open state</dfn> - - <dd> - <p>If the <a href="#content2">content model flag</a> is set to the RCDATA - or CDATA states then examine the next few characters. If they do not - match the tag name of the last start tag token emitted (case - insensitively), or if they do but they are not immediately followed by - one of the following characters:</p> - - <ul class=brief> - <li>U+0009 CHARACTER TABULATION - - <li>U+000A LINE FEED (LF) - - <li>U+000B LINE TABULATION - - <li>U+000C FORM FEED (FF)</li> - <!--<li>U+000D CARRIAGE RETURN (CR)</li>--> - - <li>U+0020 SPACE - - <li>U+003E GREATER-THAN SIGN (>) - - <li>U+002F SOLIDUS (/) - - <li>U+003C LESS-THAN SIGN (<) - - <li>EOF - </ul> - - <p>...then there is a <a href="#parse">parse error</a>. Emit a U+003C - LESS-THAN SIGN character token, a U+002F SOLIDUS character token, and - switch to the <a href="#data-state">data state</a> to process the <a - href="#next-input">next input character</a>.</p> - - <p>Otherwise, if the <a href="#content2">content model flag</a> is set to - the PCDATA state, or if the next few characters <em>do</em> match that - tag name, consume the <a href="#next-input">next input character</a>:</p> - - <dl class=switch> - <dt>U+0041 LATIN CAPITAL LETTER A through to U+005A LATIN CAPITAL LETTER - Z - - <dd>Create a new end tag token, set its tag name to the lowercase - version of the input character (add 0x0020 to the character's code - point), then switch to the <a href="#tag-name0">tag name state</a>. - (Don't emit the token yet; further details will be filled in before it - is emitted.) - - <dt>U+0061 LATIN SMALL LETTER A through to U+007A LATIN SMALL LETTER Z - - <dd>Create a new end tag token, set its tag name to the input character, - then switch to the <a href="#tag-name0">tag name state</a>. (Don't emit - the token yet; further details will be filled in before it is emitted.) - - <dt>U+003E GREATER-THAN SIGN (>) - - <dd><a href="#parse">Parse error</a>. Switch to the <a - href="#data-state">data state</a>. - - <dt>EOF - - <dd><a href="#parse">Parse error</a>. Emit a U+003C LESS-THAN SIGN - character token and a U+002F SOLIDUS character token. Reconsume the EOF - character in the <a href="#data-state">data state</a>. - - <dt>Anything else - - <dd><a href="#parse">Parse error</a>. Switch to the <a - href="#bogus">bogus comment state</a>. - </dl> - - <dt><dfn id=tag-name0>Tag name state</dfn> - - <dd> - <p>Consume the <a href="#next-input">next input character</a>:</p> - - <dl class=switch> - <dt>U+0009 CHARACTER TABULATION - - <dt>U+000A LINE FEED (LF) - - <dt>U+000B LINE TABULATION - - <dt>U+000C FORM FEED (FF)</dt> - <!--<dt>U+000D CARRIAGE RETURN (CR)</dt>--> - - <dt>U+0020 SPACE - - <dd>Switch to the <a href="#before">before attribute name state</a>. - - <dt>U+003E GREATER-THAN SIGN (>) - - <dd>Emit the current tag token. Switch to the <a href="#data-state">data - state</a>. - - <dt>U+0041 LATIN CAPITAL LETTER A through to U+005A LATIN CAPITAL LETTER - Z - - <dd>Append the lowercase version of the current input character (add - 0x0020 to the character's code point) to the current tag token's tag - name. Stay in the <a href="#tag-name0">tag name state</a>. - - <dt>U+003C LESS-THAN SIGN (<) - - <dt>EOF - - <dd><a href="#parse">Parse error</a>. Emit the current tag token. - Reconsume the character in the <a href="#data-state">data state</a>. - - <dt>U+002F SOLIDUS (/) - - <dd><a href="#parse">Parse error</a> unless this is a <a - href="#permitted">permitted slash</a>. Switch to the <a - href="#before">before attribute name state</a>. - - <dt>Anything else - - <dd>Append the current input character to the current tag token's tag - name. Stay in the <a href="#tag-name0">tag name state</a>. - </dl> - - <dt><dfn id=before>Before attribute name state</dfn> - - <dd> - <p>Consume the <a href="#next-input">next input character</a>:</p> - - <dl class=switch> - <dt>U+0009 CHARACTER TABULATION - - <dt>U+000A LINE FEED (LF) - - <dt>U+000B LINE TABULATION - - <dt>U+000C FORM FEED (FF)</dt> - <!--<dt>U+000D CARRIAGE RETURN (CR)</dt>--> - - <dt>U+0020 SPACE - - <dd>Stay in the <a href="#before">before attribute name state</a>. - - <dt>U+003E GREATER-THAN SIGN (>) - - <dd>Emit the current tag token. Switch to the <a href="#data-state">data - state</a>. - - <dt>U+0041 LATIN CAPITAL LETTER A through to U+005A LATIN CAPITAL LETTER - Z - - <dd>Start a new attribute in the current tag token. Set that attribute's - name to the lowercase version of the current input character (add - 0x0020 to the character's code point), and its value to the empty - string. Switch to the <a href="#attribute1">attribute name state</a>. - - <dt>U+002F SOLIDUS (/) - - <dd><a href="#parse">Parse error</a> unless this is a <a - href="#permitted">permitted slash</a>. Stay in the <a - href="#before">before attribute name state</a>. - - <dt>U+003C LESS-THAN SIGN (<) - - <dt>EOF - - <dd><a href="#parse">Parse error</a>. Emit the current tag token. - Reconsume the character in the <a href="#data-state">data state</a>. - - <dt>Anything else - - <dd>Start a new attribute in the current tag token. Set that attribute's - name to the current input character, and its value to the empty string. - Switch to the <a href="#attribute1">attribute name state</a>. - </dl> - - <dt><dfn id=attribute1>Attribute name state</dfn> - - <dd> - <p>Consume the <a href="#next-input">next input character</a>:</p> - - <dl class=switch> - <dt>U+0009 CHARACTER TABULATION - - <dt>U+000A LINE FEED (LF) - - <dt>U+000B LINE TABULATION - - <dt>U+000C FORM FEED (FF)</dt> - <!--<dt>U+000D CARRIAGE RETURN (CR)</dt>--> - - <dt>U+0020 SPACE - - <dd>Switch to the <a href="#after">after attribute name state</a>. - - <dt>U+003D EQUALS SIGN (=) - - <dd>Switch to the <a href="#before0">before attribute value state</a>. - - <dt>U+003E GREATER-THAN SIGN (>) - - <dd>Emit the current tag token. Switch to the <a href="#data-state">data - state</a>. - - <dt>U+0041 LATIN CAPITAL LETTER A through to U+005A LATIN CAPITAL LETTER - Z - - <dd>Append the lowercase version of the current input character (add - 0x0020 to the character's code point) to the current attribute's name. - Stay in the <a href="#attribute1">attribute name state</a>. - - <dt>U+002F SOLIDUS (/) - - <dd><a href="#parse">Parse error</a> unless this is a <a - href="#permitted">permitted slash</a>. Switch to the <a - href="#before">before attribute name state</a>. - - <dt>U+003C LESS-THAN SIGN (<) - - <dt>EOF - - <dd><a href="#parse">Parse error</a>. Emit the current tag token. - Reconsume the character in the <a href="#data-state">data state</a>. - - <dt>Anything else - - <dd>Append the current input character to the current attribute's name. - Stay in the <a href="#attribute1">attribute name state</a>. - </dl> - - <p>When the user agent leaves the attribute name state (and before - emitting the tag token, if appropriate), the complete attribute's name - must be compared to the other attributes on the same token; if there is - already an attribute on the token with the exact same name, then this is - a <a href="#parse">parse error</a> and the new attribute must be - dropped, along with the value that gets associated with it (if any).</p> - - <dt><dfn id=after>After attribute name state</dfn> - - <dd> - <p>Consume the <a href="#next-input">next input character</a>:</p> - - <dl class=switch> - <dt>U+0009 CHARACTER TABULATION - - <dt>U+000A LINE FEED (LF) - - <dt>U+000B LINE TABULATION - - <dt>U+000C FORM FEED (FF)</dt> - <!--<dt>U+000D CARRIAGE RETURN (CR)</dt>--> - - <dt>U+0020 SPACE - - <dd>Stay in the <a href="#after">after attribute name state</a>. - - <dt>U+003D EQUALS SIGN (=) - - <dd>Switch to the <a href="#before0">before attribute value state</a>. - - <dt>U+003E GREATER-THAN SIGN (>) - - <dd>Emit the current tag token. Switch to the <a href="#data-state">data - state</a>. - - <dt>U+0041 LATIN CAPITAL LETTER A through to U+005A LATIN CAPITAL LETTER - Z - - <dd>Start a new attribute in the current tag token. Set that attribute's - name to the lowercase version of the current input character (add - 0x0020 to the character's code point), and its value to the empty - string. Switch to the <a href="#attribute1">attribute name state</a>. - - <dt>U+002F SOLIDUS (/) - - <dd><a href="#parse">Parse error</a> unless this is a <a - href="#permitted">permitted slash</a>. Switch to the <a - href="#before">before attribute name state</a>. - - <dt>U+003C LESS-THAN SIGN (<) - - <dt>EOF - - <dd><a href="#parse">Parse error</a>. Emit the current tag token. - Reconsume the character in the <a href="#data-state">data state</a>. - - <dt>Anything else - - <dd>Start a new attribute in the current tag token. Set that attribute's - name to the current input character, and its value to the empty string. - Switch to the <a href="#attribute1">attribute name state</a>. - </dl> - - <dt><dfn id=before0>Before attribute value state</dfn> - - <dd> - <p>Consume the <a href="#next-input">next input character</a>:</p> - - <dl class=switch> - <dt>U+0009 CHARACTER TABULATION - - <dt>U+000A LINE FEED (LF) - - <dt>U+000B LINE TABULATION - - <dt>U+000C FORM FEED (FF)</dt> - <!--<dt>U+000D CARRIAGE RETURN (CR)</dt>--> - - <dt>U+0020 SPACE - - <dd>Stay in the <a href="#before0">before attribute value state</a>. - - <dt>U+0022 QUOTATION MARK (") - - <dd>Switch to the <a href="#attribute2">attribute value (double-quoted) - state</a>. - - <dt>U+0026 AMPERSAND (&) - - <dd>Switch to the <a href="#attribute4">attribute value (unquoted) - state</a> and reconsume this input character. - - <dt>U+0027 APOSTROPHE (') - - <dd>Switch to the <a href="#attribute3">attribute value (single-quoted) - state</a>. - - <dt>U+003E GREATER-THAN SIGN (>) - - <dd>Emit the current tag token. Switch to the <a href="#data-state">data - state</a>. - - <dt>U+003C LESS-THAN SIGN (<) - - <dt>EOF - - <dd><a href="#parse">Parse error</a>. Emit the current tag token. - Reconsume the character in the <a href="#data-state">data state</a>. - - <dt>Anything else - - <dd>Append the current input character to the current attribute's value. - Switch to the <a href="#attribute4">attribute value (unquoted) - state</a>. - </dl> - - <dt><dfn id=attribute2>Attribute value (double-quoted) state</dfn> - - <dd> - <p>Consume the <a href="#next-input">next input character</a>:</p> - - <dl class=switch> - <dt>U+0022 QUOTATION MARK (") - - <dd>Switch to the <a href="#before">before attribute name state</a>. - - <dt>U+0026 AMPERSAND (&) - - <dd>Switch to the <a href="#entity0">entity in attribute value - state</a>. - - <dt>EOF - - <dd><a href="#parse">Parse error</a>. Emit the current tag token. - Reconsume the character in the <a href="#data-state">data state</a>. - - <dt>Anything else - - <dd>Append the current input character to the current attribute's value. - Stay in the <a href="#attribute2">attribute value (double-quoted) - state</a>. - </dl> - - <dt><dfn id=attribute3>Attribute value (single-quoted) state</dfn> - - <dd> - <p>Consume the <a href="#next-input">next input character</a>:</p> - - <dl class=switch> - <dt>U+0027 APOSTROPHE (') - - <dd>Switch to the <a href="#before">before attribute name state</a>. - - <dt>U+0026 AMPERSAND (&) - - <dd>Switch to the <a href="#entity0">entity in attribute value - state</a>. - - <dt>EOF - - <dd><a href="#parse">Parse error</a>. Emit the current tag token. - Reconsume the character in the <a href="#data-state">data state</a>. - - <dt>Anything else - - <dd>Append the current input character to the current attribute's value. - Stay in the <a href="#attribute3">attribute value (single-quoted) - state</a>. - </dl> - - <dt><dfn id=attribute4>Attribute value (unquoted) state</dfn> - - <dd> - <p>Consume the <a href="#next-input">next input character</a>:</p> - - <dl class=switch> - <dt>U+0009 CHARACTER TABULATION - - <dt>U+000A LINE FEED (LF) - - <dt>U+000B LINE TABULATION - - <dt>U+000C FORM FEED (FF)</dt> - <!--<dt>U+000D CARRIAGE RETURN (CR)</dt>--> - - <dt>U+0020 SPACE - - <dd>Switch to the <a href="#before">before attribute name state</a>. - - <dt>U+0026 AMPERSAND (&) - - <dd>Switch to the <a href="#entity0">entity in attribute value - state</a>. - - <dt>U+003E GREATER-THAN SIGN (>) - - <dd>Emit the current tag token. Switch to the <a href="#data-state">data - state</a>. - - <dt>U+003C LESS-THAN SIGN (<) - - <dt>EOF - - <dd><a href="#parse">Parse error</a>. Emit the current tag token. - Reconsume the character in the <a href="#data-state">data state</a>. - - <dt>Anything else - - <dd>Append the current input character to the current attribute's value. - Stay in the <a href="#attribute4">attribute value (unquoted) state</a>. - </dl> - - <dt><dfn id=entity0>Entity in attribute value state</dfn> - - <dd> - <p>Attempt to <a href="#consume">consume an entity</a>.</p> - - <p>If nothing is returned, append a U+0026 AMPERSAND character to the - current attribute's value.</p> - - <p>Otherwise, append the returned character token to the current - attribute's value.</p> - - <p>Finally, switch back to the attribute value state that you were in - when were switched into this state.</p> - - <dt><dfn id=bogus>Bogus comment state</dfn> - - <dd> - <p><em>(This can only happen if the <a href="#content2">content model - flag</a> is set to the PCDATA state.)</em></p> - - <p>Consume every character up to the first U+003E GREATER-THAN SIGN - character (>) or the end of the file (EOF), whichever comes first. - Emit a comment token whose data is the concatenation of all the - characters starting from and including the character that caused the - state machine to switch into the bogus comment state, up to and - including the last consumed character before the U+003E character, if - any, or up to the end of the file otherwise. (If the comment was started - by the end of the file (EOF), the token is empty.)</p> - - <p>Switch to the <a href="#data-state">data state</a>.</p> - - <p>If the end of the file was reached, reconsume the EOF character.</p> - - <dt><dfn id=markup>Markup declaration open state</dfn> - - <dd> - <p><em>(This can only happen if the <a href="#content2">content model - flag</a> is set to the PCDATA state.)</em></p> - - <p>If the next two characters are both U+002D HYPHEN-MINUS (-) - characters, consume those two characters, create a comment token whose - data is the empty string, and switch to the <a href="#comment">comment - state</a>.</p> - - <p>Otherwise if the next seven chacacters are a - <span>case-insensitive</span><!-- XXX xref, ascii only --> match for the - word "DOCTYPE", then consume those characters and switch to the <a - href="#doctype0">DOCTYPE state</a>.</p> - - <p>Otherwise, is is a <a href="#parse">parse error</a>. Switch to the <a - href="#bogus">bogus comment state</a>. The next character that is - consumed, if any, is the first character that will be in the comment.</p> - - <dt><dfn id=comment>Comment state</dfn> - - <dd> - <p>Consume the <a href="#next-input">next input character</a>:</p> - - <dl class=switch> - <dt>U+002D HYPHEN-MINUS (-) - - <dd>Switch to the <a href="#comment0">comment dash state</a> - - <dt>EOF - - <dd><a href="#parse">Parse error</a>. Emit the comment token. Reconsume - the EOF character in the <a href="#data-state">data state</a>.</dd> - <!-- For - security reasons: otherwise, hostile user could put a <script> in - a comment e.g. in a blog comment and then DOS the server so that - the end tag isn't read, and then the commented <script> tag would - be treated as live code --> - - <dt>Anything else - - <dd>Append the input character to the comment token's data. Stay in the - <a href="#comment">comment state</a>. - </dl> - - <dt><dfn id=comment0>Comment dash state</dfn> - - <dd> - <p>Consume the <a href="#next-input">next input character</a>:</p> - - <dl class=switch> - <dt>U+002D HYPHEN-MINUS (-) - - <dd>Switch to the <a href="#comment1">comment end state</a> - - <dt>EOF - - <dd><a href="#parse">Parse error</a>. Emit the comment token. Reconsume - the EOF character in the <a href="#data-state">data state</a>.</dd> - <!-- For - security reasons: otherwise, hostile user could put a <script> in - a comment e.g. in a blog comment and then DOS the server so that - the end tag isn't read, and then the commented <script> tag would - be treated as live code --> - - <dt>Anything else - - <dd>Append a U+002D HYPHEN-MINUS (-) character and the input character - to the comment token's data. Switch to the <a href="#comment">comment - state</a>. - </dl> - - <dt><dfn id=comment1>Comment end state</dfn> - - <dd> - <p>Consume the <a href="#next-input">next input character</a>:</p> - - <dl class=switch> - <dt>U+003E GREATER-THAN SIGN (>) - - <dd>Emit the comment token. Switch to the <a href="#data-state">data - state</a>. - - <dt>U+002D HYPHEN-MINUS (-) - - <dd><a href="#parse">Parse error</a>. Append a U+002D HYPHEN-MINUS (-) - character to the comment token's data. Stay in the <a - href="#comment1">comment end state</a>. - - <dt>EOF - - <dd><a href="#parse">Parse error</a>. Emit the comment token. Reconsume - the EOF character in the <a href="#data-state">data state</a>.</dd> - <!-- For - security reasons: otherwise, hostile user could put a <script> in - a comment e.g. in a blog comment and then DOS the server so that - the end tag isn't read, and then the commented <script> tag would - be treated as live code --> - - <dt>Anything else - - <dd><a href="#parse">Parse error</a>. Append two U+002D HYPHEN-MINUS (-) - characters and the input character to the comment token's data. Switch - to the <a href="#comment">comment state</a>. - </dl> - - <dt><dfn id=doctype0>DOCTYPE state</dfn> - - <dd> - <p>Consume the <a href="#next-input">next input character</a>:</p> - - <dl class=switch> - <dt>U+0009 CHARACTER TABULATION - - <dt>U+000A LINE FEED (LF) - - <dt>U+000B LINE TABULATION - - <dt>U+000C FORM FEED (FF)</dt> - <!--<dt>U+000D CARRIAGE RETURN (CR)</dt>--> - - <dt>U+0020 SPACE - - <dd>Switch to the <a href="#before1">before DOCTYPE name state</a>. - - <dt>Anything else - - <dd><a href="#parse">Parse error</a>. Reconsume the current character in - the <a href="#before1">before DOCTYPE name state</a>. - </dl> - - <dt><dfn id=before1>Before DOCTYPE name state</dfn> - - <dd> - <p>Consume the <a href="#next-input">next input character</a>:</p> - - <dl class=switch> - <dt>U+0009 CHARACTER TABULATION - - <dt>U+000A LINE FEED (LF) - - <dt>U+000B LINE TABULATION - - <dt>U+000C FORM FEED (FF)</dt> - <!--<dt>U+000D CARRIAGE RETURN (CR)</dt>--> - - <dt>U+0020 SPACE - - <dd>Stay in the <a href="#before1">before DOCTYPE name state</a>. - - <dt>U+0061 LATIN SMALL LETTER A through to U+007A LATIN SMALL LETTER Z - - <dd>Create a new DOCTYPE token. Set the token's name name to the - uppercase version of the current input character (subtract 0x0020 from - the character's code point), and mark it as being in error. Switch to - the <a href="#doctype1">DOCTYPE name state</a>. - - <dt>U+003E GREATER-THAN SIGN (>) - - <dd><a href="#parse">Parse error</a>. Emit a DOCTYPE token whose name is - the empty string and that is marked as being in error. Switch to the <a - href="#data-state">data state</a>. - - <dt>EOF - - <dd><a href="#parse">Parse error</a>. Emit a DOCTYPE token whose name is - the empty string and that is marked as being in error. Reconsume the - EOF character in the <a href="#data-state">data state</a>. - - <dt>Anything else - - <dd>Create a new DOCTYPE token. Set the token's name name to the current - input character, and mark it as being in error. Switch to the <a - href="#doctype1">DOCTYPE name state</a>. - </dl> - - <dt><dfn id=doctype1>DOCTYPE name state</dfn> - - <dd> - <p>First, consume the <a href="#next-input">next input character</a>:</p> - - <dl class=switch> - <dt>U+0009 CHARACTER TABULATION - - <dt>U+000A LINE FEED (LF) - - <dt>U+000B LINE TABULATION - - <dt>U+000C FORM FEED (FF)</dt> - <!--<dt>U+000D CARRIAGE RETURN (CR)</dt>--> - - <dt>U+0020 SPACE - - <dd>Switch to the <a href="#after0">after DOCTYPE name state</a>. - - <dt>U+003E GREATER-THAN SIGN (>) - - <dd>Emit the current DOCTYPE token. Switch to the <a - href="#data-state">data state</a>. - - <dt>U+0061 LATIN SMALL LETTER A through to U+007A LATIN SMALL LETTER Z - - <dd>Append the uppercase version of the current input character - (subtract 0x0020 from the character's code point) to the current - DOCTYPE token's name. Stay in the <a href="#doctype1">DOCTYPE name - state</a>. - - <dt>EOF - - <dd><a href="#parse">Parse error</a>. Emit the current DOCTYPE token. - Reconsume the EOF character in the <a href="#data-state">data - state</a>. - - <dt>Anything else - - <dd>Append the current input character to the current DOCTYPE token's - name. Stay in the <a href="#doctype1">DOCTYPE name state</a>. - </dl> - - <p>Then, if the name of the DOCTYPE token is exactly the four letters - "HTML", then mark the token as being correct. Otherwise, mark it as - being in error.</p> - - <p class=note>Because lowercase letters in the name are uppercased by the - algorithm above, the "HTML" letters are actually case-insensitive - relative to the markup.</p> - - <dt><dfn id=after0>After DOCTYPE name state</dfn> - - <dd> - <p>Consume the <a href="#next-input">next input character</a>:</p> - - <dl class=switch> - <dt>U+0009 CHARACTER TABULATION - - <dt>U+000A LINE FEED (LF) - - <dt>U+000B LINE TABULATION - - <dt>U+000C FORM FEED (FF)</dt> - <!--<dt>U+000D CARRIAGE RETURN (CR)</dt>--> - - <dt>U+0020 SPACE - - <dd>Stay in the <a href="#after0">after DOCTYPE name state</a>. - - <dt>U+003E GREATER-THAN SIGN (>) - - <dd>Emit the current DOCTYPE token. Switch to the <a - href="#data-state">data state</a>. - - <dt>EOF - - <dd><a href="#parse">Parse error</a>. Emit the current DOCTYPE token. - Reconsume the EOF character in the <a href="#data-state">data - state</a>. - - <dt>Anything else - - <dd><a href="#parse">Parse error</a>. Mark the DOCTYPE token as being in - error, if it is not already. Switch to the <a href="#bogus0">bogus - DOCTYPE state</a>. - </dl> - - <dt><dfn id=bogus0>Bogus DOCTYPE state</dfn> - - <dd> - <p>Consume the <a href="#next-input">next input character</a>:</p> - - <dl class=switch> - <dt>U+003E GREATER-THAN SIGN (>) - - <dd>Emit the current DOCTYPE token. Switch to the <a - href="#data-state">data state</a>. - - <dt>EOF - - <dd><a href="#parse">Parse error</a>. Emit the current DOCTYPE token. - Reconsume the EOF character in the <a href="#data-state">data - state</a>. - - <dt>Anything else - - <dd>Stay in the <a href="#bogus0">bogus DOCTYPE state</a>. - </dl> - </dl> - - <p>A <dfn id=permitted>permitted slash</dfn> is a U+002F SOLIDUS character - that is immediately followed by a U+003E GREATER-THAN SIGN, if, and only - if, the current token being processed is a start tag token whose tag name - is one of the following: <code><a href="#base">base</a></code>, <code><a - href="#link">link</a></code>, <code><a href="#meta0">meta</a></code>, - <code><a href="#hr">hr</a></code>, <code><a href="#br">br</a></code>, - <code><a href="#img">img</a></code>, <code><a - href="#embed">embed</a></code>, <code><a href="#param">param</a></code>, - <code><a href="#area">area</a></code>, <code><a - href="#col">col</a></code>, <code>input</code><!-- XXX add: - , <code>command</code>, <code>event-source</code> --></p> - <!-- XXX - keep this synchronised with the list of "void elements" --> - - <h5 id=tokenising><span class=secno>8.2.3.1. </span>Tokenising entities</h5> - - <p>This section defines how to <dfn id=consume>consume an entity</dfn>. - This definition is used when parsing entities <a href="#entity" - title="entity data state">in text</a> and <a href="#entity0" title="entity - in attribute value state">in attributes</a>. - - <p>The behaviour depends on the identity of the next character (the one - immediately after the U+0026 AMPERSAND character): - - <dl class=switch> - <dt>U+0023 NUMBER SIGN (#) - - <dd> - <p>Consume the U+0023 NUMBER SIGN.</p> - - <p>The behaviour further depends on the character after the U+0023 NUMBER - SIGN:</p> - - <dl class=switch> - <dt>U+0078 LATIN SMALL LETTER X - - <dt>U+0058 LATIN CAPITAL LETTER X - - <dd> - <p>Consume the X.</p> - - <p>Follow the steps below, but using the range of characters U+0030 - DIGIT ZERO through to U+0039 DIGIT NINE, U+0061 LATIN SMALL LETTER A - through to U+0066 LATIN SMALL LETTER F, and U+0041 LATIN CAPITAL - LETTER A, through to U+0046 LATIN CAPITAL LETTER F (in other words, - 0-9, A-F, a-f).</p> - - <p>When it comes to interpreting the number, interpret it as a - hexadecimal number.</p> - - <dt>Anything else - - <dd> - <p>Follow the steps below, but using the range of characters U+0030 - DIGIT ZERO through to U+0039 DIGIT NINE (i.e. just 0-9).</p> - - <p>When it comes to interpreting the number, interpret it as a decimal - number.</p> - </dl> - - <p>Consume as many characters as match the range of characters given - above.</p> - - <p>If no characters match the range, then don't consume any characters - (and unconsume the U+0023 NUMBER SIGN character and, if appropriate, the - X character). This is a <a href="#parse">parse error</a>; nothing is - returned.</p> - - <p>Otherwise, if the next character is a U+003B SEMICOLON, consume that - too. If it isn't, there is a <a href="#parse">parse error</a>.</p> - - <p>If one or more characters match the range, then take them all and - interpret the string of characters as a number (either hexadecimal or - decimal as appropriate). - - <p>If that number is in the range 128 to 159 (0x80 to 0x9F), then this is - a <a href="#parse">parse error</a>. In the following table, find the row - with that number in the first column, and return a character token for - the Unicode character given in the second column of that row.</p> - - <table> - <thead> - <tr> - <th>Number - - <th colspan=2>Unicode character - - <tbody> - <tr> - <td>0x80 - - <td>U+20AC - - <td>EURO SIGN ('€') - - <tr> - <td>0x81 - - <td>U+FFFD - - <td>REPLACEMENT CHARACTER - - <tr> - <td>0x82 - - <td>U+201A - - <td>SINGLE LOW-9 QUOTATION MARK ('‚') - - <tr> - <td>0x83 - - <td>U+0192 - - <td>LATIN SMALL LETTER F WITH HOOK ('ƒ') - - <tr> - <td>0x84 - - <td>U+201E - - <td>DOUBLE LOW-9 QUOTATION MARK ('„') - - <tr> - <td>0x85 - - <td>U+2026 - - <td>HORIZONTAL ELLIPSIS ('…') - - <tr> - <td>0x86 - - <td>U+2020 - - <td>DAGGER ('†') - - <tr> - <td>0x87 - - <td>U+2021 - - <td>DOUBLE DAGGER ('‡') - - <tr> - <td>0x88 - - <td>U+02C6 - - <td>MODIFIER LETTER CIRCUMFLEX ACCENT ('ˆ') - - <tr> - <td>0x89 - - <td>U+2030 - - <td>PER MILLE SIGN ('‰') - - <tr> - <td>0x8A - - <td>U+0160 - - <td>LATIN CAPITAL LETTER S WITH CARON ('Š') - - <tr> - <td>0x8B - - <td>U+2039 - - <td>SINGLE LEFT-POINTING ANGLE QUOTATION MARK ('‹') - - <tr> - <td>0x8C - - <td>U+0152 - - <td>LATIN CAPITAL LIGATURE OE ('Œ') - - <tr> - <td>0x8D - - <td>U+FFFD - - <td>REPLACEMENT CHARACTER - - <tr> - <td>0x8E - - <td>U+017D - - <td>LATIN CAPITAL LETTER Z WITH CARON ('Ž') - - <tr> - <td>0x8F - - <td>U+FFFD - - <td>REPLACEMENT CHARACTER - - <tr> - <td>0x90 - - <td>U+FFFD - - <td>REPLACEMENT CHARACTER - - <tr> - <td>0x91 - - <td>U+2018 - - <td>LEFT SINGLE QUOTATION MARK ('‘') - - <tr> - <td>0x92 - - <td>U+2019 - - <td>RIGHT SINGLE QUOTATION MARK ('’') - - <tr> - <td>0x93 - - <td>U+201C - - <td>LEFT DOUBLE QUOTATION MARK ('“') - - <tr> - <td>0x94 - - <td>U+201D - - <td>RIGHT DOUBLE QUOTATION MARK ('”') - - <tr> - <td>0x95 - - <td>U+2022 - - <td>BULLET ('•') - - <tr> - <td>0x96 - - <td>U+2013 - - <td>EN DASH ('–') - - <tr> - <td>0x97 - - <td>U+2014 - - <td>EM DASH ('—') - - <tr> - <td>0x98 - - <td>U+02DC - - <td>SMALL TILDE ('˜') - - <tr> - <td>0x99 - - <td>U+2122 - - <td>TRADE MARK SIGN ('™') - - <tr> - <td>0x9A - - <td>U+0161 - - <td>LATIN SMALL LETTER S WITH CARON ('š') - - <tr> - <td>0x9B - - <td>U+203A - - <td>SINGLE RIGHT-POINTING ANGLE QUOTATION MARK ('›') - - <tr> - <td>0x9C - - <td>U+0153 - - <td>LATIN SMALL LIGATURE OE ('œ') - - <tr> - <td>0x9D - - <td>U+FFFD - - <td>REPLACEMENT CHARACTER - - <tr> - <td>0x9E - - <td>U+017E - - <td>LATIN SMALL LETTER Z WITH CARON ('ž') - - <tr> - <td>0x9F - - <td>U+0178 - - <td>LATIN CAPITAL LETTER Y WITH DIAERESIS ('Ÿ') - </table> - - <p>Otherwise, if the number is not a valid Unicode character (e.g. if the - number is higher than 1114111), or if the number is zero, then return a - character token for the U+FFFD REPLACEMENT CHARACTER character instead.</p> - - <p>Otherwise, return a character token for the Unicode character whose - code point is that number. - - <dt>Anything else - - <dd> - <p>Consume the maximum number of characters possible, with the consumed - characters case-sensitively matching one of the identifiers in the first - column of the <a href="#entities0">entities</a> table.</p> - - <p>If no match can be made, then this is a <a href="#parse">parse - error</a>. No characters are consumed, and nothing is returned.</p> - - <p>Otherwise, if the next character is a U+003B SEMICOLON, consume that - too. If it isn't, there is a <a href="#parse">parse error</a>.</p> - - <p>Return a character token for the character corresponding to the entity - name (as given by the second column of the <a - href="#entities0">entities</a> table).</p> - - <div class=example> - <p>If the markup contains <code title="">I'm &notit without - you</code>, the entity is parsed as "not", as in, <code title="">I'm - ¬it without you</code>. But if the markup was <code title="">I'm - &notin without you</code>, the entity would be parsed as "notin", - resulting in <code title="">I'm ∉ without you</code>.</p> - </div> - </dl> - - <p class=big-issue>This isn't quite right. For some entities, UAs require a - semicolon, for others they don't. We probably need to do the same for - backwards compatibility. If we do that we might be able to add more - entities, e.g. for mathematics. Probably the way to mark whether or not an - entity requires a semicolon is with an additional column in the <a - href="#entities0" title=entities>entity table lower down</a>. - - <p class=big-issue>It seems browsers convert CRs to LFs even as entities. - Should we also do that? If so, we should remove the CRs in the tree - construction phase.</p> - <!-- IE is not such a browser; you - can prove that by comparing id="
X" to id="
X" in terms of - getElementById('\nX') vs '\rX'. --> - - <h4 id=tree-construction><span class=secno>8.2.4. </span><dfn - id=tree-construction0>Tree construction</dfn></h4> - - <p>The input to the tree construction stage is a sequence of tokens from - the <a href="#tokenisation0">tokenisation</a> stage. The tree construction - stage is associated with a DOM <code>Document</code> object when a parser - is created. The "output" of this stage consists of dynamically modifying - or extending that document's DOM tree. - - <p>Tree construction passes through several phases. Initially, UAs must act - according to the steps described as being those of <a - href="#the-initial0">the initial phase</a>. - - <p>This specification does not define when an interactive user agent has to - render the <code>Document</code> available to the user, or when it has to - begin accepting user input. - - <p>When the steps below require the UA to <dfn id=append>append a - character</dfn> to a node, the UA must collect it and all subsequent - consecutive characters that would be appended to that node, and insert one - <code>Text</code> node whose data is the concatenation of all those - characters. - - <p id=mutation-during-parsing>DOM mutation events must not fire for changes - caused by the UA parsing the document. (Conceptually, the parser is not - mutating the DOM, it is constructing it.) This includes the parsing of any - content inserted using <code title=dom-document-write-HTML><a - href="#document.write0">document.write()</a></code> and <code - title=dom-document-writeln><a - href="#document.writeln">document.writeln()</a></code> calls.<!-- - XXX xref --> - <a href="#refsDOM3EVENTS">[DOM3EVENTS]</a></p> - <!-- XXX - what abotu innerHTML? --> - - <p class=note>Not all of the tag names mentioned below are conformant tag - names in this specification; many are included to handle legacy content. - They still form part of the algorithm that implementations are required to - implement to claim conformance. - - <p class=note>The algorithm described below places no limit on the depth of - the DOM tree generated, or on the length of tag names, attribute names, - attribute values, text nodes, etc. While implementators are encouraged to - avoid arbitrary limits, it is recognised that <a - href="#hardwareLimitations">practical concerns</a> will likely force user - agents to impose nesting depths. - - <h5 id=the-initial><span class=secno>8.2.4.1. </span><dfn - id=the-initial0>The initial phase</dfn></h5> - - <p>Initially, the tree construction stage must handle each token emitted - from the <a href="#tokenisation0">tokenisation</a> stage as follows: - - <dl class=switch> - <dt>A DOCTYPE token that is marked as being in error - - <dt>A comment token - - <dt>A start tag token - - <dt>An end tag token - - <dt>A character token that is not one of one of U+0009 CHARACTER - TABULATION, U+000A LINE FEED (LF), U+000B LINE TABULATION, U+000C FORM - FEED (FF), U+000D CARRIAGE RETURN (CR), or U+0020 SPACE - - <dt>An end-of-file token - - <dd> - <p>This specification does not define how to handle this case. In - particular, user agents may ignore the entirety of this specification - altogether for such documents, and instead invoke special parse modes - with a greater emphasis on backwards compatibility.</p> - - <div class=note> - <p>Browsers in particular have generally used DOCTYPE-based sniffing to - invoke an "alternative conformance mode" known as <em>quirks mode</em> - on certain documents. In this mode, emphasis is put on legacy - compatibility rather than on standards compliance. This specification - takes no position on this behaviour; documents without DOCTYPEs or with - DOCTYPEs that do not conform to the syntax allowed by this - specification are considered to be out of scope of this specification.</p> - </div> - - <div class=big-issue> - <p>As far as parsing goes, the quirks I know of are:</p> - - <ul> - <li>Comment parsing is different. - - <li><code title=""></br></code> and <code title=""></p></code> do - magical things. - - <li><code><a href="#p">p</a></code> can contain <code><a - href="#table">table</a></code> - - <li>Safari and IE have special parsing rules for <% ... %> (even - in standards mode, though clearly this should be quirks-only). - </ul> - - <p>Maybe we should just adopt all those and be done with it. One parsing - mode to rule them all. Or legitimise/codify the quirks mode parsing in - some way.</p> - - <p>Would be interesting to do a search to see how many pages hit each of - the above.</p> - <!-- biased by page rank? --></div> - - <dt>A DOCTYPE token marked as being correct - - <dd> - <p>Append a <code>DocumentType</code> node to the <code>Document</code> - node, with the <code title="">name</code> attribute set to the name - given in the DOCTYPE token (which will be "HTML"), and the other - attributes specific to <code>DocumentType</code> objects set to null, - empty lists, or the empty string as appropriate.</p> - - <p>Then, switch to <a href="#the-root1">the root element phase</a> of the - tree construction stage.</p> - <!-- XXX should set doctype on the Document object, too, unless - spec is defined to already point to it if you append --> - - - <dt>A character token that <em>is</em> one of one of U+0009 CHARACTER - TABULATION, U+000A LINE FEED (LF), U+000B LINE TABULATION, U+000C FORM - FEED (FF), U+000D CARRIAGE RETURN (CR), or U+0020 SPACE - - <dd> - <p><a href="#append" title="append a character">Append that character</a> - to the <code>Document</code> node.</p> - </dl> - - <h5 id=the-root0><span class=secno>8.2.4.2. </span><dfn id=the-root1>The - root element phase</dfn></h5> - - <p>After <a href="#the-initial0">the initial phase</a>, as each token is - emitted from the <a href="#tokenisation0">tokenisation</a> stage, it must - be processed as described in this section. - - <dl class=switch> - <dt>A DOCTYPE token - - <dd> - <p><a href="#parse">Parse error</a>. Ignore the token.</p> - - <dt>A comment token - - <dd> - <p>Append a <code>Comment</code> node to the <code>Document</code> object - with the <code title="">data</code> attribute set to the data given in - the comment token.</p> - - <dt>A character token that is one of one of U+0009 CHARACTER TABULATION, - U+000A LINE FEED (LF), U+000B LINE TABULATION, U+000C FORM FEED (FF), - U+000D CARRIAGE RETURN (CR), or U+0020 SPACE - - <dd> - <p><a href="#append" title="append a character">Append that character</a> - to the <code>Document</code> node.</p> - - <dt>A character token that is <em>not</em> one of U+0009 CHARACTER - TABULATION, U+000A LINE FEED (LF), U+000B LINE TABULATION, U+000C FORM - FEED (FF), U+000D CARRIAGE RETURN (CR), or U+0020 SPACE - - <dt>A start tag token - - <dt>An end tag token - - <dt>An end-of-file token - - <dd> - <p>Create an <code><a href="#htmlelement">HTMLElement</a></code> node - with the tag name <code><a href="#html">html</a></code>, in the <a - href="#html-namespace0">HTML namespace</a>. Append it to the - <code>Document</code> object. Switch to <a href="#the-main0">the main - phase</a> and reprocess the current token.</p> - - <p class=big-issue>Should probably make end tags be ignored, so that - "</head><!-- --><html>" puts the comment befor the root node - (or should we?)</p> - </dl> - - <p>The root element can end up being removed from the <code>Document</code> - object, e.g. by scripts; nothing in particular happens in such cases, - content continues being appended to the nodes as described in the next - section. - - <h5 id=the-main><span class=secno>8.2.4.3. </span><dfn id=the-main0>The - main phase</dfn></h5> - - <p>After <a href="#the-root1">the root element phase</a>, each token - emitted from the <a href="#tokenisation0">tokenisation</a> stage must be - processed as described in <em>this</em> section. This is by far the most - involved part of parsing an HTML document. - - <p>The tree construction stage in this phase has several pieces of state: a - <a href="#stack">stack of open elements</a>, a <a href="#list-of4">list of - active formatting elements</a>, a <a href="#head-element"><code - title="">head</code> element pointer</a>, a <a href="#form-element"><code - title="">form</code> element pointer</a>, and an <a - href="#insertion0">insertion mode</a>. - - <p class=big-issue>We could just fold insertion modes and phases into one - concept (and duplicate the two rules common to all insertion modes into - all of them). - - <h6 id=the-stack><span class=secno>8.2.4.3.1. </span>The stack of open - elements</h6> - - <p>Initially the <dfn id=stack>stack of open elements</dfn> contains just - the <code><a href="#html">html</a></code> root element node created in the - <a href="#the-root1" title="the root element phase">last phase</a> before - switching to <em>this</em> phase (or, in the <a - href="#innerhtml1"><code>innerHTML</code> case</a>, the <code><a - href="#html">html</a></code> element created to represent the element - whose <code title=dom-innerHTML-HTML><a - href="#innerhtml0">innerHTML</a></code> attribute is being set). That's - the topmost node of the stack. It never gets popped off the stack. (This - stack grows downwards.) - - <p>The <dfn id=current4>current node</dfn> is the bottommost node in this - stack. - - <p>Elements in the stack fall into the following categories: - - <dl> - <dt><dfn id=special>Special</dfn> - - <dd> - <p>The following HTML elements have varying levels of special parsing - rules: <code><a href="#address">address</a></code>, <code><a - href="#area">area</a></code>, <code><a href="#base">base</a></code>, - <code>basefont</code>, <code>bgsound</code>, <code><a - href="#blockquote">blockquote</a></code>, <code><a - href="#body0">body</a></code>, <code><a href="#br">br</a></code>, - <code>center</code>, <code><a href="#col">col</a></code>, <code><a - href="#colgroup">colgroup</a></code>, <code><a href="#dd">dd</a></code>, - <code>dir</code>, <code><a href="#div">div</a></code>, <code><a - href="#dl">dl</a></code>, <code><a href="#dt">dt</a></code>, <code><a - href="#embed">embed</a></code>, <code>fieldset</code>, - <code>form</code>, <code>frame</code>, <code>frameset</code>, <code><a - href="#h1">h1</a></code>, <code><a href="#h2">h2</a></code>, <code><a - href="#h3">h3</a></code>, <code><a href="#h4">h4</a></code>, <code><a - href="#h5">h5</a></code>, <code><a href="#h6">h6</a></code>, <code><a - href="#head">head</a></code>, <code><a href="#hr">hr</a></code>, - <code><a href="#iframe">iframe</a></code>, - <code>image</code><!-- XXX ? this isn't an element that can end up - on the stack-->, - <code><a href="#img">img</a></code>, <code>input</code>, - <code>isindex</code>, <code><a href="#li">li</a></code>, <code><a - href="#link">link</a></code>, <code>listing</code>, <code><a - href="#menu">menu</a></code>, <code><a href="#meta0">meta</a></code>, - <code>noembed</code>, <code>noframes</code>, <code><a - href="#noscript">noscript</a></code>, <code><a href="#ol">ol</a></code>, - <code>optgroup</code>, <code>option</code>, <code><a - href="#p">p</a></code>, <code><a href="#param">param</a></code>, - <code>plaintext</code>, <code><a href="#pre">pre</a></code>, <code><a - href="#script0">script</a></code>, <code>select</code>, - <code>spacer</code>, <code><a href="#style">style</a></code>, <code><a - href="#tbody">tbody</a></code>, <code>textarea</code>, <code><a - href="#tfoot0">tfoot</a></code>, <code><a - href="#thead0">thead</a></code>, <code><a - href="#title1">title</a></code>, <code><a href="#tr">tr</a></code>, - <code><a href="#ul">ul</a></code>, and <code>wbr</code>. - - <dt><dfn id=scoping>Scoping</dfn> - - <dd> - <p>The following HTML elements introduce new <a href="#have-an" - title="has an element in scope">scopes</a> for various parts of the - parsing: <code>button</code>, <code><a - href="#caption0">caption</a></code>, <code><a - href="#html">html</a></code>, <code>marquee</code>, <code><a - href="#object">object</a></code>, <code><a - href="#table">table</a></code>, <code><a href="#td">td</a></code> and - <code><a href="#th">th</a></code>. - - <dt><dfn id=formatting>Formatting</dfn> - - <dd> - <p>The following HTML elements are those that end up in the <a - href="#list-of4">list of active formatting elements</a>: <code><a - href="#a">a</a></code>, <code><a href="#b">b</a></code>, - <code>big</code>, <code><a href="#em">em</a></code>, <code><a - href="#font">font</a></code>, <code><a href="#i">i</a></code>, - <code>nobr</code>, <code>s</code>, <code><a - href="#small">small</a></code>, <code>strike</code>, <code><a - href="#strong">strong</a></code>, <code>tt</code>, and <code>u</code>. - - <dt><dfn id=phrasing>Phrasing</dfn> - - <dd> - <p>All other elements found while parsing an HTML document. - </dl> - - <p class=big-issue>Still need to add these new elements to the lists: - <code><a href="#event-source">event-source</a></code>, <code><a - href="#section">section</a></code>, <code><a href="#nav">nav</a></code>, - <code><a href="#article">article</a></code>, <code><a - href="#aside">aside</a></code>, <code><a href="#header">header</a></code>, - <code><a href="#footer">footer</a></code>, <code><a - href="#datagrid0">datagrid</a></code>, <code><a - href="#command0">command</a></code> - - <p>The <a href="#stack">stack of open elements</a> is said to <dfn - id=have-an title="has an element in scope">have an element in scope</dfn> - or <dfn id=have-an0 title="has an element in table scope">have an element - in <em>table scope</em></dfn> when the following algorithm terminates in a - match state: - - <ol> - <li> - <p>Initialise <var title="">node</var> to be the <a - href="#current4">current node</a> (the bottommost node of the stack). - - <li> - <p>If <var title="">node</var> is the target node, terminate in a match - state. - - <li> - <p>Otherwise, if <var title="">node</var> is a <code><a - href="#table">table</a></code> element, terminate in a failure state. - - <li> - <p>Otherwise, if the algorithm is the "has an element in scope" variant - (rather than the "has an element in table scope" variant), and <var - title="">node</var> is one of the following, terminate in a failure - state:</p> - - <ul class=brief> - <li><code><a href="#caption0">caption</a></code> - - <li><code><a href="#td">td</a></code> - - <li><code><a href="#th">th</a></code> - - <li><code>button</code> - - <li><code>marquee</code> - - <li><code><a href="#object">object</a></code> - </ul> - - <li> - <p>Otherwise, if <var title="">node</var> is an <code><a - href="#html">html</a></code> element, terminate in a failure state. - (This can only happen if the <var title="">node</var> is the topmost - node of the <a href="#stack">stack of open elements</a>, and prevents - the next step from being invoked if there are no more elements in the - stack.) - - <li> - <p>Otherwise, set <var title="">node</var> to the previous entry in the - <a href="#stack">stack of open elements</a> and return to step 2. (This - will never fail, since the loop will always terminate in the previous - step if the top of the stack is reached.) - </ol> - - <p>Nothing happens if at any time any of the elements in the <a - href="#stack">stack of open elements</a> are moved to a new location in, - or removed from, the <code>Document</code> tree. In particular, the stack - is not changed in this situation. This can cause, amongst other strange - effects, content to be appended to nodes that are no longer in the DOM. - - <p class=note>In some cases (namely, when <a href="#adoptionAgency">closing - misnested formatting elements</a>), the stack is manipulated in a - random-access fashion. - - <h6 id=the-list><span class=secno>8.2.4.3.2. </span>The list of active - formatting elements</h6> - - <p>Initially the <dfn id=list-of4>list of active formatting elements</dfn> - is empty. It is used to handle mis-nested <a href="#formatting" - title=formatting>formatting element tags</a>. - - <p>The list contains elements in the <a href="#formatting">formatting</a> - category, and scope markers. The scope markers are inserted when entering - buttons, <code><a href="#object">object</a></code> elements, marquees, - table cells, and table captions, and are used to prevent formatting from - "leaking" into tables, buttons, <code><a href="#object">object</a></code> - elements, and marquees. - - <p>When the steps below require the UA to <dfn id=reconstruct>reconstruct - the active formatting elements</dfn>, the UA must perform the following - steps: - - <ol> - <li>If there are no entries in the <a href="#list-of4">list of active - formatting elements</a>, then there is nothing to reconstruct; stop this - algorithm. - - <li>If the last (most recently added) entry in the <a - href="#list-of4">list of active formatting elements</a> is a marker, or - if it is an element that is in the <a href="#stack">stack of open - elements</a>, then there is nothing to reconstruct; stop this algorithm. - - <li>Let <var title="">entry</var> be the last (most recently added) - element in the <a href="#list-of4">list of active formatting - elements</a>. - - <li>If there are no entries before <var title="">entry</var> in the <a - href="#list-of4">list of active formatting elements</a>, then jump to - step 8. - - <li>Let <var title="">entry</var> be the entry one earlier than <var - title="">entry</var> in the <a href="#list-of4">list of active formatting - elements</a>. - - <li>If <var title="">entry</var> is neither a marker nor an element that - is also in the <a href="#stack">stack of open elements</a>, go to step 4. - - <li>Let <var title="">entry</var> be the element one later than <var - title="">entry</var> in the <a href="#list-of4">list of active formatting - elements</a>. - - <li>Perform a shallow clone of the element <var title="">entry</var> to - obtain <var title="">clone</var>. <a href="#refsDOM3CORE">[DOM3CORE]</a> - - <li>Append <var title="">clone</var> to the <a href="#current4">current - node</a> and push it onto the <a href="#stack">stack of open elements</a> - so that it is the new <a href="#current4">current node</a>. - - <li>Replace the entry for <var title="">entry</var> in the list with an - entry for <var title="">clone</var>. - - <li>If the entry for <var title="">clone</var> in the <a - href="#list-of4">list of active formatting elements</a> is not the last - entry in the list, return to step 7. - </ol> - - <p>This has the effect of reopening all the formatting elements that were - opened in the current body, cell, or caption (whichever is youngest) that - haven't been explicitly closed. - - <p class=note>The way this specification is written, the <a - href="#list-of4">list of active formatting elements</a> always consists of - elements in chronological order with the least recently added element - first and the most recently added element last (except for while steps 8 - to 11 of the above algorithm are being executed, of course). - - <p>When the steps below require the UA to <dfn id=clear0>clear the list of - active formatting elements up to the last marker</dfn>, the UA must - perform the following steps: - - <ol> - <li>Let <var title="">entry</var> be the last (most recently added) entry - in the <a href="#list-of4">list of active formatting elements</a>. - - <li>Remove <var title="">entry</var> from the <a href="#list-of4">list of - active formatting elements</a>. - - <li>If <var title="">entry</var> was a marker, then stop the algorithm at - this point. The list has been cleared up to the last marker. - - <li>Go to step 1. - </ol> - - <h6 id=creating><span class=secno>8.2.4.3.3. </span>Creating and inserting - HTML elements</h6> - - <p>When the steps below require the UA to <dfn id=create title="create an - element for the token">create an element for a token</dfn>, the UA must - create a node implementing the interface appropriate for the element type - corresponding to the tag name of the token (as given in the section of - this specification that defines that element, e.g. for an <code><a - href="#a">a</a></code> element it would be the <code><a - href="#htmlanchorelement">HTMLAnchorElement</a></code> interface), with - the tag name being the name of that element, with the node being in the <a - href="#html-namespace0">HTML namespace</a>, and with the attributes on the - node being those given in the given token. - - <p>When the steps below require the UA to <dfn id=insert>insert an HTML - element</dfn> for a token, the UA must first <a href="#create">create an - element for the token</a>, and then append this node to the <a - href="#current4">current node</a>, and push it onto the <a - href="#stack">stack of open elements</a> so that it is the new <a - href="#current4">current node</a>. - - <p>The steps below may also require that the UA insert an HTML element in a - particular place, in which case the UA must <a href="#create">create an - element for the token</a> and then insert or append the new node in the - location specified. (This happens in particular during the parsing of - tables with invalid content.) - - <p>The interface appropriate for an element that is not defined in this - specification is <code><a href="#htmlelement">HTMLElement</a></code>. - - <h6 id=closing><span class=secno>8.2.4.3.4. </span>Closing elements that - have implied end tags</h6> - - <p>When the steps below require the UA to <dfn id=generate>generate implied - end tags</dfn>, then, if the <a href="#current4">current node</a> is a - <code><a href="#dd">dd</a></code> element, a <code><a - href="#dt">dt</a></code> element, an <code><a href="#li">li</a></code> - element, a <code><a href="#p">p</a></code> element, a <code><a - href="#td">td</a></code> element, a <code><a href="#th">th</a></code> - element, or a <code><a href="#tr">tr</a></code> element, the UA must act - as if an end tag with the respective tag name had been seen and then <a - href="#generate">generate implied end tags</a> again. - - <p>The step that requires the UA to generate implied end tags but lists an - element to exclude from the process, then the UA must perform the above - steps as if that element was not in the above list. - - <h6 id=the-element><span class=secno>8.2.4.3.5. </span>The element pointers</h6> - - <p>Initially the <dfn id=head-element><code title="">head</code> element - pointer</dfn> and the <dfn id=form-element><code title="">form</code> - element pointer</dfn> are both null. - - <p>Once a <code><a href="#head">head</a></code> element has been parsed - (whether implicitly or explicitly) the <a href="#head-element"><code - title="">head</code> element pointer</a> gets set to point to this node. - - <p>The <a href="#form-element"><code title="">form</code> element - pointer</a> points to the last <code>form</code> element that was opened - and whose end tag has not yet been seen. It is used to make form controls - associate with forms in the face of dramatically bad markup, for - historical reasons. - - <h6 id=the-insertion><span class=secno>8.2.4.3.6. </span>The insertion mode</h6> - - <p>Initially the <dfn id=insertion0>insertion mode</dfn> is "<a - href="#before2" title="insertion mode: before head">before head</a>". It - can change to "<a href="#in-head" title="insertion mode: in head">in - head</a>", "<a href="#after1" title="insertion mode: after head">after - head</a>", "<a href="#in-body" title="insertion mode: in body">in - body</a>", "<a href="#in-table" title="insertion mode: in table">in - table</a>", "<a href="#in-caption" title="insertion mode: in caption">in - caption</a>", "<a href="#in-column" title="insertion mode: in column - group">in column group</a>", "<a href="#in-table0" title="insertion mode: - in table body">in table body</a>", "<a href="#in-row" title="insertion - mode: in row">in row</a>", "<a href="#in-cell" title="insertion mode: in - cell">in cell</a>", "<a href="#in-select" title="insertion mode: in - select">in select</a>", "<a href="#after2" title="insertion mode: after - body">after body</a>", "<a href="#in-frameset" title="insertion mode: in - frameset">in frameset</a>", and "<a href="#after3" title="insertion mode: - after frameset">after frameset</a>" during the course of the parsing, as - described below. It affects how certain tokens are processed. - - <p>If the tree construction stage is switched from <a href="#the-main0">the - main phase</a> to <a href="#the-trailing0">the trailing end phase</a> and - back again, the various pieces of state are not reset; the UA must act as - if the state was maintained. - - <p>When the steps below require the UA to <dfn id=reset>reset the insertion - mode appropriately</dfn>, it means the UA must follow these steps: - - <ol> - <li>Let <var title="">last</var> be false. - - <li>Let <var title="">node</var> be the last node in the <a - href="#stack">stack of open elements</a>. - - <li>If <var title="">node</var> is the first node in the stack of open - elements, then set <var title="">last</var> to true. If the element whose - <code title=dom-innerHTML-HTML><a href="#innerhtml0">innerHTML</a></code> - attribute is being set is neither a <code><a href="#td">td</a></code> - element nor a <code><a href="#th">th</a></code> element, then set <var - title="">node</var> to the element whose <code - title=dom-innerHTML-HTML><a href="#innerhtml0">innerHTML</a></code> - attribute is being set. (<a href="#innerhtml1"><code>innerHTML</code> - case</a>) - - <li>If <var title="">node</var> is a <code>select</code> element, then - switch the <a href="#insertion0">insertion mode</a> to "<a - href="#in-select" title="insertion mode: in select">in select</a>" and - abort these steps. (<a href="#innerhtml1"><code>innerHTML</code> - case</a>) - - <li>If <var title="">node</var> is a <code><a href="#td">td</a></code> or - <code><a href="#th">th</a></code> element, then switch the <a - href="#insertion0">insertion mode</a> to "<a href="#in-cell" - title="insertion mode: in cell">in cell</a>" and abort these steps. - - <li>If <var title="">node</var> is a <code><a href="#tr">tr</a></code> - element, then switch the <a href="#insertion0">insertion mode</a> to "<a - href="#in-row" title="insertion mode: in row">in row</a>" and abort these - steps. - - <li>If <var title="">node</var> is a <code><a - href="#tbody">tbody</a></code>, <code><a href="#thead0">thead</a></code>, - or <code><a href="#tfoot0">tfoot</a></code> element, then switch the <a - href="#insertion0">insertion mode</a> to "<a href="#in-table0" - title="insertion mode: in table body">in table body</a>" and abort these - steps. - - <li>If <var title="">node</var> is a <code><a - href="#caption0">caption</a></code> element, then switch the <a - href="#insertion0">insertion mode</a> to "<a href="#in-caption" - title="insertion mode: in caption">in caption</a>" and abort these steps. - - <li>If <var title="">node</var> is a <code><a - href="#colgroup">colgroup</a></code> element, then switch the <a - href="#insertion0">insertion mode</a> to "<a href="#in-column" - title="insertion mode: in column group">in column group</a>" and abort - these steps. (<a href="#innerhtml1"><code>innerHTML</code> case</a>) - - <li>If <var title="">node</var> is a <code><a - href="#table">table</a></code> element, then switch the <a - href="#insertion0">insertion mode</a> to "<a href="#in-table" - title="insertion mode: in table">in table</a>" and abort these steps. - - <li>If <var title="">node</var> is a <code><a href="#head">head</a></code> - element, then switch the <a href="#insertion0">insertion mode</a> to "<a - href="#in-body" title="insertion mode: in body">in body</a>" ("<a - href="#in-body" title="insertion mode: in body">in body</a>"! <em> not - "<a href="#in-head" title="insertion mode: in head">in head</a>"</em>!) - and abort these steps. (<a href="#innerhtml1"><code>innerHTML</code> - case</a>) - - <li>If <var title="">node</var> is a <code><a - href="#body0">body</a></code> element, then switch the <a - href="#insertion0">insertion mode</a> to "<a href="#in-body" - title="insertion mode: in body">in body</a>" and abort these steps. - - <li>If <var title="">node</var> is a <code>frameset</code> element, then - switch the <a href="#insertion0">insertion mode</a> to "<a - href="#in-frameset" title="insertion mode: in frameset">in frameset</a>" - and abort these steps. (<a href="#innerhtml1"><code>innerHTML</code> - case</a>) - - <li>If <var title="">node</var> is an <code><a - href="#html">html</a></code> element, then: if the <a - href="#head-element"><code title="">head</code> element pointer</a> is - null, switch the <a href="#insertion0">insertion mode</a> to "<a - href="#before2" title="insertion mode: before head">before head</a>", - otherwise, switch the <a href="#insertion0">insertion mode</a> to "<a - href="#after1" title="insertion mode: after head">after head</a>". In - either case, abort these steps. (<a - href="#innerhtml1"><code>innerHTML</code> case</a>)</li> - <!-- XXX can the head element pointer ever be - non-null when we're going through these steps? --> - - <li>If <var title="">last</var> is true, then set the <a - href="#insertion0">insertion mode</a> to "<a href="#in-body" - title="insertion mode: in body">in body</a>" and abort these steps. (<a - href="#innerhtml1"><code>innerHTML</code> case</a>) - - <li>Let <var title="">node</var> now be the node before <var - title="">node</var> in the <a href="#stack">stack of open elements</a>. - - <li>Return to step 3. - </ol> - <!--When you don't have to handle innerHTML, you can use this -simplified explanation instead: - - <ol> - - <li><p>If the <span>stack of open elements</span> <span title="has - an element in table scope">has a <code>td</code> or <code>th</code> - element in table scope</span>, then switch the <span>insertion - mode</span> to "<span title="insertion mode: in cell">in - cell</span>".</p></li> - - <li><p>Otherwise, if the <span>stack of open elements</span> <span - title="has an element in table scope">has a <code>tr</code> element - in table scope</span>, then switch the <span>insertion mode</span> - to "<span title="insertion mode: in row">in row</span>".</p></li> - - <li><p>Otherwise, if the <span>stack of open elements</span> <span - title="has an element in table scope">has a <code>tbody</code>, - <code>tfoot</code>, or <code>thead</code> element in table - scope</span>, then switch the <span>insertion mode</span> to "<span - title="insertion mode: in table body">in table - body</span>".</p></li> - - <li><p>Otherwise, if the <span>stack of open elements</span> <span - title="has an element in table scope">has a <code>caption</code> - element in table scope</span>, then switch the <span>insertion - mode</span> to "<span title="insertion mode: in caption">in - caption</span>".</p></li> - - ( you can't reach this point with a colgroup element on the - stack ) - - <li><p>Otherwise, if the <span>stack of open elements</span> <span - title="has an element in table scope">has a <code>table</code> - element in table scope</span>, then switch the <span>insertion - mode</span> to "<span title="insertion mode: in table">in - table</span>".</p></li> - - <li><p>Otherwise, switch the <span>insertion mode</span> to "<span - title="insertion mode: in body">in body</span>".</p></li> - - </ol> ---> - - <h6 id=how-to0><span class=secno>8.2.4.3.7. </span>How to handle tokens in - the main phase</h6> - - <p>Tokens in the main phase must be handled as follows: - - <dl class=switch> - <dt>A DOCTYPE token - - <dd> - <p><a href="#parse">Parse error</a>. Ignore the token.</p> - - <dt>A start tag token with the tag name "html" - - <dd> - <p>If this start tag token was not the first start tag token, then it is - a <a href="#parse">parse error</a>.</p> - - <p>For each attribute on the token, check to see if the attribute is - already present on the top element of the <a href="#stack">stack of open - elements</a>. If it is not, add the attribute and its corresponding - value to that element.</p> - - <dt>An end-of-file token - - <dd> - <p><a href="#generate">Generate implied end tags.</a></p> - - <p>If there are more than two nodes on the <a href="#stack">stack of open - elements</a>, or if there are two nodes but the second node is not a - <code><a href="#body0">body</a></code> node, this is a <a - href="#parse">parse error</a>.</p> - - <p>Otherwise, if the parser was originally created in order to handle the - setting of an element's <code title=dom-innerHTML-HTML><a - href="#innerhtml0">innerHTML</a></code> attribute, and there's more than - one element in the <a href="#stack">stack of open elements</a>, and the - second node on the <a href="#stack">stack of open elements</a> is not a - <code><a href="#body0">body</a></code> node, then this is a <a - href="#parse">parse error</a>. (<a - href="#innerhtml1"><code>innerHTML</code> case</a>)</p> - - <p><a href="#stops">Stop parsing.</a></p> - - <p class=big-issue>This fails because it doesn't imply HEAD and BODY - tags. We should probably expand out the insertion modes and merge them - with phases and then put the three things here into each insertion mode - instead of trying to factor them out so carefully.</p> - - <dt>Anything else - - <dd> - <p>Depends on the <a href="#insertion0">insertion mode</a>:</p> - - <dl class=switch> - <dt>If the <a href="#insertion0">insertion mode</a> is "<dfn id=before2 - title="insertion mode: before head">before head</dfn>" - - <dd> - <p>Handle the token as follows:</p> - - <dl class=switch> - <dt>A character token that is one of one of U+0009 CHARACTER - TABULATION, U+000A LINE FEED (LF), U+000B LINE TABULATION, U+000C - FORM FEED (FF), U+000D CARRIAGE RETURN (CR), or U+0020 SPACE - - <dd> - <p><a href="#append" title="append a character">Append the - character</a> to the <a href="#current4">current node</a>.</p> - - <dt>A comment token - - <dd> - <p>Append a <code>Comment</code> node to the <a - href="#current4">current node</a> with the <code - title="">data</code> attribute set to the data given in the comment - token.</p> - - <dt>A start tag token with the tag name "head" - - <dd> - <p><a href="#create">Create an element for the token</a>.</p> - - <p>Set the <a href="#head-element"><code title="">head</code> element - pointer</a> to this new element node.</p> - - <p>Append the new element to the <a href="#current4">current node</a> - and push it onto the <a href="#stack">stack of open elements</a>.</p> - - <p>Change the <a href="#insertion0">insertion mode</a> to "<a - href="#in-head" title="insertion mode: in head">in head</a>".</p> - - <dt>A start tag token whose tag name is one of: "base", "link", - "meta", "script", "style", "title" - - <dd> - <p>Act as if a start tag token with the tag name "head" and no - attributes had been seen, then reprocess the current token.</p> - - <p class=note>This will result in a <code><a - href="#head">head</a></code> element being generated, and with the - current token being reprocessed in the "<a href="#in-head" - title="insertion mode: in head">in head</a>" <a - href="#insertion0">insertion mode</a>.</p> - - <dt>An end tag with the tag name "html" - - <dd> - <p>Act as if a start tag token with the tag name "head" and no - attributes had been seen, then reprocess the current token.</p> - - <dt>Any other end tag - - <dd> - <p><a href="#parse">Parse error</a>. Ignore the token.</p> - - <dt>A character token that is <em>not</em> one of U+0009 CHARACTER - TABULATION, U+000A LINE FEED (LF), U+000B LINE TABULATION, U+000C - FORM FEED (FF), U+000D CARRIAGE RETURN (CR), or U+0020 SPACE - - <dt>Any other start tag token - - <dd> - <p>Act as if a start tag token with the tag name "head" and no - attributes had been seen, then reprocess the current token.</p> - - <p class=note>This will result in an empty <code><a - href="#head">head</a></code> element being generated, with the - current token being reprocessed in the "<a href="#after1" - title="insertion mode: after head">after head</a>" <a - href="#insertion0">insertion mode</a>.</p> - </dl> - - <dt id=parsing-main-inhead>If the <a href="#insertion0">insertion - mode</a> is "<dfn id=in-head title="insertion mode: in head">in - head</dfn>" - - <dd> - <p>Handle the token as follows.</p> - - <p class=note>The rules for handling "title", "style", and "script" - start tags are similar, but not identical.</p> - - <p class=note>It is possible for the <a href="#tree-construction0">tree - construction</a> stage's <a href="#the-main0" title="the main - phase">main phase</a> to be in the "<a href="#in-head" - title="insertion mode: in head">in head</a>" <a - href="#insertion0">insertion mode</a> without the <a - href="#current4">current node</a> being a <code><a - href="#head">head</a></code> element, e.g. if a <code><a - href="#head">head</a></code> end tag is immediately followed by a - <code><a href="#meta0">meta</a></code> start tag.</p> - - <dl class=switch> - <dt>A character token that is one of one of U+0009 CHARACTER - TABULATION, U+000A LINE FEED (LF), U+000B LINE TABULATION, U+000C - FORM FEED (FF), U+000D CARRIAGE RETURN (CR), or U+0020 SPACE - - <dd> - <p><a href="#append" title="append a character">Append the - character</a> to the <a href="#current4">current node</a>.</p> - - <dt>A comment token - - <dd> - <p>Append a <code>Comment</code> node to the <a - href="#current4">current node</a> with the <code - title="">data</code> attribute set to the data given in the comment - token.</p> - - <dt>A start tag with the tag name "title" - - <dd> - <p><a href="#create">Create an element for the token</a>.</p> - - <p>Append the new element to the node pointed to by the <a - href="#head-element"><code title="">head</code> element pointer</a>, - or, if that is null (<a href="#innerhtml1"><code>innerHTML</code> - case</a>), to the <a href="#current4">current node</a>.</p> - - <p>Switch the tokeniser's <a href="#content2">content model flag</a> - to the RCDATA state.</p> - - <p>Then, collect all the character tokens that the tokeniser returns - until it returns a token that is not a character token.</p> - - <p>If this process resulted in a collection of character tokens, - append a single <code>Text</code> node to the <code><a - href="#title1">title</a></code> element node whose contents is the - concatenation of all those tokens' characters.</p> - - <p>The tokeniser's <a href="#content2">content model flag</a> will - have switched back to the PCDATA state.</p> - - <p>If the next token is an end tag token with the tag name "title", - ignore it. Otherwise, this is a <a href="#parse">parse error</a>.</p> - - <dt>A start tag with the tag name "style" - - <dd> - <p><a href="#create">Create an element for the token</a>.</p> - - <p>Append the new element to the <a href="#current4">current - node</a>, unless the <a href="#insertion0">insertion mode</a> is "<a - href="#in-head" title="insertion mode: in head">in head</a>" and the - <a href="#head-element"><code title="">head</code> element - pointer</a> is not null, in which case append it to the node pointed - to by the <a href="#head-element"><code title="">head</code> element - pointer</a>. <!-- - <head></head><style><body> should put the style block in the - head, and does so by switching back to in head, but the head - isn't the current node at that point (comments should go - between the head and the body) -->.</p> - - <p>Switch the tokeniser's <a href="#content2">content model flag</a> - to the CDATA state.</p> - - <p>Then, collect all the character tokens that the tokeniser returns - until it returns a token that is not a character token, or until it - stops tokenising.</p> - - <p>If this process resulted in a collection of character tokens, - append a single <code>Text</code> node to the <code><a - href="#style">style</a></code> element node whose contents is the - concatenation of all those tokens' characters.</p> - - <p>The tokeniser's <a href="#content2">content model flag</a> will - have switched back to the PCDATA state.</p> - - <p>If the next token is an end tag token with the tag name "style", - ignore it. Otherwise, this is a <a href="#parse">parse error</a>.</p> - - <dt id=scriptTag>A start tag with the tag name "script" - - <dd> - <p><a href="#create">Create an element for the token</a>.</p> - - <p>Mark the element as being <a - href="#parser-inserted">"parser-inserted"</a>. This ensures that, if - the script is external, any <code title=dom-document-write-HTML><a - href="#document.write0">document.write()</a></code> calls in the - script will execute in-line, instead of blowing the document away, - as would happen in most other cases.</p> - - <p>Switch the tokeniser's <a href="#content2">content model flag</a> - to the CDATA state.</p> - - <p>Then, collect all the character tokens that the tokeniser returns - until it returns a token that is not a character token, or until it - stops tokenising.</p> - - <p>If this process resulted in a collection of character tokens, - append a single <code>Text</code> node to the <code><a - href="#script0">script</a></code> element node whose contents is the - concatenation of all those tokens' characters.</p> - - <p>The tokeniser's <a href="#content2">content model flag</a> will - have switched back to the PCDATA state.</p> - - <p>If the next token is not an end tag token with the tag name - "script", then this is a <a href="#parse">parse error</a>; mark the - <code><a href="#script0">script</a></code> element as <a - href="#already">"already executed"</a>. Otherwise, the token is the - <code><a href="#script0">script</a></code> element's end tag, so - ignore it.</p> - - <p>If the parser was originally created in order to handle the - setting of a node's <code title=dom-innerHTML-HTML><a - href="#innerhtml0">innerHTML</a></code> attribute, then mark the - <code><a href="#script0">script</a></code> element as <a - href="#already">"already executed"</a>, and skip the rest of the - processing described for this token (including the part below where - "<a href="#the-script" title="the script that will execute as soon - as the parser resumes">scripts that will execute as soon as the - parser resumes</a>" are executed). (<a - href="#innerhtml1"><code>innerHTML</code> case</a>)</p> - - <p class=note>Marking the <code><a href="#script0">script</a></code> - element as "already executed" prevents it from executing when it is - inserted into the document a few paragraphs below. Scripts missing - their end tags and scripts that were inserted using <code - title=dom-innerHTML-HTML><a href="#innerhtml0">innerHTML</a></code> - aren't executed.</p> - - <p>Let the <var title="">old insertion point</var> have the same - value as the current <a href="#insertion">insertion point</a>. Let - the <a href="#insertion">insertion point</a> be just before the <a - href="#next-input">next input character</a>.</p> - - <p>Append the new element to the <a href="#current4">current - node</a>, unless the <a href="#insertion0">insertion mode</a> is "<a - href="#in-head" title="insertion mode: in head">in head</a>" and the - <a href="#head-element"><code title="">head</code> element - pointer</a> is not null, in which case append it to the node pointed - to by the <a href="#head-element"><code title="">head</code> element - pointer</a>. <!-- - <head></head><script><body> should put the script in the head, - and does so by switching back to in head, but the head isn't - the current node at that point (comments should go between the - head and the body) --> - <a href="#running0" title="running a script">Special processing - occurs when a <code>script</code> element is inserted into a - document</a> that might cause some script to execute, which might - cause <a href="#document.write0" title=dom-document-write-HTML>new - characters to be inserted into the tokeniser</a>.</p> - - <p>Let the <a href="#insertion">insertion point</a> have the value of - the <var title="">old insertion point</var>. (In other words, - restore the <a href="#insertion">insertion point</a> to the value it - had before the previous paragraph. This value might be the - "undefined" value.)</p> - - <p id=scriptTagParserResumes>At this stage, if there is <a - href="#the-script" title="the script that will execute as soon as - the parser resumes">a script that will execute as soon as the parser - resumes</a>, then:</p> - - <dl class=switch> - <dt>If the tree construction stage is <a href="#nestedParsing">being - called reentrantly</a>, say from a call to <code - title=dom-document-write-HTML><a - href="#document.write0">document.write()</a></code>: - - <dd> - <p>Abort the processing of any nested invokations of the tokeniser, - yielding control back to the caller. (Tokenisation will resume - when the caller returns to the "outer" tree construction stage.) - - <dt>Otherwise: - - <dd> - <p>Follow these steps:</p> - - <ol> - <li> - <p>Let <var title="">the script</var> be <a - href="#the-script">the script that will execute as soon as the - parser resumes</a>. There is no longer <a href="#the-script" - title="the script that will execute as soon as the parser - resumes">a script that will execute as soon as the parser - resumes</a>. - - <li> - <p><a href="#pause">Pause</a> until the script has - <span>completed loading</span><!-- XXX xref -->. - - <li> - <p>Let the <a href="#insertion">insertion point</a> be just - before the <a href="#next-input">next input character</a>. - - <li> - <p><a href="#executing0" title="executing a script block">Execute - the script</a>. - - <li> - <p>Let the <a href="#insertion">insertion point</a> be undefined - again. - - <li> - <p>If there is once again <a href="#the-script" title="the script - that will execute as soon as the parser resumes">a script that - will execute as soon as the parser resumes</a>, then repeat - these steps from step 1. - </ol> - </dl> - - <dt>A start tag with the tag name "base", "link", or "meta" - - <dd> - <p><a href="#create">Create an element for the token</a>.</p> - - <p>Append the new element to the node pointed to by the <a - href="#head-element"><code title="">head</code> element pointer</a>, - or, if that is null (<a href="#innerhtml1"><code>innerHTML</code> - case</a>), to the <a href="#current4">current node</a>.</p> - - <dt>An end tag with the tag name "head" - - <dd> - <p>If the <a href="#current4">current node</a> is a <code><a - href="#head">head</a></code> element, pop the <a - href="#current4">current node</a> off the <a href="#stack">stack of - open elements</a>. Otherwise, this is a <a href="#parse">parse - error</a>.</p> - <!-- might happen if you see two </head>s - and something in between the two sends you from "after head" - back to "in head" --> - - <p>Change the <a href="#insertion0">insertion mode</a> to "<a - href="#after1" title="insertion mode: after head">after head</a>".</p> - - <dt>An end tag with the tag name "html" - - <dd> - <p>Act as described in the "anything else" entry below.</p> - - <dt>A start tag with the tag name "head" - - <dt>Any other end tag - - <dd> - <p><a href="#parse">Parse error</a>. Ignore the token.</p> - - <dt>Anything else - - <dd> - <p>If the <a href="#current4">current node</a> is a <code><a - href="#head">head</a></code> element, act as if an end tag token - with the tag name "head" had been seen.</p> - - <p>Otherwise, change the <a href="#insertion0">insertion mode</a> to - "<a href="#after1" title="insertion mode: after head">after - head</a>".</p> - - <p>Then, reprocess the current token.</p> - - <p class=big-issue>In certain UAs, <a - href="https://bugzilla.mozilla.org/attachment.cgi?id=180157&action=view">some - elements</a> don't trigger the "in body" mode straight away, but - instead get put into the head. Do we want to copy that?</p> - </dl> - - <dt>If the <a href="#insertion0">insertion mode</a> is "<dfn id=after1 - title="insertion mode: after head">after head</dfn>" - - <dd> - <p>Handle the token as follows:</p> - - <dl class=switch> - <dt>A character token that is one of one of U+0009 CHARACTER - TABULATION, U+000A LINE FEED (LF), U+000B LINE TABULATION, U+000C - FORM FEED (FF), U+000D CARRIAGE RETURN (CR), or U+0020 SPACE - - <dd> - <p><a href="#append" title="append a character">Append the - character</a> to the <a href="#current4">current node</a>.</p> - - <dt>A comment token - - <dd> - <p>Append a <code>Comment</code> node to the <a - href="#current4">current node</a> with the <code - title="">data</code> attribute set to the data given in the comment - token.</p> - - <dt>A start tag token with the tag name "body" - - <dd> - <p><a href="#insert" title="insert an HTML element">Insert a - <code>body</code> element</a> for the token.</p> - - <p>Change the <a href="#insertion0">insertion mode</a> to "<a - href="#in-body" title="insertion mode: in body">in body</a>".</p> - - <dt>A start tag token with the tag name "frameset" - - <dd> - <p><a href="#insert" title="insert an HTML element">Insert a - <code>frameset</code> element</a> for the token.</p> - - <p>Change the <a href="#insertion0">insertion mode</a> to "<a - href="#in-frameset" title="insertion mode: in frameset">in - frameset</a>".</p> - - <dt>A start tag token whose tag name is one of: "base", "link", - "meta", "script", "style", "title" - - <dd> - <p><a href="#parse">Parse error</a>. Switch the <a - href="#insertion0">insertion mode</a> back to "<a href="#in-head" - title="insertion mode: in head">in head</a>" and reprocess the - token.</p> - - <dt>Anything else - - <dd> - <p>Act as if a start tag token with the tag name "body" and no - attributes had been seen, and then reprocess the current token.</p> - </dl> - - <dt id=parsing-main-inbody>If the <a href="#insertion0">insertion - mode</a> is "<dfn id=in-body title="insertion mode: in body">in - body</dfn>" - - <dd> - <p>Handle the token as follows:</p> - - <dl class=switch> - <dt>A character token - - <dd> - <p><a href="#reconstruct">Reconstruct the active formatting - elements</a>, if any.</p> - - <p><a href="#append" title="append a character">Append the token's - character</a> to the <a href="#current4">current node</a>.</p> - - <dt>A comment token - - <dd> - <p>Append a <code>Comment</code> node to the <a - href="#current4">current node</a> with the <code - title="">data</code> attribute set to the data given in the comment - token.</p> - - <dt>A start tag token whose tag name is one of: "script", "style" - - <dd> - <p>Process the token as if the <a href="#insertion0">insertion - mode</a> had been "<a href="#in-head" title="insertion mode: in - head">in head</a>".</p> - - <dt>A start tag token whose tag name is one of: "base", "link", - "meta", "title" - - <dd> - <p><a href="#parse">Parse error</a>. Process the token as if the <a - href="#insertion0">insertion mode</a> had been "<a href="#in-head" - title="insertion mode: in head">in head</a>".</p> - - <dt>A start tag token with the tag name "body" - - <dd> - <p><a href="#parse">Parse error</a>.</p> - - <p>If the second element on the <a href="#stack">stack of open - elements</a> is not a <code><a href="#body0">body</a></code> - element, or, if the <a href="#stack">stack of open elements</a> has - only one node on it, then ignore the token. (<a - href="#innerhtml1"><code>innerHTML</code> case</a>)</p> - - <p>Otherwise, for each attribute on the token, check to see if the - attribute is already present on the <code><a - href="#body0">body</a></code> element (the second element) on the <a - href="#stack">stack of open elements</a>. If it is not, add the - attribute and its corresponding value to that element.</p> - - <dt>An end tag with the tag name "body" - - <dd> - <p>If the second element in the <a href="#stack">stack of open - elements</a> is not a <code><a href="#body0">body</a></code> - element, this is a <a href="#parse">parse error</a>. Ignore the - token. (<a href="#innerhtml1"><code>innerHTML</code> case</a>)</p> - - <p>Otherwise:</p> - - <p class=big-issue>this needs to handle closing of implied elements, - but without closing them</p> - - <p>If the <a href="#current4">current node</a> is not the <code><a - href="#body0">body</a></code> element, then this is a <a - href="#parse">parse error</a>.</p> - - <p>Change the <a href="#insertion0">insertion mode</a> to "<a - href="#after2" title="insertion mode: after body">after body</a>".</p> - - <dt>An end tag with the tag name "html" - - <dd> - <p>Act as if an end tag with tag name "body" had been seen, then, if - that token wasn't ignored, reprocess the current token.</p> - - <p class=note>The fake end tag token here can only be ignored in the - <a href="#innerhtml1"><code>innerHTML</code> case</a>.</p> - - <dt>A start tag whose tag name is one of: "address", "blockquote", - "center", "dir", "div", "dl", "fieldset", "listing", "menu", "ol", - "p", "ul" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> <a - href="#have-an" title="has an element in scope">has a <code>p</code> - element in scope</a>, then act as if an end tag with the tag name - <code><a href="#p">p</a></code> had been seen.</p> - - <p><a href="#insert" title="insert an html element">Insert an HTML - element</a> for the token.</p> - - <dt>A start tag whose tag name is "pre" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> <a - href="#have-an" title="has an element in scope">has a <code>p</code> - element in scope</a>, then act as if an end tag with the tag name - <code><a href="#p">p</a></code> had been seen.</p> - - <p><a href="#insert" title="insert an html element">Insert an HTML - element</a> for the token.</p> - - <p>If the next token is a U+000A LINE FEED (LF) character token, then - ignore that token and move on to the next one. (Newlines at the - start of <code><a href="#pre">pre</a></code> blocks are ignored as - an authoring convenience.)</p> - - <dt>A start tag whose tag name is "form" - - <dd> - <p>If the <a href="#form-element"><code title=form>form</code> - element pointer</a> is not null, ignore the token with a <a - href="#parse">parse error</a>.</p> - - <p>Otherwise:</p> - - <p>If the <a href="#stack">stack of open elements</a> <a - href="#have-an" title="has an element in scope">has a <code>p</code> - element in scope</a>, then act as if an end tag with the tag name - <code><a href="#p">p</a></code> had been seen.</p> - - <p><a href="#insert" title="insert an html Element">Insert an HTML - element</a> for the token, and set the <code title=form>form</code> - element pointer to point to the element created.</p> - - <dt>A start tag whose tag name is "li" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> <a - href="#have-an" title="has an element in scope">has a <code>p</code> - element in scope</a>, then act as if an end tag with the tag name - <code><a href="#p">p</a></code> had been seen.</p> - - <p>Run the following algorithm:</p> - - <ol> - <li> - <p>Initialise <var title="">node</var> to be the <a - href="#current4">current node</a> (the bottommost node of the - stack). - - <li> - <p>If <var title="">node</var> is an <code><a - href="#li">li</a></code> element, then pop all the nodes from the - <a href="#current4">current node</a> up to <var - title="">node</var>, including <var title="">node</var>, then stop - this algorithm. If more than one node is popped, then this is a <a - href="#parse">parse error</a>. - - <li> - <p>If <var title="">node</var> is not in the <a - href="#formatting">formatting</a> category, and is not in the <a - href="#phrasing">phrasing</a> category, and is not an <code><a - href="#address">address</a></code> or <code><a - href="#div">div</a></code> element, then stop this algorithm. - </li> - <!-- an element <foo> is in this - list if the following markup: - - <!DOCTYPE html><body><ol><li><foo><li> - - ...results in the second <li> not being (in any way) a - descendant of the first <li>, or if <foo> is a formatting - element that gets reopened later. --> - - <li> - <p>Otherwise, set <var title="">node</var> to the previous entry in - the <a href="#stack">stack of open elements</a> and return to step - 2. - </ol> - - <p>Finally, <a href="#insert" title="insert an html element">insert - an <code>li</code> element</a>.</p> - - <dt>A start tag whose tag name is "dd" or "dt" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> <a - href="#have-an" title="has an element in scope">has a <code>p</code> - element in scope</a>, then act as if an end tag with the tag name - <code><a href="#p">p</a></code> had been seen.</p> - - <p>Run the following algorithm:</p> - - <ol> - <li> - <p>Initialise <var title="">node</var> to be the <a - href="#current4">current node</a> (the bottommost node of the - stack). - - <li> - <p>If <var title="">node</var> is a <code><a - href="#dd">dd</a></code> or <code><a href="#dt">dt</a></code> - element, then pop all the nodes from the <a - href="#current4">current node</a> up to <var title="">node</var>, - including <var title="">node</var>, then stop this algorithm. If - more than one node is popped, then this is a <a - href="#parse">parse error</a>. - - <li> - <p>If <var title="">node</var> is not in the <a - href="#formatting">formatting</a> category, and is not in the <a - href="#phrasing">phrasing</a> category, and is not an <code><a - href="#address">address</a></code> or <code><a - href="#div">div</a></code> element, then stop this algorithm. - </li> - <!-- an element <foo> is in this - list if the following markup: - - <!DOCTYPE html><body><ol><dt><foo><dt> - - ...results in the second <li> not being (in any way) a - descendant of the first <li>, or if <foo> is a formatting - element that gets reopened later. --> - - <li> - <p>Otherwise, set <var title="">node</var> to the previous entry in - the <a href="#stack">stack of open elements</a> and return to step - 2. - </ol> - - <p>Finally, <a href="#insert" title="insert an html element">insert - an HTML element</a> with the same tag name as the token's.</p> - - <dt>A start tag token whose tag name is "plaintext" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> <a - href="#have-an" title="has an element in scope">has a <code>p</code> - element in scope</a>, then act as if an end tag with the tag name - <code><a href="#p">p</a></code> had been seen.</p> - - <p><a href="#insert" title="insert an html element">Insert an HTML - element</a> for the token.</p> - - <p>Switch the <a href="#content2">content model flag</a> to the - PLAINTEXT state.</p> - - <p class=note>Once a start tag with the tag name "plaintext" has been - seen, that will be the last token ever seen other than character - tokens (and the end-of-file token), because there is no way to - switch the <a href="#content2">content model flag</a> out of the - PLAINTEXT state.</p> - - <dt>An end tag whose tag name is one of: "address", "blockquote", - "center", "dir", "div", "dl", "fieldset", "listing", "menu", "ol", - "pre", "ul" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> <a - href="#have-an">has an element in scope</a> with the same tag name - as that of the token, then <a href="#generate">generate implied end - tags</a>.</p> - - <p>Now, if the <a href="#current4">current node</a> is not an element - with the same tag name as that of the token, then this is a <a - href="#parse">parse error</a>.</p> - - <p>If the <a href="#stack">stack of open elements</a> <a - href="#have-an">has an element in scope</a> with the same tag name - as that of the token, then pop elements from this stack until an - element with that tag name has been popped from the stack.</p> - <!-- XXX quirk (except for in certain cases?): - <p>Otherwise, act as if a start tag with the tag name given in - the token had been seen, then reprocess the current token.</p> - --> - - - <dt>An end tag whose tag name is "form" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> <a - href="#have-an">has an element in scope</a> with the same tag name - as that of the token, then <a href="#generate">generate implied end - tags</a>.</p> - - <p>Now, if the <a href="#current4">current node</a> is not an element - with the same tag name as that of the token, then this is a <a - href="#parse">parse error</a>.</p> - - <p>Otherwise, if the <a href="#current4">current node</a> is an - element with the same tag name as that of the token pop that element - from the stack.</p> - - <p>In any case, set the <a href="#form-element"><code - title="">form</code> element pointer</a> to null.</p> - - <dt>An end tag whose tag name is "p" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> <a - href="#have-an" title="has an element in scope">has a <code>p</code> - element in scope</a>, then <a href="#generate">generate implied end - tags</a>, except for <code><a href="#p">p</a></code> elements.</p> - - <p>If the <a href="#current4">current node</a> is not a <code><a - href="#p">p</a></code> element, then this is a <a - href="#parse">parse error</a>.</p> - - <p>If the <a href="#stack">stack of open elements</a> <a - href="#have-an" title="has an element in scope">has a <code>p</code> - element in scope</a>, then pop elements from this stack until the - stack no longer <a href="#have-an" title="has an element in - scope">has a <code>p</code> element in scope</a>.</p> - <!-- XXX quirk: - <p>Otherwise, act as if a start tag with the tag name - <code>p</code> had been seen, then reprocess the current - token.</p> - --> - - - <dt>An end tag whose tag name is "dd", "dt", or "li" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> <a - href="#have-an">has an element in scope</a> whose tag name matches - the tag name of the token, then <a href="#generate">generate implied - end tags</a>, except for elements with the same tag name as the - token.</p> - - <p>If the <a href="#current4">current node</a> is not an element with - the same tag name as the token, then this is a <a - href="#parse">parse error</a>.</p> - - <p>If the <a href="#stack">stack of open elements</a> <a - href="#have-an">has an element in scope</a> whose tag name matches - the tag name of the token, then pop elements from this stack until - an element with that tag name has been popped from the stack.</p> - - <dt>A start tag whose tag name is one of: "h1", "h2", "h3", "h4", - "h5", "h6" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> <a - href="#have-an" title="has an element in scope">has a <code>p</code> - element in scope</a>, then act as if an end tag with the tag name - <code><a href="#p">p</a></code> had been seen.</p> - - <p>If the <a href="#stack">stack of open elements</a> <a - href="#have-an" title="has an element in scope">has in scope</a> an - element whose tag name is one of "h1", "h2", "h3", "h4", "h5", or - "h6", then this is a <a href="#parse">parse error</a>; pop elements - from the stack until an element with one of those tag names has been - popped from the stack.</p> - - <p><a href="#insert" title="insert an html element">Insert an HTML - element</a> for the token.</p> - - <dt>An end tag whose tag name is one of: "h1", "h2", "h3", "h4", "h5", - "h6" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> <a - href="#have-an" title="has an element in scope">has in scope</a> an - element whose tag name is one of "h1", "h2", "h3", "h4", "h5", or - "h6", then <a href="#generate">generate implied end tags</a>.</p> - - <p>Now, if the <a href="#current4">current node</a> is not an element - with the same tag name as that of the token, then this is a <a - href="#parse">parse error</a>.</p> - - <p>If the <a href="#stack">stack of open elements</a> <a - href="#have-an" title="has an element in scope">has in scope</a> an - element whose tag name is one of "h1", "h2", "h3", "h4", "h5", or - "h6", then pop elements from the stack until an element with one of - those tag names has been popped from the stack.</p> - <!-- XXX quirk: - <p>Otherwise, act as if a start tag with the tag name given in - the token had been seen, then reprocess the current token.</p> - --> - </dd> - <!-- ADOPTION AGENCY ELEMENTS - Mozilla-only: bdo blink del ins sub sup q - Safari-only: code dfn kbd nobr samp var wbr - Both: a b big em font i s small strike strong tt u --> - - <dt>A start tag whose tag name is "a" - - <dd> - <p>If the <a href="#list-of4">list of active formatting elements</a> - contains an element whose tag name is "a" between the end of the - list and the last marker on the list (or the start of the list if - there is no marker on the list), then this is a <a - href="#parse">parse error</a>; act as if an end tag with the tag - name "a" had been seen, then remove that element from the <a - href="#list-of4">list of active formatting elements</a> and the <a - href="#stack">stack of open elements</a> if the end tag didn't - already remove it (it might not have if the element is not <a - href="#have-an0" title="has an element in table scope">in table - scope</a>).</p> - - <p class=example>In the non-conforming stream - <code><a href="a">a<table><a href="b">b</table>x</code>, - the first <code><a href="#a">a</a></code> element would be closed - upon seeing the second one, and the "x" character would be inside a - link to "b", not to "a". This is despite the fact that the outer - <code><a href="#a">a</a></code> element is not in table scope - (meaning that a regular <code></a></code> end tag at the start of - the table wouldn't close the outer <code><a href="#a">a</a></code> - element).</p> - - <p><a href="#reconstruct">Reconstruct the active formatting - elements</a>, if any.</p> - - <p><a href="#insert" title="insert an html element">Insert an HTML - element</a> for the token. Add that element to the <a - href="#list-of4">list of active formatting elements</a>.</p> - - <dt>A start tag whose tag name is one of: "b", "big", "em", "font", - "i", "nobr", "s", "small", "strike", "strong", "tt", "u" - - <dd> - <p><a href="#reconstruct">Reconstruct the active formatting - elements</a>, if any.</p> - - <p><a href="#insert" title="insert an html element">Insert an HTML - element</a> for the token. Add that element to the <a - href="#list-of4">list of active formatting elements</a>.</p> - - <dt id=adoptionAgency>An end tag whose tag name is one of: "a", "b", - "big", "em", "font", "i", "nobr", "s", "small", "strike", "strong", - "tt", "u" - - <dd> - <p>Follow these steps:</p> - - <ol> - <li> - <p>Let the <var title="">formatting element</var> be the last - element in the <a href="#list-of4">list of active formatting - elements</a> that:</p> - - <ul> - <li>is between the end of the list and the last scope marker in - the list, if any, or the start of the list otherwise, and - - <li>has the same tag name as the token. - </ul> - - <p>If there is no such node, or, if that node is also in the <a - href="#stack">stack of open elements</a> but the element is not <a - href="#have-an" title="has an element in scope">in scope</a>, then - this is a <a href="#parse">parse error</a>. Abort these steps. The - token is ignored.</p> - - <p>Otherwise, if there is such a node, but that node is not in the - <a href="#stack">stack of open elements</a>, then this is a <a - href="#parse">parse error</a>; remove the element from the list, - and abort these steps.</p> - - <p>Otherwise, there is a <var title="">formatting element</var> and - that element is in <a href="#stack" title="stack of open - elements">the stack</a> and is <a href="#have-an" title="has an - element in scope">in scope</a>. If the element is not the <a - href="#current4">current node</a>, this is a <a - href="#parse">parse error</a>. In any case, proceed with the - algorithm as written in the following steps.</p> - - <li> - <p>Let the <var title="">furthest block</var> be the topmost node - in the <a href="#stack">stack of open elements</a> that is lower - in the stack than the <var title="">formatting element</var>, and - is not an element in the <a href="#phrasing">phrasing</a> or <a - href="#formatting">formatting</a> categories. There might not be - one. - - <li> - <p>If there is no <var title="">furthest block</var>, then the UA - must skip the subsequent steps and instead just pop all the nodes - from the bottom of the <a href="#stack">stack of open - elements</a>, from the <a href="#current4">current node</a> up to - the <var title="">formatting element</var>, and remove the <var - title="">formatting element</var> from the <a - href="#list-of4">list of active formatting elements</a>. - - <li> - <p>Let the <var title="">common ancestor</var> be the element - immediately above the <var title="">formatting element</var> in - the <a href="#stack">stack of open elements</a>. - - <li> - <p>If the <var title="">furthest block</var> has a parent node, - then remove the <var title="">furthest block</var> from its parent - node. - - <li> - <p>Let a bookmark note the position of the <var title="">formatting - element</var> in the <a href="#list-of4">list of active formatting - elements</a> relative to the elements on either side of it in the - list. - - <li> - <p>Let <var title="">node</var> and <var title="">last node</var> - be the <var title="">furthest block</var>. Follow these steps:</p> - - <ol> - <li>Let <var title="">node</var> be the element immediately prior - to <var title="">node</var> in the <a href="#stack">stack of open - elements</a>. - - <li>If <var title="">node</var> is not in the <a - href="#list-of4">list of active formatting elements</a>, then - remove <var title="">node</var> from the <a href="#stack">stack - of open elements</a> and then go back to step 1. - - <li>Otherwise, if <var title="">node</var> is the <var - title="">formatting element</var>, then go to the next step in - the overall algorithm. - - <li>Otherwise, if <var title="">last node</var> is the <var - title="">furthest block</var>, then move the aforementioned - bookmark to be immediately after the <var title="">node</var> in - the <a href="#list-of4">list of active formatting elements</a>. - - <li>If <var title="">node</var> has any children, perform a - shallow clone of <var title="">node</var>, replace the entry for - <var title="">node</var> in the <a href="#list-of4">list of - active formatting elements</a> with an entry for the clone, - replace the entry for <var title="">node</var> in the <a - href="#stack">stack of open elements</a> with an entry for the - clone, and let <var title="">node</var> be the clone. - - <li>Insert <var title="">last node</var> into <var - title="">node</var>, first removing it from its previous parent - node if any. - - <li>Let <var title="">last node</var> be <var title="">node</var>. - - <li>Return to step 1 of this inner set of steps. - </ol> - - <li> - <p>Insert whatever <var title="">last node</var> ended up being in - the previous step into the <var title="">common ancestor</var> - node, first removing it from its previous parent node if any. - - <li> - <p>Perform a shallow clone of the <var title="">formatting - element</var>. - - <li> - <p>Take all of the child nodes of the <var title="">furthest - block</var> and append them to the clone created in the last step. - - <li> - <p>Append that clone to the <var title="">furthest block</var>. - - <li> - <p>Remove the <var title="">formatting element</var> from the <a - href="#list-of4">list of active formatting elements</a>, and - insert the clone into the <a href="#list-of4">list of active - formatting elements</a> at the position of the aforementioned - bookmark. - - <li> - <p>Remove the <var title="">formatting element</var> from the <a - href="#stack">stack of open elements</a>, and insert the clone - into the <a href="#stack">stack of open elements</a> immediately - after (i.e. in a more deeply nested position than) the position of - the <var title="">furthest block</var> in that stack. - - <li> - <p>Jump back to step 1 in this series of steps. - </ol> - - <p class=note>The way these steps are defined, only elements in the - <a href="#formatting">formatting</a> category ever get cloned by - this algorithm.</p> - <!--XXX - <div class="example"> - <p class="big-issue">Need an example.</p> - </div> ---> - - <p class=note>Because of the way this algorithm causes elements to - change parents, it has been dubbed the "adoption agency algorithm" - (in contrast with other possibly algorithms for dealing with - misnested content, which included the "incest algorithm", the - "secret affair algorithm", and the "Heisenberg algorithm").</p> - - <dt>A start tag token whose tag name is "button" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> <a - href="#have-an" title="has an element in scope">has a - <code>button</code> element in scope</a>, then this is a <a - href="#parse">parse error</a>; act as if an end tag with the tag - name "button" had been seen, then reprocess the token.</p> - - <p>Otherwise:</p> - - <p><a href="#reconstruct">Reconstruct the active formatting - elements</a>, if any.</p> - - <p><a href="#insert">Insert an HTML element</a> for the token.</p> - - <p>Insert a marker at the end of the <a href="#list-of4">list of - active formatting elements</a>.</p> - - <dt>A start tag token whose tag name is one of: "marquee", "object" - - <dd> - <p><a href="#reconstruct">Reconstruct the active formatting - elements</a>, if any.</p> - - <p><a href="#insert">Insert an HTML element</a> for the token.</p> - - <p>Insert a marker at the end of the <a href="#list-of4">list of - active formatting elements</a>.</p> - - <dt>An end tag token whose tag name is one of: "button", "marquee", - "object" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> <a - href="#have-an" title="has an element in scope">has in scope</a> an - element whose tag name is the same as the tag name of the token, - then <a href="#generate">generate implied end tags</a>.</p> - - <p>Now, if the <a href="#current4">current node</a> is not an element - with the same tag name as the token, then this is a <a - href="#parse">parse error</a>.</p> - - <p>Now, if the <a href="#stack">stack of open elements</a> <a - href="#have-an">has an element in scope</a> whose tag name matches - the tag name of the token, then pop elements from the stack until - that element has been popped from the stack, and <a - href="#clear0">clear the list of active formatting elements up to - the last marker</a>.</p> - - <dt>A start tag token whose tag name is "xmp" - - <dd> - <p><a href="#reconstruct">Reconstruct the active formatting - elements</a>, if any.</p> - - <p><a href="#insert">Insert an HTML element</a> for the token.</p> - - <p>Switch the <a href="#content2">content model flag</a> to the CDATA - state.</p> - - <dt>A start tag whose tag name is "table" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> <a - href="#have-an" title="has an element in scope">has a <code>p</code> - element in scope</a>, then act as if an end tag with the tag name - <code><a href="#p">p</a></code> had been seen.</p> - <!-- XXX quirks: don't do this --> - <p><a href="#insert">Insert an HTML element</a> for the token.</p> - - <p>Change the <a href="#insertion0">insertion mode</a> to "<a - href="#in-table" title="insertion mode: in table">in table</a>".</p> - - <dt>A start tag whose tag name is one of: "area", "basefont", - "bgsound", "br", "embed", "img", "param", "spacer", "wbr" - - <dd> - <p><a href="#reconstruct">Reconstruct the active formatting - elements</a>, if any.</p> - - <p><a href="#insert" title="insert an html element">Insert an HTML - element</a> for the token. Immediately pop the <a - href="#current4">current node</a> off the <a href="#stack">stack of - open elements</a>.</p> - - <dt>A start tag whose tag name is "hr" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> <a - href="#have-an" title="has an element in scope">has a <code>p</code> - element in scope</a>, then act as if an end tag with the tag name - <code><a href="#p">p</a></code> had been seen.</p> - <!-- XXX quirks: don't do this --> - <p><a href="#insert" title="insert an html element">Insert an HTML - element</a> for the token. Immediately pop the <a - href="#current4">current node</a> off the <a href="#stack">stack of - open elements</a>.</p> - - <dt>A start tag whose tag name is "image" - - <dd> - <p><a href="#parse">Parse error</a>. Change the token's tag name to - "img" and reprocess it. (Don't ask.)</p> - <!-- As of - 2005-12, studies showed that around 0.2% of pages used the - <image> element. --> - - - <dt>A start tag whose tag name is "input" - - <dd> - <p><a href="#reconstruct">Reconstruct the active formatting - elements</a>, if any.</p> - - <p><a href="#insert" title="insert an html element">Insert an - <code>input</code> element</a> for the token.</p> - - <p>If the <a href="#form-element"><code title="">form</code> element - pointer</a> is not null, then <span>associate</span><!--XXX - xref! --> - the <code>input</code> element with the <code>form</code> element - pointed to by the <a href="#form-element"><code title="">form</code> - element pointer</a>.</p> - - <p>Pop that <code>input</code> element off the <a href="#stack">stack - of open elements</a>.</p> - - <dt id=isindex>A start tag whose tag name is "isindex" - - <dd> - <p><a href="#parse">Parse error</a>.</p> - - <p>If the <a href="#form-element"><code title="">form</code> element - pointer</a> is not null, then ignore the token.</p> - - <p>Otherwise:</p> - - <p>Act as if a start tag token with the tag name "form" had been - seen.</p> - - <p>Act as if a start tag token with the tag name "hr" had been seen.</p> - - <p>Act as if a start tag token with the tag name "p" had been seen.</p> - - <p>Act as if a start tag token with the tag name "label" had been - seen.</p> - - <p>Act as if a stream of character tokens had been seen (see below - for what they should say).</p> - - <p>Act as if a start tag token with the tag name "input" had been - seen, with all the attributes from the "isindex" token, except with - the "name" attribute set to the value "isindex" (ignoring any - explicit "name" attribute).</p> - - <p>Act as if a stream of character tokens had been seen (see below - for what they should say).</p> - - <p>Act as if an end tag token with the tag name "label" had been - seen.</p> - - <p>Act as if an end tag token with the tag name "p" had been seen.</p> - - <p>Act as if a start tag token with the tag name "hr" had been seen.</p> - - <p>Act as if an end tag token with the tag name "form" had been seen.</p> - - <p>The two streams of character tokens together should, together with - the <code>input</code> element, express the equivalent of "This is a - searchable index. Insert your search keywords here: (input field)" - in the user's preferred language.</p> - - <p class=big-issue> Then need to specify that if the form submission - causes just a single form control, whose name is "isindex", to be - submitted, then we submit just the value part, not the "isindex=" - part.</p> - </dd> - <!-- XXX keygen support; don't forget form element pointer! - - <dt>A start tag whose tag name is "keygen"</dt> - <dd> - ... - </dd> ---> - - <dt>A start tag whose tag name is "textarea" - - <dd> - <p><a href="#create">Create an element for the token</a>.</p> - - <p>If the <a href="#form-element"><code title="">form</code> element - pointer</a> is not null, then <span>associate</span><!--XXX - xref! --> - the <code>textarea</code> element with the <code>form</code> element - pointed to by the <a href="#form-element"><code title="">form</code> - element pointer</a>.</p> - - <p>Append the new element to the <a href="#current4">current - node</a>.</p> - - <p>Switch the tokeniser's <a href="#content2">content model flag</a> - to the RCDATA state.</p> - - <p>If the next token is a U+000A LINE FEED (LF) character token, then - ignore that token and move on to the next one. (Newlines at the - start of <code>textarea</code> elements are ignored as an authoring - convenience.)</p> - - <p>Then, collect all the character tokens that the tokeniser returns - until it returns a token that is not a character token, or until it - stops tokenising.</p> - - <p>If this process resulted in a collection of character tokens, - append a single <code>Text</code> node, whose contents is the - concatenation of all those tokens' characters, to the new element - node.</p> - - <p>The tokeniser's <a href="#content2">content model flag</a> will - have switched back to the PCDATA state.</p> - - <p>If the next token is an end tag token with the tag name - "textarea", ignore it. Otherwise, this is a <a href="#parse">parse - error</a>.</p> - - <dt>A start tag whose tag name is one of: "iframe", "noembed", - "noframes" - - <dt>A start tag whose tag name is "noscript", if <a - href="#scripting2">scripting is enabled</a>: - - <dd> - <p><a href="#create">Create an element for the token</a>.</p> - - <p>For "iframe" tags, the node must be an <code><a - href="#htmliframeelement">HTMLIFrameElement</a></code> object, for - the other tags it must be an <code><a - href="#htmlelement">HTMLElement</a></code> object.</p> - - <p>Append the new element to the <a href="#current4">current - node</a>.</p> - - <p>Switch the tokeniser's <a href="#content2">content model flag</a> - to the CDATA state.</p> - - <p>Then, collect all the character tokens that the tokeniser returns - until it returns a token that is not a character token, or until it - stops tokenising.</p> - - <p>If this process resulted in a collection of character tokens, - append a single <code>Text</code> node, whose contents is the - concatenation of all those tokens' characters, to the new element - node.</p> - - <p>The tokeniser's <a href="#content2">content model flag</a> will - have switched back to the PCDATA state.</p> - - <p>If the next token is an end tag token with the same tag name as - the start tag token, ignore it. Otherwise, this is a <a - href="#parse">parse error</a>.</p> - - <dt>A start tag whose tag name is "select" - - <dd> - <p><a href="#reconstruct">Reconstruct the active formatting - elements</a>, if any.</p> - - <p><a href="#insert">Insert an HTML element</a> for the token.</p> - - <p>Change the <a href="#insertion0">insertion mode</a> to "<a - href="#in-select" title="insertion mode: in select">in select</a>".</p> - </dd> - <!-- XXX quirks: - <dt>An end tag whose tag name is "br"</dt> - <dd> - <p>Act as if a start tag token with the tag name "br" had been - seen. Ignore the end tag token.</p> - </dd> ---> - - <dt>A start or end tag whose tag name is one of: "caption", "col", - "colgroup", "frame", "frameset", "head", "option", "optgroup", - "tbody", "td", "tfoot", "th", "thead", "tr" - - <dt>An end tag whose tag name is one of: "area", "basefont", - "bgsound", <!--XXX quirks: remove br-->"br", "embed", "hr", "iframe", - "image", "img", "input", "isindex", "noembed", "noframes", "param", - "select", "spacer", "table", "textarea", "wbr"</dt> - <!-- add keygen if we add the start tag --> - - <dt>An end tag whose tag name is "noscript", if <a - href="#scripting2">scripting is enabled</a>: - - <dd> - <p><a href="#parse">Parse error</a>. Ignore the token.</p> - - <dt>A start or end tag whose tag name is one of: "event-source", - "section", "nav", "article", "aside", "header", "footer", "datagrid", - "command" - - <dd> <!-- XXXX --> - <p class=big-issue>Work in progress!</p> - - <dt>A start tag token not covered by the previous entries - - <dd> - <p><a href="#reconstruct">Reconstruct the active formatting - elements</a>, if any.</p> - - <p><a href="#insert">Insert an HTML element</a> for the token.</p> - - <p class=note>This element will be a <a href="#phrasing">phrasing</a> - element.</p> - <!-- -Put the following into the MathML namespace if parsed: - math, mrow, mfrac, msqrt, mroot, mstyle, merror, mpadded, - mphantom, mfenced, menclose, msub, msup, msubsup, munder, - mover, munderover, mmultiscripts, mtable, mlabeledtr, mtr, - mtd, maction ---> - - - <dt>An end tag token not covered by the previous entries - - <dd> - <p>Run the following algorithm:</p> - - <ol> - <li> - <p>Initialise <var title="">node</var> to be the <a - href="#current4">current node</a> (the bottommost node of the - stack). - - <li> - <p>If <var title="">node</var> has the same tag name as the end tag - token, then:</p> - - <ol> - <li> - <p><a href="#generate">Generate implied end tags</a>. - - <li> - <p>If the tag name of the end tag token does not match the tag - name of the <a href="#current4">current node</a>, this is a <a - href="#parse">parse error</a>. - - <li> - <p>Pop all the nodes from the <a href="#current4">current - node</a> up to <var title="">node</var>, including <var - title="">node</var>, then stop this algorithm. - </ol> - - <li> - <p>Otherwise, if <var title="">node</var> is in neither the <a - href="#formatting">formatting</a> category nor the <a - href="#phrasing">phrasing</a> category, then this is a <a - href="#parse">parse error</a>. Stop this algorithm. The end tag - token is ignored. - - <li> - <p>Set <var title="">node</var> to the previous entry in the <a - href="#stack">stack of open elements</a>. - - <li> - <p>Return to step 2. - </ol> - </dl> - - <dt id=parsing-main-intable>If the <a href="#insertion0">insertion - mode</a> is "<dfn id=in-table title="insertion mode: in table">in - table</dfn>" - - <dd> - <dl class=switch> - <dt>A character token that is one of one of U+0009 CHARACTER - TABULATION, U+000A LINE FEED (LF), U+000B LINE TABULATION, U+000C - FORM FEED (FF), U+000D CARRIAGE RETURN (CR), or U+0020 SPACE - - <dd> - <p><a href="#append" title="append a character">Append the - character</a> to the <a href="#current4">current node</a>.</p> - - <dt>A comment token - - <dd> - <p>Append a <code>Comment</code> node to the <a - href="#current4">current node</a> with the <code - title="">data</code> attribute set to the data given in the comment - token.</p> - - <dt>A start tag whose tag name is "caption" - - <dd> - <p><a href="#clear1">Clear the stack back to a table context</a>. - (See below.)</p> - - <p>Insert a marker at the end of the <a href="#list-of4">list of - active formatting elements</a>.</p> - - <p><a href="#insert">Insert an HTML element</a> for the token, then - switch the <a href="#insertion0">insertion mode</a> to "<a - href="#in-caption" title="insertion mode: in caption">in - caption</a>".</p> - - <dt>A start tag whose tag name is "colgroup" - - <dd> - <p><a href="#clear1">Clear the stack back to a table context</a>. - (See below.)</p> - - <p><a href="#insert">Insert an HTML element</a> for the token, then - switch the <a href="#insertion0">insertion mode</a> to "<a - href="#in-column" title="insertion mode: in column group">in column - group</a>".</p> - - <dt>A start tag whose tag name is "col" - - <dd> - <p>Act as if a start tag token with the tag name "colgroup" had been - seen, then reprocess the current token.</p> - - <dt>A start tag whose tag name is one of: "tbody", "tfoot", "thead" - - <dd> - <p><a href="#clear1">Clear the stack back to a table context</a>. - (See below.)</p> - - <p><a href="#insert">Insert an HTML element</a> for the token, then - switch the <a href="#insertion0">insertion mode</a> to "<a - href="#in-table0" title="insertion mode: in table body">in table - body</a>".</p> - - <dt>A start tag whose tag name is one of: "td", "th", "tr" - - <dd> - <p>Act as if a start tag token with the tag name "tbody" had been - seen, then reprocess the current token.</p> - - <dt>A start tag whose tag name is "table" - - <dd> - <p><a href="#parse">Parse error</a>. Act as if an end tag token with - the tag name "table" had been seen, then, if that token wasn't - ignored, reprocess the current token.</p> - - <p class=note>The fake end tag token here can only be ignored in the - <a href="#innerhtml1"><code>innerHTML</code> case</a>.</p> - - <dt>An end tag whose tag name is "table" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> does not <a - href="#have-an0" title="has an element in table scope">have an - element in table scope</a> with the same tag name as the token, this - is a <a href="#parse">parse error</a>. Ignore the token. (<a - href="#innerhtml1"><code>innerHTML</code> case</a>)</p> - - <p>Otherwise:</p> - - <p><a href="#generate">Generate implied end tags</a>.</p> - - <p>Now, if the <a href="#current4">current node</a> is not a <code><a - href="#table">table</a></code> element, then this is a <a - href="#parse">parse error</a>.</p> - - <p>Pop elements from this stack until a <code><a - href="#table">table</a></code> element has been popped from the - stack.</p> - - <p><a href="#reset">Reset the insertion mode appropriately</a>.</p> - - <dt>An end tag whose tag name is one of: "body", "caption", "col", - "colgroup", "html", "tbody", "td", "tfoot", "th", "thead", "tr" - - <dd> - <p><a href="#parse">Parse error</a>. Ignore the token.</p> - - <dt>Anything else - - <dd> - <p><a href="#parse">Parse error</a>. Process the token as if the <a - href="#insertion0">insertion mode</a> was "<a href="#in-body" - title="insertion mode: in body">in body</a>", with the following - exception:</p> - - <p>If the <a href="#current4">current node</a> is a <code><a - href="#table">table</a></code>, <code><a - href="#tbody">tbody</a></code>, <code><a - href="#tfoot0">tfoot</a></code>, <code><a - href="#thead0">thead</a></code>, or <code><a - href="#tr">tr</a></code> element, then, whenever a node would be - inserted into the <a href="#current4">current node</a>, it must - instead be inserted into the <em><a href="#foster">foster parent - element</a></em>.</p> - - <p>The <dfn id=foster>foster parent element</dfn> is the parent - element of the last <code><a href="#table">table</a></code> element - in the <a href="#stack">stack of open elements</a>, if there is a - <code><a href="#table">table</a></code> element and it has such a - parent element. If there is no <code><a - href="#table">table</a></code> element in the <a href="#stack">stack - of open elements</a> (<a href="#innerhtml1"><code>innerHTML</code> - case</a>), then the <em><a href="#foster">foster parent - element</a></em> is the first element in the <a href="#stack">stack - of open elements</a> (the <code><a href="#html">html</a></code> - element). Otherwise, if there is a <code><a - href="#table">table</a></code> element in the <a href="#stack">stack - of open elements</a>, but the last <code><a - href="#table">table</a></code> element in the <a href="#stack">stack - of open elements</a> has no parent, or its parent node is not an - element, then the <em><a href="#foster">foster parent - element</a></em> is the element before the last <code><a - href="#table">table</a></code> element in the <a href="#stack">stack - of open elements</a>.</p> - - <p>If the <em><a href="#foster">foster parent element</a></em> is the - parent element of the last <code><a href="#table">table</a></code> - element in the <a href="#stack">stack of open elements</a>, then the - new node must be inserted immediately <em>before</em> the last - <code><a href="#table">table</a></code> element in the <a - href="#stack">stack of open elements</a> in the <a - href="#foster">foster parent element</a>; otherwise, the new node - must be <em>appended</em> to the <a href="#foster">foster parent - element</a>.</p> - </dl> - - <p>When the steps above require the UA to <dfn id=clear1>clear the - stack back to a table context</dfn>, it means that the UA must, while - the <a href="#current4">current node</a> is not a <code><a - href="#table">table</a></code> element or an <code><a - href="#html">html</a></code> element, pop elements from the <a - href="#stack">stack of open elements</a>. If this causes any elements - to be popped from the stack, then this is a <a href="#parse">parse - error</a>.</p> - - <p class=note>The <a href="#current4">current node</a> being an - <code><a href="#html">html</a></code> element after this process is an - <a href="#innerhtml1"><code>innerHTML</code> case</a>.</p> - - <dt id=parsing-main-incaption>If the <a href="#insertion0">insertion - mode</a> is "<dfn id=in-caption title="insertion mode: in caption">in - caption</dfn>" - - <dd> - <dl class=switch> - <dt>An end tag whose tag name is "caption" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> does not <a - href="#have-an0" title="has an element in table scope">have an - element in table scope</a> with the same tag name as the token, this - is a <a href="#parse">parse error</a>. Ignore the token. (<a - href="#innerhtml1"><code>innerHTML</code> case</a>)</p> - - <p>Otherwise:</p> - - <p><a href="#generate">Generate implied end tags</a>.</p> - - <p>Now, if the <a href="#current4">current node</a> is not a <code><a - href="#caption0">caption</a></code> element, then this is a <a - href="#parse">parse error</a>.</p> - - <p>Pop elements from this stack until a <code><a - href="#caption0">caption</a></code> element has been popped from the - stack.</p> - - <p><a href="#clear0">Clear the list of active formatting elements up - to the last marker</a>.</p> - - <p>Switch the <a href="#insertion0">insertion mode</a> to "<a - href="#in-table" title="insertion mode: in table">in table</a>".</p> - - <dt>A start tag whose tag name is one of: "caption", "col", - "colgroup", "tbody", "td", "tfoot", "th", "thead", "tr" - - <dt>An end tag whose tag name is "table" - - <dd> - <p><a href="#parse">Parse error</a>. Act as if an end tag with the - tag name "caption" had been seen, then, if that token wasn't - ignored, reprocess the current token.</p> - - <p class=note>The fake end tag token here can only be ignored in the - <a href="#innerhtml1"><code>innerHTML</code> case</a>.</p> - - <dt>An end tag whose tag name is one of: "body", "col", "colgroup", - "html", "tbody", "td", "tfoot", "th", "thead", "tr" - - <dd> - <p><a href="#parse">Parse error</a>. Ignore the token.</p> - - <dt>Anything else - - <dd> - <p>Process the token as if the <a href="#insertion0">insertion - mode</a> was "<a href="#in-body" title="insertion mode: in body">in - body</a>".</p> - </dl> - - <dt id=parsing-main-incolgroup>If the <a href="#insertion0">insertion - mode</a> is "<dfn id=in-column title="insertion mode: in column - group">in column group</dfn>" - - <dd> - <dl class=switch> - <dt>A character token that is one of one of U+0009 CHARACTER - TABULATION, U+000A LINE FEED (LF), U+000B LINE TABULATION, U+000C - FORM FEED (FF), U+000D CARRIAGE RETURN (CR), or U+0020 SPACE - - <dd> - <p><a href="#append" title="append a character">Append the - character</a> to the <a href="#current4">current node</a>.</p> - - <dt>A comment token - - <dd> - <p>Append a <code>Comment</code> node to the <a - href="#current4">current node</a> with the <code - title="">data</code> attribute set to the data given in the comment - token.</p> - - <dt>A start tag whose tag name is "col" - - <dd> - <p><a href="#insert" title="insert an HTML element">Insert a - <code>col</code> element</a> for the token. Immediately pop the <a - href="#current4">current node</a> off the <a href="#stack">stack of - open elements</a>.</p> - - <dt>An end tag whose tag name is "colgroup" - - <dd> - <p>If the <a href="#current4">current node</a> is the root <code><a - href="#html">html</a></code> element, then this is a <a - href="#parse">parse error</a>, ignore the token. (<a - href="#innerhtml1"><code>innerHTML</code> case</a>)</p> - - <p>Otherwise, pop the <a href="#current4">current node</a> (which - will be a <code><a href="#colgroup">colgroup</a></code> element) - from the <a href="#stack">stack of open elements</a>. Switch the <a - href="#insertion0">insertion mode</a> to "<a href="#in-table" - title="insertion mode: in table">in table</a>".</p> - - <dt>An end tag whose tag name is "col" - - <dd> - <p><a href="#parse">Parse error</a>. Ignore the token.</p> - - <dt>Anything else - - <dd> - <p>Act as if an end tag with the tag name "colgroup" had been seen, - and then, if that token wasn't ignored, reprocess the current token.</p> - - <p class=note>The fake end tag token here can only be ignored in the - <a href="#innerhtml1"><code>innerHTML</code> case</a>.</p> - </dl> - - <dt id=parsing-main-intbody>If the <a href="#insertion0">insertion - mode</a> is "<dfn id=in-table0 title="insertion mode: in table body">in - table body</dfn>" - - <dd> - <dl class=switch> - <dt>A start tag whose tag name is "tr" - - <dd> - <p><a href="#clear2">Clear the stack back to a table body - context</a>. (See below.)</p> - - <p><a href="#insert" title="insert an HTML element">Insert a - <code>tr</code> element</a> for the token, then switch the <a - href="#insertion0">insertion mode</a> to "<a href="#in-row" - title="insertion mode: in row">in row</a>".</p> - - <dt>A start tag whose tag name is one of: "th", "td" - - <dd> - <p><a href="#parse">Parse error</a>. Act as if a start tag with the - tag name "tr" had been seen, then reprocess the current token.</p> - - <dt>An end tag whose tag name is one of: "tbody", "tfoot", "thead" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> does not <a - href="#have-an0" title="has an element in table scope">have an - element in table scope</a> with the same tag name as the token, this - is a <a href="#parse">parse error</a>. Ignore the token.</p> - - <p>Otherwise:</p> - - <p><a href="#clear2">Clear the stack back to a table body - context</a>. (See below.)</p> - - <p>Pop the <a href="#current4">current node</a> from the <a - href="#stack">stack of open elements</a>. Switch the <a - href="#insertion0">insertion mode</a> to "<a href="#in-table" - title="insertion mode: in table">in table</a>".</p> - - <dt>A start tag whose tag name is one of: "caption", "col", - "colgroup", "tbody", "tfoot", "thead" - - <dt>An end tag whose tag name is "table" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> does not <a - href="#have-an0" title="has an element in table scope">have a - <code>tbody</code>, <code>thead</code>, or <code>tfoot</code> - element in table scope</a>, this is a <a href="#parse">parse - error</a>. Ignore the token. (<a - href="#innerhtml1"><code>innerHTML</code> case</a>)</p> - - <p>Otherwise:</p> - - <p><a href="#clear2">Clear the stack back to a table body - context</a>. (See below.)</p> - - <p>Act as if an end tag with the same tag name as the <a - href="#current4">current node</a> ("tbody", "tfoot", or "thead") had - been seen, then reprocess the current token.</p> - - <dt>An end tag whose tag name is one of: "body", "caption", "col", - "colgroup", "html", "td", "th", "tr" - - <dd> - <p><a href="#parse">Parse error</a>. Ignore the token.</p> - - <dt>Anything else - - <dd> - <p>Process the token as if the <a href="#insertion0">insertion - mode</a> was "<a href="#in-table" title="insertion mode: in - table">in table</a>".</p> - </dl> - - <p>When the steps above require the UA to <dfn id=clear2>clear the - stack back to a table body context</dfn>, it means that the UA must, - while the <a href="#current4">current node</a> is not a <code><a - href="#tbody">tbody</a></code>, <code><a - href="#tfoot0">tfoot</a></code>, <code><a - href="#thead0">thead</a></code>, or <code><a - href="#html">html</a></code> element, pop elements from the <a - href="#stack">stack of open elements</a>. If this causes any elements - to be popped from the stack, then this is a <a href="#parse">parse - error</a>.</p> - - <p class=note>The <a href="#current4">current node</a> being an - <code><a href="#html">html</a></code> element after this process is an - <a href="#innerhtml1"><code>innerHTML</code> case</a>.</p> - - <dt id=parsing-main-intr>If the <a href="#insertion0">insertion mode</a> - is "<dfn id=in-row title="insertion mode: in row">in row</dfn>" - - <dd> - <dl class=switch> - <dt>A start tag whose tag name is one of: "th", "td" - - <dd> - <p><a href="#clear3">Clear the stack back to a table row context</a>. - (See below.)</p> - - <p><a href="#insert" title="insert an HTML element">Insert an HTML - element</a> for the token, then switch the <a - href="#insertion0">insertion mode</a> to "<a href="#in-cell" - title="insertion mode: in cell">in cell</a>".</p> - - <p>Insert a marker at the end of the <a href="#list-of4">list of - active formatting elements</a>.</p> - - <dt>An end tag whose tag name is "tr" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> does not <a - href="#have-an0" title="has an element in table scope">have an - element in table scope</a> with the same tag name as the token, this - is a <a href="#parse">parse error</a>. Ignore the token. (<a - href="#innerhtml1"><code>innerHTML</code> case</a>)</p> - - <p>Otherwise:</p> - - <p><a href="#clear3">Clear the stack back to a table row context</a>. - (See below.)</p> - - <p>Pop the <a href="#current4">current node</a> (which will be a - <code><a href="#tr">tr</a></code> element) from the <a - href="#stack">stack of open elements</a>. Switch the <a - href="#insertion0">insertion mode</a> to "<a href="#in-table0" - title="insertion mode: in table body">in table body</a>".</p> - - <dt>A start tag whose tag name is one of: "caption", "col", - "colgroup", "tbody", "tfoot", "thead", "tr" - - <dt>An end tag whose tag name is "table" - - <dd> - <p>Act as if an end tag with the tag name "tr" had been seen, then, - if that token wasn't ignored, reprocess the current token.</p> - - <p class=note>The fake end tag token here can only be ignored in the - <a href="#innerhtml1"><code>innerHTML</code> case</a>.</p> - - <dt>An end tag whose tag name is one of: "tbody", "tfoot", "thead" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> does not <a - href="#have-an0" title="has an element in table scope">have an - element in table scope</a> with the same tag name as the token, this - is a <a href="#parse">parse error</a>. Ignore the token.</p> - - <p>Otherwise, act as if an end tag with the tag name "tr" had been - seen, then reprocess the current token.</p> - - <dt>An end tag whose tag name is one of: "body", "caption", "col", - "colgroup", "html", "td", "th" - - <dd> - <p><a href="#parse">Parse error</a>. Ignore the token.</p> - - <dt>Anything else - - <dd> - <p>Process the token as if the <a href="#insertion0">insertion - mode</a> was "<a href="#in-table" title="insertion mode: in - table">in table</a>".</p> - </dl> - - <p>When the steps above require the UA to <dfn id=clear3>clear the - stack back to a table row context</dfn>, it means that the UA must, - while the <a href="#current4">current node</a> is not a <code><a - href="#tr">tr</a></code> element or an <code><a - href="#html">html</a></code> element, pop elements from the <a - href="#stack">stack of open elements</a>. If this causes any elements - to be popped from the stack, then this is a <a href="#parse">parse - error</a>.</p> - - <p class=note>The <a href="#current4">current node</a> being an - <code><a href="#html">html</a></code> element after this process is an - <a href="#innerhtml1"><code>innerHTML</code> case</a>.</p> - - <dt id=parsing-main-intd>If the <a href="#insertion0">insertion mode</a> - is "<dfn id=in-cell title="insertion mode: in cell">in cell</dfn>" - - <dd> - <dl class=switch> - <dt>An end tag whose tag name is one of: "td", "th" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> does not <a - href="#have-an0" title="has an element in table scope">have an - element in table scope</a> with the same tag name as that of the - token, then this is a <a href="#parse">parse error</a> and the token - must be ignored.</p> - - <p>Otherwise:</p> - - <p><a href="#generate">Generate implied end tags</a>, except for - elements with the same tag name as the token.</p> - - <p>Now, if the <a href="#current4">current node</a> is not an element - with the same tag name as the token, then this is a <a - href="#parse">parse error</a>.</p> - - <p>Pop elements from this stack until an element with the same tag - name as the token has been popped from the stack.</p> - - <p><a href="#clear0">Clear the list of active formatting elements up - to the last marker</a>.</p> - - <p>Switch the <a href="#insertion0">insertion mode</a> to "<a - href="#in-row" title="insertion mode: in row">in row</a>". (The <a - href="#current4">current node</a> will be a <code><a - href="#tr">tr</a></code> element at this point.)</p> - - <dt>A start tag whose tag name is one of: "caption", "col", - "colgroup", "tbody", "td", "tfoot", "th", "thead", "tr" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> does - <em>not</em> <a href="#have-an0" title="has an element in table - scope">have a <code>td</code> or <code>th</code> element in table - scope</a>, then this is a <a href="#parse">parse error</a>; ignore - the token. (<a href="#innerhtml1"><code>innerHTML</code> case</a>)</p> - - <p>Otherwise, <a href="#close2">close the cell</a> (see below) and - reprocess the current token.</p> - - <dt>An end tag whose tag name is one of: "body", "caption", "col", - "colgroup", "html" - - <dd> - <p><a href="#parse">Parse error</a>. Ignore the token.</p> - - <dt>An end tag whose tag name is one of: "table", "tbody", "tfoot", - "thead", "tr" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> does not <a - href="#have-an0" title="has an element in table scope">have an - element in table scope</a> with the same tag name as that of the - token (which can only happen for "tbody", "tfoot" and "thead", or, - in the <a href="#innerhtml1"><code>innerHTML</code> case</a>), then - this is a <a href="#parse">parse error</a> and the token must be - ignored.</p> - - <p>Otherwise, <a href="#close2">close the cell</a> (see below) and - reprocess the current token.</p> - - <dt>Anything else - - <dd> - <p>Process the token as if the <a href="#insertion0">insertion - mode</a> was "<a href="#in-body" title="insertion mode: in body">in - body</a>".</p> - </dl> - - <p>Where the steps above say to <dfn id=close2>close the cell</dfn>, - they mean to follow the following algorithm:</p> - - <ol> - <li> - <p>If the <a href="#stack">stack of open elements</a> <a - href="#have-an0" title="has an element in table scope">has a - <code>td</code> element in table scope</a>, then act as if an end - tag token with the tag name "td" had been seen. - - <li> - <p>Otherwise, the <a href="#stack">stack of open elements</a> will <a - href="#have-an0" title="has an element in table scope">have a - <code>th</code> element in table scope</a>; act as if an end tag - token with the tag name "th" had been seen. - </ol> - - <p class=note>The <a href="#stack">stack of open elements</a> cannot - have both a <code><a href="#td">td</a></code> and a <code><a - href="#th">th</a></code> element <a href="#have-an0" title="has an - element in table scope">in table scope</a> at the same time, nor can - it have neither when the <a href="#insertion0">insertion mode</a> is - "<a href="#in-cell" title="insertion mode: in cell">in cell</a>".</p> - - <dt id=parsing-main-inselect>If the <a href="#insertion0">insertion - mode</a> is "<dfn id=in-select title="insertion mode: in select">in - select</dfn>" - - <dd> - <p>Handle the token as follows:</p> - - <dl class=switch> - <dt>A character token - - <dd> - <p><a href="#append" title="append a character">Append the token's - character</a> to the <a href="#current4">current node</a>.</p> - - <dt>A comment token - - <dd> - <p>Append a <code>Comment</code> node to the <a - href="#current4">current node</a> with the <code - title="">data</code> attribute set to the data given in the comment - token.</p> - - <dt>A start tag token whose tag name is "option" - - <dd> - <p>If the <a href="#current4">current node</a> is an - <code>option</code> element, act as if an end tag with the tag name - "option" had been seen.</p> - - <p><a href="#insert">Insert an HTML element</a> for the token.</p> - - <dt>A start tag token whose tag name is "optgroup" - - <dd> - <p>If the <a href="#current4">current node</a> is an - <code>option</code> element, act as if an end tag with the tag name - "option" had been seen.</p> - - <p>If the <a href="#current4">current node</a> is an - <code>optgroup</code> element, act as if an end tag with the tag - name "optgroup" had been seen.</p> - - <p><a href="#insert">Insert an HTML element</a> for the token.</p> - - <dt>An end tag token whose tag name is "optgroup" - - <dd> - <p>First, if the <a href="#current4">current node</a> is an - <code>option</code> element, and the node immediately before it in - the <a href="#stack">stack of open elements</a> is an - <code>optgroup</code> element, then act as if an end tag with the - tag name "option" had been seen.</p> - - <p>If the <a href="#current4">current node</a> is an - <code>optgroup</code> element, then pop that node from the <a - href="#stack">stack of open elements</a>. Otherwise, this is a <a - href="#parse">parse error</a>, ignore the token.</p> - - <dt>An end tag token whose tag name is "option" - - <dd> - <p>If the <a href="#current4">current node</a> is an - <code>option</code> element, then pop that node from the <a - href="#stack">stack of open elements</a>. Otherwise, this is a <a - href="#parse">parse error</a>, ignore the token.</p> - - <dt>An end tag whose tag name is "select" - - <dd> - <p>If the <a href="#stack">stack of open elements</a> does not <a - href="#have-an0" title="has an element in table scope">have an - element in table scope</a> with the same tag name as the token, this - is a <a href="#parse">parse error</a>. Ignore the token. (<a - href="#innerhtml1"><code>innerHTML</code> case</a>)</p> - - <p>Otherwise:</p> - - <p>Pop elements from the <a href="#stack">stack of open elements</a> - until a <code>select</code> element has been popped from the stack.</p> - - <p><a href="#reset">Reset the insertion mode appropriately</a>.</p> - - <dt>A start tag whose tag name is "select" - - <dd> - <p><a href="#parse">Parse error</a>. Act as if the token had been an - end tag with the tag name "select" instead.</p> - - <dt>An end tag whose tag name is one of: "caption", "table", "tbody", - "tfoot", "thead", "tr", "td", "th" - - <dd> - <p><a href="#parse">Parse error</a>.</p> - - <p>If the <a href="#stack">stack of open elements</a> <a - href="#have-an0">has an element in table scope</a> with the same tag - name as that of the token, then act as if an end tag with the tag - name "select" had been seen, and reprocess the token. Otherwise, - ignore the token.</p> - - <dt>Anything else - - <dd> - <p><a href="#parse">Parse error</a>. Ignore the token.</p> - </dl> - - <dt id=parsing-main-afterbody>If the <a href="#insertion0">insertion - mode</a> is "<dfn id=after2 title="insertion mode: after body">after - body</dfn>" - - <dd> - <p>Handle the token as follows:</p> - - <dl class=switch> - <dt>A character token that is one of one of U+0009 CHARACTER - TABULATION, U+000A LINE FEED (LF), U+000B LINE TABULATION, U+000C - FORM FEED (FF), U+000D CARRIAGE RETURN (CR), or U+0020 SPACE - - <dd> - <p>Process the token as it would be processed if the <a - href="#insertion0">insertion mode</a> was "<a href="#in-body" - title="insertion mode: in body">in body</a>".</p> - - <dt>A comment token - - <dd> - <p>Append a <code>Comment</code> node to the first element in the <a - href="#stack">stack of open elements</a> (the <code><a - href="#html">html</a></code> element), with the <code - title="">data</code> attribute set to the data given in the comment - token.</p> - - <dt>An end tag with the tag name "html" - - <dd> - <p>If the parser was originally created in order to handle the - setting of <em>an element</em>'s <code title=dom-innerHTML-HTML><a - href="#innerhtml0">innerHTML</a></code> attribute, this is a <a - href="#parse">parse error</a>; ignore the token. (The element will - be an <code><a href="#html">html</a></code> element in this case.) - (<a href="#innerhtml1"><code>innerHTML</code> case</a>)</p> - - <p>Otherwise, switch to <a href="#the-trailing0">the trailing end - phase</a>.</p> - - <dt>Anything else - - <dd> - <p><a href="#parse">Parse error</a>. Set the <a - href="#insertion0">insertion mode</a> to "<a href="#in-body" - title="insertion mode: in body">in body</a>" and reprocess the - token.</p> - </dl> - - <dt id=parsing-main-inframeset>If the <a href="#insertion0">insertion - mode</a> is "<dfn id=in-frameset title="insertion mode: in frameset">in - frameset</dfn>" - - <dd> - <p>Handle the token as follows:</p> - - <dl class=switch> - <dt>A character token that is one of one of U+0009 CHARACTER - TABULATION, U+000A LINE FEED (LF), U+000B LINE TABULATION, U+000C - FORM FEED (FF), U+000D CARRIAGE RETURN (CR), or U+0020 SPACE - - <dd> - <p><a href="#append" title="append a character">Append the - character</a> to the <a href="#current4">current node</a>.</p> - - <dt>A comment token - - <dd> - <p>Append a <code>Comment</code> node to the <a - href="#current4">current node</a> with the <code - title="">data</code> attribute set to the data given in the comment - token.</p> - - <dt>A start tag with the tag name "frameset" - - <dd> - <p><a href="#insert" title="Insert an HTML element">Insert a - <code>frameset</code> element</a> for the token.</p> - - <dt>An end tag with the tag name "frameset" - - <dd> - <p>If the <a href="#current4">current node</a> is the root <code><a - href="#html">html</a></code> element, then this is a <a - href="#parse">parse error</a>; ignore the token. (<a - href="#innerhtml1"><code>innerHTML</code> case</a>)</p> - - <p>Otherwise, pop the <a href="#current4">current node</a> from the - <a href="#stack">stack of open elements</a>.</p> - - <p>If the parser was <em>not</em> originally created in order to - handle the setting of an element's <code title=dom-innerHTML-HTML><a - href="#innerhtml0">innerHTML</a></code> attribute (<a - href="#innerhtml1"><code>innerHTML</code> case</a>), and the <a - href="#current4">current node</a> is no longer a - <code>frameset</code> element, then change the <a - href="#insertion0">insertion mode</a> to "<a href="#after3" - title="insertion mode: after frameset">after frameset</a>".</p> - - <dt>A start tag with the tag name "frame" - - <dd> - <p><a href="#insert">Insert an HTML element</a> for the token. - Immediately pop the <a href="#current4">current node</a> off the <a - href="#stack">stack of open elements</a>.</p> - - <dt>A start tag with the tag name "noframes" - - <dd> - <p>Process the token as if the <a href="#insertion0">insertion - mode</a> had been "<a href="#in-body" title="insertion mode: in - body">in body</a>".</p> - - <dt>Anything else - - <dd> - <p><a href="#parse">Parse error</a>. Ignore the token.</p> - </dl> - - <dt id=parsing-main-afterframeset>If the <a href="#insertion0">insertion - mode</a> is "<dfn id=after3 title="insertion mode: after - frameset">after frameset</dfn>" - - <dd> - <p>Handle the token as follows:</p> - - <dl class=switch> - <dt>A character token that is one of one of U+0009 CHARACTER - TABULATION, U+000A LINE FEED (LF), U+000B LINE TABULATION, U+000C - FORM FEED (FF), U+000D CARRIAGE RETURN (CR), or U+0020 SPACE - - <dd> - <p><a href="#append" title="append a character">Append the - character</a> to the <a href="#current4">current node</a>.</p> - - <dt>A comment token - - <dd> - <p>Append a <code>Comment</code> node to the <a - href="#current4">current node</a> with the <code - title="">data</code> attribute set to the data given in the comment - token.</p> - - <dt>An end tag with the tag name "html" - - <dd> - <p>Switch to <a href="#the-trailing0">the trailing end phase</a>.</p> - - <dt>A start tag with the tag name "noframes" - - <dd> - <p>Process the token as if the <a href="#insertion0">insertion - mode</a> had been "<a href="#in-body" title="insertion mode: in - body">in body</a>".</p> - - <dt>Anything else - - <dd> - <p><a href="#parse">Parse error</a>. Ignore the token.</p> - </dl> - </dl> - </dl> - - <p class=big-issue>This doesn't handle UAs that don't support frames, or - that do support frames but want to show the NOFRAMES content. Supporting - the former is easy; supporting the latter is harder. - - <h5 id=the-trailing><span class=secno>8.2.4.4. </span><dfn - id=the-trailing0>The trailing end phase</dfn></h5> - - <p>After <a href="#the-main0">the main phase</a>, as each token is emitted - from the <a href="#tokenisation0">tokenisation</a> stage, it must be - processed as described in this section. - - <dl class=switch> - <dt>A DOCTYPE token - - <dd> - <p><a href="#parse">Parse error</a>. Ignore the token.</p> - - <dt>A comment token - - <dd> - <p>Append a <code>Comment</code> node to the <code>Document</code> object - with the <code title="">data</code> attribute set to the data given in - the comment token.</p> - - <dt>A character token that is one of one of U+0009 CHARACTER TABULATION, - U+000A LINE FEED (LF), U+000B LINE TABULATION, U+000C FORM FEED (FF), - U+000D CARRIAGE RETURN (CR), or U+0020 SPACE - - <dd> - <p>Process the token as it would be processed in <a href="#the-main0">the - main phase</a>.</p> - - <dt>A character token that is <em>not</em> one of U+0009 CHARACTER - TABULATION, U+000A LINE FEED (LF), U+000B LINE TABULATION, U+000C FORM - FEED (FF), U+000D CARRIAGE RETURN (CR), or U+0020 SPACE - - <dt>A start tag token - - <dt>An end tag token - - <dd> - <p><a href="#parse">Parse error</a>. Switch back to <a - href="#the-main0">the main phase</a> and reprocess the token.</p> - - <dt>An end-of-file token - - <dd> - <p><a href="#stops">Stop parsing</a>.</p> - </dl> - - <h4 id=the-end><span class=secno>8.2.5. </span>The End</h4> - - <p>Once the user agent <dfn id=stops title="stop parsing">stops - parsing</dfn> the document, the user agent must follow the steps in this - section. - - <p>First, <!--the user agent must <span title="fire a DOMContentLoaded - event">fire a <code - title="event-DOMContentLoaded">DOMContentLoaded</code> event</span> - at <span>the <code>body</code> element</span>.</p> - - <p>Then, -->the - rules for <a href="#when-a">when a script completes loading</a> start - applying (script execution is no longer managed by the parser). - - <p>If any of the scripts in the <a href="#list-of1">list of scripts that - will execute as soon as possible</a> have <span>completed - loading</span><!-- XXX xref -->, or if the <a href="#list-of0">list of - scripts that will execute asynchronously</a> is not empty and the first - script in that list has <span>completed loading</span><!-- XXX xref - -->, - then the user agent must act as if those scripts just completed loading, - following the rules given for that in the <code><a - href="#script0">script</a></code> element definition. - - <p>Then, if the <a href="#list-of">list of scripts that will execute when - the document has finished parsing</a> is not empty, and the first item in - this list has already <span>completed loading</span><!--XXX - xref -->, - then the user agent must act as if that script just finished loading. - - <p>By this point, there will be no scripts that have loaded but have not - yet been executed. - - <p>The user agent must then <a href="#firing2">fire a simple event</a> - called <code title=event-DOMContentLoaded>DOMContentLoaded</code> at the - <code>Document</code>. - - <p>Once everything that <dfn id=delays title="delay the load event">delays - the load event</dfn> has completed, the user agent must <a href="#firing4" - title="fire a load event">fire a <code title=event-load>load</code> - event</a> at <a href="#the-body0">the <code>body</code> element</a>.</p> - <!-- XXX make sure things "delay the load event" --> - <!--XXX need to handle -http://lxr.mozilla.org/mozilla/source/parser/htmlparser/src/CNavDTD.cpp#2354 -2354 // Don't open transient styles if it makes the stack deep, bug 58917. ---> - <!--XXX -http://lxr.mozilla.org/mozilla/source/parser/htmlparser/src/nsHTMLTokenizer.cpp#749 ---> - <!-- -see also CTextToken::ConsumeCharacterData() for CDATA parsing? - -1212 1 Here's a tricky case from bug 22596: <h5><li><h5> -1213 How do we know that the 2nd <h5> should close the <LI> rather than nest inside the <LI>? -1214 (Afterall, the <h5> is a legal child of the <LI>). -1215 -1216 The way you know is that there is no root between the two, so the <h5> binds more -1217 tightly to the 1st <h5> than to the <LI>. -1218 2. Also, bug 6148 shows this case: <SPAN><DIV><SPAN> -1219 From this case we learned not to execute this logic if the parent is a block. -1220 -1221 3. Fix for 26583 -1222 Ex. <A href=foo.html><B>foo<A href-bar.html>bar</A></B></A> <- A legal HTML -1223 In the above example clicking on "foo" or "bar" should link to -1224 foo.html or bar.html respectively. That is, the inner <A> should be informed -1225 about the presence of an open <A> above <B>..so that the inner <A> can close out -1226 the outer <A>. The following code does it for us. -1227 -1228 4. Fix for 27865 [ similer to 22596 ]. Ex: <DL><DD><LI>one<DD><LI>two - - http://lxr.mozilla.org/mozilla/source/parser/htmlparser/src/CNavDTD.cpp#1211 - -815 // Here's a problem. If theTag is legal in here, we don't move it -816 // out. So if we're moving stuff out of here, the parent of theTag -817 // gets closed at this point. But some things are legal -818 // _everywhere_ and hence would effectively close out misplaced -819 // content in tables. This is undesirable, so treat them as -820 // illegal here so they'll be shipped out with their parents and -821 // siblings. See bug 40855 for an explanation (that bug was for -822 // comments, but the same issues arise with whitespace, newlines, -823 // noscript, etc). Script is special, though. Shipping it out -824 // breaks document.write stuff. See bug 243064. - - http://lxr.mozilla.org/mozilla/source/parser/htmlparser/src/CNavDTD.cpp#825 - - -1326 /************************************************************************************** -1327 * -1328 * Now a little code to deal with bug #49687 (crash when layout stack gets too deep) -1329 * I've also opened this up to any container (not just inlines): re bug 55095 -1330 * Improved to handle bug 55980 (infinite loop caused when DEPTH is exceeded and -1331 * </P> is encountered by itself (<P>) is continuously produced. -1332 * -1333 **************************************************************************************/ - -1912 // Oh boy!! we found a "stray" tag. Nav4.x and IE introduce line break in -1913 // such cases. So, let's simulate that effect for compatibility. -1914 // Ex. <html><body>Hello</P>There</body></html> -http://lxr.mozilla.org/mozilla/source/parser/htmlparser/src/CNavDTD.cpp#1912 - -http://lxr.mozilla.org/seamonkey/search?string=nested -/parser/htmlparser/src/CNavDTD.cpp, line 791 - * 2. <CENTER><DL><DT><A><CENTER> allow nested <CENTER> -/parser/htmlparser/src/CNavDTD.cpp, line 792 - * 3. <TABLE><TR><TD><TABLE>... allow nested <TABLE> -/parser/htmlparser/src/CNavDTD.cpp, line 2562 - // Discard nested forms - bug 72639 -/parser/htmlparser/src/nsElementTable.cpp, line 1453 - * 2. <CENTER><DL><DT><A><CENTER> allow nested <CENTER> -/parser/htmlparser/src/nsElementTable.cpp, line 1454 - * 3. <TABLE><TR><TD><TABLE>... allow nested <TABLE> -/parser/htmlparser/src/nsElementTable.cpp, line 1901 - // Ex: <H1><LI><H1><LI>. Inner LI has the potential of getting nested ---> - - <h3 id=namespaces><span class=secno>8.3. </span>Namespaces</h3> - - <p>The <dfn id=html-namespace0>HTML namespace</dfn> is: - <code>http://www.w3.org/1999/xhtml</code> - - <h3 id=entities><span class=secno>8.4. </span><dfn - id=entities0>Entities</dfn></h3> - - <p>This table lists the entity names that are supported by HTML, and the - code points to which they refer. It is referenced by the previous - sections.</p> - <!--XXX - entities: - 94 // If an entity value is greater than 255 then: - 95 // Nav 4.x does not treat it as an entity, - 96 // IE treats it as an entity if terminated with a semicolon. - 97 // Resembling IE!! -http://lxr.mozilla.org/mozilla/source/parser/htmlparser/src/nsHTMLTokens.cpp#94 ---> - - <table> - <thead> - <tr> - <th> Entity Name - - <th> Character - - <tbody> - <tr> - <td> <code title="">AElig</code> - - <td> U+00C6 - - <tr> - <td> <code title="">Aacute</code> - - <td> U+00C1 - - <tr> - <td> <code title="">Acirc</code> - - <td> U+00C2 - - <tr> - <td> <code title="">Agrave</code> - - <td> U+00C0 - - <tr> - <td> <code title="">Alpha</code> - - <td> U+0391 - - <tr> - <td> <code title="">Aring</code> - - <td> U+00C5 - - <tr> - <td> <code title="">Atilde</code> - - <td> U+00C3 - - <tr> - <td> <code title="">Auml</code> - - <td> U+00C4 - - <tr> - <td> <code title="">Beta</code> - - <td> U+0392 - - <tr> - <td> <code title="">Ccedil</code> - - <td> U+00C7 - - <tr> - <td> <code title="">Chi</code> - - <td> U+03A7 - - <tr> - <td> <code title="">Dagger</code> - - <td> U+2021 - - <tr> - <td> <code title="">Delta</code> - - <td> U+0394 - - <tr> - <td> <code title="">ETH</code> - - <td> U+00D0 - - <tr> - <td> <code title="">Eacute</code> - - <td> U+00C9 - - <tr> - <td> <code title="">Ecirc</code> - - <td> U+00CA - - <tr> - <td> <code title="">Egrave</code> - - <td> U+00C8 - - <tr> - <td> <code title="">Epsilon</code> - - <td> U+0395 - - <tr> - <td> <code title="">Eta</code> - - <td> U+0397 - - <tr> - <td> <code title="">Euml</code> - - <td> U+00CB - - <tr> - <td> <code title="">Gamma</code> - - <td> U+0393 - - <tr> - <td> <code title="">Iacute</code> - - <td> U+00CD - - <tr> - <td> <code title="">Icirc</code> - - <td> U+00CE - - <tr> - <td> <code title="">Igrave</code> - - <td> U+00CC - - <tr> - <td> <code title="">Iota</code> - - <td> U+0399 - - <tr> - <td> <code title="">Iuml</code> - - <td> U+00CF - - <tr> - <td> <code title="">Kappa</code> - - <td> U+039A - - <tr> - <td> <code title="">Lambda</code> - - <td> U+039B - - <tr> - <td> <code title="">Mu</code> - - <td> U+039C - - <tr> - <td> <code title="">Ntilde</code> - - <td> U+00D1 - - <tr> - <td> <code title="">Nu</code> - - <td> U+039D - - <tr> - <td> <code title="">OElig</code> - - <td> U+0152 - - <tr> - <td> <code title="">Oacute</code> - - <td> U+00D3 - - <tr> - <td> <code title="">Ocirc</code> - - <td> U+00D4 - - <tr> - <td> <code title="">Ograve</code> - - <td> U+00D2 - - <tr> - <td> <code title="">Omega</code> - - <td> U+03A9 - - <tr> - <td> <code title="">Omicron</code> - - <td> U+039F - - <tr> - <td> <code title="">Oslash</code> - - <td> U+00D8 - - <tr> - <td> <code title="">Otilde</code> - - <td> U+00D5 - - <tr> - <td> <code title="">Ouml</code> - - <td> U+00D6 - - <tr> - <td> <code title="">Phi</code> - - <td> U+03A6 - - <tr> - <td> <code title="">Pi</code> - - <td> U+03A0 - - <tr> - <td> <code title="">Prime</code> - - <td> U+2033 - - <tr> - <td> <code title="">Psi</code> - - <td> U+03A8 - - <tr> - <td> <code title="">Rho</code> - - <td> U+03A1 - - <tr> - <td> <code title="">Scaron</code> - - <td> U+0160 - - <tr> - <td> <code title="">Sigma</code> - - <td> U+03A3 - - <tr> - <td> <code title="">THORN</code> - - <td> U+00DE - - <tr> - <td> <code title="">Tau</code> - - <td> U+03A4 - - <tr> - <td> <code title="">Theta</code> - - <td> U+0398 - - <tr> - <td> <code title="">Uacute</code> - - <td> U+00DA - - <tr> - <td> <code title="">Ucirc</code> - - <td> U+00DB - - <tr> - <td> <code title="">Ugrave</code> - - <td> U+00D9 - - <tr> - <td> <code title="">Upsilon</code> - - <td> U+03A5 - - <tr> - <td> <code title="">Uuml</code> - - <td> U+00DC - - <tr> - <td> <code title="">Xi</code> - - <td> U+039E - - <tr> - <td> <code title="">Yacute</code> - - <td> U+00DD - - <tr> - <td> <code title="">Yuml</code> - - <td> U+0178 - - <tr> - <td> <code title="">Zeta</code> - - <td> U+0396 - - <tr> - <td> <code title="">aacute</code> - - <td> U+00E1 - - <tr> - <td> <code title="">acirc</code> - - <td> U+00E2 - - <tr> - <td> <code title="">acute</code> - - <td> U+00B4 - - <tr> - <td> <code title="">aelig</code> - - <td> U+00E6 - - <tr> - <td> <code title="">agrave</code> - - <td> U+00E0 - - <tr> - <td> <code title="">alefsym</code> - - <td> U+2135 - - <tr> - <td> <code title="">alpha</code> - - <td> U+03B1 - - <tr> - <td> <code title="">amp</code> - - <td> U+0026 - - <tr> - <td> <code title="">AMP</code> - - <td> U+0026 - - <tr> - <td> <code title="">and</code> - - <td> U+2227 - - <tr> - <td> <code title="">ang</code> - - <td> U+2220 - - <tr> - <td> <code title="">apos</code> - - <td> U+0027 - - <tr> - <td> <code title="">aring</code> - - <td> U+00E5 - - <tr> - <td> <code title="">asymp</code> - - <td> U+2248 - - <tr> - <td> <code title="">atilde</code> - - <td> U+00E3 - - <tr> - <td> <code title="">auml</code> - - <td> U+00E4 - - <tr> - <td> <code title="">bdquo</code> - - <td> U+201E - - <tr> - <td> <code title="">beta</code> - - <td> U+03B2 - - <tr> - <td> <code title="">brvbar</code> - - <td> U+00A6 - - <tr> - <td> <code title="">bull</code> - - <td> U+2022 - - <tr> - <td> <code title="">cap</code> - - <td> U+2229 - - <tr> - <td> <code title="">ccedil</code> - - <td> U+00E7 - - <tr> - <td> <code title="">cedil</code> - - <td> U+00B8 - - <tr> - <td> <code title="">cent</code> - - <td> U+00A2 - - <tr> - <td> <code title="">chi</code> - - <td> U+03C7 - - <tr> - <td> <code title="">circ</code> - - <td> U+02C6 - - <tr> - <td> <code title="">clubs</code> - - <td> U+2663 - - <tr> - <td> <code title="">cong</code> - - <td> U+2245 - - <tr> - <td> <code title="">copy</code> - - <td> U+00A9 - - <tr> - <td> <code title="">COPY</code> - - <td> U+00A9 - - <tr> - <td> <code title="">crarr</code> - - <td> U+21B5 - - <tr> - <td> <code title="">cup</code> - - <td> U+222A - - <tr> - <td> <code title="">curren</code> - - <td> U+00A4 - - <tr> - <td> <code title="">dArr</code> - - <td> U+21D3 - - <tr> - <td> <code title="">dagger</code> - - <td> U+2020 - - <tr> - <td> <code title="">darr</code> - - <td> U+2193 - - <tr> - <td> <code title="">deg</code> - - <td> U+00B0 - - <tr> - <td> <code title="">delta</code> - - <td> U+03B4 - - <tr> - <td> <code title="">diams</code> - - <td> U+2666 - - <tr> - <td> <code title="">divide</code> - - <td> U+00F7 - - <tr> - <td> <code title="">eacute</code> - - <td> U+00E9 - - <tr> - <td> <code title="">ecirc</code> - - <td> U+00EA - - <tr> - <td> <code title="">egrave</code> - - <td> U+00E8 - - <tr> - <td> <code title="">empty</code> - - <td> U+2205 - - <tr> - <td> <code title="">emsp</code> - - <td> U+2003 - - <tr> - <td> <code title="">ensp</code> - - <td> U+2002 - - <tr> - <td> <code title="">epsilon</code> - - <td> U+03B5 - - <tr> - <td> <code title="">equiv</code> - - <td> U+2261 - - <tr> - <td> <code title="">eta</code> - - <td> U+03B7 - - <tr> - <td> <code title="">eth</code> - - <td> U+00F0 - - <tr> - <td> <code title="">euml</code> - - <td> U+00EB - - <tr> - <td> <code title="">euro</code> - - <td> U+20AC - - <tr> - <td> <code title="">exist</code> - - <td> U+2203 - - <tr> - <td> <code title="">fnof</code> - - <td> U+0192 - - <tr> - <td> <code title="">forall</code> - - <td> U+2200 - - <tr> - <td> <code title="">frac12</code> - - <td> U+00BD - - <tr> - <td> <code title="">frac14</code> - - <td> U+00BC - - <tr> - <td> <code title="">frac34</code> - - <td> U+00BE - - <tr> - <td> <code title="">frasl</code> - - <td> U+2044 - - <tr> - <td> <code title="">gamma</code> - - <td> U+03B3 - - <tr> - <td> <code title="">ge</code> - - <td> U+2265 - - <tr> - <td> <code title="">gt</code> - - <td> U+003E - - <tr> - <td> <code title="">GT</code> - - <td> U+003E - - <tr> - <td> <code title="">hArr</code> - - <td> U+21D4 - - <tr> - <td> <code title="">harr</code> - - <td> U+2194 - - <tr> - <td> <code title="">hearts</code> - - <td> U+2665 - - <tr> - <td> <code title="">hellip</code> - - <td> U+2026 - - <tr> - <td> <code title="">iacute</code> - - <td> U+00ED - - <tr> - <td> <code title="">icirc</code> - - <td> U+00EE - - <tr> - <td> <code title="">iexcl</code> - - <td> U+00A1 - - <tr> - <td> <code title="">igrave</code> - - <td> U+00EC - - <tr> - <td> <code title="">image</code> - - <td> U+2111 - - <tr> - <td> <code title="">infin</code> - - <td> U+221E - - <tr> - <td> <code title="">int</code> - - <td> U+222B - - <tr> - <td> <code title="">iota</code> - - <td> U+03B9 - - <tr> - <td> <code title="">iquest</code> - - <td> U+00BF - - <tr> - <td> <code title="">isin</code> - - <td> U+2208 - - <tr> - <td> <code title="">iuml</code> - - <td> U+00EF - - <tr> - <td> <code title="">kappa</code> - - <td> U+03BA - - <tr> - <td> <code title="">lArr</code> - - <td> U+21D0 - - <tr> - <td> <code title="">lambda</code> - - <td> U+03BB - - <tr> - <td> <code title="">lang</code> - - <td> U+2329 - - <tr> - <td> <code title="">laquo</code> - - <td> U+00AB - - <tr> - <td> <code title="">larr</code> - - <td> U+2190 - - <tr> - <td> <code title="">lceil</code> - - <td> U+2308 - - <tr> - <td> <code title="">ldquo</code> - - <td> U+201C - - <tr> - <td> <code title="">le</code> - - <td> U+2264 - - <tr> - <td> <code title="">lfloor</code> - - <td> U+230A - - <tr> - <td> <code title="">lowast</code> - - <td> U+2217 - - <tr> - <td> <code title="">loz</code> - - <td> U+25CA - - <tr> - <td> <code title="">lrm</code> - - <td> U+200E - - <tr> - <td> <code title="">lsaquo</code> - - <td> U+2039 - - <tr> - <td> <code title="">lsquo</code> - - <td> U+2018 - - <tr> - <td> <code title="">lt</code> - - <td> U+003C - - <tr> - <td> <code title="">LT</code> - - <td> U+003C - - <tr> - <td> <code title="">macr</code> - - <td> U+00AF - - <tr> - <td> <code title="">mdash</code> - - <td> U+2014 - - <tr> - <td> <code title="">micro</code> - - <td> U+00B5 - - <tr> - <td> <code title="">middot</code> - - <td> U+00B7 - - <tr> - <td> <code title="">minus</code> - - <td> U+2212 - - <tr> - <td> <code title="">mu</code> - - <td> U+03BC - - <tr> - <td> <code title="">nabla</code> - - <td> U+2207 - - <tr> - <td> <code title="">nbsp</code> - - <td> U+00A0 - - <tr> - <td> <code title="">ndash</code> - - <td> U+2013 - - <tr> - <td> <code title="">ne</code> - - <td> U+2260 - - <tr> - <td> <code title="">ni</code> - - <td> U+220B - - <tr> - <td> <code title="">not</code> - - <td> U+00AC - - <tr> - <td> <code title="">notin</code> - - <td> U+2209 - - <tr> - <td> <code title="">nsub</code> - - <td> U+2284 - - <tr> - <td> <code title="">ntilde</code> - - <td> U+00F1 - - <tr> - <td> <code title="">nu</code> - - <td> U+03BD - - <tr> - <td> <code title="">oacute</code> - - <td> U+00F3 - - <tr> - <td> <code title="">ocirc</code> - - <td> U+00F4 - - <tr> - <td> <code title="">oelig</code> - - <td> U+0153 - - <tr> - <td> <code title="">ograve</code> - - <td> U+00F2 - - <tr> - <td> <code title="">oline</code> - - <td> U+203E - - <tr> - <td> <code title="">omega</code> - - <td> U+03C9 - - <tr> - <td> <code title="">omicron</code> - - <td> U+03BF - - <tr> - <td> <code title="">oplus</code> - - <td> U+2295 - - <tr> - <td> <code title="">or</code> - - <td> U+2228 - - <tr> - <td> <code title="">ordf</code> - - <td> U+00AA - - <tr> - <td> <code title="">ordm</code> - - <td> U+00BA - - <tr> - <td> <code title="">oslash</code> - - <td> U+00F8 - - <tr> - <td> <code title="">otilde</code> - - <td> U+00F5 - - <tr> - <td> <code title="">otimes</code> - - <td> U+2297 - - <tr> - <td> <code title="">ouml</code> - - <td> U+00F6 - - <tr> - <td> <code title="">para</code> - - <td> U+00B6 - - <tr> - <td> <code title="">part</code> - - <td> U+2202 - - <tr> - <td> <code title="">permil</code> - - <td> U+2030 - - <tr> - <td> <code title="">perp</code> - - <td> U+22A5 - - <tr> - <td> <code title="">phi</code> - - <td> U+03C6 - - <tr> - <td> <code title="">pi</code> - - <td> U+03C0 - - <tr> - <td> <code title="">piv</code> - - <td> U+03D6 - - <tr> - <td> <code title="">plusmn</code> - - <td> U+00B1 - - <tr> - <td> <code title="">pound</code> - - <td> U+00A3 - - <tr> - <td> <code title="">prime</code> - - <td> U+2032 - - <tr> - <td> <code title="">prod</code> - - <td> U+220F - - <tr> - <td> <code title="">prop</code> - - <td> U+221D - - <tr> - <td> <code title="">psi</code> - - <td> U+03C8 - - <tr> - <td> <code title="">quot</code> - - <td> U+0022 - - <tr> - <td> <code title="">QUOT</code> - - <td> U+0022 - - <tr> - <td> <code title="">rArr</code> - - <td> U+21D2 - - <tr> - <td> <code title="">radic</code> - - <td> U+221A - - <tr> - <td> <code title="">rang</code> - - <td> U+232A - - <tr> - <td> <code title="">raquo</code> - - <td> U+00BB - - <tr> - <td> <code title="">rarr</code> - - <td> U+2192 - - <tr> - <td> <code title="">rceil</code> - - <td> U+2309 - - <tr> - <td> <code title="">rdquo</code> - - <td> U+201D - - <tr> - <td> <code title="">real</code> - - <td> U+211C - - <tr> - <td> <code title="">reg</code> - - <td> U+00AE - - <tr> - <td> <code title="">REG</code> - - <td> U+00AE - - <tr> - <td> <code title="">rfloor</code> - - <td> U+230B - - <tr> - <td> <code title="">rho</code> - - <td> U+03C1 - - <tr> - <td> <code title="">rlm</code> - - <td> U+200F - - <tr> - <td> <code title="">rsaquo</code> - - <td> U+203A - - <tr> - <td> <code title="">rsquo</code> - - <td> U+2019 - - <tr> - <td> <code title="">sbquo</code> - - <td> U+201A - - <tr> - <td> <code title="">scaron</code> - - <td> U+0161 - - <tr> - <td> <code title="">sdot</code> - - <td> U+22C5 - - <tr> - <td> <code title="">sect</code> - - <td> U+00A7 - - <tr> - <td> <code title="">shy</code> - - <td> U+00AD - - <tr> - <td> <code title="">sigma</code> - - <td> U+03C3 - - <tr> - <td> <code title="">sigmaf</code> - - <td> U+03C2 - - <tr> - <td> <code title="">sim</code> - - <td> U+223C - - <tr> - <td> <code title="">spades</code> - - <td> U+2660 - - <tr> - <td> <code title="">sub</code> - - <td> U+2282 - - <tr> - <td> <code title="">sube</code> - - <td> U+2286 - - <tr> - <td> <code title="">sum</code> - - <td> U+2211 - - <tr> - <td> <code title="">sup</code> - - <td> U+2283 - - <tr> - <td> <code title="">sup1</code> - - <td> U+00B9 - - <tr> - <td> <code title="">sup2</code> - - <td> U+00B2 - - <tr> - <td> <code title="">sup3</code> - - <td> U+00B3 - - <tr> - <td> <code title="">supe</code> - - <td> U+2287 - - <tr> - <td> <code title="">szlig</code> - - <td> U+00DF - - <tr> - <td> <code title="">tau</code> - - <td> U+03C4 - - <tr> - <td> <code title="">there4</code> - - <td> U+2234 - - <tr> - <td> <code title="">theta</code> - - <td> U+03B8 - - <tr> - <td> <code title="">thetasym</code> - - <td> U+03D1 - - <tr> - <td> <code title="">thinsp</code> - - <td> U+2009 - - <tr> - <td> <code title="">thorn</code> - - <td> U+00FE - - <tr> - <td> <code title="">tilde</code> - - <td> U+02DC - - <tr> - <td> <code title="">times</code> - - <td> U+00D7 - - <tr> - <td> <code title="">trade</code> - - <td> U+2122 - - <tr> - <td> <code title="">TRADE</code> - - <td> U+2122 - - <tr> - <td> <code title="">uArr</code> - - <td> U+21D1 - - <tr> - <td> <code title="">uacute</code> - - <td> U+00FA - - <tr> - <td> <code title="">uarr</code> - - <td> U+2191 - - <tr> - <td> <code title="">ucirc</code> - - <td> U+00FB - - <tr> - <td> <code title="">ugrave</code> - - <td> U+00F9 - - <tr> - <td> <code title="">uml</code> - - <td> U+00A8 - - <tr> - <td> <code title="">upsih</code> - - <td> U+03D2 - - <tr> - <td> <code title="">upsilon</code> - - <td> U+03C5 - - <tr> - <td> <code title="">uuml</code> - - <td> U+00FC - - <tr> - <td> <code title="">weierp</code> - - <td> U+2118 - - <tr> - <td> <code title="">xi</code> - - <td> U+03BE - - <tr> - <td> <code title="">yacute</code> - - <td> U+00FD - - <tr> - <td> <code title="">yen</code> - - <td> U+00A5 - - <tr> - <td> <code title="">yuml</code> - - <td> U+00FF - - <tr> - <td> <code title="">zeta</code> - - <td> U+03B6 - - <tr> - <td> <code title="">zwj</code> - - <td> U+200D - - <tr> - <td> <code title="">zwnj</code> - - <td> U+200C - </table> - - <h2 id=wysiwyg><span class=secno>9. </span>WYSIWYG editors</h2> - - <p><dfn id=wysiwyg1>WYSIWYG editors</dfn> are authoring tools with a - predominantly presentation-driven user interface. - - <h3 id=presentational><span class=secno>9.1. </span>Presentational markup</h3> - - <h4 id=wysiwyg0><span class=secno>9.1.1. </span><dfn id=wysiwyg2>WYSIWYG - signature</dfn></h4> - - <p>WYSIWYG editors must include a <code><a href="#meta0">meta</a></code> - element in the <code><a href="#head">head</a></code> element whose <code - title=attr-meta-name><a href="#name">name</a></code> attribute has the - value <code title=meta-generator><a href="#generator">generator</a></code> - and whose <code title=attr-meta-content><a - href="#content0">content</a></code> attribute's value ends with the string - "<code title="">(WYSIWYG editor)</code>". Non-WYSIWYG authoring tools must - not include this string in their generator string. - - <h4 id=the-font><span class=secno>9.1.2. </span>The <dfn - id=font><code>font</code></dfn> element</h4> - - <p><a href="#transparent0">Transparent</a> <a href="#block-level0" - title="block-level elements">block-level element</a>, and <a - href="#transparent0">transparent</a> <a href="#strictly">strictly - inline-level content</a>. - - <dl class=element> - <dt>Contexts in which this element may be used: - - <dd>Where <span>block-level content</span> is allowed. - - <dd>Where <a href="#strictly">strictly inline-level content</a> is - allowed. - - <dt>Content model: - - <dd><a href="#transparent0">Transparent</a>. - - <dt>Element-specific attributes:</dt> - <!-- - <dd><code title="attr-font-color">color</code></dd> - <dd><code title="attr-font-face">face</code></dd> - <dd><code title="attr-font-size">size</code></dd>--> - - <dd><code title=attr-font-style><a href="#style0">style</a></code> - - <dt>DOM interface: - - <dd> - <pre - class=idl>interface <dfn id=htmlfontelement>HTMLFontElement</dfn> : <a href="#htmlelement">HTMLElement</a> {<!-- - attribute DOMString <span title="dom-font-color">color</span>; - attribute DOMString <span title="dom-font-face">face</span>; - attribute DOMString <span title="dom-font-size">size</span>;--> - readonly attribute CSSStyleDeclaration <a href="#style1" title=dom-font-style>style</a>; -};</pre> - </dl> - - <p>The <code><a href="#font">font</a></code> element doesn't represent - anything. It must not be used except by <a href="#wysiwyg1">WYSIWYG - editors</a>, which may use it to achieve presentational affects. Even - WYSIWYG editors, however, should make every effort to use appropriate - semantic markup and avoid the use of media-specific presentational markup. - - <p>Conformance checkers must consider this element to be non-conforming if - it is used on a page lacking the <a href="#wysiwyg2">WYSIWYG - signature</a>. - - <p>A <code><a href="#font">font</a></code> element can only contain content - that would still be conformant if all elements with <a - href="#transparent0">transparent</a> content models were replaced by their - contents. - - <div class=example> - <p>The following would be syntactically legal (as the output from a - WYSIWYG editor, though not anywhere else):</p> - - <pre><!DOCTYPE HTML> -<html> - <head> - <title></title> - <meta name="generator" content="Sample Editor 1.0 <em>(WYSIWYG editor)</em>"> - </head> - <body> - <font style="display: block; border: solid"> - <h1>Hello.</h1> - </font> - <p> - <font style="color: orange; background: white">How</font> - <font style="color: yellow; background: white">do</font> - <font style="color: green; background: white"><em><em></em>you<em></em></em></font> - <font style="color: blue; background: white">do?</font> - </p> - </body> -</html></pre> - - <p>The first <code><a href="#font">font</a></code> element is conformant - because <code><a href="#h1">h1</a></code> and <code><a - href="#p">p</a></code> elements are both allowed in <code><a - href="#body0">body</a></code> elements. the next four are allowed because - text and <code><a href="#em">em</a></code> elements are allowed in - <code><a href="#p">p</a></code> elements.</p> - </div> - - <p>The <dfn id=style0 title=attr-font-style><code>style</code></dfn> - attribute, if specified, must contain only a list of zero or more - semicolon-separated (;) CSS declarations. <a href="#refsCSS21">[CSS21]</a></p> - <!-- XXX deal with each of the use cases in this: - http://lists.w3.org/Archives/Public/www-html/2003Jan/0277.html --> - - <p>The declarations specified must be parsed and treated as the body of a - declaration block whose selector matches just that <code><a - href="#font">font</a></code> element. For the purposes of the CSS cascade, - the attribute must be considered to be a 'style' attribute at the author - level. - - <p>The <dfn id=style1 title=dom-font-style><code>style</code></dfn> DOM - attribute must return a <code>CSSStyleDeclaration</code> whose value - represents the declarations specified in the attribute, if present. - Mutating the <code>CSSStyleDeclaration</code> object must create a <code - title=attr-font-style><a href="#style0">style</a></code> attribute on the - element (if there isn't one already) and then change its value to be a - value representing the serialised form of the - <code>CSSStyleDeclaration</code> object. <a href="#refsCSSOM">[CSSOM]</a> - - <h2 id=rendering><span class=secno>10. </span>Rendering</h2> - - <p class=big-issue>This section will probably include details on how to - render DATAGRID (including <span id=datagridPseudos>its - pseudo-elements</span>), drag-and-drop, etc, in a visual medium, in - concert with CSS. Terms that need to be defined include: <dfn - id=sizing>sizing of embedded content</dfn> - - <p>CSS UAs in visual media must, when scrolling a page to a fragment - identifier, align the top of the viewport with the target element's top - border edge.</p> - <!-- XXX horiz pos given bidi, and not - scrolling when not required to? --> - <!-- Elements that have been dropped: ACRONYM APPLET B BASEFONT BLINK -BIG CENTER DIR DIV FONT FRAME FRAMESET I ISINDEX MARQUEE NOEMBED -NOFRAMES S SPACER STRIKE TT U --> - <!-- XXX bits and pieces that were removed from the semantic parts: - - <p>In CSS-aware user agents, the default presentation of this - element should be achieved by including the following rules, or - their equivalent, in the UA's user agent style sheet:</p> - - <pre>@namespace xh url(http://www.w3.org/1999/xhtml); -xh|section { display: block; margin: 1em 0; }</pre> - - <h4>Section headers</h4> - - <p>For <code>h1</code> elements, CSS-aware visual user agents should - derive the size of the header from the level of <code>section</code> - nesting. This effect should be achieved by including the following - rules, or their equivalent, in the UA's user agent style sheet:</p> - - <pre>@namespace xh url(http://www.w3.org/1999/xhtml); -xh|section xh|h1 { /* same styles as h2 */ } -xh|section xh|section xh|h1 { /* same styles as h4 */ } -xh|section xh|section xh|section xh|h1 { /* same styles as h4 */ } -xh|section xh|section xh|section xh|section xh|h1 { /* same styles as h5 */ } -xh|section xh|section xh|section xh|section xh|section xh|h1 { /* same styles as h6 */ }</pre> - - <p>Authors should use <code>h1</code> elements to denote headers in - sections. Authors may instead use <code>h2</code> ... - <code>h6</code> elements, for backwards compatibility with user - agents that do not support <code>section</code> elements.</p> - ---> - - <p class=big-issue> must define letting the user <dfn id=obtain>obtain a - physical form</dfn> of a document (printing) and what this means for the - UA - - <h3 id=rendering0><span class=secno>10.1. </span>Rendering and the DOM</h3> - - <p class=big-issue>This section is wrong. mediaMode will end up on Window, - I think. All views implement Window. - - <p>Any object implement the <code>AbstractView</code> interface must also - implement the <code><a - href="#mediamodeabstractview">MediaModeAbstractView</a></code> interface. - - <pre - class=idl>interface <dfn id=mediamodeabstractview>MediaModeAbstractView</dfn> { - readonly attribute DOMString <a href="#mediamode">mediaMode</a>; -};</pre> - - <p>The <dfn id=mediamode><code>mediaMode</code></dfn> attribute on objects - implementing the <code><a - href="#mediamodeabstractview">MediaModeAbstractView</a></code> interface - must return the string that represents the canvas' current rendering mode - (<code>screen</code>, <code>print</code>, etc). This is a lowercase - string, as <a - href="http://www.w3.org/TR/CSS21/media.html#media-types">defined by the - CSS specification</a>. <a href="#refsCSS21">[CSS21]</a> - - <p>Some user agents may support multiple media, in which case there will - exist multiple objects implementing the <code>AbstractView</code> - interface. Only the default view implements the <code><a - href="#window">Window</a></code> interface. The other views can be reached - using the <code><a href="#view">view</a></code> attribute of the - <code>UIEvent</code> inteface, during event propagation. There is no way - currently to enumerate all the views.</p> - <!-- XXX examples! --> - - <h2 id=no><span class=secno>11. </span>Things that you can't do with this - specification because they are better handled using other technologies - that are further described herein</h2> - - <p><em>This section is non-normative.</em> - - <p>There are certain features that are not handled by this specification - because a client side markup language is not the right level for them, or - because the features exist in other languages that can be integrated into - this one. This section covers some of the more common requests. - - <h3 id=localisation><span class=secno>11.1. </span>Localisation</h3> - - <p>If you wish to create localised versions of an HTML application, the - best solution is to preprocess the files on the server, and then use HTTP - content negotation to serve the appropriate language.</p> - <!-- <p>XXX example here</p> --> - - <h3 id=declarative><span class=secno>11.2. </span>Declarative 2D vector - graphics and animation</h3> - - <p>Embedding vector graphics into XHTML documents is the domain of SVG.</p> - <!-- <p>XXX example here</p> --> - - <h3 id=declarative0><span class=secno>11.3. </span>Declarative 3D scenes</h3> - - <p>Embedding 3D imagery into XHTML documents is the domain of X3D, or - technologies based on X3D that are namespace-aware.</p> - <!-- <p>XXX example here</p> --> - - <h3 id=timers><span class=secno>11.4. </span>Timers</h3> - - <p>This section is expected to be moved to the Window Object specification - in due course. - - <pre class=idl> -interface <dfn id=windowtimers>WindowTimers</dfn> { - // timers - long <a href="#settimeout">setTimeout</a>(in <a href="#timeouthandler">TimeoutHandler</a> handler, in long timeout); - long <a href="#settimeout">setTimeout</a>(in <a href="#timeouthandler">TimeoutHandler</a> handler, in long timeout, <var title="">arguments...</var>); - long <a href="#settimeout">setTimeout</a>(in DOMString code, in long timeout); - long <a href="#settimeout">setTimeout</a>(in DOMString code, in long timeout, in DOMString language); - void <a href="#cleartimeout">clearTimeout</a>(in long handle); - long <a href="#setinterval...">setInterval</a>(in <a href="#timeouthandler">TimeoutHandler</a> handler, in long timeout); - long <a href="#setinterval...">setInterval</a>(in <a href="#timeouthandler">TimeoutHandler</a> handler, in long timeout, <var title="">arguments...</var>); - long <a href="#setinterval...">setInterval</a>(in DOMString code, in long timeout); - long <a href="#setinterval...">setInterval</a>(in DOMString code, in long timeout, in DOMString language); - void <a href="#clearinterval">clearInterval</a>(in long handle); -}; - -interface <dfn id=timeouthandler>TimeoutHandler</dfn> { - void handleEvent(<var title="">arguments...</var>); -}; -</pre> - - <p>The <code><a href="#windowtimers">WindowTimers</a></code> interface must - be obtainable from any <code><a href="#window">Window</a></code> object - using binding-specific casting methods. - - <p>The <code><a href="#settimeout">setTimeout</a></code> and <code><a - href="#setinterval...">setInterval</a></code> methods allow authors to - schedule timer-based events. - - <p>The <dfn id=settimeout title=setTimeout><code>setTimeout(<var - title="">handler</var>, <var title="">timeout</var>[, <var - title="">arguments...</var>])</code></dfn> method takes a reference to a - <code><a href="#timeouthandler">TimeoutHandler</a></code> object and a - length of time in milliseconds. It must return a handle to the timeout - created, and then asynchronously wait <var title="">timeout</var> - milliseconds and then invoke <code>handleEvent()</code> on the <var - title="">handler</var> object. If any <var title="">arguments...</var> - were provided, they must be passed to the <var title="">handler</var> as - arguments to the <code>handleEvent()</code> function. - - <p>In the ECMAScript DOM binding, the ECMAScript native - <code>Function</code> type must implement the <code><a - href="#timeouthandler">TimeoutHandler</a></code> interface such that - invoking the <code>handleEvent()</code> method of that interface on the - object from another language binding invokes the function itself, with the - arguments passed to <code>handleEvent()</code> as the arguments passed to - the function. In the ECMAScript DOM binding itself, however, the - <code>handleEvent()</code> method of the interface is not directly - accessible on <code>Function</code> objects. Such functions must be called - in the scope of the <a href="#browsing0">browsing context</a> in which - they were created. - - <p>Alternatively, <dfn id=settimeout0 title=""><code>setTimeout(<var - title="">code</var>, <var title="">timeout</var>[, <var - title="">language</var>])</code></dfn> may be used. This variant takes a - string instead of a <code><a - href="#timeouthandler">TimeoutHandler</a></code> object. That string must - be parsed using the specified <var title="">language</var> (defaulting to - ECMAScript if the third argument is omitted) and executed in the scope of - the <a href="#browsing0">browsing context</a> associated with the <code><a - href="#window">Window</a></code> object on which the <code - title=setTimeout><a href="#settimeout">setTimeout()</a></code> method was - invoked. - - <p class=big-issue>Need to define <var title="">language</var> values. - - <p>The <dfn id=setinterval...><code>setInterval(...)</code></dfn> variants - must work in the same way as the <code><a - href="#settimeout">setTimeout</a></code> variants except that the <var - title="">handler</var> or <code><a href="#code">code</a></code> must be - invoked again every <var title="">timeout</var> milliseconds, not just the - once. - - <p>The <dfn id=cleartimeout><code>clearTimeout()</code></dfn> and <dfn - id=clearinterval><code>clearInterval()</code></dfn> methods take one - integer (the value returned by <code><a - href="#settimeout">setTimeout</a></code> and <code><a - href="#setinterval...">setInterval</a></code> respectively) and must - cancel the specified timeout. When called with a value that does not - correspond to an active timeout or interval, the methods must return - without doing anything. - - <p>Timeouts must never fire while another script is executing. (Thus the - HTML scripting model is strictly single-threaded and not reentrant.) - - <h3 id=events2><span class=secno>11.5. </span>Events</h3> - - <p id=js-function-listener>In the ECMAScript DOM binding, the ECMAScript - native <code>Function</code> type must implement the - <code>EventListener</code> interface such that invoking the - <code>handleEvent()</code> method of that interface on the object from - another language binding invokes the function itself, with the - <code>event</code> argument as its only argument. In the ECMAScript - binding itself, however, the <code>handleEvent()</code> method of the - interface is not directly accessible on <code>Function</code> objects. - Such functions, when invoked, must be called in the scope of the <a - href="#browsing0">browsing context</a> that they were created in. - - <h2 class=no-num id=references>References</h2> - - <p class=big-issue>This section will be written in a future - draft.<!--XXX--> - - <h2 class=no-num id=acknowledgements>Acknowledgements</h2> - - <p>Thanks to Aankhen, Aaron Leventhal, Adrian Sutton, Alexey Feldgendler, - Andrew Gove, Anne van Kesteren, Anthony Hickson, Asbjørn Ulsberg, - Ben Godfrey, Ben Meadowcroft, Benjamin Hawkes-Lewis, Bert Bos, Bjoern - Hoehrmann, Boris Zbarsky, Brad Fults, Brad Neuberg, Brendan Eich, Brett - Wilson, Carlos Perelló Marín, Chao Cai, Channy Yun, Charl - van Niekerk<!--status.whatwg.org maintainer-->, Charles Iliya Krempeaux, - Charles McCathieNevile, Christian Biesinger, Christian Johansen, Chriswa, - Daniel Peng, Daniel Spång, Darin Alder, Darin Fisher, Dave - Townsend<!-- Mossop on moz irc -->, David Baron, David Flanagan, David - Håsäther, David Hyatt, Derek Featherstone, Dimitri Glazkov, - dolphinling, Doron Rosenberg, Eira Monstad, Elliotte Harold, Erik - Arvidsson, fantasai, Franck 'Shift' Quélain, Geoffrey Sneddon, - Håkon Wium Lie, Henri Sivonen, Henrik Lied, Ignacio Javier, J. King, - James Graham, James M Snell, James Perrett, Jan-Klaas Kollhof, Jasper - Bryant-Greene, Jeff Cutsinger, Jens Bannmann, Joel Spolsky, John Harding, - Johnny Stenback, Jon Perlow, Jonathan Worent, Jorgen Horstink, Josh - Levenberg, Joshua Randall, Jukka K. Korpela, Kai Hendry, <!-- Keryx - Web, = Lars Gunther --> - Kornel Lesinski, 黒澤剛志 (KUROSAWA Takeshi), - Kristof Zelechovski, Lachlan Hunt, Larry Page, Lars Gunther, Laurens - Holst, Lenny Domnitser, Léonard Bouchet, Leons Petrazickis, - Logan<!-- on moz irc -->, Maciej Stachowiak, Malcolm Rowe, Mark - Nottingham, Mark Schenk, Martijn Wargers, Martin Atkins, Martin Honnen, - Mathieu Henri, Matthew Mastracci, Matthew Raymond, Matthew Thomas, Mattias - Waldau, Max Romantschuk, Michael 'Ratt' Iannarelli, Michael A. Nachbaur, - Michael A. Puls II<!--Shadow2531-->, Michael Gratton, Michael Powers, - Michel Fortin, Mihai Şucan<!-- from - ROBO Design -->, Mike - Dierken<!-- S. Mike Dierken -->, Mike Dixon, Mike Schinkel, Mike Shaver, - Mikko Rantalainen, Neil Deakin, Olav Junker Kjær, Philip Taylor, - Rajas Moonka, Rimantas Liubertas, Robert O'Callahan, Robert Sayre, Roman - Ivanov, S. Mike Dierken, Sam Ruby, Sean Knapp, Shaun Inman, Simon Pieters, - Stefan Haustein, Stephen Ma, Steve Runyon, Steven Garrity, Stewart Brodie, - Stuart Parmenter, Tantek Çelik, Thomas Broyer, Thomas O'Connor, Tim - Altman, Vladimir Vukićević, Wakaba, William Swanson, and - everyone on the WHATWG mailing list for their useful and substantial - comments. - - <p>Special thanks to Richard Williamson for creating the first - implementation of <code><a href="#canvas">canvas</a></code> in Safari, - from which the canvas feature was designed. - - <p>Special thanks also to the Microsoft employees who first implemented the - event-based drag-and-drop mechanism, <code title=attr-contenteditable><a - href="#contenteditable0">contenteditable</a></code>, and other features - first widely deployed by the Windows Internet Explorer browser. - - <p>Special thanks and $10,000 to David Hyatt who came up with a broken - implementation of the <a href="#adoptionAgency">adoption agency - algorithm</a> that the editor had to reverse engineer and fix before using - it in the parsing section. - - <p>Thanks also the Microsoft blogging community for some ideas, to the - attendees of the W3C Workshop on Web Applications and Compound Documents - for inspiration, and to the #mrt crew, the #mrt.no crew, and the cabal for - their ideas and support.</p> - <!-- Hopefully Kam won't notice he's covered by these - acknowledgements three times! --> - <!-- - ! menus - -<hyatt> the ability to get the current focused window in a window hierarchy - -wizards -tabbed interface - -Application object? http://longhorn.msdn.microsoft.com/lhsdk/ref/ns/msavalon.windows/c/application/application.aspx - -<input type="text" menu="foo" icon="g.png"/> <menu id="foo"> <menuitem icon="g.png" onclick="engine('yahoo')">Yahoo</menuitem> ... </menu> - -> One more aspect I want you think about - for "user interface systems" in -> general: The windowing system. -> Different kinds of windows ("document", "browser (file-system/network or -> otherwise)", "palette", "application modal dialog", "system modal dialog"), -> the rules for layering them (appropriately flexible to allow different -> implementations, e.g. MacOS vs. X-Windows), and simplifications for handheld -> devices (which are sometimes single window devices anyway, but sometimes -> they are one "normal" window plus sometimes one "dialog" window on top. - -window.open for dialogs - - -Thus, they lack things like proper windows, tree -widgets, menu bars, rich text areas and so forth. This is what I would -like XUL to solve. - Paul Prescod - - - - -Olav: -> <product> to indicate something you can buy, like a cd on amazon -> or a biker jacket at harleydavidson.com - - -Drop downs often have a title for when there is no selection. - -http://www.w3.org/mid/BAY1-F150PNOkJvX41K000418e1@hotmail.com - -http://crew.tweakers.net/crisp/newlayout/index.html -http://crew.tweakers.net/crisp/newlayout/list_topics.html -http://crew.tweakers.net/crisp/newlayout/list_messages.html -http://crew.tweakers.net/crisp/newlayout/list_messages_mod.html - -http://mail.mozilla.org/private/gui-toolkit/2004-April/000041.html - -> > > A standard for rich edit widgets would also be of interest to me. -> > -> > As in WYSIWIG editing? Of the bold/italic/underline/larger/smaller kind? -> > -> > Or do you mean as in the bare bones to be able to build an editor on top -> > of? As in something that basically just gives you a cursor and the ability -> > to tell where the selection is and some way to hook into the Undo -> > functionality? -> -> I have use cases for both...I have a more desperate business need for -> the latter (and have build apps using the gross APIs out there today) -> but there are a lot of circumstances where an editor that already has -> all standard HTML editing behaviour would be fine. -> -- Paul Prescod - - * a way of selecting rows, so that you can declaratively have buttons - outside the template that move a "selected row" around. => web apps - - -Calendar with list of days that have events (think: blog calendars) - -Find object at (x,y) -Find mouse position - -Styling scrollbars: - - ::scrollbars { ... } - - -table of contents? - - -http://www.gadgetopia.com/2004/05/04/FileIconTag.html - - -on going back -on going forward -on came from back -on came from forward -better state serialisation for going back/forward - - -some sort of markup to tell google _not_ to index a particular part of the site - -drop down menu with URIs to replace the silly <select> hacks. - -http://www.cs.tut.fi/~jkorpela/html/em.html - -<htmlarea>, <xmlarea>... - -> 3) Extensible syntax highlighting (coloring). I am aware that a ton of -> code editors don't even do this well. The ability to load a syntax -> definition file and have it color a block of code would do wonders for -> making the web a more friendly place to script. - - Ryan Johnson - -toolbars, status bars. - Didier PH Martin - - * methods/properties for scrolling managing, especially in - TextArea, such as .scrollTop and .scrollHeight in Mozilla and - - - -Robert Bateman: - - I've looked thru as many of the examples from around the web as I can find and - don't see an obvious way to do date calculations. - - What I'm trying to do is populate an xsd:date field with now() plus 5 days as - it's default value. The field in question is a proposed "due date" for a - work order. - - I've seen that I can get a "difference" between two dates, but no - calculations. - - -Wladimir Palant pointed out problems with chunking with server-sent-events - - - -> 2. Some method of integration to allow Web apps to respond -> to the browser's Cut, Copy, Paste, and Select All menu -> items and keyboard equivalents. These work automatically -> for text fields in any Web application; it would be -> great if apps could make them work for stocks, address -> book cards, message attachments, transactions, photos, -> and so on too. -> -> I'd add Undo and Redo to that list, but unfortunately -> IE6 doesn't have Undo and Redo menu items. - - mpt - - - ->> maybe except for the server sent events and the clipboard ->> api (but even in those cases it might be possible). -> -> Clipboard API I don't really want to see, given the problems IE's -> implementation of such brought up. A better standardised drag-and-drop -> interface would be great though, as doing it with mouse events and IE's -> proprietary events is annoying-to-impossible to get right all the time. -> -> I really like the idea of server-side events, though I would prefer to -> have them set up by a scripting call rather than an HTML element. - - Andrew Clover - - - <html application="application"> - -...would, instead of showing the Web page itself, the first time, show -(inline in the browser): - - :::: Security Warning ::::::::::::::::::::::::::::::::::::: - :: :: - :: The Web page at this domain: :: - :: ': - :: paypcl.com - :: - :: ...wishes to launch an application in a separate - :: window. Do you trust this domain? - :: - :: [x] Remember this decision. - :: - :: (( Trust paypcl.com )) ( Display as Web page ) - :: - :::::. -- (spurred on by Jose Dinuncio) - - - :::: Security Warning ::::::::::::::::::::::::::::::::::::: - :: :: - :: This Web page wishes to launch an application in a :: - :: separate window. Do you trust this domain? :: - :: :: - :: paypcl.com ' - :: - :: ( Trust this site for now ) - :: - :: ( Always trust this site ) - :: - :: (( Display as Web page )) - :: - :::::. - - -breadcrumb navigation markup -other markup: - http://www.stuffandnonsense.co.uk/archives/whats_in_a_name_pt2.html - - -common icons: http://www.intersmash.com/300images/ - - -http://www.gadgetopia.com/2004/06/18/DoYouWantToSaveYourChanges.html#Comments - -http://www.mojavelinux.com/cooker/demos/domTT/index.html - -http://www.mozilla.org/projects/ui/accessibility/dynamic-accessibility.html - -http://blog.colorstudy.com/ianb/weblog/2004/06/23.html -http://daringfireball.net/2004/06/location_field - -listview/gridview API -http://www.activewidgets.com/grid/ - - -> I would rather have it that changing the dom attribute 'value' or typing -> in the textarea, would also change the contents of the textnode in the -> textarea. -> -> In that way the dom level 2 traversal and range specification would not -> be useless for textarea's. -> -> The same goes for input text controls and probably also for other form -> controls. - - martijnw - - - -1. point to an xml instance and cause the page to be filled in -2. serialise the site to a version of that xml instance - -<menu> - <li state="bar"/> -</menu> -<button state="bar"/> -<state id="bar" label="" disabled="" value=""/> - -<input state="foo"/> -<input state="foo"/> -<input state="foo 2"/> -<input state="foo 2"/> -<state id="foo" model="x" ref="cat:orderLine[$v1]/cat:foo"/> - -<instance src=""/> - -<instance id="x"> - -<Order xmlns="urn:oasis:names:tc:ubl:Order:1.0:0.70" xmlns:cat="urn:oasis:names:tc:ubl:CommonAggregateTypes:1.0:0.70"> - <cat:ID/> - <cat:IssueDate/> - <cat:LineExtensionTotalAmount currencyID="USD"/> - <cat:BuyerParty> - <cat:ID/> - <cat:PartyName> - <cat:Name/> - </cat:PartyName> - <cat:Address> - <cat:ID/> - <cat:Street/> - <cat:CityName/> - <cat:PostalZone/> - <cat:CountrySub-Entity/> - </cat:Address> - <cat:BuyerContact> - <cat:ID/> - <cat:Name/> - </cat:BuyerContact> - </cat:BuyerParty> - <cat:SellerParty> - <cat:ID/> - <cat:PartyName> - <cat:Name/> - </cat:PartyName> - <cat:Address> - <cat:ID/> - <cat:Street/> - <cat:CityName/> - <cat:CountrySub-Entity/> - </cat:Address> - </cat:SellerParty> - <cat:DeliveryTerms> - <cat:ID/> - <cat:SpecialTerms/> - </cat:DeliveryTerms> - <cat:OrderLine> - <cat:BuyersID/> - <cat:SellersID/> - <cat:LineExtensionAmount currencyID=""/> - <cat:Quantity unitCode="">1</cat:Quantity> - <cat:Item> - <cat:ID/> - <cat:Description>Enter description here</cat:Description> - <cat:SellersItemIdentification> - <cat:ID>Enter part number here</cat:ID> - </cat:SellersItemIdentification> - <cat:BasePrice> - <cat:PriceAmount currencyID="">0.00</cat:PriceAmount> - </cat:BasePrice> - </cat:Item> - </cat:OrderLine> -</Order> - -</instance> - - - - - <h2>Tree and List Widgets</h2> - click item to go uri - doube click to submit form with value - sort list by any column - specify column headers, column sort types - specify data inline, or out of band - data can be linear or a one way tree - rows can have an icon associated with them - rows can have overlays associated with them - - progress meter - - http://www.gazingus.org/html/menuDropdown.html - - - -Disclosure triangles - - -I think UAs should automatically highlight the accesskey (or add it in -brackets if it isn't already in the string). I am thinking of writing some -text - optional, of course, since this wouldn't apply to all UAs or all -platforms - that specifies this. - -I also think that there should be an accesskey value which is basically -"auto", and which picks a non-clashing access key based on the element -content. - - - -| adding HTTP authentication capabilities to HTML allow sites to: -| - remove a site's authentication state from the browser when -| activated (i.e., a "log out" interface) -| - add user data to a site's authentication state in the browser -| (i.e., "log on" interfaces) -| - display the user's current authentication state -| -| There are a few good reasons to do this. Many sites use cookies to -| authenticate users, because HTTP authentication doesn't have any -| mechanism to allow logging out (a key requirement of financial -| institutions and other sensitive applications), and because the UI for -| HTTP authentication can't be controlled, and doesn't offer an -| "anyonymous" / "not logged in" view. -| -| By accommodating HTTP authentication in Web forms, it will be possible -| to have styled, custom "log on" interfaces as part of pages, as well -| as "log out" facilities, while still retaining the benefits of HTTP -| authentication. -| -| Specifically, HTTP authentication is more secure than cookies (when -| Digest auth is used), and is more amenable to automated processes -| (agents, spiders, etc.) as well as alternate browsing devices (screen -| readers, etc.). - - -http://jogin.com/weblog/archives/2004/07/19/hierarchy - - -Yeah, <header> and <footer> or similar elements are almost certainly going -to be defined at some point, along with <content> (for the main body of -the page), <entry> or <post> or <article> to refer to a unit of text -bigger than a section but smaller than a page, <aside> to mean a -side bar, <note> to mean a note... and so forth. Suggestions welcome. -We'll probably keep it to a minimum though. The idea is just to relieve -the most common pseudo-semantic uses of <div>. - - -http://lxr.mozilla.org/seamonkey/source/dom/public/idl/base/nsIDOMWindow.idl -scrollBy, etc -http://lxr.mozilla.org/seamonkey/source/dom/public/idl/base/nsIDOMWindowInternal.idl -DOM level 0 - - -DH: I was arguing that you should be able to get the CSS info for -document fragments if you had an owner document with CSS in it. - - - -So maybe: - - var library = new ZipFile("data.zip"); - library.onload = function() { - var sound1 = library.getAudio("sound1.wav"); // returns an Audio object - var image1 = library.getImage("image1.png"); // returns an HTMLImageElement - var doc1 = library.getXMLDocument("doc1.xml"); // returns a Document - var doc2 = library.getHTMLDocument("doc1.html"); // returns an HTMLDocument - } - -Also maybe supporting more than one file at a time: - - var library = new ResourceLoader("data.zip"); - library.add("moredata.zip"); - library.onload = function() { ... } - library.onloading = function() { - reportLoadProgress(library.progress); // 0.0 .. 1.0 - } - -...although I'm not sure how we would then deal with filename clashes. - - var library = new AudioZip("sounds.zip"); - library.onload = function() { - var sound1 = library["sound1.wav"]; - sound.play(); - } - - -If we define onbeforeunload, then we have to say that the JS -implementation of EventListener::handleEvent checks for that event, -treating the return value as the string to use for the unload warning -message if there is a return value, and calling preventDefault if -there isn't. - - -> > > Schematic editors, layout editors, interactive maps, data -> > > visualization for network flows, etc. -> Searching the web for the above keywords should find you a lot more. - - Denis Bohm - - - -Jens Meiert: -- For non-native English speakers, it's sometimes difficult to understand -the difference between <cite /> and <quote />, since citations often seem to -be quoted, too (this is a presentational aspect, I know). -- Is it right that the <dfn /> element [1] /must/ be used only in the -context of the definition of the enclosed term (as the example suggests)? -(If so, wouldn't it be useful to add this note, too?) - - -http://secunia.com/advisories/9711/ -In particular number 7. - Chris Hofmann - - -> [1] http://www.stopdesign.com/log/2004/08/25/microsoft-advances.html -> [2] http://www.stopdesign.com/articles/throwing_tables/ - - -In other areas, however, the replacement is not a match in terms of functionality. Like it or not, but showModalDialog is a better way to provide feature-rich user feedback windows than window.confirm (which Firefox supports, even though there is NO PUBLIC STANDARD for it). With showModalDialog, I can pop a window offering "Yes," "No," or "Cancel" buttons that requires a response before proceeding. With window.confirm, I have to craft all my questions as something to which "OK" or "Cancel" makes sense, never mind asking for three, four, or five state responses. -- http://news.zdnet.com/2100-9588-5438955.html ( John Carroll ) - - - -> http://channel9.msdn.com/wiki/default.aspx/Channel9.InternetExplorerFeatureRequests -> Alternate way of caching content -> Avalon Integration -> getData/setData improvement (clipboardData) -> Input type=file improvements -> HTML editing: Editing Tables -> Input type=file improvements -> .NET framework -> -> http://channel9.msdn.com/wiki/default.aspx/Channel9.InternetExplorerOutrageous -> Some decent controls - - lachlan.hunt@lachy.id.au - - -http://lists.w3.org/Archives/Member/w3c-html-wg/2004JulSep/att-0135/role072704a.html - - -> I've encountered two situations where setting or retrieving the caret -> position would be useful. The first is a situation where I'd like to -> apply an input mask to a text box. For example, I'd like the ability to -> create a text box where the date delimiters (dashes or slashes) appear -> automatically in a text box upon entering the field, and when the user -> types in the field, it fills into the appropriate spaces in the input -> box and sets the text selection to the next appropriate position, all -> while allowing the user to reposition the cursor within the text box -> with a keyboard or mouse without being able to edit or delete the -> delimiters (dashes or slashes). This would be very similar to input -> mask features in certain native apps that I've used. - - Greg Kilwein - -> The second situation is an application that would like to highlight text -> in a text box or textarea for the purposes of a spell check, thesaurus, -> or search-and-replace operation. - - Greg Kilwein - - - - -HTMLImageElement.click(x, y); (for Csaba Gabor) -or clickPoint, if click() can't be done in IE -can this be emulated in IE by posting a synthetic moue click event -with those X and Y coords? - - -<menulabel>, or rather menus in general, need an icon attribute and a -hide attribute, like the <command> element. - - -What about safe clipboard access. -As discussed before by others as well: -The user initiates a paste action as recognized by the UISystem the user is working in. -E.g pressing Ctrl-V or selecting paste from a context menu. -An event is fired and a Listener can now access the pasted data as part of the event object. -The same for cut and copy. The Listner can set data as part of the event object. -This is safe and will not allow any script to mess with the clipboard without the user specifically asking for it -by initiating a cut/copy/paste action. - - Jan-Klaas Kollhof - - -Need to say that NodeList's items are enumerable, so that for (var x in myNodeList) { } works. - thank Dethe Elza - -rel="" on submit buttons? - -what does <label> _mean_? how about an empty one, one which contains -more than one control, no controls? - - -data: URIs and same-origin policy when navigated to from http:? - - Hallvord Reiar Michaelsen Steen - - -need conformance section for editors, which says stuff like "can't be -conforming if editor has an "italics" button" - -people want multiline tooltips with explicit line breaks - - - -attributes of type ID that have no value beyond the empty string do -not give the element an ID of "". - - -ability for a web app to save a file to the local disk: - var file = window.openFile(); // throws up UI - file.read(); - var file = window.saveAsFile(); // throws up UI - file.write(); -...or something? Or use data: URIs and right-click-to-save? - -http://lxr.mozilla.org/mozilla/source/dom/public/idl/html/nsIDOMNSHTMLDocument.idl - - - <p><em>This section is non-normative.</em></p> - - -how to handle 404s and 500s and other non-OK responses when it comes -to <script>, <link>, <style>, etc. - - -normative classes: - -example - -note - -warning - -issue - hCard, hCalendar - wiki based registration, first come first served - * class: - * applies to elements: - * processing model: - * status: - - -<Hixie> vlad: you should define what the UA should do with out-of-order aDATs -<pav> its an error -<pav> pretty sure we say that somewhere -<Hixie> yes i know it's an error -<Hixie> but that doesn't say what the UA should do -<pav> error == image is invalid -<vlad> yep -<vlad> either broken image icon -<vlad> or display first frame (fall back to normal PNG) -<vlad> up to the UA -<Hixie> right -<Hixie> you should say which one -<pav> its up to the UA -<Hixie> why? -<vlad> "SHOULD display the first frame, but MAY display broken image icon if that's not convenient", in rfc parlance -<vlad> because it's not useful to specify that, IMO -<Hixie> up to the UA means one UA will implement something, it'll become a popular UA, then all the others will have to copy it. -<vlad> how a UA wants to handle image errors is up to the UA -<pav> we're designing an image format, not the html image tag -<pav> the html spec should say what to do with it - - -should we say that elements in HTML must be lowercase? (but with error -handling for uppercase tags, obviously)? If so, update examples. - -<title> is for out of context headers -<h1> is for in-context headers - -The parsing rules of HTML - -media="" is case-insensitive -case-sensitivity of other attributes, and what it means - -empty title attribute is equivalent to missing attribute for purposes -of alternate style sheet processing - - -<p>s that contain <ul><ol><table><dl><blockquote>? (did we get all those?) - - - -> I'd like search engines to be able to show me the title of a page in the -> same consistent position in a search result, and the name of the site -> (if available) in the same consistent position in a search result, and -> the name of the author (if available) in the same consistent position in -> a search result. -> -> For that to happen, it would help slightly if the HTML specification -> stopped SHOULD-ing the current <title> behavior. It would help more if -> the HTML specification contained clear, straightforward markup for -> author and site name (and encouraged UAs to present this information -> when the document is taken out of context). - - <title site="" publisher="" author="">Page Title</title> - <title>Page Title - <site></site> - <author></author> (<publisher></publisher>)</title> - - <title>Page Title</title> - <link rel="top" title="" href=""> - <link rel="publisher" title="" href=""> - <link rel="author" title="" href=""> - - - h1 is styled appropriately, h2 to h6 are styled according to legacy. - - -[onclick] should make element focusable; enter should send onclick - -define implied <html>, <head>, <body>, <p>, </p>, etc. - -http://www.aujsproduction.com/samples/wishlist/revampedselector.asp - - -interactive elements can't be nested (as in <a><button><input></button></a>) - - -need a summary of all the content models and how they interact: - a | interactive strictly inline-level element | where inline-level content is expected | strictly inline-level content | interactive elements must not be nested - i | strictly inline-level element | where inline-level content is expected | strictly inline-level content | - em | strictly inline-level element | where inline-level content is expected | inline-level content | - p | block-level element, structured inline- | where block-level content is expected, | inline-level content | must not be nested - | level element | where inline-level content is expected | | -...etc - - -need a summary of the differences between the HTML and XML serialisations. -e.g. how <p><ul> is allowed in one but not the other - - - -Google suggest: oninput -> submit a form whose only contents is the -drop down list which you refresh (<datalist>). - -Inline editing of <select multiple=""> boxes - -image buttons shouldn't be used unless you want the coordinate - -need for the spec to say something about sending proprietary data over -the network, e.j. in XMLHttpRequest and other data streams. Is it ok, -if the page is doing the translation? - -built-in spell-checking in <input type="text">, <textarea> - -author-driven highlighting of individual words in text fields - - -support access Array element via () instead of [] (IEism) -- https://bugzilla.mozilla.org/show_bug.cgi?id=289876 - - -atom can do this: - <author> - <name>Mark Pilgrim</name> - <uri>http://example.org/</uri> - <email>f8dy@example.com</email> - </author> - <contributor> - <name>Sam Ruby</name> - <uri>http://intertwingly.net/blog/</uri> - </contributor> -how do we do this in HTML5? (what's the use case?) - -how to interpret an HTML5 document for syndication -http://hixie.ch/specs/hsf/hsf - - - -section "rendering HTML" has to cope with: - <q> element's quotes - <section> <h1> - default margins and paddings for <ul>, <form>, etc. - - <h4>The <code>q</code> element</h4> - <p class="big-issue">Need to deal with the quotemark problem without - adding verbose markup, breaking existing documents, or adding - redundant elements.</p> - - - -<Hixie> here's how <object> works (assuming you don't support ActiveX) -<Hixie> 1. look at the data="" attribute. If it's not there, go to the step i'll label "bail" below. -<Hixie> 2. fetch the file indicated by the data="" attribute. -<Hixie> 3. while waiting for the MIME type, treat <object> as a replaced element of transparent nothingness, intrinsic size zero. -<hyatt> (so we would honor width/height) -<hyatt> (because it's replaced) -<Hixie> (yes) -<Hixie> 4. if the MIME type is a long time coming (e.g. DNS is being slow) then jump to the "bail" step below until you have the MIME type, then jump back to step 5. -<Hixie> 5. Once you have the MIME type, examine it. If it's a plugin type, jump to the plugin step below. If it's an image, jump to the image step below. If it's a document type (HTML, XML, etc) jump to the iframe step below. Otherwise, you don't recognise it, and jump to the "bail" step. -<Hixie> plugin step: collect all the <param> element children in the <object>. instantiate the plugin and pass the params to it. -<Hixie> image step: render the <object> as if it was an <img> -<Hixie> document step: render the <object> as if it was an <iframe> -<Hixie> bail step: render the <object> as if it was a <span> - - if there is no authoratative MIME type, then use the type="" attribute. - - if type="" is something you know you don't support, you MAY not download it - - if type="" is dynamically changed, do nothing - - if data="" is dynamically changed, redo loop - -<hyatt> apparently your url can come from <param> -<hyatt> not just the data attribute -<hyatt> our code looks for params with "src", "movie", "code" and "url" -<hyatt> and also tries to find the type on a param -<Hixie> oh that's you trying to have hacky activex support -<Hixie> opera does that too -<hyatt> yeah we support activex versions of plugins that are common -<hyatt> like flash and quicktime and realaudio -<Hixie> that would be a step 1b. if no data attribute, then look for a <param> to get you a URL instead. -<Hixie> and if you find one, carry on as if that was your data="". - - -should have some text talking about the fact that it's ok if your page -passes through a period of non-conformance while script is running, -but that in between scripts it should be compliant. - - -how to handle 205 reset content responses and other HTTP codes in -response to link clicks, link clicks with target="" attributes, -window.open(), the user typing a URI in the URL bar, etc. - -XXX Native code for fast sorting of many data? - -http://www.microsoft.com/mind/1097/directanim.asp - - -events: onmousewheel -<hyatt> with a wheelDelta field on the WheelEvent (whcih comes off UIEvent) -<hyatt> but in OS X you can wheel horizontally -<hyatt> so we actually added wheelX, wheelY, and wheelZ -<hyatt> with wheelDelta just mapping to wheelY for WinIE compat -<Hixie_> oh i don't mind wheelZ, maybe we can even say ctrl+wheel should map to it on some platforms (windows) -<hyatt> but if you hold down Shift+mouse wheel in mac apps on os x you'll wheel horizontally -wheelDelta is multiples of 120 -http://msdn.microsoft.com/workshop/author/dhtml/reference/properties/wheeldelta.asp - -events: -http://damowmow.com/temp/safari/WebCore-315/khtml/ecma/kjs_events.cpp - -Need to resolve whether <a rel=""> should affect an out-of-band UI (or -whether it should just be a may), see -https://bugs.opera.com/show_bug.cgi?id=169791 - - -should have appendix listing what was already implemented -- http://www.xml.com/pub/a/2005/04/27/deviant.html - -| Hixie and Steven shared an item: in both XHTML2 and HTML5, it will -| be possible to have a list child of a paragraph. That's good, from a -| structural point of view. But that's bad, from a user's point of -| view. Imagine you have a paragraph, with red background color. And -| you have an unordered list in your clipboard. You place the caret at -| the end of the paragraph and paste your list. Where does it end up? -| In the paragraph or after it? Red background or not? I really fear -| that, once again, document model authors are completely neglecting -| the authoring side. - - http://www.glazman.org/weblog/dotclear/index.php?2005/05/27/1055-adam-2 - -need to define how to process MIME types in <style> and <script> and so forth. - -http://www.paulgraham.com/popular.html - - - - <p>In the ECMAScript DOM binding, objects implementing this interface - can also be dereferenced using square bracket notation (e.g. - <code>foo[1]</code> or <code>foo["bar"]</code>). Dereferencing with - an integer index is equivalent to invoking the <code>item()</code> - method with that index, and dereferencing with a string index is - equivalent to invoking the <code>namedItem()</code> method with that - index.</p> - - -"you have mail": bubble notification; flash taskbar button, -=> how do you stop advertisers? - - - -events should bubble from documents to Window - -say something about events fired on <body> -> document -> window, like -onload? onpopstate is defined as body->html->doc->window; as is the -local storage event. What about the old ones, how do they work? load, -error, scroll, resize, etc? - -If we assuming that bubbling events bubble from document to window, -then it seems reasonable for scroll events that bubble to be fired at -the document if the window is resized, and scroll events that don't -bubble to be fired at elements if they are scrolled. window.onscroll -and document.onscroll should both work. - - -[HIT TESTING TRANSPARENCY] -Definition: IE considers a point of an element "transparent" if any -one of the following are true: - - 1. All of the following are true: - a: The computed value of 'background-image' is 'none', and - b: The computed value of 'background-color' is 'transparent', and - c: The point is over a pixel of an AlphaImageLoader filter image - that has an alpha value of 0 (fully transparent), or the - element does not have an AlphaImageLoader filter applied; - - 2. The point is outside the element's CSS clip rectangle; - - 3. The computed value of 'visibility' is 'hidden'; - - 4. The element is a transparent IFRAME (in IE, an IFRAME with the - custom attribute "allowtransparency"); - - 5. The element is an OBJECT with the custom attribute "wmode" set to - "transparent" and the point in question is fully transparent. - -Given those definitions, when a mouse event occurs, IE finds the -target element as follows: - - A. Take the topmost node that is under the point where the pointer - was for the event. For CSS boxes, borders, padding areas and - content areas are considered part of the node, margins and - leading generated by the 'line-height' property are not. - - B. If there is no node at that point, no event is fired. STOP. - - C. If the node is a text node, then the event is fired at the text - node's nearest ancestor element node. STOP. - - D. If the node is not an element, assign the node's nearest - ancestor element node to a variable X. Otherwise, assign the - element node itself to X. - - E. If the element X is the BODY element or the HTML element and its - document is not the document of a transparent IFRAME, goto step - H. Similarly, if the element X is a TABLE element, or is an IMG - element, goto step H. - - F. If the point where the pointer was is, per the above definition, - a point that on the element X is transparent, then ignore that - element and assign the element that is below that element in the - stacking order to X. If there is no element below X, or if the - point on X is not transparent and so the previous condition - doesn't apply, then leave X as is and go straight to step H. - - G. Goto step E. - - H. If the element X is now a BODY or TABLE element, but the element - assigned to X in step D was some other element, assign the - element originally assigned in step D back to X. - - I. The event goes to X. STOP - - - - -mousedown's default action is focus, so canceling mousedown stops focus transference. -e.g. on http://www.mozilla.org/editor/midasdemo/ - -xref all the _ERR exceptions to DOM3CORE - - -<select><option><hr> support - - -raising an exception when the wrong number of arguments is passed - -is that a language-specific thing, or what? - -why |new XMLHttpRequest()| returns an object that .toStrings to -[object XMLHttpRequest], same with new TCPConnection(); what if a -constructor is called without using "new" in JS? - - -reload: fire an event when "reload" is pressed so that the page can -reload its data instead of the whole page. cancel the event cancels -the HTTP reload. Abuse prevention required, though. - - -load event: fire on body, document, window? or just let it bubble? - - -http://msdn.microsoft.com/workshop/author/dhtml/reference/methods/elementfrompoint.asp -http://msdn.microsoft.com/workshop/author/dhtml/reference/methods/showmodaldialog.asp - - -refs for TCP/IP (rfc793) and IPv6 - -http://www.joelonsoftware.com/items/2004/06/17.html -http://www.joelonsoftware.com/items/2004/06/18.html - - -<neutralise> block that kills scripting or anything dangerous? - - -XXXX need explanation of when to use undo/redo, and when to use back/forward - -XXX "alternate style sheet" should be "alternative style sheet" - - - - - <h5>Using the <code>a</code> element with the <code>command</code> attribute</h5> - - <p>If an <code>a</code> element has a <code - title="command-attribute">command</code> attribute, then:</p> - - <p>If the element's <code>title</code> attribute is absent, then - when the UA attempts to display the element's hint, it must instead - use the specified command's Hint.</p> - - <p>Even if the element's <code>href</code> attribute is absent, the - element must still match the CSS <code>:link</code> or - <code>:visited</code> pseudo-classes. It must match the - <code>:visited</code> pseudo-class if the command's action is to - follow a link that has already been visited by the user, and must - match the <code>:link</code> pseudo-class otherwise.</p> - - <p>If a <code>DOMActivate</code> event is dispatched on the element - and is not canceled, and the event has no other default action, and - the command's Disabled State is false (enabled), then the command's - Action must be triggered as the default action.</p> - - <p class="note">The <code>DOMActivate</code> event is fired as the - default action of the <code>click</code> event.</p> - - <p>If the command's Disabled State is true (disabled) then the - element must be disabled and must therefore match the - <code>:disabled</code> pseudo-class. UAs should style disabled links - in such a way as to clearly convey their disabled state.</p> - - <p>The Label, Icon, Checked State and Type facets of the command are - ignored by the <code>a</code> element (except for <a - href="#pseudosAndCommands">matching CSS pseudo-classes</a>).</p> - - <h5>Using the <code>button</code> element with the <code>command</code> attribute</h5> - - <p>If a <code>button</code> element has a <code - title="command-attribute">command</code> attribute, then:</p> - - <p>If the element's <code>title</code> attribute is absent, then - when the UA attempts to display the element's hint, it must instead - use the specified command's Hint.</p> - - <p>If a <code>DOMActivate</code> event is dispatched on the element - and is not canceled, and the event has no other default action, and - the command's Disabled State is false (enabled), and the button's - <code>disabled</code> attribute is absent, then the command's Action - must be triggered as the default action.</p> - - <p class="note">The <code>DOMActivate</code> event is fired as the - default action of the <code>click</code> event.</p> - - <p>If the command's Disabled State is true (disabled) then the - element must be disabled. The <code>button</code> element must also - be disabled if the element's <code>disabled</code> attribute is - set.</p> - - <p>The Label, Icon, Checked State and Type facets of the command are - ignored by the <code>button</code> element (except for <a - href="#pseudosAndCommands">matching CSS pseudo-classes</a>).</p> - - <h5>Using the <code>input</code> element with the <code>command</code> attribute</h5> - - <p>If an <code>input</code> element has no <code>type</code> - attribute and no <code>name</code> attribute, and it has a <code - title="command-attribute">command</code> attribute, then:</p> - - <p>If the command is of Type "command" then the element must - generally be styled and behave as if it was of type - <code>button</code>; if the Type of the command is "radio" then the - element must generally be styled and behave as if it was of type - <code>radio</code>; and if the Type of the command is "checkbox" - then the element must generally be styled and behave as if it was of - type <code>checkbox</code>.</p> - - <p>If the command is of Type "command" and the element's - <code>value</code> attribute is absent, then when the UA attempts to - display the element's caption, it must instead use the specified - command's Label. The Label facet is ignored if the command is not of - Type "command".</p> - - <p>The UA may use the Icon facet of the command to render an - icon in the control, if appropriate for the UI used.</p> - - <p>If the element's <code>title</code> attribute is absent, then - when the UA attempts to display the element's hint, it must instead - use the specified command's Hint.</p> - - <p>If a <code>DOMActivate</code> event is dispatched on the element - and is not canceled, and the event has no other default action, and - the command's Disabled State is false (enabled), and the element's - <code>disabled</code> attribute is absent, then the command's Action - must be triggered as the default action.</p> - - <p class="note">The <code>DOMActivate</code> event is fired as the - default action of the <code>click</code> event.</p> - - <p>If the command's Disabled State is true (disabled) then the - element must be disabled. The <code>input</code> element must also - be disabled if the element's <code>disabled</code> attribute is - set.</p> - - <p>If the command's Checked State is true (checked) then the element - must be checked. The <code>input</code> element must also be checked - if the element's <code>checked</code> attribute is set.</p> - - - - - <p>This element should not be directly displayed. In CSS-aware user - agents, this should be achieved by including the following rules, or - their equivalent, in the UA's user agent style sheet:</p> - - <pre>@namespace xh url(http://www.w3.org/1999/xhtml); -xh|command { display: none; }</pre> - - - - <h5 id="command-with-command">Using the <code>command</code> element with the <code>command</code> attribute</h5> - - <p>If a <code>command</code> element has a <code - title="command-attribute">command</code> attribute, then:</p> - - <p>If the element's <code>label</code> attribute is absent, then - when the UA attempts to display the element's caption, it must instead - use the specified command's Label.</p> - - <p>If the element's <code>icon</code> attribute is absent, then - when the UA attempts to display the element's icon, it must instead - use the specified command's Icon.</p> - - <p>If the element's <code>title</code> attribute is absent, then - when the UA attempts to display the element's hint, it must instead - use the specified command's Hint.</p> - - <p>If a <code>click</code> event is dispatched on the element and is - not canceled, and the command's Disabled State is false (enabled), - and the element's own <code>disabled</code> attribute is absent, - then the command's Action must be triggered as the default - action.</p> - - <p>If the command's Disabled State is true (disabled) then the - element must be disabled. The <code>command</code> element must also - be disabled if the element's <code>disabled</code> attribute is - set.</p> - - <p>If the command's Checked State is true (checked) then the - element must be checked. The <code>command</code> element must also - be checked if the element's <code>checked</code> attribute is - set.</p> - - <p>When a <code title="command-element">command</code> element has a - <code title="command-attribute">command</code> attribute, any <code - title="attr-command-type">type</code> and <code - title="attr-command-radiogroup">radiogroup</code> attribute is - ignored.</p> - - - - <h4>The 'icon' property</h4> - - <p>UAs should use the command's Icon as the default generic icon - provided by the user agent when the 'icon' property computes to - 'auto' on an element that either defines a command or refers to one - using the <code title="command-attribute">command</code> - attribute.</p> - - <h4 id="pseudosAndCommands">CSS pseudo-classes and commands</h4> - - <p>When an element uses the <code - title="command-attribute">command</code> attribute, any UI - pseudo-classes from the following list that apply to the element - defining the command also apply to the elements that refer to that - command.</p> - - <dl> - - <dt>:enabled, :disabled</dt> - - <dd>Matches commands whose Disabled State facet is False and True - respectively.</dd> - - <dt>:checked</dt> - - <dd>Matches commands whose Type facet is either "radio" or - "checkbox", and whose Checked State facet is true.</dd> - - </dl> - - - - <p><code>menu</code> elements with explicit <code>label</code> - attributes, and <code>menu</code> elements following - <code>menulabel</code> elements, should be hidden. In CSS-aware UAs, - this effect should be achieved by including the following rules, or - their equivalent, in the UA's user agent style sheet:</p> - - <pre>@namespace xh url(http://www.w3.org/1999/xhtml); -xh|menu[label], xh|menulabel + xh|menu { display: none; }</pre> - - <p>All other <code>menu</code> elements should be rendered - identically to <code>ul</code> elements. In CSS-aware UAs, this - effect may be achieved by including rules similar to the following - in the UA's user agent style sheet:</p> - - <pre>@namespace xh url(http://www.w3.org/1999/xhtml); -xh|menu { display: block; margin: 0 0 0 40px; list-style: disc; }</pre> - - - - - <h5>Displaying menus</h5> - - <p>When a <code>menu</code> element is activated, the associated - menu should be constructed and shown. (For details on how a - <code>menu</code> element can be activated, see the sections on - <span>menu links</span> and <span>menu bars</span>.)</p> - - <p>The styles applied to each element in the <code>menu</code> - element, as well as the element itself, may be applied when - constructing a menu. UAs are recommended to not apply styling to - context menus and menus for application menu bars, and to only use - styles for in-page menus.</p> - - <p>If user agents support styling of menus, they should only support - the '<code>background</code>', '<code>color</code>', - '<code>border</code>', '<code>padding</code>' and - '<code>font</code>' properties on menus and menu items. (This list - might be incomplete; in general, properties that merely affect the - appearance of the element should work, but properties that affect - the layout should not.)</p> - - <p>As the user interacts with a menu, the elements from which the - menu was created should have appropriate pseudo-classes (:hover, - :focus, :active) applied.</p> - - <p>The menu items must only consider the computed styles of the - elements from which they were derived, not other elements.</p> - - <div class="example"> - - <p>For example, take this menu:</p> - - <pre><menu> -<li><command label="a"/></li> -<menu></pre> - - <p>The menu has one menu item, labelled "a".</p> - - <p>Styles applied to the <code>li</code> element in this menu would - have no effect on the rendered menu, except in so far as styles - inherit from that element to the <code>command</code> element.</p> - - <p>Styles applied to the <code>command</code> element could affect - the menu. While the user is hovering over the menu item, the - <code>:hover</code> pseudo-class matches the <code>command</code> - element and any appropriate newly matching rules could be - applied.</p> - - </div> - - <p>When activated from a <span title="menu links">menu link</span>, - a menu must be placed in an Appropriate Place. Specifically, if the - <code>a</code> element is displayed as a vertically-stacked box (as - is typically seen for elements with '<code>display: block</code>', - '<code>list-item</code>', or '<code>table</code>'), then the menu - should appear vertically below the element, anchored so that one of - its top corners coincides with a bottom corner of the box so that - the menu and the box each have a horizontal sides in common (or a - bottom corner of the menu coincides with a top corner of the box, if - there isn't enough room for the menu to drop down); otherwise, if - the element is displayed as a horizontally stacked box - ('<code>display: inline</code>', '<code>table-cell</code>', etc), - the menu should appear to the <em>side</em> of the box in an - analogous way. If the element is on the right of the page, the menu - should drop to the left, and vice versa.</p> - - <p>UAs should implement the drop-down behaviour in more - platform-appropriate ways if the platform conventions differ from - the behaviour described above.</p> - - - - - <h4>The <dfn title="command-attribute"><code>command</code></dfn> - attribute</h4> - - <p>Any element that can define a command can also, instead, have a - <code>command</code> attribute that specifies the ID of a command - that the element should defer to. In this case the element does not - define a command, but, in the absence of attributes to the contrary, - reflects the state of the element specified.</p> - - <p>If the <code>command</code> attribute specifies an ID that is not - the ID of an element that defines a command, then the - <code>command</code> DOM attribute is set to the null value, and the - element acts as if it was linked to an element that defined a - command with no Label, no Hint, no Icon, no Action, that was not - Hidden, not Disabled, not Checked, and that was of Type - "command".</p> - - -replaceable DOM properties: http://lxr.mozilla.org/mozilla/source/dom/src/base/nsDOMClassInfo.cpp#5928 -< brendan>|Hixie: so yeah, lxr for JSRESOLVE_QUALIFIED - -screen object: -screen contains top left width height pixelDepth colorDepth availWidth availHeight availLeft availTop - - - - <p>The most direct way to represent a command is by using the <code - title="command-element">command</code> element. A <code - title="command-element">command</code> element defines a command if - it does not have a <code title="command-attribute">command</code> - attribute.</p> - - <div class="example"> - <pre>... - <command id="c_stop" label="Emergency Stop" onclick="dostop()"/> - <command id="c_go" label="Go" onclick="dogo()"/> - <command id="c_lamp" label="Headlamps" onclick="dof2()" disabled="disabled"/> -...</pre> -</div> - - <p>The <code>command</code> element, in addition to the core and - internationalisation attributes, may have the following - attributes specified:</p> - - <dl> - - <!-+- yes i know that some of these are core attributes. If you can - give me a better introductory paragraph, I'm all for it. -+-> - - <dt><dfn title="attr-command-type"><code>type</code></dfn></dt> - - <dd>The command's Type. If present, this attribute must either have - the value <code>radio</code>, in which case the command is of Type - "radio", or the value <code>checkbox</code>, in which case the - command is (amazingly) of Type "checkbox". Any other value, or the - absence of the attribute altogether, means that the command is of - Type "command".</dd> - - <dt><dfn title="attr-command-id"><code>id</code></dfn></dt> - - <dd>The command's ID. If this attribute is not specified, then the - command is anonymous.</dd> - - <dt><dfn title="attr-command-label"><code>label</code></dfn></dt> - - <dd>The command's Label. If the attribute is not specified, the - command's Label is given by the element's <code>textContent</code> - DOM attribute.</dd> - - <dt><dfn title="attr-command-title"><code>title</code></dfn></dt> - - <dd>The command's Hint. If the attribute is not specified, the - command's Hint is the empty string.</dd> - - <dt><dfn title="attr-command-icon"><code>icon</code></dfn></dt> - - <dd>A URI to the command's Icon. If the attribute is not specified, - then the command has no Icon.</dd> - - <dt><dfn title="attr-command-onclick"><code>onclick</code></dfn></dt> - - <dd>An event handler attribute that listens for <code>click</code> - events.</dd> - - <dt><dfn title="attr-command-hide"><code>hide</code></dfn></dt> - - <dd>The command's Hidden State. If the attribute is present, the - command is hidden (and also disabled, regardless of the value of - the <code>disabled</code> attribute), otherwise, the command is - shown. If the attribute is present, it should have the value - "<code>hide</code>". <!-+-The name of the attribute reflects the - fact that Hidden commands in menus are hidden.-+-></dd> - - <dt><dfn title="attr-command-disabled"><code>disabled</code></dfn></dt> - - <dd>The command's Disabled State. If the attribute is present, the - command is disabled, otherwise, the command is enabled. If the - attribute is present, it should have the value - "<code>disabled</code>".</dd> - - <dt><dfn title="attr-command-checked"><code>checked</code></dfn></dt> - - <dd>The command's Checked State. If the attribute is present, the - command is checked, otherwise, the command is not. If the attribute - is present, it should have the value "<code>checked</code>".</dd> - - <dt><dfn title="attr-command-radiogroup"><code>radiogroup</code></dfn></dt> - - <dd>An attribute indicating the name of the group of commands that - will be toggled when the command itself is toggled. (Described <a - href="#radiocommand">below</a>.)</dd> - - <dt><dfn title="attr-command-default"><code>default</code></dfn></dt> - - <dd>An attribute indicating whether the command is the default - command. If the attribute is present, the command is the default - command, otherwise it is not. If it is set, it should have the - value <code>default</code>. Used by context menus to indicate what - the default option would be. The :default pseudo-class matches - <code>command</code> elements with this attribute.</dd> - - </dl> - - <p>In addition, <code title="command-element">command</code> - elements may also have a <code - title="command-attribute">command</code> attribute, as <a - href="#command-with-command">described below</a>.</p> - - <p>The Type, ID, Label, Hint, Icon, Hidden State, Disabled State, - and Checked State of the command defined by a <code - title="command-element">command</code> element are as described - above. The Action of a <code title="command-element">command</code> - element is that a <code>{null, "click"}</code> event is fired on the - element.</p> - - <p>If the Type of the command is "checkbox", when a - <code>click</code> event is dispatched on the element, user agents - must toggle the value of the <code>checked</code> attribute before - the event is dispatched in the document. (If the attribute is - absent, then it is set to the value <code>checked</code>, and if the - attribute is present, it is removed.) If the default action of the - event is canceled, the value of the attribute must be changed back - to the value it had before the event was dispatched.</p> - - <p id="radiocommand">If the Type of the command is "radio", when a - <code>click</code> event is dispatched on the element, user agents - must set the value of the <code>checked</code> attribute on the - element to <code>checked</code>, and remove the attribute from any - <code>command</code> elements with <code>type</code> set to - <code>radio</code> and the same parent element and same - <code>radiogroup</code> attribute, before the event is dispatched in - the document. (If the element has no <code>radiogroup</code> - attribute, then the elements "with the same <code>radiogroup</code> - attribute" are those elements with <em>no</em> - <code>radiogroup</code> attribute.) If the default action of the - event is canceled, the value of the attributes that were changed - must be changed back to the values they had before the event was - dispatched.</p> - - <p>In HTML the <code>command</code> element is an empty element with - no end tag.</p> - - <p>Authors should put <code>command</code> elements inside the - <code>head</code> element, inside any element that may contain - <span>block-level elements</span> or <span>inline-level - content</span>, or inside <code>commandset</code> elements.</p> <!-+- - should, because hey, if they want to put them elsewhere, why not. - XXX -+-> - - <p>Authors should not put elements or text inside - <code>command</code> elements.</p> - - - - - <p>The <code title="dom-command-ro-command">command</code> DOM attribute - is defined with the <code title="attr-command">command</code> - content attribute.</p> - - -Need to become consistent about whether or not to quote keyword -("<code title="">foo</code>" vs <code>foo</code>) - - - - XXX command icons in rendering section: - - If the element defining the command has no explicit icon, then the - attribute must instead return the computed value of the CSS '<code - title="">icon</code>' property on that element. <a - href="#refsCSS3UI">[CSS3UI]</a> - - If the computed value of '<code title="">icon</code>' is - '<code>auto</code>', - - -search for event-click and make them all point to: -<a href="http://www.w3.org/TR/DOM-Level-3-Events/events.html#event-click"><code>click</code></a> -...or something. - -<code>DOMActivate -> <code title="event-DOMActivate">DOMActivate - - -onclick="" only fires if it is a MouseEvent - - -<form> .submit definition - see http://lxr.mozilla.org/mozilla/source/content/html/content/src/nsHTMLFormElement.cpp#600 -for how to handle multiple calls in series - - -http://lxr.mozilla.org/mozilla/source/content/html/content/src/nsHTMLFormElement.cpp#699 - -How events are handled: -http://lxr.mozilla.org/mozilla/ident?i=HandleDOMEvent - -http://www.quirksmode.org/js/events_compinfo.html -e.g. mousedown mouseup click mousedown mouseup click dblclick - -http://msdn.microsoft.com/library/default.asp?url=/workshop/author/dhtml/reference/events.asp - - - -05:46 < bz>|Hixie: let's put it this way -05:46 < bz>|Hixie: 1) A script is executed when its data is available -05:47 < bz>|Hixie: 2) The data for an inline script is available when its </script> is seen -05:47 < bz>|Hixie: 3) The data for a script with src is available when it finishes loading -05:47 < bz>|Hixie: all good so far? -05:47 < Hixie>|i'm waiting for the bit where src= causes blocking in the normal, non-d.w case -05:47 < bz>|Hixie: 4) The data for a script with src starts loading when the <script> node is inserted into the DOM -05:48 < shaver>|it causes parser blocking in the normal case -05:48 < bz>|Hixie: 5) When such a load starts, all further parsing is suspended until the load has completed and the script has executed. -05:48 < bz>|Hixie: so if we forget document.write -05:48 < bz>|Hixie: and look at the HTML: <script src="foo"></script><div> -05:48 < bz>|Hixie: the text "<div>" will nto be parsed until after the script runs -05:49 < bz>|Hixie: this is needed so that if the script does document.write that text can be inserted _before_ the "<div>" text into the parser -05:49 < Hixie>|sure -05:49 < Hixie>|all this is fine -05:49 < bz>|Hixie: ok. So now let's look at our case -05:49 < Hixie>|but how does document.write() know when to return? -05:49 -!- davel [davel@moz-4F4E281A.dsl.static.sonic.net] has quit [Quit: davel] -05:49 < bz>|It gives the data to the parser, and tells the parser to parse it -05:49 < bz>|Once the parser returns, document.write returns -05:50 < bz>|The parser returns when it runs out of data to parse (it's parsed it all) -05:50 < bz>|Or if it's explicitly suspended (eg by a <script src="">) -05:50 < Hixie>|AH -05:50 < bz>|All this in Gecko -05:50 < Hixie>|ok that was the key piece of information i was missing -05:50 < Hixie>|the "explicit suspension" -05:50 < Hixie>|ok -but test IE on this... - - -XXX publish a "Valid HTML5!" button with a kitten on it. Made by an artist. (Doodle?) - - -XXX rename "Block-level" and "inline-level" to something else to -prevent terminology clash with CSS. - - Interaction with document.open/write/close is undefined - How to determine the character encoding - Integration with quirks mode problems - <style> parsing needs tweaking if we want to exactly match IE - <base> parsing needs tweaking to handle multiple <base>s - <isindex> needs some prose in the form submission section - No-frames and no-script modes aren't yet defined - Execution of <script> is not yet defined - New HTML5 elements aren't yet defined - There are various cases (marked) where EOF handling is undefined - Interaction with the "load" event is undefined - - -hsivonen: -> To make document conformance a more useful concept for the purpose of catching -> author errors, I suggest that the following attributes be made required: -> href and rel on link -> href on base -> name and content on meta (other than the encoding decl) -> src on img -> code, height and width on applet -> name and value on param -... -> To allow user agents see whether the author provided the empty string as the -> alternative text of whether the author just didn't care, I suggest that the -> alt attribute on img be made optional. -(i agree -ian) -... -> On the other hand, I have doubts about the requirement of significant -> inline content. When the W3C said that paragraphs mustn't be empty, -> various applications started emitting <p> </p>. If the WHAT WG says -> that paragraphs must contend significant inline content, are the -> developers of those applications suddenly going to decide not to allow -> them to paragraphs to be saved or are they going to come up with an even -> more crufty work-around to comply with the machine-checkable -> requirements of the spec? -(i agree, i think we should drop "significant inline content". -ian) - - -bjoern: -> If the concern here is what the specification should say, then that's -> what a valid state is, not what a valid document is, since the class of -> "predictably valid" documents does not cover many dynamic documents. - - - -arv asks for: a way to track download progress of, e.g., images when -you are preloading 10 images; cf onprogress on XHR in mozilla - - -window.getAttention() or some similar API to let the user know the -page wants attention? How do you reduce the chance of irritation? -see also https://bugzilla.mozilla.org/show_bug.cgi?id=293412 - - - - -ITEM - -Items have: - - parents, children - - properties - - commands that can apply to them - - - - <li>Inline markup for pop-up windows, for example for dialog boxes - or tool palettes, so that dialogs need not be defined in separate - files.</li> - - <li>Command updating: applications that have several access - points for the same feature, for instance a menu item and a - tool-bar button, would benefit from having to disable such - commands only once, instead of having to keep each access point - synchronized with the feature's availability at all times. - Similarly menu items or tool-bar buttons that represent a toggle - state could automatically stay synchronized whenever - toggled.</li> - - <li>More device-independent DOM events: The DOM event set needs - device-independent events, such as events that fire when a button - or link is activated, whether via the mouse or the keyboard. - <code>DOMActivate</code> is a start, but it lacks equivalent HTML - attributes, and additional events may be needed.</li> - - <li>Richer widget set: the existing HTML controls are quite - limited, some controls for commonly used types such as date - controls and range controls would be useful.</li> - - <li>Sortable and multicolumn tree views and list views with rich - formatting.</li> - - <li>Ability to define custom widgets cleanly, for example using - XBL and APIs to query and control focus state, widget state, the - position and state of input devices, etc.</li> - - <li>Rich text editing: an underlying architecture upon which - domain-specific editors can be created, including things like - control over the caret position.</li> - - <li>A predefined HTML editor based on the rich text editing - architecture.</li> - - <li>Drag and drop APIs.</li> - - <li>Text selection manipulation APIs.</li> - - <li>Clipboard APIs (if the security and privacy concerns can be - addressed).</li> - - <li>Flexible box model: The existing box model in CSS is designed - largely for documents rather than user interface. We need a new - box model designed for user interface which would relieve author - complaints about other aspects of CSS and also reduce the need - for tables for layout.</li> - - <li>Window-based state management (so that new windows don't - interfere with existing sessions), for example implemented as a - per-domain, per-window "file system". This would allow multiple - instances of the same application (from the same site) to run - without the instances overwriting each other's cookies.</li> - - <li>Markup to denote <span>mutually exclusive sections</span> (as - in the commonly seen wizard interfaces).</li> - - <li>An improved CSS object model, for example with better APIs - for animation, simpler ways to navigate the rendered content, a - way to find the position of an element, methods to list the - elements under a coordinate, etc.</li> - - <li>Better defined user authentication state handling. (Being able - to "log out" of sites reliably, for instance, or being able to - integrate the HTTP authentication model into the Web page.)</li> - - -offline storage / caching pining: -http://groups.google.com/group/mozilla.dev.platform/browse_frm/thread/bf866101aa238773/a298294c27b9380a?lnk=gst&q=offline&rnum=1#a298294c27b9380a - - -DOM0 quirks that Mozilla knows about: -http://lxr.mozilla.org/seamonkey/source/dom/src/base/nsDOMClassInfo.cpp - - - -mutually exclusive sections: - <p class="example">For example, in an application for an online - mutiplayer game, there could be four mutually exclusive sections: - one for the login page, one for the network status page displayed - while the user is logging in, one for a "lobby" where players get - together to organise a game, and one for the actual game. The - different sections are the various states that the application can - reach.</p> - - -XXX make a consistent decision of which of the following formats to use: - - U+1234 FOO BAR character ("foo") - U+1234 FOO BAR character ('foo') - U+1234 FOO BAR character (foo) - U+1234 FOO BAR ("foo") character - U+1234 FOO BAR ('foo') character - U+1234 FOO BAR (foo) character - U+1234 FOO BAR character ("<code title="">foo</code>") - U+1234 FOO BAR character ('<code title="">foo</code>') - U+1234 FOO BAR character (<code title="">foo</code>) - U+1234 FOO BAR ("<code title="">foo</code>") character - U+1234 FOO BAR ('<code title="">foo</code>') character - U+1234 FOO BAR (<code title="">foo</code>) character - -And make these match: - - 0x12 (ASCII FOO) - 0x12 (ASCII "foo") - 0x12 (ASCII 'foo') - 0x12 ("foo") - 0x12 ('foo') - ---> - <script src="http://status.whatwg.org/annotate-web-apps.js" - type="text/javascript"></script> |