Skip to content

Commit 5e3ced0

Browse files
ShaneKShaneK
authored
docs(angular): adding overlays documentation with explanation of 8.8's new custom injector functionality (#4372)
* docs(angular): adding overlays documentation with explanation of 8.8's new custom injector functionality * chore(spelling): adding CDK to word list * chore(modal-options): updating interfaces to follow consistent naming patterns * docs(overlays): adding docs for overlays section
1 parent d175dc0 commit 5e3ced0

File tree

3 files changed

+215
-0
lines changed

3 files changed

+215
-0
lines changed

‎cspell-wordlist.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ Udemy
1313
Vetur
1414
Wistia
1515
WCAG
16+
CDK
1617

1718
actionsheet
1819
fabs

‎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: Overlays
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 Types
191+
192+
Ionic Angular exports its own `ModalOptions` and `PopoverOptions` types that extend the core options with Angular-specific properties like `injector`:
193+
194+
- `ModalOptions` - Extends core `ModalOptions` with the `injector` property
195+
- `PopoverOptions` - Extends core `PopoverOptions` with the `injector` property
196+
197+
These types are exported from `@ionic/angular` and `@ionic/angular/standalone`:
198+
199+
```typescript
200+
import type { ModalOptions, PopoverOptions } from '@ionic/angular/standalone';
201+
```
202+
203+
## Docs for Overlays in Ionic
204+
205+
For full docs and to see usage examples, visit the docs page for each of the overlays in Ionic:
206+
207+
- [Action Sheet](https://ionicframework.com/docs/api/action-sheet)
208+
- [Alert](https://ionicframework.com/docs/api/alert)
209+
- [Loading](https://ionicframework.com/docs/api/loading)
210+
- [Modal](https://ionicframework.com/docs/api/modal)
211+
- [Picker](https://ionicframework.com/docs/api/picker)
212+
- [Popover](https://ionicframework.com/docs/api/popover)
213+
- [Toast](https://ionicframework.com/docs/api/toast)

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