Skip to content

Commit d28c831

Browse files
liamdebeasiliamdebeasi
authored
docs(config): move framework config guides to unified config guide (#2727)
1 parent 194897b commit d28c831

File tree

23 files changed

+939
-765
lines changed

23 files changed

+939
-765
lines changed

‎docs/angular/platform.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ Below is a table listing all the possible platform values along with correspondi
6363

6464
#### Customizing Platform Detection Functions
6565

66-
The function used to detect a specific platform can be overridden by providing an alternative function in the global [Ionic config](./config). Each function takes `window` as a parameter and returns a boolean.
66+
The function used to detect a specific platform can be overridden by providing an alternative function in the global [Ionic config](../developing/config). Each function takes `window` as a parameter and returns a boolean.
6767

6868
```tsx
6969
import { IonicModule } from '@ionic/angular';

‎versioned_docs/version-v6/angular/config.md‎ renamed to ‎docs/developing/config.md‎

Lines changed: 24 additions & 136 deletions
Original file line numberDiff line numberDiff line change
@@ -2,158 +2,57 @@
22
title: Config
33
---
44

5-
<head>
6-
<title>Config | Ionic Config to Change Component Properties Globally</title>
7-
<meta
8-
name="description"
9-
content="Ionic Config provides a way to change the properties of components globally across an app. Config can set the app mode, tab button layout, animations, and more."
10-
/>
11-
</head>
12-
135
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.
146

157
## Global Config
168

17-
To override the default Ionic configurations for your app, provide your own custom config to `IonicModule.forRoot(...)`. The available config keys can be found in the [`IonicConfig`](#ionicconfig) interface.
9+
The available config keys can be found in the [`IonicConfig`](#ionicconfig) interface.
1810

19-
For example, to disable ripple effects and default the mode to Material Design:
11+
The following example disables ripple effects and default the mode to Material Design:
2012

21-
```tsx title="app.module.ts"
22-
import { IonicModule } from '@ionic/angular';
13+
import GlobalExample from '@site/docs/developing/config/global/index.md';
2314

24-
@NgModule({
25-
...
26-
imports: [
27-
IonicModule.forRoot({
28-
rippleEffect: false,
29-
mode: 'md'
30-
})
31-
],
32-
...
33-
})
34-
```
15+
<GlobalExample />
3516

3617
## Per-Component Config
3718

3819
Ionic Config is not reactive. Updating the config's value after the component has rendered will result in the previous value. It is recommended to use a component's properties instead of updating the config, when you require reactive values.
3920

40-
**Not recommended**
41-
42-
```ts
43-
import { IonicModule } from '@ionic/angular';
44-
45-
@NgModule({
46-
...
47-
imports: [
48-
IonicModule.forRoot({
49-
// Not recommended when your app requires reactive values
50-
backButtonText: 'Go Back'
51-
})
52-
],
53-
...
54-
})
55-
```
56-
57-
**Recommended**
58-
59-
```html
60-
<ion-back-button [text]="backButtonText"></ion-back-button>
61-
```
62-
63-
```ts
64-
@Component(...)
65-
class MyComponent {
66-
backButtonText = this.config.get('backButtonText');
67-
68-
constructor(private config: Config) { }
21+
import PerComponentExample from '@site/docs/developing/config/per-component/index.md';
6922

70-
localeChanged(locale: string) {
71-
if (locale === 'es_ES') {
72-
this.backButtonText = 'Devolver';
73-
}
74-
}
75-
76-
}
77-
```
23+
<PerComponentExample />
24+
7825

7926
## Per-Platform Config
8027

8128
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.
8229

83-
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.
84-
8530
In the following example, we are disabling all animations in our Ionic app only if the app is running in a mobile web browser.
86-
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.
87-
88-
```tsx
89-
import { isPlatform, IonicModule } from '@ionic/angular';
90-
91-
@NgModule({
92-
...
93-
imports: [
94-
IonicModule.forRoot({
95-
animated: !isPlatform('mobileweb')
96-
})
97-
],
98-
...
99-
})
100-
```
10131

102-
**Per-platform config with fallback for unmatched platforms:**
32+
import PerPlatformExample from '@site/docs/developing/config/per-platform/index.md';
10333

104-
```tsx
105-
import { isPlatform, IonicModule } from '@ionic/angular';
34+
<PerPlatformExample />
10635

107-
const getConfig = () => {
108-
if (isPlatform('hybrid')) {
109-
return {
110-
backButtonText: 'Previous',
111-
tabButtonLayout: 'label-hide'
112-
}
113-
}
11436

115-
return {
116-
menuIcon: 'ellipsis-vertical'
117-
}
118-
}
119-
@NgModule({
120-
...
121-
imports: [
122-
IonicModule.forRoot(getConfig())
123-
],
124-
...
125-
})
126-
```
37+
### Fallbacks
12738

128-
**Per-platform config overrides:**
39+
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:
12940

130-
```tsx
131-
import { isPlatform, IonicModule } from '@ionic/angular';
41+
import PerPlatformFallbackExample from '@site/docs/developing/config/per-platform-overrides/index.md';
13242

133-
const getConfig = () => {
134-
let config = {
135-
animated: false
136-
};
43+
<PerPlatformFallbackExample />
13744

138-
if (isPlatform('iphone')) {
139-
config = {
140-
...config,
141-
backButtonText: 'Previous'
142-
}
143-
}
45+
### Overrides
14446

145-
return config;
146-
}
147-
@NgModule({
148-
...
149-
imports: [
150-
IonicModule.forRoot(getConfig())
151-
],
152-
...
153-
})
154-
```
47+
This final example allows you to accumulate a config object based upon different platform requirements.
15548

156-
## Methods
49+
import PerPlatformOverridesExample from '@site/docs/developing/config/per-platform-fallback/index.md';
50+
51+
<PerPlatformOverridesExample />
52+
53+
## Reading the Config (Angular)
54+
55+
Ionic Angular provides a `Config` provider for accessing the Ionic Config.
15756

15857
### get
15958

@@ -202,19 +101,6 @@ class AppComponent {
202101
| **Description** | Returns a config value as a `number`. Returns `0` if the config is not defined. |
203102
| **Signature** | `getNumber(key: string, fallback?: number) => number` |
204103

205-
#### Examples
206-
207-
```ts
208-
import { Config } from '@ionic/angular';
209-
210-
@Component(...)
211-
class AppComponent {
212-
constructor(config: Config) {
213-
const keyboardHeight = config.getNumber('keyboardHeight');
214-
}
215-
}
216-
```
217-
218104
## Interfaces
219105

220106
### IonicConfig
@@ -254,5 +140,7 @@ Below are the config options that Ionic uses.
254140
| `statusTap` | `boolean` | If `true`, clicking or tapping the status bar will cause the content to scroll to the top. |
255141
| `swipeBackEnabled` | `boolean` | If `true`, Ionic will enable the "swipe-to-go-back" gesture across the application. |
256142
| `tabButtonLayout` | `TabButtonLayout` | Overrides the default "layout" of all `ion-bar-button` across the whole application. |
143+
| `toastDuration` | `number` | Overrides the default `duration` for all `ion-toast` components. |
257144
| `toastEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-toast`, overriding the default "animation". |
258145
| `toastLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-toast`, overriding the default "animation". |
146+
| `toggleOnOffLabels` | `boolean` | Overrides the default `enableOnOffLabels` in all `ion-toggle` components. |

‎docs/developing/config/global/index.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
import Tabs from '@theme/Tabs';
2+
import TabItem from '@theme/TabItem';
3+
4+
<Tabs
5+
groupId="global-config"
6+
defaultValue="javascript"
7+
values={[
8+
{ value: 'javascript', label: 'JavaScript' },
9+
{ value: 'angular', label: 'Angular' },
10+
{ value: 'react', label: 'React' },
11+
{ value: 'vue', label: 'Vue' },
12+
]}
13+
>
14+
<TabItem value="javascript">
15+
16+
```javascript title="example.js"
17+
window.Ionic = {
18+
config: {
19+
rippleEffect: false,
20+
mode: 'md'
21+
}
22+
}
23+
```
24+
</TabItem>
25+
<TabItem value="angular">
26+
27+
```tsx title="app.module.ts"
28+
import { IonicModule } from '@ionic/angular';
29+
30+
@NgModule({
31+
...
32+
imports: [
33+
IonicModule.forRoot({
34+
rippleEffect: false,
35+
mode: 'md'
36+
})
37+
],
38+
...
39+
})
40+
```
41+
</TabItem>
42+
<TabItem value="react">
43+
44+
The `setupIonicReact` function must be called before rendering any Ionic components (including `IonApp`).
45+
```tsx title="App.tsx"
46+
import { setupIonicReact } from '@ionic/react';
47+
48+
setupIonicReact({
49+
rippleEffect: false,
50+
mode: 'md',
51+
});
52+
```
53+
</TabItem>
54+
<TabItem value="vue">
55+
56+
```tsx title="main.ts"
57+
58+
import { IonicVue } from '@ionic/vue';
59+
import { createApp } from 'vue';
60+
61+
createApp(App).use(IonicVue, {
62+
rippleEffect: false,
63+
mode: 'md',
64+
});
65+
```
66+
</TabItem>
67+
</Tabs>

0 commit comments

Comments
 (0)