Skip to content

Commit e087ff8

Browse files
ltmltm
committed
Tag v5 docs
1 parent 2aac19f commit e087ff8

File tree

569 files changed

+92880
-0
lines changed

Some content is hidden

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

569 files changed

+92880
-0
lines changed

‎docusaurus.config.js

+12
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,9 @@ module.exports = {
3131
srcDark: 'img/framework-logo-dark.svg',
3232
},
3333
items: [
34+
{
35+
type: 'docsVersionDropdown',
36+
},
3437
{
3538
to: '/',
3639
activeBaseRegex: '^/docs/(?!api|components|cli|native)',
@@ -228,6 +231,15 @@ module.exports = {
228231
}
229232
return `https://github.com/ionic-team/ionic-docs/edit/main/${versionDocsDirPath}/${docPath}`;
230233
},
234+
lastVersion: 'current',
235+
versions: {
236+
'current': {
237+
label: 'v6-beta',
238+
},
239+
'v5': {
240+
banner: 'none',
241+
},
242+
},
231243
},
232244
blog: false,
233245
},

‎versioned_docs/version-v5/angular/config.md

+177
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# Config
2+
3+
Ionic Config provides a way to change the properties of components globally across an app. It can set the app mode, tab button layout, animations, and more.
4+
5+
## Global Config
6+
7+
To override the initial Ionic config for the app, provide a config in `IonicModule.forRoot` in the `app.module.ts` file.
8+
9+
```typescript
10+
import { IonicModule } from '@ionic/angular';
11+
12+
@NgModule({
13+
...
14+
imports: [
15+
BrowserModule,
16+
IonicModule.forRoot({
17+
rippleEffect: false,
18+
mode: 'md'
19+
}),
20+
AppRoutingModule
21+
],
22+
...
23+
})
24+
```
25+
26+
In the above example, we are disabling the Material Design ripple effect across the app, as well as forcing the mode to be Material Design.
27+
28+
29+
## Per-Component Config
30+
31+
Ionic Config is not reactive, so it is recommended to use a component's properties when you want to override its default behavior rather than set its config globally.
32+
33+
```typescript
34+
import { IonicModule } from '@ionic/angular';
35+
36+
@NgModule({
37+
...
38+
imports: [
39+
BrowserModule,
40+
IonicModule.forRoot({
41+
backButtonText: 'Go Back'
42+
}),
43+
AppRoutingModule
44+
],
45+
...
46+
})
47+
```
48+
49+
This will set the default text for `ion-back-button` to `Go Back`. However, if you were to change the value of the `backButtonText` config to `Do Not Go Back`, the `ion-back-button` default text would still default to `Go Back` as the component has already been initialized and rendered. Instead, it is recommended to use the `text` property on `ion-back-button`.
50+
51+
```html
52+
<ion-back-button [text]="getBackButtonText()"></ion-back-button>
53+
```
54+
55+
In this example we have used our `ion-back-button` in such a way that the text can be dynamically updated if there were to be a change that warranted it, such as a language or locale change. The `getBackButtonText` method would be responsible for returning the correct text.
56+
57+
## Per-Platform Config
58+
59+
Ionic Config can also be set on a per-platform basis. For example, this allows you to disable animations if the app is being run in a browser on a potentially slower device. Developers can take advantage of the Platform utilities to accomplish this.
60+
61+
Since the config is set at runtime, you will not have access to the Platform Dependency Injection. Instead, you can use the underlying functions that the provider uses directly.
62+
63+
In the following example, we are disabling all animations in our Ionic app only if the app is running in a mobile web browser.
64+
The `isPlatform()` call returns `true` or `false` based upon the platform that is passed in. See the [Platform Documentation](platform.md#platforms) for a list of possible values.
65+
66+
67+
```typescript
68+
import { isPlatform, IonicModule } from '@ionic/angular';
69+
70+
@NgModule({
71+
...
72+
imports: [
73+
BrowserModule,
74+
IonicModule.forRoot({
75+
animated: !isPlatform('mobileweb')
76+
}),
77+
AppRoutingModule
78+
],
79+
...
80+
})
81+
```
82+
83+
The next example allows you to set an entirely different configuration based upon the platform, falling back to a default config if no platforms match:
84+
85+
```typescript
86+
import { isPlatform, IonicModule } from '@ionic/angular';
87+
88+
const getConfig = () => {
89+
if (isPlatform('hybrid')) {
90+
return {
91+
backButtonText: 'Previous',
92+
tabButtonLayout: 'label-hide'
93+
}
94+
}
95+
96+
return {
97+
menuIcon: 'ellipsis-vertical'
98+
}
99+
}
100+
@NgModule({
101+
...
102+
imports: [
103+
BrowserModule,
104+
IonicModule.forRoot(getConfig()),
105+
AppRoutingModule
106+
],
107+
...
108+
})
109+
```
110+
111+
Finally, this example allows you to accumulate a config object based upon different platform requirements:
112+
113+
```typescript
114+
import { isPlatform, IonicModule } from '@ionic/angular';
115+
116+
const getConfig = () => {
117+
let config = {
118+
animated: false
119+
};
120+
121+
if (isPlatform('iphone')) {
122+
config = {
123+
...config,
124+
backButtonText: 'Previous'
125+
}
126+
}
127+
128+
return config;
129+
}
130+
@NgModule({
131+
...
132+
imports: [
133+
BrowserModule,
134+
IonicModule.forRoot(getConfig()),
135+
AppRoutingModule
136+
],
137+
...
138+
})
139+
```
140+
141+
## Config Options
142+
143+
Below is a list of config options that Ionic uses.
144+
145+
| Config | Type | Description |
146+
|--------------------------|--------------------|----------------------------------------------------------------------------------------------------------|
147+
| `actionSheetEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-action-sheet`, overriding the default "animation".
148+
| `actionSheetLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-action-sheet`, overriding the default "animation".
149+
| `alertEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-alert`, overriding the default "animation".
150+
| `alertLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-alert`, overriding the default "animation".
151+
| `animated` | `boolean` | If `true`, Ionic will enable all animations and transitions across the app.
152+
| `backButtonIcon` | `string` | Overrides the default icon in all `<ion-back-button>` components.
153+
| `backButtonText` | `string` | Overrides the default text in all `<ion-back-button>` components.
154+
| `hardwareBackButton` | `boolean` | If `true`, Ionic will respond to the hardware back button in an Android device.
155+
| `infiniteLoadingSpinner` | `SpinnerTypes` | Overrides the default spinner type in all `<ion-infinite-scroll-content>` components.
156+
| `loadingEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-loading`, overriding the default "animation".
157+
| `loadingLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-loading`, overriding the default "animation".
158+
| `loadingSpinner` | `SpinnerTypes` | Overrides the default spinner for all `ion-loading` overlays.
159+
| `menuIcon` | `string` | Overrides the default icon in all `<ion-menu-button>` components.
160+
| `menuType` | `string` | Overrides the default menu type for all `<ion-menu>` components.
161+
| `modalEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-modal`, overriding the default "animation".
162+
| `modalLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-modal`, overriding the default "animation".
163+
| `mode` | `Mode` | The mode determines which platform styles to use for the whole application.
164+
| `navAnimation` | `AnimationBuilder` | Overrides the default "animation" of all `ion-nav` and `ion-router-outlet` across the whole application.
165+
| `pickerEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-picker`, overriding the default "animation".
166+
| `pickerLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-picker`, overriding the default "animation".
167+
| `popoverEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-popover`, overriding the default "animation".
168+
| `popoverLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-popover`, overriding the default "animation".
169+
| `refreshingIcon` | `string` | Overrides the default icon in all `<ion-refresh-content>` components.
170+
| `refreshingSpinner` | `SpinnerTypes` | Overrides the default spinner type in all `<ion-refresh-content>` components.
171+
| `sanitizerEnabled` | `boolean` | If `true`, Ionic will enable a basic DOM sanitizer on component properties that accept custom HTML.
172+
| `spinner` | `SpinnerTypes` | Overrides the default spinner in all `<ion-spinner>` components.
173+
| `statusTap` | `boolean` | If `true`, clicking or tapping the status bar will cause the content to scroll to the top.
174+
| `swipeBackEnabled` | `boolean` | If `true`, Ionic will enable the "swipe-to-go-back" gesture across the application.
175+
| `tabButtonLayout` | `TabButtonLayout` | Overrides the default "layout" of all `ion-bar-button` across the whole application.
176+
| `toastEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-toast`, overriding the default "animation".
177+
| `toastLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-toast`, overriding the default "animation".

‎versioned_docs/version-v5/angular/lifecycle.md

+102
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
sidebar_label: Lifecycle
3+
---
4+
5+
# Ionic Page Life Cycle
6+
7+
This guide covers how the page life cycle works in an app built with Ionic and Angular.
8+
9+
10+
![Ionic life cycle events demo](/img/guides/lifecycle/ioniclifecycle.png)
11+
12+
## Angular Life Cycle Events
13+
14+
Ionic embraces the life cycle events provided by Angular. The two Angular events you will find using the most are:
15+
16+
17+
| Event Name | Description |
18+
|--------------------|------------------------------------------------------------------|
19+
| `ngOnInit` | Fired once during component initialization. This event can be used to initialize local members and make calls into services that only need to be done once. |
20+
| `ngOnDestroy` | Fired right before Angular destroys the view. Useful for cleanup like unsubscribing from observables. |
21+
22+
For more info on the Angular Component Life Cycle events, visit their [component lifecycle docs](https://angular.io/guide/lifecycle-hooks).
23+
24+
> Components that use `ion-nav` or `ion-router-outlet` should not use the `OnPush` change detection strategy. Doing so will prevent lifecycle hooks such as `ngOnInit` from firing. Additionally, asynchronous state changes may not render properly.
25+
26+
## Ionic Page Events
27+
28+
In addition to the Angular life cycle events, Ionic Angular provides a few additional events that you can use:
29+
30+
| Event Name | Description |
31+
|--------------------|------------------------------------------------------------------|
32+
| `ionViewWillEnter` | Fired when the component routing to is about to animate into view. |
33+
| `ionViewDidEnter` | Fired when the component routing to has finished animating. |
34+
| `ionViewWillLeave` | Fired when the component routing from is about to animate. |
35+
| `ionViewDidLeave` | Fired when the component routing to has finished animating. |
36+
37+
The difference between `ionViewWillEnter` and `ionViewDidEnter` is when they fire. The former fires right after `ngOnInit` but before the page transition begins, and the latter directly after the transition ends.
38+
39+
For `ionViewWillLeave` and `ionViewDidLeave`, `ionViewWillLeave` gets called directly before the transition away from the current page begins, and `ionViewDidLeave` does not get called until after the new page gets successfully transitioned into (after the new pages `ionViewDidEnter` fires).
40+
41+
42+
![Ionic life cycle events demo](/img/guides/lifecycle/ioniclifecycle.gif)
43+
44+
## How Ionic Handles the Life of a Page
45+
46+
Ionic has its router outlet, called `<ion-router-outlet />`. This outlet extends Angular's `<router-outlet />` with some additional functionality to enable better experiences for mobile devices.
47+
48+
When an app is wrapped in `<ion-router-outlet />`, Ionic treats navigation a bit differently. When you navigate to a new page, Ionic will keep the old page in the existing DOM, but hide it from your view and transition the new page. The reason we do this is two-fold:
49+
50+
1) We can maintain the state of the old page (data on the screen, scroll position, etc..)
51+
2) We can provide a smoother transition back to the page since it is already there and doesn't need to be recreated.
52+
53+
Pages are only removed from the DOM when they are "popped", for instance, by pressing the back button in the UI or the browsers back button.
54+
55+
Because of this special handling, the `ngOnInit` and `ngOnDestroy` methods might not fire when you would usually think they should.
56+
57+
`ngOnInit` will only fire each time the page is freshly created, but not when navigated back to the page. For instance, navigating between each page in a tabs interface will only call each page's `ngOnInit` method once, but not on subsequent visits. `ngOnDestroy` will only fire when a page "popped".
58+
59+
## Route Guards
60+
61+
In Ionic 3, there were a couple of additional life cycle methods that were useful to control when a page could be entered (`ionViewCanEnter`) and left (`ionViewCanLeave`). These could be used to protect pages from unauthorized users and to keep a user on a page when you don't want them to leave (like during a form fill).
62+
63+
These methods were removed in Ionic 4 in favor of using Angular's Route Guards.
64+
65+
A route guard helps determine if a particular action can be taken against a route. They are classes that implement a certain interface. The `CanActivate` and `CanDeactivate` interfaces can be used to implement the same type of logic that the removed events `ionViewCanEnter` and `ionViewCanLeave` did.
66+
67+
```typescript
68+
@Injectable()
69+
export class AuthGuard implements CanActivate {
70+
constructor(private authService: AuthService) {}
71+
72+
canActivate(route: ActivatedRouteSnapshot, state: RouterStateSnapshot) {
73+
return this.authService.isAuthenticated();
74+
}
75+
}
76+
```
77+
78+
To use this guard, add it to the appropriate param in the route definition:
79+
80+
```typescript
81+
{ path: 'settings', canActivate: [AuthGuard], loadChildren: '...', }
82+
```
83+
84+
For more info on how to use route guards, go to Angular's [router documentation](https://angular.io/guide/router).
85+
86+
## Guidance for Each Life Cycle Method
87+
88+
Below are some tips on uses cases for each of the life cycle events.
89+
90+
- `ngOnInit` - Initialize your component and load data from services that don't need refreshing on each subsequent visit.
91+
- `ionViewWillEnter` - Since `ionViewWillEnter` is called every time the view is navigated to (regardless if initialized or not), it's a good method to load data from services. However, if your data comes back during the animation, it can start lots of DOM manipulation, which can cause some janky animations.
92+
- `ionViewDidEnter` - If you see performance problems from using `ionViewWillEnter` when loading data, you can do your data calls in `ionViewDidEnter` instead. This event won't fire until after the page is visible by the user, however, so you might want to use either a loading indicator or a skeleton screen, so content doesn't flash in un-naturally after the transition is complete.
93+
- `ionViewWillLeave` - Can be used for cleanup, like unsubscribing from observables. Since `ngOnDestroy` might not fire when you navigate from the current page, put your cleanup code here if you don't want it active while the screen is not in view.
94+
- `ionViewDidLeave` - When this event fires, you know the new page has fully transitioned in, so any logic you might not normally do when the view is visible can go here.
95+
- `ngOnDestroy` - Cleanup logic for your pages that you don't want to clean up in `ionViewWillLeave`.
96+
97+
98+
99+
100+
101+
102+

0 commit comments

Comments
 (0)