Skip to content

Commit c9f4754

Browse files
brandyscarneybrandyscarney
authored
merge feature-8.7
2 parents 2f858c8 + f8de8aa commit c9f4754

File tree

82 files changed

+1628
-355
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

82 files changed

+1628
-355
lines changed

‎docs/angular/injection-tokens.md

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
---
2+
title: Angular Injection Tokens
3+
sidebar_label: Injection Tokens
4+
---
5+
6+
<head>
7+
<title>Angular Injection Tokens | Access Ionic Elements via Dependency Injection</title>
8+
<meta
9+
name="description"
10+
content="Learn how to use Ionic's Angular injection tokens to access Ionic elements through Angular's dependency injection system for more streamlined component interactions."
11+
/>
12+
</head>
13+
14+
Ionic provides Angular injection tokens that allow you to access Ionic elements through Angular's dependency injection system. This provides a more Angular-idiomatic way to interact with Ionic components programmatically.
15+
16+
## Benefits
17+
18+
Using injection tokens provides several advantages:
19+
20+
- **Type Safety**: Full TypeScript support with proper typing for the modal element
21+
- **Angular Integration**: Works seamlessly with Angular's dependency injection system
22+
- **Simplified Code**: Eliminates the need for `ViewChild` queries or manual element references
23+
- **Better Testing**: Easier to mock and test components that use injection tokens
24+
25+
## IonModalToken
26+
27+
The `IonModalToken` injection token allows you to inject a reference to the current modal element directly into your Angular components. This is particularly useful when you need to programmatically control modal behavior, listen to modal events, or access modal properties.
28+
29+
Starting in `@ionic/angular` v8.7.0, you can use this injection token to streamline modal interactions in your Angular applications.
30+
31+
### Basic Usage
32+
33+
To use the `IonModalToken`, inject it into your component's constructor:
34+
35+
```tsx
36+
import { Component, inject } from '@angular/core';
37+
import { IonButton, IonContent, IonHeader, IonModalToken, IonTitle, IonToolbar } from '@ionic/angular/standalone';
38+
39+
@Component({
40+
selector: 'app-modal',
41+
template: `
42+
<ion-header>
43+
<ion-toolbar>
44+
<ion-title>Modal Content</ion-title>
45+
</ion-toolbar>
46+
</ion-header>
47+
<ion-content>
48+
<p>This is modal content</p>
49+
<ion-button (click)="closeModal()">Close Modal</ion-button>
50+
</ion-content>
51+
`,
52+
imports: [IonHeader, IonToolbar, IonTitle, IonContent, IonButton],
53+
})
54+
export class ModalComponent {
55+
private modalToken = inject(IonModalToken);
56+
57+
closeModal() {
58+
this.modalToken.dismiss();
59+
}
60+
}
61+
```
62+
63+
### Listening to Modal Events
64+
65+
You can use the injected modal reference to listen to modal lifecycle events:
66+
67+
```tsx
68+
import { Component, inject, OnInit } from '@angular/core';
69+
import { IonButton, IonContent, IonHeader, IonModalToken, IonTitle, IonToolbar } from '@ionic/angular/standalone';
70+
71+
@Component({
72+
selector: 'app-modal',
73+
template: `
74+
<ion-header>
75+
<ion-toolbar>
76+
<ion-title>Modal with Events</ion-title>
77+
</ion-toolbar>
78+
</ion-header>
79+
<ion-content>
80+
<p>Check the console for modal events</p>
81+
<ion-button (click)="closeModal()">Close</ion-button>
82+
</ion-content>
83+
`,
84+
imports: [IonHeader, IonToolbar, IonTitle, IonContent, IonButton],
85+
})
86+
export class ModalComponent implements OnInit {
87+
private modalToken = inject(IonModalToken);
88+
89+
ngOnInit() {
90+
this.modalToken.addEventListener('ionModalWillDismiss', (event) => {
91+
console.log('Modal will dismiss:', event.detail);
92+
});
93+
94+
this.modalToken.addEventListener('ionModalDidDismiss', (event) => {
95+
console.log('Modal did dismiss:', event.detail);
96+
});
97+
}
98+
99+
closeModal() {
100+
this.modalToken.dismiss({ result: 'closed by button' });
101+
}
102+
}
103+
```
104+
105+
### Accessing Modal Properties
106+
107+
The injected modal reference provides access to all modal properties and methods:
108+
109+
```tsx
110+
import { Component, inject, OnInit } from '@angular/core';
111+
import { IonButton, IonContent, IonHeader, IonModalToken, IonTitle, IonToolbar } from '@ionic/angular/standalone';
112+
113+
@Component({
114+
selector: 'app-modal',
115+
template: `
116+
<ion-header>
117+
<ion-toolbar>
118+
<ion-title>Modal Properties</ion-title>
119+
</ion-toolbar>
120+
</ion-header>
121+
<ion-content>
122+
<p>Modal ID: {{ modalId }}</p>
123+
<ion-button (click)="toggleBackdropDismiss()"> Toggle Backdrop Dismiss: {{ backdropDismiss }} </ion-button>
124+
</ion-content>
125+
`,
126+
imports: [IonHeader, IonToolbar, IonTitle, IonContent, IonButton],
127+
})
128+
export class ModalComponent implements OnInit {
129+
private modalToken = inject(IonModalToken);
130+
131+
modalId = '';
132+
backdropDismiss = true;
133+
134+
ngOnInit() {
135+
this.modalId = this.modalToken.id || 'No ID';
136+
this.backdropDismiss = this.modalToken.backdropDismiss;
137+
}
138+
139+
toggleBackdropDismiss() {
140+
this.backdropDismiss = !this.backdropDismiss;
141+
this.modalToken.backdropDismiss = this.backdropDismiss;
142+
}
143+
}
144+
```
145+
146+
### Opening a Modal with Injection Token Content
147+
148+
When opening a modal that uses the injection token, you can pass the component directly to the modal controller:
149+
150+
```tsx
151+
import { Component, inject } from '@angular/core';
152+
import { IonContent, IonButton, ModalController } from '@ionic/angular/standalone';
153+
import { ModalComponent } from './modal.component';
154+
155+
@Component({
156+
selector: 'app-home',
157+
template: `
158+
<ion-content>
159+
<ion-button (click)="openModal()">Open Modal</ion-button>
160+
</ion-content>
161+
`,
162+
})
163+
export class HomePage {
164+
private modalController = inject(ModalController);
165+
166+
async openModal() {
167+
const myModal = await this.modalController.create({
168+
component: ModalComponent,
169+
componentProps: {
170+
// Any props you want to pass to the modal content
171+
},
172+
});
173+
174+
await myModal.present();
175+
}
176+
}
177+
```

‎docs/api/reorder-group.md

Lines changed: 49 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,27 +16,71 @@ import Slots from '@ionic-internal/component-api/v8/reorder-group/slots.md';
1616
import EncapsulationPill from '@components/page/api/EncapsulationPill';
1717

1818

19-
The reorder group is a container for items using the [reorder](./reorder) component. When the user drags an item and drops it in a new position, the `ionItemReorder` event is dispatched. A handler for this event should be implemented that calls the `complete` method.
19+
The reorder group is a container for items using the [reorder](./reorder) component. When the user drags an item and drops it, the `ionReorderEnd` event is dispatched. A handler for this event should be implemented that calls the `complete` method.
2020

21-
The `detail` property of the `ionItemReorder` event includes all of the relevant information about the reorder operation, including the `from` and `to` indexes. In the context of reordering, an item moves `from` an index `to` a new index. For example usage of the reorder group, see the [reorder](./reorder) documentation.
21+
The `detail` property of the `ionReorderEnd` event includes all of the relevant information about the reorder operation, including the `from` and `to` indexes. In the context of reordering, an item moves `from` an index `to` an index. For example usage of the reorder group, see the [reorder](./reorder) documentation.
2222

2323

2424
## Interfaces
2525

26-
### ItemReorderEventDetail
26+
### ReorderMoveEventDetail
2727

2828
```typescript
29-
interface ItemReorderEventDetail {
29+
interface ReorderMoveEventDetail {
30+
from: number;
31+
to: number;
32+
}
33+
```
34+
35+
### ReorderEndEventDetail
36+
37+
```typescript
38+
interface ReorderEndEventDetail {
3039
from: number;
3140
to: number;
3241
complete: (data?: boolean | any[]) => any;
3342
}
3443
```
3544

36-
### ItemReorderCustomEvent
45+
### ReorderMoveCustomEvent
46+
47+
While not required, this interface can be used in place of the `CustomEvent` interface for stronger typing with Ionic events emitted from this component.
48+
49+
```typescript
50+
interface ReorderMoveCustomEvent extends CustomEvent {
51+
detail: ReorderMoveEventDetail;
52+
target: HTMLIonReorderGroupElement;
53+
}
54+
55+
```
56+
57+
### ReorderEndCustomEvent
3758

3859
While not required, this interface can be used in place of the `CustomEvent` interface for stronger typing with Ionic events emitted from this component.
3960

61+
```typescript
62+
interface ReorderEndCustomEvent extends CustomEvent {
63+
detail: ReorderEndEventDetail;
64+
target: HTMLIonReorderGroupElement;
65+
}
66+
```
67+
68+
### ItemReorderEventDetail (deprecated)
69+
70+
**_Deprecated_** — Use the `ionReorderEnd` event with `ReorderEndEventDetail` instead.
71+
72+
```typescript
73+
interface ItemReorderEventDetail {
74+
from: number;
75+
to: number;
76+
complete: (data?: boolean | any[]) => any;
77+
}
78+
```
79+
80+
### ItemReorderCustomEvent (deprecated)
81+
82+
**_Deprecated_** — Use the `ionReorderEnd` event with `ReorderEndCustomEvent` instead.
83+
4084
```typescript
4185
interface ItemReorderCustomEvent extends CustomEvent {
4286
detail: ItemReorderEventDetail;

‎docs/api/reorder.md

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill';
2020

2121
Reorder is a component that allows an item to be dragged to change its order within a group of items. It must be used within a [reorder group](./reorder-group) to provide a visual drag and drop interface.
2222

23-
The reorder is the anchor used to drag and drop the items. Once the reorder is complete, the `ionItemReorder` event will be dispatched from the reorder group and the `complete` method needs to be called.
23+
The reorder is the anchor used to drag and drop the items. Once the reorder is complete, the `ionReorderEnd` event will be dispatched from the reorder group and the `complete` method needs to be called.
2424

2525

2626
## Basic Usage
@@ -73,6 +73,29 @@ import UpdatingData from '@site/static/usage/v8/reorder/updating-data/index.md';
7373

7474
<UpdatingData />
7575

76+
## Event Handling
77+
78+
### Using `ionReorderStart` and `ionReorderEnd`
79+
80+
The `ionReorderStart` event is emitted when the user begins a reorder gesture. This event fires when the user taps and holds an item, before any movement occurs. This is useful for preparing the UI for the reorder operation, such as hiding certain elements or updating the visual state of items. For example, icons in list items can be hidden while they are being dragged and shown again when the reorder is complete.
81+
82+
The `ionReorderEnd` event is emitted when the user completes the reorder gesture. This occurs when the user releases the item they are dragging, for example by lifting their finger on a touch screen or releasing the mouse button. The event includes the `from` and `to` indices of the item, as well as the `complete` method that should be called to finalize the reorder operation. The `from` index will always be the position of the item when the gesture started, while the `to` index will be its final position. This event will fire even if no items have changed position, in which case the `from` and `to` indices will be the same.
83+
84+
import ReorderStartEndEvents from '@site/static/usage/v8/reorder/reorder-start-end-events/index.md';
85+
86+
<ReorderStartEndEvents />
87+
88+
### Using `ionReorderMove`
89+
90+
The `ionReorderMove` event is emitted continuously during the reorder gesture as the user drags an item. The event includes the `from` and `to` indices of the item. Unlike `ionReorderEnd`, the `from` index in this event represents the last known position of the item (which updates as the item moves), while the `to` index represents its current position. If the item has not changed position since the last event, the `from` and `to` indices will be the same. This event is useful for tracking position changes during the drag operation. For example, the ranking or numbering of items can be updated in real-time as they are being dragged to maintain a logical ascending order.
91+
92+
:::warning
93+
Do not call the `complete` method during the `ionReorderMove` event as it can break the gesture.
94+
:::
95+
96+
import ReorderMoveEvent from '@site/static/usage/v8/reorder/reorder-move-event/index.md';
97+
98+
<ReorderMoveEvent />
7699

77100
## Usage with Virtual Scroll
78101

0 commit comments

Comments
 (0)