[whatwg] HTML 5 : Misconceptions Documented

[Garrett Smith]

I'm a little surprised at the lack of response here, so I'm replying
to myself here, just to keep this issue active.

I did a little more research and found that the misconception is more
common that I thought: DOM objects that have indexed properties are
often mistaken for arrays. This is the "misconception" that I found
documented in HTML5.

The following documents discuss DOM Collections using the term "Array":
 http://www.quirksmode.org/dom/w3c_core.html#t60
 http://www.quirksmode.org/dom/tests/attributesArray.html
 http://www.quirksmode.org/dom/tests/stylesheets.html
 http://ajaxian.com/archives/preloading-images-with-jquery#javascript-1
 http://jennifermadden.com/javascript/arraySimple.html
 http://httpunit.sourceforge.net/doc/javascript-support.html

Ian had politely asked me to post this information to the list.

Calling an HTMLCollection an array will mislead developers who don't
know the difference. It might also lead a reader to believe that the
author of the HTML specification deliberately used the word 'array'
and that "elements" is an array (not an HTMLCollection).

It seems that the only benefit in calling an HTMLCollection an array
is that 'array' is shorter to type.

Typing "HTMLCollection" is longer than typing "array" but it is misleading.

But that still leaves the other two issues. The first is the worst, I
think, because it relies on deprecated behavior and isn't very good
practice.

Garrett

On Tue, Jul 29, 2008 at 11:33 PM, Garrett Smith <dhtmlkitchen at gmail.com> wrote:
> I took a brief look at the WF 2.0 document yesterday and found some
> serious misconceptions and examples of "programming by coincidence."
> These reflect very poorly on html5.
>
> The errors can be found on the link:
> http://www.whatwg.org/specs/web-forms/current-work/#select-check-default
>
> Doc Bugs:
> 1) Treating a a form element as an HTMLCollection.
> 2) The use of - with - to augment the scope chain is not necessary.
> 3) Calling the "elements" HTMLCollection an "array"
>
> (1) The definition of HTMLFormElement does not have a specialized [[Get]]
> for element names (nor should there be, as this is known to be
> problematic). The example in the documetation depends on such behavior.
>
> (2) - with - augments the scope chain with the object. This is completely
> unnecessary here and will create problems if, for example, there is an
> element named "watch". It is a bad practice and I see this influence in the
> popular libraries.
>
> (3) There is no specification for a special [[Get]] for the "elements"
> HTMLCollection as a shortcut to "namedItem", either (though this would not
> seem to be a problem, and all implementations have supported this behavior
> for quite a long time). I did notice that the elements collection is
> mistakenly called an 'array'. This is a serious documentation mistake of
> the worst kind: The spreading of misinformation. It will continue influence
> the muddy knowledge that is so common among most developers who tend want
> to call "push" et c directly on that NodeList object (see the
> "dojo.NodeList" for details). The elements Collection should be called an
> HTMLCollection and this should be changed immediately.
>
> // WRONG
> document.forms[0].qty,
>
> The "elements" property is what the example should use:-
>
> // RIGHT.
> document.forms[0].elements.namedItem('qty');
> document.forms[0].elements.qty; // Access via custom get
>
> This avoids ambiguity when having a form that has an element named "name",
> for example. It becomes ambiguous as to whether the "form.name" refers to
> the element or the form's "name" attribute. Problems could also arise with
> "action", "length", "toString", "elements".
>
> -------------------------------------------------
> // (GS) Don't augment scope chain here.
> with (document.forms[0]) {
>
> // (GS) Don't treat a form as a collection.
> // Use the 'elements' colletion.
>  if (qty.validity.valueMissing) {
>    // the quantity control is required but not filled in
>  } else if (qty.validity.typeMismatch) {
>    // the quantity control is filled in, but it is not a number
>  }
> }
>
> And further down:-
>
> // (GS) Don't treat a form as a collection.
> // Use the 'elements' colletion.
> var myControl = document.forms[0].addr;
>
> if (myControl.value == 'a at b.c') {
>  myControl.setCustomValidity('You must enter your real address.');
> }
> -------------------------------------------------
> Fixed:
>
> var f = document.forms[0],
>    qv = f.elements.namedItem('qty').validity;
>
>  if (qv.valueMissing) {
>    // Value required but not filled in.
>  } else if (qv.typeMismatch) {
>    // Value filled in, but it is not a number.
>  }
> }
>
> var addErrInvalidMsg = 'You must enter your real address.';
> var addr = document.forms[0].elements.namedItem('addr');
> if (addr.value === 'a at b.c') {
>  addr.setCustomValidity(addErrInvalidMsg);
> }
>