Gecko DOM Reference

There was a scripting error on this page. While it is being addressed by site editors, you can view partial content below.

General Notes

 

ToDo

I'm ready to help with this.  I'll get on it as soon as time permits.  Contact me if you have ideas (mine are just to copy the layout of other pages). --Jesdisciple 20 June 2009

They scare me; I don't understand the formatting on them - somebody else please do it. JesseW 02:00, 27 Jun 2005 (PDT)
  • Decide if we want to migrate the Preface
I think it's pretty out of date, and might not be worth importing... JesseW 02:14, 27 Jun 2005 (PDT)
  • Decide what to do about window.updateCommands - while the Gecko DOM Reference has a page on it, the page contains no real information. We could write some, remove the red link from the ToC page, or something else.
Found something on bugzilla and migrated it to that page, though I have no idea if it's correct as I'm not familiar with window.updateCommands. --Maian 04:54, 19 October 2005 (PDT)
  • Migrate the window.onX properties - they are somewhat different than the onX pages - should we merge the information, make seperate pages, or what?
  • Decide what to do with the DOM Event Handler List
it seems like we probably have a better format for this, so migrating it might be a waste of time, plus most of the descriptions are blank. It's also incomplete, I think. JesseW 02:14, 27 Jun 2005 (PDT)

Re: Jesse's changes

  • Wouldnt a __NOTOC__ have made sense here? instead of removing the sections. This could have also formed an actual "Table of contents" with quick-links to each sections information, such as document -> innerHTML instead of having to click Document then innerHTML to get there... (hell with advanced import methods we could simply import in, but we are not at that stage yet). -Callek 21:10, 14 Jun 2005 (PDT)
Sorry; forgot about NOTOC. I'll revert, and do it that way. Yes, it would be nice to have a full table of contents on this page eventually; I was just getting tired of having to either click on the ToC or scroll down to reach the actual links. A temporary NOTOC until we can get the full one put in is a better solution. JesseW 22:23, 14 Jun 2005 (PDT)
Yeah, the original first-page for this document was thrown together really quickly because I just needed somewhere to stash GT's new version of the window.open document. It needs to be sorted out, and I need to figure out what a "proper TOC" should look like for Devmo. I will work on that today. dria 05:15, 15 Jun 2005 (PDT)
  • OK, I've revamped the TOC and document, element, and window subpages. If you have a major problem with the new formatting, let me know. Try to format new pages the same way, and the TOC page (this one) should link to the top level sections of the subpages as well, like the others. - dria 06:30, 15 Jun 2005 (PDT)

Needs technical review

Judging from the pages I've edited so far, the reference needs a tecnical review badly. I'm marking it as such. --Nickolay 10:33, 19 Aug 2005 (PDT)

Mixing interfaces

[from Talk:DOM:element] It's bad that we mix the methods of different interfaces all on one page, e.g. DOM:element.length is actually a member of NodeList. It's probably ok to mix the Node and Element interfaces (with proper warnings), but mixing completely different things like NodeList here is really bad. --Nickolay 06:10, 18 Aug 2005 (PDT)

[update] Well, in fact I think we should not even mix Element and Node interfaces together, given that we attempt to document stuff like getAttributeNode. We might want to include Node's methods on Element page, but not just have a single page with methods of the two mixed together. --Nickolay 07:42, 18 Aug 2005 (PDT)

[from Talk:DOM:document] Should there be a section that includes inherited interfaces? For example, Document inherits the Node interface (thus gaining appendChild() and company). --Maian 12:04, 28 September 2005 (PDT)

Also, this and other pages actually cover multiple interfaces. document implements Document, HTMLDocument, DocumentView, and lots of other interfaces. window implements Window and AbstractView. Elements implement Element, Event Target, and others. And so forth. Should these interfaces be mentioned? If so, how will formatting take this into account. The simple with-or-without asterisk doesn't work with more than two interfaces. --Maian 12:17, 28 September 2005 (PDT)

Okay, I take back what I said before about this reference. It should really mention, and even be based on interfaces description. Otherwise it's not going be technically correct.
My current idea is to describe the DOM interfaces (e.g. DOM:EventTarget.*), and have the pages like DOM:document/DOM:element list all the methods of implemented interfaces (using mediawiki include; we'll probably need to tweak it to be useful). Pages like DOM:element would link to the interfaces' pages for detailed description.
One of my concerns is that this info would duplicate the nsIDOM* interfaces description.
BTW, should this be moved to Talk:Gecko DOM Reference? --Nickolay 07:57, 15 October 2005 (PDT)
Sounds like a good idea. --Maian 08:17, 15 October 2005 (PDT)
This would also help in determining where to put static properties, namely constants. For example, the nodeType constants on Node and the DOM:event.eventPhase constants on Event. --Maian 01:14, 17 October 2005 (PDT)
It looks like the naming scheme is to have interfaces be capitalized (DOM:EventTarget) and to have "prototypical" instances be lowercased/camel-cased (DOM:window). So would that mean there will both be a DOM:Document and DOM:document, one for the interface and one to actually describe what a document is? How would this be for more specific objects, such as say, the br element? DOM:HTMLBRElement and DOM:br? If you plan to take this approach, it would be nice to have a list of what the prototypical instance names would be. --Maian 20:30, 17 October 2005 (PDT)
I don't like the DOM:Document vs DOM:document and having both DOM:HTMLBRElement and DOM:br. I don't have a good idea how to deal with it, and frankly I don't care about HTML-specific DOM. --Nickolay 08:04, 18 October 2005 (PDT)
I'd prefer for it to all be capitalized, but DOM:element and DOM:range already set a precedent. We should decide on these trivial details before creating new sections before it bites us in the behind later on when we'll have to do a bunch of moves. Concerning HTML, are you saying we shouldn't have any HTML DOM pages? --Maian 04:30, 19 October 2005 (PDT)
Sure if we go with documenting the interfaces, we should have them capitalized, as in the spec. DOM:element is not strictly about the Element interface, so it doesn't actually set a precedent. Concerning HTML, I just said that I don't care about it. --Nickolay 05:52, 19 October 2005 (PDT)

XUL references

A number of references to XUL objects and methods are appearing on the DOM:window page (e.g. window.content, window.atob, window.btoa). Should these be in a separate section, or somehow highlighted as being part of XUL 'DOM' and not the HTML DOM?

--RobG 20:44, 9 January 2006 (PST)

I would personally like that, I suggest bringing it up on the mailing list. --Callek 15:11, 10 January 2006 (PST)

Format

There's some inconsistency in how each page in this reference is structured, so I'm going to propose a guideline.

For methods:

  1. Summary
  2. Syntax
  3. Parameters
  4. Returns
  5. Notes/Description and any subsections (omit if n/a)
  6. Examples (omit if n/a)
  7. See also (omit if n/a)

For properties:

  1. Summary
  2. Syntax
  3. Returns
  4. Notes/Description and any subsections (omit of n/a)
  5. Examples (omit if n/a)
  6. See also (omit if n/a)

For interfaces (or objects that represent that interface, e.g. window, document):

  1. Summary
  2. Description and any subsections
  3. Static properties (omit if n/a)
  4. Static methods (omit if n/a)
  5. Properties (omit if n/a)
  6. Methods (omit if n/a)
  7. See also (omit if n/a)

Example of method page:

(breadcrumbs and template)

== Summary ==
Concise one or two-liner.

== Syntax ==
 foo(a, b, c)

Static method of [[DOM:Interface]]

== Parameters ==
 ; <code>a</code>: desc
 ; <code>b</code>: desc
 ; <code>c</code>: desc

== Returns ==
A string that does blah.

== Description ==
Elaborate on summary.

== Examples ==
=== Example: Using <code>foo</code> ===
...

== See also ==
[[DOM:Interface.bar|bar]],
[[DOM:window.alert|window.alert]]

How's that?

Also, how should methods and properties be referenced in name? Choose one of the following schemes:

  • Node.appendChild; Node.ELEMENT_NODE - always use "."
  • Node's appendChild; Node.ELEMENT_NODE - only use "." for static properties/methods
  • Node.appendChild(); Node.ELEMENT_NODE - always use "." and use "()" with methods
  • Node's appendChild(); Node.ELEMENT_NODE - only use "." for static properties/methods and use "()" with methods

Forgot to mention: how would static and instance props/methods be distinguished in the wiki name considering the above?

--Maian 09:09, 17 October 2005 (PDT)

I don't like that each page consists of many small sections. I also don't like how things like return values and other are called 'parameters'. Therefore I suggest that we merge syntax/parameters/returns into a single section, get rid of 'summary' section, and use __NOTOC__ on most pages. For example see Sandbox:DOM:element.hasAttribute.
We don't seem to use parentheses for methods' pages in wiki. I don't think we have to use different naming scheme for static properties - just mention that they are static on the page itself.
We probably should discuss it on the mailing list before doing major reformatting.
--Nickolay 11:52, 17 October 2005 (PDT)
Why "summary"? Summary is wrongly used here. Summary is often used in article; I explained in RobG's talk page page why summary is not best used (along with an example). FYI, scientific documents use "Synopsis". Either we use "Definition" as the first section or, like Nickolay suggested, we get rid of the 'summary' section. Either way is fine with me.
I also agree that we should merge syntax/parameters/return value into a single section. Parameters obviously should apply to functions, to methods and not to properties. The old Gecko DOM reference was clearly wrong on that.
--GT January 24th 2006
That sounds good, though in that sample page, I think it should just say "boolVal" (or something similar) instead of "[ true | false ]":
boolVal = element.hasAttribute(''attrName'')
or
hasAttribute(''attrName'')
...
returns a boolean (if not described elsewhere, describe what it returns)
or IDL-like:
boolean hasAttribute(''attrName'')
--Maian 20:23, 17 October 2005 (PDT)
[true | false] thing was copied, I don't like it either. The reference seems to use boolVal = method() notation, and I'm fine with it. --Nickolay 08:06, 18 October 2005 (PDT) [edit 17 Jan 2006] after some discussion on RobG's talk page I'm not sure I'm fine with it anymore. Maybe IDL would indeed be better (for me at least)
Updated Sandbox:DOM:element.hasAttribute --Nickolay 10:39, 8 January 2006 (PST)

References

There are properties and methods included in the DOM reference that aren't implemented by Gecko, e.g. DOM:element clientLeft and clientTop.

I've added Not currently supported after them on the index page and in their actual page. There are also links to MSDN for a number of properties and methods that aren't in the W3C DOM, should that be done for all that don't have a W3C reference? Should all references to MSDN be removed?

Should methods, properties, whatever that aren't implemented by Gecko be mentioned at all? There are many, many MS IE methods and properties that aren't mentioned here—I'm not suggesting that they should, just that it's inconsistent that some are but most aren't. Should anything be done about it?

--RobG 03:51, 8 January 2006 (PST)

I think that links to MSDN can be kept if they are useful to our readers.
I personally find it strange that we're documenting IE-only properties in the Gecko DOM reference. I think it was discussed on the list briefly. --Nickolay 10:30, 8 January 2006 (PST)
Even now, "IE-only" and "DOM 0" properties, over time, can become W3C recommendations* and/or receive Gecko support at some point. Therefore, having them all somewhere here would at least remove any doubt about whether a property is either not supported or if it's just missing from this wiki. (*For example, CSSOM View Module is a working draft as of 2008 and includes properties such as element.offsetLeft and window.innerHeight which are currently documented under DOM 0 with MSDN links - that should probably change - but maybe only if the working draft becomes a recommendation?) --George3 16:22, 19 July 2008 (PDT)

Attributes

We need some information about attributes vs attr-nodes and non-namespace-aware methods vs namespace-aware ones (in particular the gotcha with attributes being in the null namespace by default, even if there's a non-null default namespace specified using xmlns ). --Nickolay 06:33, 28 May 2006 (PDT)

Document Tags and Contributors

Contributors to this page: Jesdisciple, George3, Nickolay, GT, Callek, RobG, Maian, Gor1, JesseW, Dria
Last updated by: Jesdisciple,