I want to dynamically create a template. This should be used to build a ComponentType
at runtime and place (even replace) it somewhere inside of the hosting Component.
Until RC4 I was using ComponentResolver
, but with RC5 I get the following message:
ComponentResolver is deprecated for dynamic compilation.
Use ComponentFactoryResolver together with @NgModule/@Component.entryComponents or ANALYZE_FOR_ENTRY_COMPONENTS provider instead.
For runtime compile only, you can also use Compiler.compileComponentSync/Async.
I found this document (Angular 2 Synchronous Dynamic Component Creation)
And understand that I can use either
ngIf
with ComponentFactoryResolver
. If I pass known components inside of @Component({entryComponents: [comp1, comp2], ...})
- I can use .resolveComponentFactory(componentToRender);
Compiler
... But the question is how to use that Compiler
? The note above says that I should call: Compiler.compileComponentSync/Async
- so how?
For example. I want to create (based on some configuration conditions) this kind of template for one kind of settings
<form>
<string-editor
[propertyName]="'code'"
[entity]="entity"
></string-editor>
<string-editor
[propertyName]="'description'"
[entity]="entity"
></string-editor>
...
and in another case this one (string-editor
is replaced with text-editor
)
<form>
<text-editor
[propertyName]="'code'"
[entity]="entity"
></text-editor>
...
And so on (different number/date/reference editors
by property types, skipped some properties for some users...). i.e. this is an example, the real configuration could generate much more different and complex templates.
The template is changing, so I cannot use ComponentFactoryResolver
and pass existing ones... I need a solution with the Compiler
.
NOTE: to get solution for previous version, check the history of this post
Similar topic is discussed here Equivalent of $compile in Angular 2. We need to use JitCompiler
and NgModule
. Read more about NgModule
in Angular2 here:
There is a working plunker/example (dynamic template, dynamic component type, dynamic module,JitCompiler
, ... in action)
The principal is:
1) create Template
2) find ComponentFactory
in cache - go to 7)
3) - create Component
4) - create Module
5) - compile Module
6) - return (and cache for later use) ComponentFactory
7) use Target and ComponentFactory
to create an Instance of dynamic Component
Here is a code snippet (more of it here) - Our custom Builder is returning just built/cached ComponentFactory
and the view Target placeholder consume to create an instance of the DynamicComponent
// here we get a TEMPLATE with dynamic content === TODO
var template = this.templateBuilder.prepareTemplate(this.entity, useTextarea);
// here we get Factory (just compiled or from cache)
this.typeBuilder
.createComponentFactory(template)
.then((factory: ComponentFactory<IHaveDynamicData>) =>
{
// Target will instantiate and inject component (we'll keep reference to it)
this.componentRef = this
.dynamicComponentTarget
.createComponent(factory);
// let's inject @Inputs to component instance
let component = this.componentRef.instance;
component.entity = this.entity;
//...
});
This is it - in nutshell it. To get more details.. read below
.
Observe a plunker and come back to read details in case some snippet requires more explanation
.
Below description of this scenario, we will
PartsModule:NgModule
(holder of small pieces)DynamicModule:NgModule
, which will contain our dynamic component (and reference PartsModule
dynamically)Component
type (only if template has changed)RuntimeModule:NgModule
. This module will contain the previously created Component
typeJitCompiler.compileModuleAndAllComponentsAsync(runtimeModule)
to get ComponentFactory
DynamicComponent
- job of the View Target placeholder and ComponentFactory
@Inputs
to new instance (switch from INPUT
to TEXTAREA
editing), consume @Outputs
We need an NgModule
s.
While I would like to show a very simple example, in this case, I would need three modules (in fact 4 - but I do not count the AppModule). Please, take this rather than a simple snippet as a basis for a really solid dynamic component generator.
There will be one module for all small components, e.g. string-editor
, text-editor
(date-editor
, number-editor
...)
@NgModule({
imports: [
CommonModule,
FormsModule
],
declarations: [
DYNAMIC_DIRECTIVES
],
exports: [
DYNAMIC_DIRECTIVES,
CommonModule,
FormsModule
]
})
export class PartsModule { }
Where
DYNAMIC_DIRECTIVES
are extensible and are intended to hold all small parts used for our dynamic Component template/type. Check app/parts/parts.module.ts
The second will be module for our Dynamic stuff handling. It will contain hosting components and some providers.. which will be singletons. Therefor we will publish them standard way - with forRoot()
import { DynamicDetail } from './detail.view';
import { DynamicTypeBuilder } from './type.builder';
import { DynamicTemplateBuilder } from './template.builder';
@NgModule({
imports: [ PartsModule ],
declarations: [ DynamicDetail ],
exports: [ DynamicDetail],
})
export class DynamicModule {
static forRoot()
{
return {
ngModule: DynamicModule,
providers: [ // singletons accross the whole app
DynamicTemplateBuilder,
DynamicTypeBuilder
],
};
}
}
Check the usage of the
forRoot()
in theAppModule
Finally, we will need an adhoc, runtime module.. but that will be created later, as a part of DynamicTypeBuilder
job.
The forth module, application module, is the one who keeps declares compiler providers:
...
import { COMPILER_PROVIDERS } from '@angular/compiler';
import { AppComponent } from './app.component';
import { DynamicModule } from './dynamic/dynamic.module';
@NgModule({
imports: [
BrowserModule,
DynamicModule.forRoot() // singletons
],
declarations: [ AppComponent],
providers: [
COMPILER_PROVIDERS // this is an app singleton declaration
],
Read (do read) much more about NgModule there:
In our example we will process detail of this kind of entity
entity = {
code: "ABC123",
description: "A description of this Entity"
};
To create a template
, in this plunker we use this simple/naive builder.
The real solution, a real template builder, is the place where your application can do a lot
// plunker - app/dynamic/template.builder.ts
import {Injectable} from "@angular/core";
@Injectable()
export class DynamicTemplateBuilder {
public prepareTemplate(entity: any, useTextarea: boolean){
let properties = Object.keys(entity);
let template = "<form >";
let editorName = useTextarea
? "text-editor"
: "string-editor";
properties.forEach((propertyName) =>{
template += `
<${editorName}
[propertyName]="'${propertyName}'"
[entity]="entity"
></${editorName}>`;
});
return template + "</form>";
}
}
A trick here is - it builds a template which uses some set of known properties, e.g. entity
. Such property(-ies) must be part of dynamic component, which we will create next.
To make it a bit more easier, we can use an interface to define properties, which our Template builder can use. This will be implemented by our dynamic Component type.
export interface IHaveDynamicData {
public entity: any;
...
}
ComponentFactory
builderVery important thing here is to keep in mind:
our component type, build with our
DynamicTypeBuilder
, could differ - but only by its template (created above). Components' properties (inputs, outputs or some protected) are still same. If we need different properties, we should define different combination of Template and Type Builder
So, we are touching the core of our solution. The Builder, will 1) create ComponentType
2) create its NgModule
3) compile ComponentFactory
4) cache it for later reuse.
An dependency we need to receive:
// plunker - app/dynamic/type.builder.ts
import { JitCompiler } from '@angular/compiler';
@Injectable()
export class DynamicTypeBuilder {
// wee need Dynamic component builder
constructor(
protected compiler: JitCompiler
) {}
And here is a snippet how to get a ComponentFactory
:
// plunker - app/dynamic/type.builder.ts
// this object is singleton - so we can use this as a cache
private _cacheOfFactories:
{[templateKey: string]: ComponentFactory<IHaveDynamicData>} = {};
public createComponentFactory(template: string)
: Promise<ComponentFactory<IHaveDynamicData>> {
let factory = this._cacheOfFactories[template];
if (factory) {
console.log("Module and Type are returned from cache")
return new Promise((resolve) => {
resolve(factory);
});
}
// unknown template ... let's create a Type for it
let type = this.createNewComponent(template);
let module = this.createComponentModule(type);
return new Promise((resolve) => {
this.compiler
.compileModuleAndAllComponentsAsync(module)
.then((moduleWithFactories) =>
{
factory = _.find(moduleWithFactories.componentFactories
, { componentType: type });
this._cacheOfFactories[template] = factory;
resolve(factory);
});
});
}
Above we create and cache both
Component
andModule
. Because if the template (in fact the real dynamic part of that all) is the same.. we can reuse
And here are two methods, which represent the really cool way how to create a decorated classes/types in runtime. Not only @Component
but also the @NgModule
protected createNewComponent (tmpl:string) {
@Component({
selector: 'dynamic-component',
template: tmpl,
})
class CustomDynamicComponent implements IHaveDynamicData {
@Input() public entity: any;
};
// a component for this particular template
return CustomDynamicComponent;
}
protected createComponentModule (componentType: any) {
@NgModule({
imports: [
PartsModule, // there are 'text-editor', 'string-editor'...
],
declarations: [
componentType
],
})
class RuntimeComponentModule
{
}
// a module for just this Type
return RuntimeComponentModule;
}
Important:
our component dynamic types differ, but just by template. So we use that fact to cache them. This is really very important. Angular2 will also cache these.. by the type. And if we would recreate for the same template strings new types... we will start to generate memory leaks.
ComponentFactory
used by hosting componentFinal piece is a component, which hosts the target for our dynamic component, e.g. <div #dynamicContentPlaceHolder></div>
. We get a reference to it and use ComponentFactory
to create a component. That is in a nutshell, and here are all the pieces of that component (if needed, open plunker here)
Let's firstly summarize import statements:
import {Component, ComponentRef,ViewChild,ViewContainerRef} from '@angular/core';
import {AfterViewInit,OnInit,OnDestroy,OnChanges,SimpleChange} from '@angular/core';
import { IHaveDynamicData, DynamicTypeBuilder } from './type.builder';
import { DynamicTemplateBuilder } from './template.builder';
@Component({
selector: 'dynamic-detail',
template: `
<div>
check/uncheck to use INPUT vs TEXTAREA:
<input type="checkbox" #val (click)="refreshContent(val.checked)" /><hr />
<div #dynamicContentPlaceHolder></div> <hr />
entity: <pre>{{entity | json}}</pre>
</div>
`,
})
export class DynamicDetail implements AfterViewInit, OnChanges, OnDestroy, OnInit
{
// wee need Dynamic component builder
constructor(
protected typeBuilder: DynamicTypeBuilder,
protected templateBuilder: DynamicTemplateBuilder
) {}
...
We just receive, template and component builders. Next are properties which are needed for our example (more in comments)
// reference for a <div> with #dynamicContentPlaceHolder
@ViewChild('dynamicContentPlaceHolder', {read: ViewContainerRef})
protected dynamicComponentTarget: ViewContainerRef;
// this will be reference to dynamic content - to be able to destroy it
protected componentRef: ComponentRef<IHaveDynamicData>;
// until ngAfterViewInit, we cannot start (firstly) to process dynamic stuff
protected wasViewInitialized = false;
// example entity ... to be recieved from other app parts
// this is kind of candiate for @Input
protected entity = {
code: "ABC123",
description: "A description of this Entity"
};
In this simple scenario, our hosting component does not have any @Input
. So it does not have to react to changes. But despite of that fact (and to be ready for coming changes) - we need to introduce some flag if the component was already (firstly) initiated. And only then we can start the magic.
Finally we will use our component builder, and its just compiled/cached ComponentFacotry
. Our Target placeholder will be asked to instantiate the Component
with that factory.
protected refreshContent(useTextarea: boolean = false){
if (this.componentRef) {
this.componentRef.destroy();
}
// here we get a TEMPLATE with dynamic content === TODO
var template = this.templateBuilder.prepareTemplate(this.entity, useTextarea);
// here we get Factory (just compiled or from cache)
this.typeBuilder
.createComponentFactory(template)
.then((factory: ComponentFactory<IHaveDynamicData>) =>
{
// Target will instantiate and inject component (we'll keep reference to it)
this.componentRef = this
.dynamicComponentTarget
.createComponent(factory);
// let's inject @Inputs to component instance
let component = this.componentRef.instance;
component.entity = this.entity;
//...
});
}
Also, we need to keep a reference to compiled template.. to be able properly destroy()
it, whenever we will change it.
// this is the best moment where to start to process dynamic stuff
public ngAfterViewInit(): void
{
this.wasViewInitialized = true;
this.refreshContent();
}
// wasViewInitialized is an IMPORTANT switch
// when this component would have its own changing @Input()
// - then we have to wait till view is intialized - first OnChange is too soon
public ngOnChanges(changes: {[key: string]: SimpleChange}): void
{
if (this.wasViewInitialized) {
return;
}
this.refreshContent();
}
public ngOnDestroy(){
if (this.componentRef) {
this.componentRef.destroy();
this.componentRef = null;
}
}
That is pretty much it. Do not forget to Destroy anything what was built dynamically (ngOnDestroy). Also, be sure to cache dynamic types
and modules
if the only difference is their template.
Check it all in action here
to see previous versions (e.g. RC5 related) of this post, check the history