[whatwg] HTML 5 : Misconceptions Documented

[Garrett Smith]

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);
}