I was not sure if "only" was expressive enough. Maybe "onlyChild", but I don't like the mixed case. But "only" does seem to map to the children the same way "first" and "last" do, so maybe "only" is good enough.

The functionality is implemented as replace/only position arguments. We have time to come up with better names until 1.3.

I didn't close this ticket because I've noticed a bizarre thing --- it returns a Boolean value, and it is always true, unless the node or refNode are computable to false --- empty strings, nulls, or undefineds. The inline documentation says that it "returns true if successful, false otherwise". I can think of one possible scenario for being unsuccessful with seemingly valid arguments: using before/after/replace when refNode doesn't have a parent. Right now it just bombs.

Another problem is what to do with the instantiated fragment after the successful placement --- the only way to access it in some cases is to run dojo.query(). Or reverse the placement manually --- grab the next sibling, or the first child, or whatever you were doing while placing. The reversing doesn't work very well when instantiating a fragment. Anyway it feels clumsy --- just take a look at tests in dojo/tests/_base/html_element.html.

The better option is to return the instantiated node/fragment as the return value, but it'll break the current API. OTOH, the current return code seems pretty much useless to me.

I agree with Eugene: the current return is broken, and if the Dojo/Dijit/Dojox? codebase is any indication, it is never even checked. So I'm fine if returned the first arg (if it was a node to start) or the generated _toDom node.

The problem with returning a _toDom result is the issue Alex raised where you could get a DocumentFragment? back, and it does not operate like something that may be intelligible to the developer. I can see the issue: you can't do things like .innerHTML on a DocumentFragment?.

I think the developer can handle it: if they are passing in lots of top level HTML elements for creation (a minority case compared with just making one top level node -- which we then return just the bare DOM node), then they can handle the container type that holds them, particularly if we document.

We stick with the bare browser constructs for these kinds of methods. Maybe for Dojo 2.0 we could standardize on dojo.NodeList?, but for now, I would not feel comfortable starting to introduce NodeList? returns piecemeal. Exposing DocumentFragment? and having the developer learn about the normal DOM constructs does not seem onerous, particularly if it was documented.

But, this was the reason for setting _toDom to private. So not sure yet how to resolve that.

Looking at this, my best suggestion for alternatives to only/replace is something that involves "inner" and "outer". The most descriptive would be replaceInner/replaceOuter but that is too long. If you consider it interesting we can probably find something suitable.