Opened 10 years ago

Closed 10 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 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.

Change History (17)

comment:1 Changed 10 years ago by Eugene Lazutkin

Cc: James Burke added
Status: newassigned

This is ticket follows #7890.

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

comment:2 Changed 10 years ago by Eugene Lazutkin

Cc: dante added

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

comment:3 Changed 10 years ago by Eugene Lazutkin

Component: CoreHTML

comment:4 Changed 10 years ago by 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.

comment:5 Changed 10 years ago by 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.

comment:6 Changed 10 years ago by Eugene Lazutkin

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

comment:7 Changed 10 years ago by 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.

comment:8 in reply to:  7 ; Changed 10 years ago by 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.

comment:9 Changed 10 years ago by Mike Wilson

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

comment:10 Changed 10 years ago by 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.

comment:11 Changed 10 years ago by Eugene Lazutkin

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

comment:12 Changed 10 years ago by Eugene Lazutkin

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

comment:13 Changed 10 years ago by Eugene Lazutkin

Owner: changed from Eugene Lazutkin to dante
Status: assignednew

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 10 years ago by Eugene Lazutkin

Description: modified (diff)

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

comment:15 Changed 10 years ago by dante

Priority: normalhigh
Status: newassigned

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

comment:16 in reply to:  8 Changed 10 years ago by 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.

comment:17 Changed 10 years ago by dante

Resolution: fixed
Status: assignedclosed

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

Note: See TracTickets for help on using tickets.