Re: Selectors API naming

I agree with what Bjoern says below about the need to avoid name clashes.

If developers don't like the long names such as getElementsBySelectors(),
then they can write their own JavaScript wrapper functions that have
shorter names, such as function matchAll(...) { return
getElementsBySelectors(...); }

Jon

Jon Ferraiolo <jferrai@us.ibm.com>
Web Architect, Emerging Technologies
IBM, Menlo Park, CA
Mobile: +1-650-926-5865



                                                                           
             Bjoern Hoehrmann                                              
             <derhoermi@gmx.ne                                             
             t>                                                         To 
             Sent by:                  "Anne van Kesteren"                 
             public-webapi-req         <annevk@opera.com>                  
             uest@w3.org                                                cc 
                                       "Web API WG (public)"               
                                       <public-webapi@w3.org>              
             12/21/2006 03:24                                      Subject 
             PM                        Re: Selectors API naming            
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           





* Anne van Kesteren wrote:
>[...]

I would like to point out that there exists a valid technical reason for
using different method names than the ones in the current draft. One of
reasons why the DOM uses longer, more descriptive names is to avoid name
clashes. The current draft essentially reserves the names 'matchAll' and
'matchSingle' for attributes and methods on all specialized Document and
Element interfaces. This implies, among other things, that you cannot
make a markup language where you have

  <foo matchAll='...' or <foo match-single='...' etc.

and provide a 1:1 mapping from attributes in the markup to attributes in
the DOM since foo.matchAll would be the Selector API method where it is
implemented on Element nodes which is likely to occur in the future as
per the current draft. The same goes for any other use of these names,
you could not make a .matchAll attribute that, for example, indicates if
all children of an element match the element in a specialized DOM API
where this is desired functionality. The naming should therefore not be
taken lightly.

As far as the names go, I do not think they are intuitive at all. I tend
to associate boolean semantics and text string operations with match*
names, document.matchAll sounds to me more like a method to highlight
text strings in a document, for example to highlight search terms on a
page. In fact, several web sites I use have match=search+terms in the
URL for exactly this purpose. For these two reasons, I think that the
name should include terms like 'CSS' or 'Selector' in its name.

>These names would also be slightly confusing as they would not take a
>selector but rather a group of selectors. I suppose the group in favor of

>these methods find that acceptable. I wonder if they find the
>inconsistency with the other DOM methods to be acceptable as well.

I do not think that properties of return values such as liveness should
influence naming, so I do not really see how picking such a name would
introduce any new inconsistency. As for selector groups, you could just
use getElementsBySelectors(...) or getElementsByCssQuery(...) or just
cssQuery(...). I'd be fine with 'cssQuery' and 'cssQueryOne' instead of
the current methods; these names happen to be exactly as long, would not
have either of the problems mentioned above, and are already well-known
among developers if

  http://www.google.com/search?q=matchall+css
  http://www.google.com/search?q=cssquery+css

counts as "evidence". We already broke the getElementsBy... convention
with the .selectNodes(...) and .selectSingleNode(...) methods, we have
plenty of experience that this is not too big an issue. I'd be fine with
the getElementsBy... versions above though of course.

>It seems that libraries find there's a need to provide shortcuts for the
>several of the above mentioned methods (notably document.getElementById
>and document.getElementsByTagName). Several authors have argued that they

>don't see a need for such a thing but no "evidence" has been provided. No

>evidence to the contrary either, though.

These libraries typically do not simply set up some alias for a feature
like the Selectors API, they would add code to detect whether the user
agent supports the feature, might switch to an alternate pure-script im-
plementation in case it does not, they might have work arounds for known
issues, they might have a pre-defined namespace resolver so you have the
prefixes for all the common namespaces available, they might add some
tracing code for debugging purposes, and they might add other features.

Further, no name can remove the `document.` you have to put in front of
it, and if you can have document.matchAll(...) or cssQ(...), you'd pick
the latter. As such I do not think the argument, if we pick a short name
the library designers won't write wrapper functions, holds at all. If I
were to make considerable use of the API, I would certainly write one,
if only so I can use BH.cssQuery(...) instead of document.matchAll(...,
BH.stdNamespaceResolver).
--
Björn Höhrmann · mailto:bjoern@hoehrmann.de · http://bjoern.hoehrmann.de
Weinh. Str. 22 · Telefon: +49(0)621/4309674 · http://www.bjoernsworld.de
68309 Mannheim · PGP Pub. KeyID: 0xA4357E78 · http://www.websitedev.de/