I worked today on updating The XMLHttpRequest Object specification and the Selectors API specification. There’s now a NETWORK_ERR exception which is raised in the rare case that you do a synchronous XMLHttpRequest and some type of network error occurs. It has code 101 and you can’t rely on that number for the foreseeable future. Specifications rock your world! Besides that I resolved all outstanding issues I thought were worth fixing and now I’m hoping some implementation experience can tell me what else needs to be changed. There is a start of an XMLHttpRequest testsuite, but it’s far from complete. All testsuites are.
The Selectors API is almost ready for Last Call. I think I sorted out the naming issue. We’ll have the following methods (prefixed by the node type on which they can be found):
Document.get()
Document.getAll()
Element.get()
Element.getAll()
Heh, may the world fall on me. Naming is a bitch. There is some half thought out rationale too:
get* methods.
As you see I also added the relevant methods on Element nodes. Why wait? The open question I have now is whether or not we need Element.matchesSelector(). I’m opting to leave it out for now, but if I get some more good use cases I suppose I can include it. It can pretty trivally be defined in terms of Document.getAll().
I like it in a decent compromise kind of way, for exactly the reasons you specify. Although it isn't really specfic in what you will be getting and how you will be getting it. I guess that's not really a problem as you will figure it out once and then remember it.
Extending it to Element is excellent! Then it works just like the other get* things.
What exactly does matchesSelector do? If it does what I think it does it would be very useful for checking if a class is defined on a specific node in a node list and stuff like that.
I don't like the naming at all. It totally contradicts what's specified in DOM1 and DOM2 in terms of consistency.
Well, I think it sucks.
~Grauw
I’m glad you add the Selector interface to elements too! :-)
Quick question: why do you have two interfaces, DocumentSelector and ElementSelector?
Dean, the main reason is that in the future we might want to add methods, such as matchesSelector, only to Element objects. (And there might be equivalent use cases for something just on Document.) From an ECMAScript perspective this shouldn’t really matter though.
I think the names are too generic. Document.get()? Get what? Based on a string? What kind of string?
Elements aren't the only things worth getting from a Document. (Nodes is an obvious one.) CSS Selectors aren't the only ways to reference document-things. (XPath is an obvious one.)
Elements are the most obvious and common one. I don’t think this is about being theoretically correct, but more about having something that is easy to use. I suppose the two don’t go always hand in hand.
That discussion thread is interesting — it shows two arguable approaches and two groups of supporters, each of which thinks the other is nuts.
I find something odd, though, Anne. Both you and several others make reference to the “failures” of getElementById and getElementsByTagName as overly-verbose methods, citing the common $ alias as proof.
I will agree that the full method names are annoying to type, but the DOM spec contains a large number of similar functions that do different things, so I don’t think the verbosity is unwarranted. Plus the spec itself points out the safety of detailed method names for an API that’s supposed to be language-independent.
Obviously I prefer typing $ over document.getElementById, but that doesn’t mean I want to see $ get put into a specification somewhere. I don’t think it’s a problem to alias a long method name, and wouldn’t mind making another alias for whatever method name the group decides on. (Consider that existing toolkits with CSS-matching functions would preserve their own terminology anyway — I’m sure Prototype will use $$ even after document.get is implemented.)
I like document.match best, and think it’s a good compromise, but standards mean you don’t always your way, and that’s fine with me.
As for Element.matchesSelector: I’m in favor of a native implementation if it’s demonstrably faster than doing a document.get(".foo").include(elementFoo) (i.e., looking for the element in the returned NodeList). I suppose this depends on whether document.get performance varies based on the size of the returned NodeList (which is unlikely).
Sorry, but those names are terrible. "get"? Get what? By what criteria? I'd rather have "match()" and "matchAll()", if it comes to that.
I'd never seen anyone float just "get()", so I'm not sure why that struck you as descriptive. In fact, I've seen at least 2 calls for brevity by dropping the "get".
I agree with the previous comment. I preferred match and matchAll. get is just too generic.
Oops! I mean matchAll and matchSingle. match on its own is also too generic.
Sorry for hogging the comments but I have written an implementation of this spec and the only thing that is stopping me publishing it is you keeping changing the names! :-) Mail me if you want a look at the code.
I don't get why getElementsBySelector() hits the wrong string with anyone. We already have getElementsByTagName() and the likes, and breaking the established naming standard (however unpleasant you may find it) is a big "no no" in my book.
I'm not a big fan of writing those big method names either, which is why I am a heavy user of Prototype and other libraries that contain $() and other similar shortcuts. Standardizing get() is like creating a standard around .NET's WebClient library instead of standardizing HTTP itself. Standards aren't supposed to be verbose, but they are supposed to be complete, unambigous, easy to understand and considerate of previous work. getElementsBySelector() gets you that. get() doesn't.
get is way too generic. I don't understand why getElementsBySelector is bad? It is consistent and descriptive. Most people will use $() and $$() or something they added anyway.
matchesSelector is very useful when trying to figure out if a behavior should be applied to an element. A very common function people use a lot is hasClass('foo'). That could be replaced by matchesSelector('.foo').
"get" strikes me as a very bad method name - not from a "what does it mean" perspective, but a reserved word perspective.
get a = function () { return null; };
with(document) {
get (b).firstChild.nodeValue = 'ouch';
}
Not sure if ECMAScript 4 will make this a problem, but ECMAScript is not the only language that needs to be taken care of. There will almost certainly be some language where "get" will be reserved for this purpose. Has this potential issue been considered?