Skip to content

Commit cfea9d7

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

File tree

2 files changed

+202
-0
lines changed

2 files changed

+202
-0
lines changed

‎docs/angular/overlays.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
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(private modalController: ModalController, private injector: Injector) {}
75+
76+
async openModal() {
77+
const modal = await this.modalController.create({
78+
component: MyModalComponent,
79+
injector: this.injector, // Pass the component's injector
80+
});
81+
await modal.present();
82+
}
83+
}
84+
```
85+
86+
The modal component can now inject `MyRouteService`:
87+
88+
```typescript
89+
import { Component, inject } from '@angular/core';
90+
import { MyRouteService } from '../my-route.service';
91+
92+
@Component({
93+
selector: 'app-my-modal',
94+
templateUrl: './my-modal.component.html',
95+
})
96+
export class MyModalComponent {
97+
private myRouteService = inject(MyRouteService);
98+
}
99+
```
100+
101+
### Creating a Custom Injector
102+
103+
You can also create a custom injector with specific providers:
104+
105+
```typescript
106+
import { Component, Injector } from '@angular/core';
107+
import { ModalController } from '@ionic/angular/standalone';
108+
import { MyModalComponent } from './my-modal.component';
109+
import { MyService } from './my.service';
110+
111+
@Component({
112+
selector: 'app-feature',
113+
templateUrl: './feature.component.html',
114+
})
115+
export class FeatureComponent {
116+
constructor(private modalController: ModalController, private injector: Injector) {}
117+
118+
async openModal() {
119+
const myService = new MyService();
120+
myService.configure({ someOption: true });
121+
122+
const customInjector = Injector.create({
123+
providers: [{ provide: MyService, useValue: myService }],
124+
parent: this.injector,
125+
});
126+
127+
const modal = await this.modalController.create({
128+
component: MyModalComponent,
129+
injector: customInjector,
130+
});
131+
await modal.present();
132+
}
133+
}
134+
```
135+
136+
### Using with Angular CDK Directionality
137+
138+
A common use case is providing the Angular CDK `Dir` directive to overlays for bidirectional text support:
139+
140+
```typescript
141+
import { Component, Injector } from '@angular/core';
142+
import { Dir } from '@angular/cdk/bidi';
143+
import { ModalController } from '@ionic/angular/standalone';
144+
import { MyModalComponent } from './my-modal.component';
145+
146+
@Component({
147+
selector: 'app-feature',
148+
templateUrl: './feature.component.html',
149+
})
150+
export class FeatureComponent {
151+
constructor(private modalController: ModalController, private injector: Injector) {}
152+
153+
async openModal() {
154+
const modal = await this.modalController.create({
155+
component: MyModalComponent,
156+
injector: this.injector, // Includes Dir from component tree
157+
});
158+
await modal.present();
159+
}
160+
}
161+
```
162+
163+
### Popover Controller
164+
165+
The `PopoverController` supports the same `injector` option:
166+
167+
```typescript
168+
import { Component, Injector } from '@angular/core';
169+
import { PopoverController } from '@ionic/angular/standalone';
170+
import { MyPopoverComponent } from './my-popover.component';
171+
172+
@Component({
173+
selector: 'app-feature',
174+
templateUrl: './feature.component.html',
175+
})
176+
export class FeatureComponent {
177+
constructor(private popoverController: PopoverController, private injector: Injector) {}
178+
179+
async openPopover(event: Event) {
180+
const popover = await this.popoverController.create({
181+
component: MyPopoverComponent,
182+
event: event,
183+
injector: this.injector,
184+
});
185+
await popover.present();
186+
}
187+
}
188+
```
189+
190+
## Angular Options Interfaces
191+
192+
Ionic provides Angular-specific option interfaces that extend the core options with Angular-specific properties:
193+
194+
- `AngularModalOptions` - Extends `ModalOptions` with the `injector` property
195+
- `AngularPopoverOptions` - Extends `PopoverOptions` with the `injector` property
196+
197+
These types are exported from `@ionic/angular` and `@ionic/angular/standalone`:
198+
199+
```typescript
200+
import type { AngularModalOptions, AngularPopoverOptions } from '@ionic/angular/standalone';
201+
```

‎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)