Nodes, children, append new element

Question

Given this code:

Element elem  = new Element.html("<p>This is a paragraph.</p>");

document.body.append(elem);
document.body.children.add(elem);
document.body.nodes.add(elem);

The results are the same when I add to body.children or to body.nodes. What is the difference between the two? Which is better?

Answer 1

I'll try to explain it easily.

Let's assume this HTML snippet:

<div>
  Hey!
  <span>How is it going?</span>
</div>

Now, the thing is that the children property comes from the Element class. It returns a list of other Element objects:

List<Element> children

So, elements can have children who are elements, and so forth.

But then we have the nodes property, which comes from the Node class. It returns a list of other Node objects:

List<Node> nodes

So, nodes can have child nodes who are nodes themselves too.

The question you should ask is what's the difference between a node and an element?

Let me add some comments to our previous HTML snippet:

<div> <!-- Element -->
  Hey! <!-- Node -->
  <span> <!-- Element -->
    How is it going? <!-- Node -->
  </span>
</div>

Remember, Element extends Node, which means that <div> and <span> are not only elements, but also nodes! Everything is a node in HTML. In fact, even comments <!-- foo --> are nodes!

When you access the nodes property, you will retrieve a list of nodes, basically a list of everything under it, including HTML comments and text.

Retriving the nodes for the <div> tag above would return one Node ("hey!") and one Element (<span>). However, retrieving the children property would only return a list with a single Element (<span>).

So, nodes literally contains everything, including elements, text nodes, comments, document types and more.

To answer your question now:

 document.body.append(elem);
 document.body.children.add(elem);

These two are the same, the first is just a wrapper for convenience.

When you add to nodes or children, there isn't really much difference. However, if you retrieve the property, the result can differ. I would generally advise you to use children because the results are more what you would expect.

Implementation wise, there are little differences as Kyrra mentioned, but nothing too concerning.

Answer 2

EDIT: Kai's answer is much better.

ORIGINAL:
document.body.append(elem) is just a wrapper for document.body.children.add(elem).

As well, document.body.elements is just a wrapper for document.body.children.

.nodes and .children use different underlying classes to implement their functionality. Functionality wise, these 2 children provided the same set of List functions. Both are missing implementations for: sort, setRange, removeRange, insertRange, and the setter for length. Though, the 3 range functions may be implemented in the future.

The important difference between nodes and children is that nodes uses lazy initialization for accessing the children. Specifically, its' constructor just does:

_ChildNodeListLazy(this._this);

While the constructor for children does:

_ChildrenElementList._wrap(Element element)
  : _childElements = element.$dom_children,
    _element = element;

The children class calls the $dom_children immediately at construction, which makes sure the children from the DOM are accessible. The nodes class does not use any of the native $dom_* calls until you do something (like adding an item).

Beyond that, nodes and children seem to be the same.

As far as which is better, it depends on your use case. If you will be saving a reference to the child list but not accessing it right away, nodes is better. But neither is all that efficient right now as the getter for nodes and children both create new instances of the wrapper classes every time you call the getter (calling body.children creates a new instance of the _ChildrenElementList class). Because of this, if you are doing a lot of subsequent calls on the children of body, I'd recommend using the .. notation.

document.body.children
    ..add(a)
    ..add(b)
    ..add(c)
    ..add(d);

You can see more information about the cascade operator .. in the language tour.