Parameter Passing Mechanisms in Angular with ng-template Inside ngFor and ngIf

Problem Background and Challenges

In Angular development, developers often combine *ngFor and *ngIf directives to dynamically render list items and select different templates based on conditions. A common scenario involves rendering a list of links, where each link may have different types (e.g., "simple" or "complex"), requiring distinct content displays based on type. An initial attempt might look like this:

<ul>
    <li *ngFor='let link of links'>
        <ng-container *ngIf="link.type == 'complex'; then complexLink else simpleLink"></ng-container>
    </li>
</ul>

<ng-template #simpleLink>
    ...
    {{ link.some_property }}
</ng-template>

<ng-template #complexLink>
    ...
    {{ link.some_property }}
</ng-template>

However, this approach leads to a critical issue: the link variable is undefined inside the ng-template, because ng-template does not inherit the context of the external ngFor loop by default. When attempting to access link.some_property, Angular throws an error indicating an inability to read properties of an undefined object. This stems from Angular's template scoping mechanism—each ng-template creates an independent scope, and without explicit data passing, it cannot access external variables.

Core Solution: Using ngTemplateOutlet with Context Passing

To resolve this, the best practice is to use the ngTemplateOutlet directive combined with ngTemplateOutletContext to dynamically render templates and pass parameters. This method allows injecting external data (e.g., the link object) into the template, ensuring safe access inside. Here is the improved code example:

<ul>
    <li *ngFor='let link of links'>
        <ng-container 
             [ngTemplateOutlet]="link.type == 'complex' ? complexLink : simpleLink" 
             [ngTemplateOutletContext]="{link: link}">
        </ng-container>
    </li>
</ul>

<ng-template #simpleLink let-link='link'>
    Simple : {{ link.name }}
</ng-template>

<ng-template #complexLink let-link='link'>
    Complex : {{ link.name }}
</ng-template>

In this solution, key steps include:

1. Dynamic Template Selection: Bind an expression via [ngTemplateOutlet] that decides which template to render (complexLink or simpleLink) based on the value of link.type. This replaces the *ngIf then/else syntax, offering more flexible control.
2. Context Passing: Use [ngTemplateOutletContext] to pass an object to the template. Here, the context object is {link: link}, where the key link is the name referenced inside the template, and the value link is the link object from the current loop iteration.
3. Template Parameter Declaration: In the ng-template, declare a local variable link via let-link='link' syntax, which maps to the link key in the context object. This allows the template to directly use the link variable to access passed data.

The advantage of this method lies in its clear data flow: data is explicitly passed from the parent component or loop context to the child template, avoiding scope confusion. Moreover, it supports passing multiple parameters, e.g., extending the context to {link: link, index: i} to include index information.

In-Depth Principles and Best Practices

Understanding how ngTemplateOutlet works is crucial for effective use. In Angular, ng-template is a lazy template that does not render automatically unless activated by directives like ngTemplateOutlet. When ngTemplateOutlet is bound to a template reference, Angular instantiates the template and injects the provided context object into the template's local variables. This is analogous to a function call, where the context object is passed as a parameter, and the template receives it via let-* syntax.

From a performance perspective, this approach is generally more efficient than using components or services, as it avoids unnecessary component instantiation and change detection overhead. However, developers should note the following best practices:

• Keep Contexts Concise: Pass only necessary data into the template to reduce memory usage and change detection complexity.
• Use Type Safety: In TypeScript, define interfaces for context objects to ensure correct data structures, e.g., interface TemplateContext { link: Link; }.
• Avoid Over-Nesting: If template logic becomes too complex, consider refactoring it into a separate component to improve maintainability and testability.

Other potential solutions include using *ngIf with inline templates, but this can lead to code duplication and reduced readability. For instance, embedding conditional logic directly inside ng-container might work but prevents template reuse. Therefore, for scenarios requiring dynamic selection and parameterization, ngTemplateOutlet is the most recommended method.

Summary and Extended Considerations

Through this exploration, we have addressed the parameter passing issue in Angular when ng-template is nested within ngFor and ngIf. The core solution involves using ngTemplateOutlet and ngTemplateOutletContext to explicitly pass data, ensuring templates can access external variables. This method is not only applicable to link rendering scenarios but can also extend to any use case requiring dynamic template selection and parameterization, such as form fields, dynamic UI components, etc.

In practical development, developers should choose solutions based on specific needs. For simple conditional rendering, *ngIf may suffice; but for complex data flows and template reuse, ngTemplateOutlet offers greater flexibility and control. By mastering these techniques, developers can build more robust and maintainable Angular applications, avoiding common template errors.