Enhance dojo.place()

[Eugene Lazutkin]

Enhance dojo.place() by adding two more placement options:

• "children" to replace all children of the reference node with the new node or HTML fragment.
• "replace" to replace the reference node with the new node or HTML fragment.

See more details in #7890.

[Eugene Lazutkin]

This is ticket follows #7890.

If somebody has better names for placement options, please post your candidates here in the ticket.

[Eugene Lazutkin]

In #7890 James proposed to use "only" to indicate the replacement of all children.

[Mike Wilson]

I think the names are quite nice. There may be some risk for "replace" being interpreted as replacing just children, which is the other option.

An alternative could be something along the lines of "inner" and "outer", analogous with IE's innerHTML/outerHTML, but I can't say it's significantly better.

[James Burke]

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.

"replace" seems good, expresses what will happen.

[Eugene Lazutkin]

(In [16298]) Implementing replace/only placing options with tests, !strict, refs #8380.

[Eugene Lazutkin]

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.

[Mike Wilson]

Replying to elazutkin:

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 like that better, and the node/fragment will always evaluate to true so a false return value could still be used to signal error.

dojo.place() with position="only" is not so intuitive I think. I'll try to think of alternatives.

[Mike Wilson]

It should really be dojo.replace() for these two new options (just kidding ;-)

[James Burke]

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.

[Eugene Lazutkin]

Hmm, broken again? Comment 10 was addressed in [16391].

[Eugene Lazutkin]

(In [16393]) Adding a missing unit test for a placement with a number rather than a string, !strict, refs #8380.

[Eugene Lazutkin]

Please review the documentation: ​http://docs.dojocampus.org/dojo/place

If you see ways to improve it, please do not hesitate to edit the entry.

Reassigning this ticket to Pete, so he can close it after reviewing the doc.

[Eugene Lazutkin]

dojo.create() enhancements are tracked in #8446.

[dante]

will review / edit all docs pertaining and close out. thanks for all the great work guys!

[Mike Wilson]

Replying to mikewse:

dojo.place() with position="only" is not so intuitive I think. I'll try to think of alternatives.

As promised I've done a little thinking about the placement names. I had a look at HTML5 and realized that IE's outerHTML is actually making it into the standard.

With the current naming scheme the following will be equivalent (I guess?):

dojo.place("<div>...</div>", parentNode, "only");
dojo.attr(parentNode, "innerHTML", "<div>...</div>");

and so will the following:

dojo.place("<div>...</div>", parentNode, "replace");
dojo.attr(parentNode, "outerHTML", "<div>...</div>");

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.

[dante]

awesome docs uhop, thanks. it's on me to finish the dom guide now.