Opened 11 years ago
Closed 11 years ago
#8380 closed enhancement (fixed)
Enhance dojo.place()
Reported by: | Eugene Lazutkin | Owned by: | dante |
---|---|---|---|
Priority: | high | Milestone: | 1.3 |
Component: | HTML | Version: | 1.2.3 |
Keywords: | Cc: | James Burke, dante | |
Blocked By: | Blocking: |
Description (last modified by )
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.
Change History (17)
comment:1 Changed 11 years ago by
Cc: | James Burke added |
---|---|
Status: | new → assigned |
comment:2 Changed 11 years ago by
Cc: | dante added |
---|
In #7890 James proposed to use "only" to indicate the replacement of all children.
comment:3 Changed 11 years ago by
Component: | Core → HTML |
---|
comment:4 Changed 11 years ago by
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.
comment:5 Changed 11 years ago by
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.
comment:6 Changed 11 years ago by
comment:7 follow-up: 8 Changed 11 years ago by
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, null
s, or undefined
s. 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.
comment:8 follow-up: 16 Changed 11 years ago by
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.
comment:9 Changed 11 years ago by
It should really be dojo.replace() for these two new options (just kidding ;-)
comment:10 Changed 11 years ago by
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.
comment:12 Changed 11 years ago by
comment:13 Changed 11 years ago by
Owner: | changed from Eugene Lazutkin to dante |
---|---|
Status: | assigned → new |
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.
comment:14 Changed 11 years ago by
Description: | modified (diff) |
---|
dojo.create() enhancements are tracked in #8446.
comment:15 Changed 11 years ago by
Priority: | normal → high |
---|---|
Status: | new → assigned |
will review / edit all docs pertaining and close out. thanks for all the great work guys!
comment:16 Changed 11 years ago by
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.
comment:17 Changed 11 years ago by
Resolution: | → fixed |
---|---|
Status: | assigned → closed |
awesome docs uhop, thanks. it's on me to finish the dom guide now.
This is ticket follows #7890.
If somebody has better names for placement options, please post your candidates here in the ticket.