Skip to content

Commit 82426f9

Browse files
ShaneKShaneK
committed
docs(angular): adding overlays documentation with explanation of 8.8's new custom injector functionality
1 parent f744648 commit 82426f9

File tree

2 files changed

+214
-0
lines changed

2 files changed

+214
-0
lines changed

‎docs/angular/overlays.md‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
---
2+
title: Overlay Components
3+
sidebar_label: Overlay Components
4+
---
5+
6+
<head>
7+
<title>Angular Overlay Components: Modals, Popovers with Custom Injectors</title>
8+
<meta
9+
name="description"
10+
content="Learn how to use overlay components like modals and popovers in Ionic Angular, including passing custom injectors for dependency injection."
11+
/>
12+
</head>
13+
14+
Ionic provides overlay components such as modals and popovers that display content on top of your application. In Angular, these overlays can be created using controllers like `ModalController` and `PopoverController`.
15+
16+
## Creating Overlays
17+
18+
Overlays can be created programmatically using their respective controllers:
19+
20+
```typescript
21+
import { Component } from '@angular/core';
22+
import { ModalController } from '@ionic/angular/standalone';
23+
import { MyModalComponent } from './my-modal.component';
24+
25+
@Component({
26+
selector: 'app-home',
27+
templateUrl: './home.component.html',
28+
})
29+
export class HomeComponent {
30+
constructor(private modalController: ModalController) {}
31+
32+
async openModal() {
33+
const modal = await this.modalController.create({
34+
component: MyModalComponent,
35+
componentProps: {
36+
title: 'My Modal',
37+
},
38+
});
39+
await modal.present();
40+
}
41+
}
42+
```
43+
44+
## Custom Injectors
45+
46+
By default, overlay components use the root injector for dependency injection. This means that services or tokens provided at the route level or within a specific component tree are not accessible inside the overlay.
47+
48+
The `injector` option allows you to pass a custom Angular `Injector` when creating a modal or popover. This enables overlay components to access services and tokens that are not available in the root injector.
49+
50+
### Use Cases
51+
52+
Custom injectors are useful when you need to:
53+
54+
- Access route-scoped services from within an overlay
55+
- Use Angular CDK's `Dir` directive for bidirectional text support
56+
- Access any providers that are not registered at the root level
57+
58+
### Usage
59+
60+
To use a custom injector, pass it to the `create()` method:
61+
62+
```typescript
63+
import { Component, Injector } from '@angular/core';
64+
import { ModalController } from '@ionic/angular/standalone';
65+
import { MyModalComponent } from './my-modal.component';
66+
import { MyRouteService } from './my-route.service';
67+
68+
@Component({
69+
selector: 'app-feature',
70+
templateUrl: './feature.component.html',
71+
providers: [MyRouteService], // Service provided at route level
72+
})
73+
export class FeatureComponent {
74+
constructor(
75+
private modalController: ModalController,
76+
private injector: Injector
77+
) {}
78+
79+
async openModal() {
80+
const modal = await this.modalController.create({
81+
component: MyModalComponent,
82+
injector: this.injector, // Pass the component's injector
83+
});
84+
await modal.present();
85+
}
86+
}
87+
```
88+
89+
The modal component can now inject `MyRouteService`:
90+
91+
```typescript
92+
import { Component, inject } from '@angular/core';
93+
import { MyRouteService } from '../my-route.service';
94+
95+
@Component({
96+
selector: 'app-my-modal',
97+
templateUrl: './my-modal.component.html',
98+
})
99+
export class MyModalComponent {
100+
private myRouteService = inject(MyRouteService);
101+
}
102+
```
103+
104+
### Creating a Custom Injector
105+
106+
You can also create a custom injector with specific providers:
107+
108+
```typescript
109+
import { Component, Injector } from '@angular/core';
110+
import { ModalController } from '@ionic/angular/standalone';
111+
import { MyModalComponent } from './my-modal.component';
112+
import { MyService } from './my.service';
113+
114+
@Component({
115+
selector: 'app-feature',
116+
templateUrl: './feature.component.html',
117+
})
118+
export class FeatureComponent {
119+
constructor(
120+
private modalController: ModalController,
121+
private injector: Injector
122+
) {}
123+
124+
async openModal() {
125+
const myService = new MyService();
126+
myService.configure({ someOption: true });
127+
128+
const customInjector = Injector.create({
129+
providers: [{ provide: MyService, useValue: myService }],
130+
parent: this.injector,
131+
});
132+
133+
const modal = await this.modalController.create({
134+
component: MyModalComponent,
135+
injector: customInjector,
136+
});
137+
await modal.present();
138+
}
139+
}
140+
```
141+
142+
### Using with Angular CDK Directionality
143+
144+
A common use case is providing the Angular CDK `Dir` directive to overlays for bidirectional text support:
145+
146+
```typescript
147+
import { Component, Injector } from '@angular/core';
148+
import { Dir } from '@angular/cdk/bidi';
149+
import { ModalController } from '@ionic/angular/standalone';
150+
import { MyModalComponent } from './my-modal.component';
151+
152+
@Component({
153+
selector: 'app-feature',
154+
templateUrl: './feature.component.html',
155+
})
156+
export class FeatureComponent {
157+
constructor(
158+
private modalController: ModalController,
159+
private injector: Injector
160+
) {}
161+
162+
async openModal() {
163+
const modal = await this.modalController.create({
164+
component: MyModalComponent,
165+
injector: this.injector, // Includes Dir from component tree
166+
});
167+
await modal.present();
168+
}
169+
}
170+
```
171+
172+
### Popover Controller
173+
174+
The `PopoverController` supports the same `injector` option:
175+
176+
```typescript
177+
import { Component, Injector } from '@angular/core';
178+
import { PopoverController } from '@ionic/angular/standalone';
179+
import { MyPopoverComponent } from './my-popover.component';
180+
181+
@Component({
182+
selector: 'app-feature',
183+
templateUrl: './feature.component.html',
184+
})
185+
export class FeatureComponent {
186+
constructor(
187+
private popoverController: PopoverController,
188+
private injector: Injector
189+
) {}
190+
191+
async openPopover(event: Event) {
192+
const popover = await this.popoverController.create({
193+
component: MyPopoverComponent,
194+
event: event,
195+
injector: this.injector,
196+
});
197+
await popover.present();
198+
}
199+
}
200+
```
201+
202+
## Angular Options Interfaces
203+
204+
Ionic provides Angular-specific option interfaces that extend the core options with Angular-specific properties:
205+
206+
- `AngularModalOptions` - Extends `ModalOptions` with the `injector` property
207+
- `AngularPopoverOptions` - Extends `PopoverOptions` with the `injector` property
208+
209+
These types are exported from `@ionic/angular` and `@ionic/angular/standalone`:
210+
211+
```typescript
212+
import type { AngularModalOptions, AngularPopoverOptions } from '@ionic/angular/standalone';
213+
```

‎sidebars.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,7 @@ module.exports = {
8787
'angular/build-options',
8888
'angular/lifecycle',
8989
'angular/navigation',
90+
'angular/overlays',
9091
'angular/injection-tokens',
9192
'angular/virtual-scroll',
9293
'angular/slides',

0 commit comments

Comments
 (0)