Support for Dynamic Content Projection

[mhevery]

Use Case

<ng-content> allows for static (compile time resolution) projection of content. There are cases where the projection needs to be controlled programmatically. A common example is when the parent component would like to wrap/decorate the child components during projection.

Mental Model

The mental model would be that <ng-content> is for fast static projection, but for dynamic projection one would use a query to get a hold of the child components in the form of ViewRefs which could then be inserted programmatically at any location in the tree.

Possible Solution

• ContentViewRef extends ViewRef
• @Content(selector) Provides a way to select direct children content elements using CSS selectors. (This would be after directives such as ngFor would unroll the content, and it would be in the correct order.)
• This would allow selection of elements rather than directives. These ContentViewRefs could then be reinserted to any ViewContainerRef
• We would need ngViewOutlet (similar to ngTemplateOutlet).

@Component({
  template: `
  <div *ngFor="let view of allViews">
    <template ngViewOutlet="view"></template>
  </div>
  <ng-content><!-- project non selected nodes, such as text nodes --></ng-content>
`
})
class MySelect {
  @Content('*') allViews: ContentViewRef[];

  // another example
  @Content('my-option') optionViews: ContentViewRef[];
}

@Component({
  selector: 'app',
  template: `
<my-select>
     Option
    <my-option>header</my-option>
    <my-option *ngFor="let item in items">unrolled items {{item}}</my-option>
    <my-option-group>
        <my-option>
            foo <b>bar</b>
            <other-directive />
</my-option>
        <my-separator></my-separator>
        <my-option></my-option>
</my-option-group>
</my-select>
`
})
class App {}

[mhevery]

@tbosch looking for your input on how feasible this is.
@pkozlowski-opensource & @Mlaval looking for your input if this fits your use case.
/cc @vsavkin

[pkozlowski-opensource]

@mhevery thnx for opening this one. After reading through the proposal it looks like it would cover use-cases we've discussed yesterday plus solve some other ones I've bumped into previously. So it is all good from this perspective.

There would be much more details to figure out and APIs to design, but IMO we can start working off your initial proposal. It would be great to have @tbosch input and see how we can move forward on this item.

[tbosch]

Technically this would work.
However, I don't like calling these projected elements view as:

• these ContentViews consist of always only one element, not potentially multiple ones.
• we explain to our users that a "View" is an instance of a template, which is either the content of the template property in the @Component annotation or an embedded template via <template> or <...*...>. These ContentViews are none of this.
• Using a ViewRef would require using an AppView internally to keep track of the elements. However, a AppView class contains a lot of logic that is not needed for this use case (e.g. change detectors, debug information, ...) that is not needed here.

[tbosch]

Under the cover, we would do the following:

• for each property annotation with @Content, collect the list of matching elements from the content area of the component. Note that this needs to to already recurse into projected ViewContainerRefs (e.g. from projected ngFors). I.e. the property needs to be updated whenever a projected ngFor unrolls.
• have an API to insert these nodes / ViewContainerRefs after/before other nodes.

Regarding how / when to update the property: Use a QueryList as value for the property annotated with @Content as well.

• i.e. use the same algorithm we already use for marking QueryLists as dirty when e.g. an ngFor unrolls
• i.e. update the QueryList after the content has been checked only if the query is dirty.

[tbosch]

Inserting the nodes requires a container that keeps track of them:

Given the following example:

<template [ngIf]>
  <template [ngIf]></template>
</template>

Here, the nodes of the nested ngIf template are siblings to the nodes of the parent ngIf template in the DOM. When the parent ngIf becomes false, it also needs to detach the nodes of the nested ngIf template. For this to work, the root nodes of a view are represented as a list that contains either plain nodes or AppElements. When a view needs to be attached/detached, it loops over these nodes and recursed into the root AppElements ViewContainerRef as well.

For ContentViewRefs we need a similar mechanism. I.e. if nodes are inserted at the top level of a View, we need to keep track of the inserted nodes on the AppElement so that we can remove them when needed. It could be a ViewContainerRef or a different container.

[tbosch]

Given the above comments / analysis, I think we should do the following:

class MySelect {
  // query for nodes:
  @ContentChildren('my-option') optionEls: QueryList<ElementRef>;

  // inserting nodes:
  someAction() {
    this.someViewContainer.insertElements(this.optionEls);
  }
}

As the optionEls could contain an unrolled ngFor, ViewContainerRef.insertElements needs to subscribe to changes of the QueryList and append new nodes / detach old nodes when the QueryList changes.

Also, we should change the semantics of @ContentChildren / @ViewChildren as follows:

• when given a string, always do a css selector for this element / elements. Don't special case elements that have references on them any more. Right now, @ContentChildren('someString') only selects elements that have a reference someString, e.g. <div #someString>.
• if no read property is given in @ContentChildren / @ViewChildren, always return the ElementRefs. If a user needs a special directive / component, he should use the read property. Right now, @ContentChildren(...) returns the component instance if there is one present on that element and otherwise an ElementRef.

Finally, we should rename ViewContainerRef and its properties:

• ViewContainerRef -> ContainerRef
• ViewContainerRef.views -> ContainerRef.entries: Array<QueryList | ViewRef>

[tbosch]

Applied to the use case of wrapping projected elements:

@Component({
  template: `
  <div *ngFor="let contentEl of allContentEls">
    <template [ngViewOutlet]="contentEl"></template>
  </div>
`
})
class MySelect {
  @ContentChildren('*') allContentEls: QueryList<ElementRef>;
}

I.e. ngViewOutlet will support taking a element directly, wrap it into a QueryList that just contains that single element and call ViewContainerRef.insertElements on its ViewContainerRef.

[pkozlowski-opensource]

@tbosch the latest proposal looks really great! I still need to go over all the use-cases I've got on my mind, but looks like a very promising start.

One question for now, though: would I be able to get directives instances present on a given Element so I can make decisions based on this? If so, what would be the proposed API?

[tbosch]

To get directives, you have to query for them as well:

class MySelect {
  @ContentChildren('*', read: MyOption) allContentOptions: QueryList<MyOption>;
}

We could change this to allow an array in read:

class MySelect {
  @ContentChildren('*', read: [MyOption, MyOptionGroup]) allContentOptions: QueryList<MyOption | MyOptionGroup>;
}

Or if you need the combination of ElementRef and MyOption:

class MySelect {
  @ContentChildren('*', readTuple: [ElementRef, MyOption, MyOptionGroup]) allContentOptions: QueryList<Array<ElementRef | MyOption | MyOptionGroup>>;
}

The QueryList would always contain an array with 3 entries with the indices:

• 0: ElementRef instance
• 1: MyOption instance if existing or null
• 2: MyOptionGroup instance if existing or null

[lacolaco]

Can does this feature allow us to do processing like $compile ?

@Component({
  selector: 'my-cmp',
  template: `
    <template [ngViewOutlet]="dynamicTemplate"></template>
`
})
class MyComponent {
  dynamicTemplate = `<p>Hello</p>`; 
}

renderer HTML

<my-cmp>
  <p>Hello</p>
</my-cmp>

[mhevery]

@laco0416 sorry this has nothing to do with $compile it is more of a custom transclude

[tbosch]

@pkozlowski-opensource @mhevery I changed my proposal above to use ElementRefs instead of plain DOM elements. This more aligned to how we give users access to elements in DI.

Also, I think we should only support this API for elements, not for text nodes (which would only be selected by * anyways). Text nodes are just too brittle when it comes to how many there are / looping over them (e.g. a user just adding whitespace between elements results in extra entries).