More on Ownership and Containment

Contained Components

Components are typically defined in a components block, which may itself be nested within another components block, like so: 

components: [
  {kind: "PageHeader", name: "header", layoutKind: "", components: [
      {name: "title"},
      {name: "description", style: "font-size: 14px"}
  ]}
]

All of the objects created in this block are owned by the object that defines the block. Even the title and description objects from the inner components block, which is part of the declaration of the PageHeader ("header"), are owned by the defining object and not by header. We call title and description "contained components", because they are owned by one object (the defining one), but contained by another (header).

This system, in which an object's owner may differ from its container, allows us to specify a complex layout of objects that are all owned by the object that defines them. For example, in the object that defines the above components, you could create another component inside the PageHeader using this method: 

this.$.header.createComponent({name: "moreInfo", owner: this});

Like title and description, the new component will be contained by this.$.header, but owned by this.

Note that there is an alternative syntax that can be used to create the same new component: 

this.$.header.createContainedComponent({name: "moreInfo"});

However, we highly recommend using the createComponent syntax instead of createContainedComponent, since it lets you avoid thinking about component containment altogether.

The code flow for creating contained components looks like this:

Code flow for creating contained components

KindComponents

Components that are declared in the components block of a kind definition are strictly owned by the instance, and we call them kindComponents.

It's also possible to create kindComponents using the API, like so: 

this.$.header.createComponents([{name: "moreInfo"}]);

The new component is both owned and contained by this.$.header.

The code flow for creating kindComponents looks like this:

Code flow for creating kindComponents

To create components contained by this.$.header but owned by this, you could do the following: 

this.$.header.createComponents([{name: "moreInfo"}], {owner: this});