Influence a future W3C Standard: Selectors API

[zcorpan]

Hey,

There has been a lot of discussion on the public-webapi@w3.org mailing list about what names these methods should have. I was interested in what you guys think are the best names.

What do they do?
Simply put, you can get either the first element in the document, or a static nodelist of all elements in the document, that match a group of selectors, using two different methods. They can both be used on Documents and on Elements. Example (using "XXX" and "YYY" as method names here, respectively):

var e = document.XXX("#nav ul");
var items = e.YYY("li"); // static nodelist

This will be supported natively in browsers in due course so you don't need to use libraries for this anymore.

See the working draft of the spec, or the editor's draft.

So what do you think are appropriate names for these two methods? Why?

[zcorpan]

Oops. The last two should have been:

• getElementBySelectors(), getElementsBySelectors()
• getElementBySelectors(), getElementListBySelectors()

...that is, with an s on the end. Sorry for the typo.

[Kravvitz]

Why would there be two different methods? Why would you want a method that could only ever return a single element?

[AutisticCuckoo]

For efficiency reasons, probably. A simple ID selector can never match more than one element, so returning an array or node list is unnecessary.

Returning a single element node would let us skip the array index reference. Compare to these existing functions:

var e1 = document.getElementById("foo");
var e2 = document.getElementsByTagName("body").item(0);

[zcorpan]

Yeah, it's for performance. The second method will have to walk the entire tree, and the common case is probably that you just want one element matching the selector.

[AutisticCuckoo]

Off Topic:

walk the entire tree

Random Friday thought: why is it called 'walking' a tree? Shouldn't it really be 'climbing' a tree?

[mw22]

Well, personally I prefer getElementsBySelector() instead of getElementListBySelectors(), but I think it is at least a lot better than getAll(), which I don't like at all.

I think the getElementBySelectors() method is totally unnecessary.

[zcorpan]

Off Topic:


Random Friday thought: why is it called 'walking' a tree? Shouldn't it really be 'climbing' a tree?

Off Topic:

Climbing sounds more like an all-out effort, while walking the tree is actually a pretty simple task.

Well except the trees that come from IE, you can get around in circles in those and see the same things twice! More like a bush full of weeds and fungus.

[MikeFoster]

getElementsBySelectors() is more in line with the existing naming convention - even tho matchOne/matchAll is certainly easier to type. But having only one letter difference between two (long) function names is just asking for typo bugs

Seeing as how IE only just now supports CSS1 - I think we'll be using our own Js implementations of these functions for a long time to come

[Kravvitz]

For efficiency reasons, probably. A simple ID selector can never match more than one element, so returning an array or node list is unnecessary.

For an ID, why wouldn't you just use getElementById(). I suppose it would be useful if you use :first-child or :last-child though.

Yeah, it's for performance. The second method will have to walk the entire tree, and the common case is probably that you just want one element matching the selector.

Even if an ID selector was used at the beginning of the selector chain?

[zcorpan]

Even if an ID selector was used at the beginning of the selector chain?

Yeah. Multiple elements can have the same ID. It is invalid, mind you, but it would "work" just like it already does in CSS.

[Raffles]

This is great, but when you say browsers will implement it, has Microsoft made any noise about when they're going to update their javascript engine?

getElementListBySelector() is a bit of a mouthful and get()/getAll() sounds Microsoftish (like document.all) so I agree with the others that it's best to stick with the name convention - I vote for option 3.

[Kravvitz]

Perhaps getOneElementBySelectors() and getElementsBySelectors() would be less prone to unnoticed typos.

[Raffles]

What about merging both into one: getElement(s)BySelector(s)()?

On a more serious note, am I right in thinking that getElementBySelectors('#nav li.even') would only match the first li.even in the ul? Or would it be the last?

[zcorpan]

On a more serious note, am I right in thinking that getElementBySelectors('#nav li.even') would only match the first li.even in the ul? Or would it be the last?

The first.

The get(selectors, nsresolver) method, when invoked, must return the first Element node in document order (using depth-first pre-order traversal) that matches the group of selectors (selectors), if any. Otherwise it must return null.

[felgall]

Yeah. Multiple elements can have the same ID. It is invalid, mind you, but it would "work" just like it already does in CSS.

Since having a second element with the same ID is invalid there is no need for a browser to continue looking once it finds the first one since the subsequent ones shouldn't be there and it is therefore more correct to ignore them and assume that they don't exist than it would be to continue searching for something which in a valid page wont be there. Any browser that continues searching once it finds the first occurrence of an id is just being inefficient.

[felgall]

This is great, but when you say browsers will implement it, has Microsoft made any noise about when they're going to update their javascript engine?

getElementListBySelector() is a bit of a mouthful and get()/getAll() sounds Microsoftish (like document.all) so I agree with the others that it's best to stick with the name convention - I vote for option 3.

At Microsoft's current rate of progress of implementing CSS I would say that if a standard were adopted for this TODAY then it would probably make it into Internet Explorer 14 (which Microsoft will probably release in approximately 2084 - assuming of course that they still exist by then)

[zcorpan]

Since having a second element with the same ID is invalid there is no need for a browser to continue looking once it finds the first one since the subsequent ones shouldn't be there and it is therefore more correct to ignore them and assume that they don't exist than it would be to continue searching for something which in a valid page wont be there. Any browser that continues searching once it finds the first occurrence of an id is just being inefficient.

Authoring conformance requirements and UA conformance requirements are two completely separate things. UAs are not free to do whatever they want when faced with something that authors are not allowed to do. They must still follow the spec, and now the spec says that UAs must catch all elements matching the group of selectors. If there are two elements matching the selector "#foo" then they must both be catched.

However, I've asked the WG about this case. If it ends up making the spec clearer then that's a good thing.

Edit:

http://lists.w3.org/Archives/Public/...7Jan/0119.html

[felgall]

Presumably after determining that there are multiple elements with the same id on a web page the browser will then report an ERROR and refuse to process any of them since the page is invalid and to do anything else would be compounding the error. Only by IGNORING any subsequent occurrences and treating the page as if only the first one exists is any consistent approach that doesn't involve giving an error possible. So presumably if the search for subsequent occurrences is required to continue past the first occurrence of an ID the browser will be required to abort the display of the page as soon as an invalid second occurrence is found. At least aborting the display of the page will make it more obvious to the author of the page that they have made a stupid error.

[MikeFoster]

If there are two elements matching the selector "#foo" then they must both be catched.

That makes about as much sense as event.button == 0 for left click