[whatwg] getElementsByClassName() feedback

[Garrett Smith]

It is often desirable to capture events on bubble and interrogate the
EventTarget using a hasClassName function to see if it has a className
that the program is concerned with.

Assuming an - addCallback - function that acts as an adapter for
addEventListener/attachEvent,

addCallback(document, "mousedown", docMouseDown);

function docMouseDown(ev) {
  var target = EventUtil.getTarget(ev);
  if(!hasClassName(target, "panelActuator") ) return;
}

The above code relies on a - hasClassName - function. These are
widespread on the web and the practice is very common. It might be
useful to have a native function that does the same thing. For
example, the following code assumes a - hasClassName  - function on an
element:-

function docMouseDown(ev) {
  var target = EventUtil.getTarget(ev);
  if(target.hasClassName("panelActuator"));
}

I would like to propose three methods on HTMLElement:-

hasClassName
removeClassName
addClassName

removeClassName - removes the className from the element, trimming ws.
addClassName

Existing code (library functions) would be able to leverage the native
code where available. For example, the following code could be
refactored:-

/** @param {HTMLElement} el
  * @param {String} klass className token(s) to be removed.
  * @description removes all occurrences of <code>klass</code> from
  * element's className.
  */
function removeClass(el, klass) {
    el.className = normalizeString(el.className.replace(
  getTokenizedExp(klass, "g")," "));
}

-

function removeClass(el, klass) {
    if(el.removeClassName) {
        el.removeClassName(klass);
    }  else {
        el.className = normalizeString(el.className.replace(
  getTokenizedExp(klass, "g")," "));
    }
}

. When implementation of Element removeClass is widespread enough, the
function could be replaced with inline code.

If the selectors API gets widespread enough use, it might also be
useful to have Element method | isMatchingSelector(selectorText) |.

Garrett

On Mon, Oct 8, 2007 at 1:25 PM, Ian Hickson <ian at hixie.ch> wrote:
> On Sat, 14 Jan 2006, Karoly Negyesi wrote:
>>
>> A getElementsByCSSSelector IMO would be great and introduces minimal
>> plus burden on browsers -- they have CSS selector code anyways.
>>
>> It's very unfriendly that I can do magic with CSS2/3 selectors and then
>> I need to translate them myself if I want to change them on-the-fly.
>
> You may find this specification to be of interest:
>
>   http://dev.w3.org/cvsweb/~checkout~/2006/webapi/selectors-api/Overview.html?content-type=text/html;%20charset=utf-8
>
>
> On Tue, 24 Oct 2006, Dean Edwards wrote:
>> > >
>> > > Personally, I prefer a comma delimited list. Passing an array seems
>> > > yukky.
>> >
>> > Really? I always thought the comma-separated argument to window.open()
>> > was one of the ugliest APIs ever...
>>
>> This isn't the same thing. We are faking varargs so whatever we do is
>> going to look a bit ugly. Nine times out of ten this method will be
>> called with one argument:
>>
>> var menus = document.getElementsByClassName("menu");
>>
>> That is much more intuitive for the most common case.
>
> True.
>
>
> On Tue, 24 Oct 2006, Gervase Markham wrote:
>>
>> Why not allow a string in the single class name case, but require an
>> array for multiple class names?
>>
>> Alternatively, we could make it more obvious that it takes an array by
>> calling it document.getElementsByClassNames(["...", "..."]); This gives
>> a little hint, and is a more accurate description of what the function
>> does.
>
> Also true...
>
>
> On Sun, 5 Nov 2006, Anne van Kesteren wrote:
>>
>> I think this hasn't been suggested before. Perhaps the method should
>> accept a DOMTokenString as argument instead of an array. This allows
>> things like ele.getElementsByClassName(ele.className) etc. The only
>> problem is how to get a DOMTokenString without first getting .className
>> from somewhere. Perhaps it should be a constructor as well. 'x = new
>> DOMTokenString("aaa bbb")'
>
> We could, though that's far more awkward.
>
>
>> * The examples use a mix of accepting arrays and strings. This should be
>> fixed I assume.
>
> Fixed.
>
>
>> * In "HTML, XHTML, SVG and MathML elements" you can drop XHTML as it's
>> clearly defined in the specification what HTML elements means.
>
> Ok.
>
>
> On Sun, 5 Nov 2006, Anne van Kesteren wrote:
>>
>> Hixie, the title attribute of the remove(token) definition says
>> dom-tokenstring-add rather than dom-tokenstring-remove...
>
> Fixed.
>
>
> On Fri, 2 Feb 2007, Robert Sayre wrote:
>>
>> I landed support for this on the Mozilla trunk, and it will appear in
>> upcoming Firefox alphas and betas. The array argument turned out to be
>> quite a pain to implement, so we cut it. If other implementors feel it's
>> worth it, we can put that support back in.
>
> Ok. I've changed the spec to use a space-separated list.
>
>
> On Sat, 7 Jul 2007, Lachlan Hunt wrote:
>>
>> It could be defined to accept either a space separated string or an
>> array. Using the [Overloads] extended attributed defined in the Language
>> Bindings for DOM Specifications draft [1], it could be defined like
>> this:
>>
>> NodeList getElementsByClassName(in DOMString classNames);
>> [Overloads=getElementsByClassName]
>>      NodeList getElementsByClassNameArray(in DOMString[] classNames);
>>
>> For ECMAScript, that effectively means that getElementsByClassName() can
>> be called with either a space separated string of class names or an
>> array.
>
> I've dropped the array form altogether.
>
>
> On Mon, 9 Jul 2007, Jonas Sicking wrote:
>>
>> I agree with Simon here. Allowing arrays to be passed in doesn't add any
>> extra value and complicates the implementation significantly. I think
>> that the by far most common case is going to be passing a single class
>> name, so adding multiple ways of passing multiple class names seems like
>> overkill.
>
> Agreed.
>
>
> On Tue, 10 Jul 2007, Dan Dorman wrote:
>>
>> Granted, the most common case will indeed be asking for a single class
>> name.  But, if we're going to the trouble of accepting multiple class
>> names, it seems shortsighted to restrict the parameter for the
>> multi-class case to a space-separated string, which is really just a
>> kludgey way of representing a list (or array).
>
> Agreed as well, but implementation feedback seems to be that accepting an
> array is more expensive than it's worth.
>
> --
> Ian Hickson               U+1047E                )\._.,--....,'``.    fL
> http://ln.hixie.ch/       U+263A                /,   _.. \   _\  ;`._ ,.
> Things that are impossible just take longer.   `._.-(,_..'--(,_..'`-.;.'
>