Question about siblings and returned values

[mercmobily]

Hi,

In the doc, I read:

We could also use sibling combinators to place the referenced element. We could place the "second" element after (as the next sibling) the "first" element:

put(first, "+", second);

It also says:

The put function returns the last top level element created or referenced. In the examples above, the newly create element would be returned.

Now... look at this code:

      var first = put('div.first');
      var second = put('div.second');

      var t = put( first, "+", second );
      console.log(first);
      console.log(second);
      console.log('--------');
      console.log(t);

Now... this is meant to modify first so that it adds "second" as a sibling (note that I am using the same example given in the docs). But that's not what's happening:

<div class=​"first">​</div>​
<div class=​"second">​</div>​
--------
null 

So:

• The last top element created or referenced should be "second", but that's not returned
• If you write put( first, "+", second ), it implies that the result is an element where first and second are siblings, but... that element doesn't even exist, nor we asked put() to create it!

Something that would make more sense is:

      var first = put('div.first');
      var second = put('div.second');

      var t = put( 'div', first, "+", second );
      console.log(first);
      console.log(second);
      console.log('--------');
      console.log(t);

Result:

<div class=​"first">​</div>
<div class=​"second">​</div>​
--------
<div>​
  <div class=​"first">​</div>​
  <div class=​"second">​</div>​
</div>​

So, "div" is created, it's appended first, and then "second" as a sibling of first. Now it makes sense... except, why is the newly created div returned, rather than second (which is the last element referenced!)

Help? :D

Merc.

[mercmobily]

Hi,

Note that I would normally answer my own questions by looking at the source code. However, opening the 230 lines of put.js makes me feel so braindead, and it's so beyond anything I could ever come up with, that I have no choice but ask here...!

Merc.

[kriszyp]

I added some more explanation in the documentation to try to clarify the return values and combination operator behavior. Let me know if you think it makes sense, or if the docs (or behavior) should be different.

[mercmobily]

Hi,

(It's an honour talking to you. I am in awe when I look at your code!)

The put function returns the last top level element created or referenced from a selector. In the examples above, the newly create element would be returned. Note that passing in an existing node will not change the return value (as it is assumed you already have a reference to it).

This clarifies it a lot. So, "existing elements don't count"!

But according to this sentence:

 var first = put('div.first');
 var second = put('div.second');
 var t = put( first, second );

put seems to return first. This is a case that is not actually covered by the sentence above: it looks to me like if there are no elements created, then the first one is returned. Is that the case? If so, I think it should be in the doc, so that the explanation is formally complete! (I won't commit this into my own memory till you answered this...)

the "second" element after (as the next sibling) the "first" element (which needs a parent in order to have a sibling):

Ah, of course. Of course. Now, while I have you, in the doc you write:

Or we can do a simple append of an existing element to another element:

put(parent, ">", child);

In the docs, this is the very first time you introduce > (you talk about < as a way to change the "currently referenced element", but not >. I am especially confused, because it seems to be the very same as:

put(parent, child)

Is there actually a difference between the two? Could you maybe introduce > first?

Sorry about being such a pain with the docs...

Merc.

On 15 March 2013 11:54, Kris Zyp notifications@github.com wrote:

I added some more explanation in the documentation to try to clarify the return values and combination operator behavior. Let me know if you think it makes sense, or if the docs (or behavior) should be different.

— Reply to this email directly or view it on GitHubhttps://github.com/kriszyp/put-selector/issues/18#issuecomment-14942731 .

[mercmobily]

Hi,

OK trying to be a little more constructive here... maybe let's add this to the documentation? (note the added sentence)

The put function returns the last top level element created or referenced from a selector. In the examples above, the newly create element would be returned. Note that passing in an existing node will not change the return value (as it is assumed you already have a reference to it). Also note that if you only pass existing nodes reference, the first passed reference will be returned.

If this is correct (and it seems to be, looking at the source code), then the only question remaining is the one about '>'

Bye!

Merc.

[mercmobily]

Thanks Kris, glad I could help a little.

[kriszyp]

Thank you for the help!