From f9596a214c4553ca38db18cf000186ddb79304c4 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Thu, 26 Jan 2023 20:00:22 +0000 Subject: [PATCH 01/13] docs(config): create consolidated config page --- docs/developing/config.md | 59 +++++++++++++++++++++++ docs/developing/config/global/index.md | 67 ++++++++++++++++++++++++++ sidebars.js | 1 + 3 files changed, 127 insertions(+) create mode 100644 docs/developing/config.md create mode 100644 docs/developing/config/global/index.md diff --git a/docs/developing/config.md b/docs/developing/config.md new file mode 100644 index 00000000000..c1543837ca5 --- /dev/null +++ b/docs/developing/config.md @@ -0,0 +1,59 @@ +--- +title: Config +--- + +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. + +## Global Config + +The available config keys can be found in the [`IonicConfig`](#ionicconfig) interface. + +The following example disables ripple effects and default the mode to Material Design: + +import GlobalExample from '@site/docs/developing/config/global/index.md'; + + + +## Interfaces + +### IonicConfig + +Below are the config options that Ionic uses. + +| Config | Type | Description | +| ------------------------ | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `actionSheetEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-action-sheet`, overriding the default "animation". | +| `actionSheetLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-action-sheet`, overriding the default "animation". | +| `alertEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-alert`, overriding the default "animation". | +| `alertLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-alert`, overriding the default "animation". | +| `animated` | `boolean` | If `true`, Ionic will enable all animations and transitions across the app. | +| `backButtonDefaultHref` | `string` | Overrides the default value for the `defaultHref` property in all `` components. | +| `backButtonIcon` | `string` | Overrides the default icon in all `` components. | +| `backButtonText` | `string` | Overrides the default text in all `` components. | +| `hardwareBackButton` | `boolean` | If `true`, Ionic will respond to the hardware back button in an Android device. | +| `infiniteLoadingSpinner` | `SpinnerTypes` | Overrides the default spinner type in all `` components. | +| `loadingEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-loading`, overriding the default "animation". | +| `loadingLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-loading`, overriding the default "animation". | +| `loadingSpinner` | `SpinnerTypes` | Overrides the default spinner for all `ion-loading` overlays. | +| `menuIcon` | `string` | Overrides the default icon in all `` components. | +| `menuType` | `string` | Overrides the default menu type for all `` components. | +| `modalEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-modal`, overriding the default "animation". | +| `modalLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-modal`, overriding the default "animation". | +| `mode` | `Mode` | The mode determines which platform styles to use for the whole application. | +| `navAnimation` | `AnimationBuilder` | Overrides the default "animation" of all `ion-nav` and `ion-router-outlet` across the whole application. | +| `pickerEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-picker`, overriding the default "animation". | +| `pickerLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-picker`, overriding the default "animation". | +| `platform` | [`PlatformConfig`](/docs/angular/platform#customizing-platform-detection-methods) | Overrides the default platform detection methods. | +| `popoverEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-popover`, overriding the default "animation". | +| `popoverLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-popover`, overriding the default "animation". | +| `refreshingIcon` | `string` | Overrides the default icon in all `` components. | +| `refreshingSpinner` | `SpinnerTypes` | Overrides the default spinner type in all `` components. | +| `sanitizerEnabled` | `boolean` | If `true`, Ionic will enable a basic DOM sanitizer on component properties that accept custom HTML. | +| `spinner` | `SpinnerTypes` | Overrides the default spinner in all `` components. | +| `statusTap` | `boolean` | If `true`, clicking or tapping the status bar will cause the content to scroll to the top. | +| `swipeBackEnabled` | `boolean` | If `true`, Ionic will enable the "swipe-to-go-back" gesture across the application. | +| `tabButtonLayout` | `TabButtonLayout` | Overrides the default "layout" of all `ion-bar-button` across the whole application. | +| `toastDuration` | `number` | Overrides the default `duration` for all `ion-toast` components. | +| `toastEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-toast`, overriding the default "animation". | +| `toastLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-toast`, overriding the default "animation". | +| `toggleOnOffLabels` | `boolean` | Overrides the default `enableOnOffLabels` in all `ion-toggle` components. | diff --git a/docs/developing/config/global/index.md b/docs/developing/config/global/index.md new file mode 100644 index 00000000000..bbfbaa83a71 --- /dev/null +++ b/docs/developing/config/global/index.md @@ -0,0 +1,67 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + +```javascript title="example.js" +window.Ionic = { + config: { + rippleEffect: false, + mode: 'md' + } +} +``` + + + +```tsx title="app.module.ts" +import { IonicModule } from '@ionic/angular'; + +@NgModule({ + ... + imports: [ + IonicModule.forRoot({ + rippleEffect: false, + mode: 'md' + }) + ], + ... +}) +``` + + + +The `setupIonicReact` function must be called before rendering any Ionic components (including `IonApp`). +```tsx title="App.tsx" +import { setupIonicReact } from '@ionic/react'; + +setupIonicReact({ + rippleEffect: false, + mode: 'md', +}); +``` + + + +```tsx title="main.ts" + +import { IonicVue } from '@ionic/vue'; +import { createApp } from 'vue'; + +createApp(App).use(IonicVue, { + rippleEffect: false, + mode: 'md', +}); +``` + + \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index e9610cbdb0d..de8815476f5 100644 --- a/sidebars.js +++ b/sidebars.js @@ -30,6 +30,7 @@ module.exports = { 'developing/tips', 'developing/hardware-back-button', 'developing/keyboard', + 'developing/config' ], }, { From cbe176baba30e01ff7398eb94251e4200f6b99d8 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Thu, 26 Jan 2023 20:12:03 +0000 Subject: [PATCH 02/13] docs(config): add per-component config --- docs/angular/config.md | 46 +----- docs/developing/config.md | 8 + docs/developing/config/per-component/index.md | 143 ++++++++++++++++++ 3 files changed, 152 insertions(+), 45 deletions(-) create mode 100644 docs/developing/config/per-component/index.md diff --git a/docs/angular/config.md b/docs/angular/config.md index 9e6849a3729..00d73c06d13 100644 --- a/docs/angular/config.md +++ b/docs/angular/config.md @@ -213,48 +213,4 @@ class AppComponent { const keyboardHeight = config.getNumber('keyboardHeight'); } } -``` - -## Interfaces - -### IonicConfig - -Below are the config options that Ionic uses. - -| Config | Type | Description | -| ------------------------ | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `actionSheetEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-action-sheet`, overriding the default "animation". | -| `actionSheetLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-action-sheet`, overriding the default "animation". | -| `alertEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-alert`, overriding the default "animation". | -| `alertLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-alert`, overriding the default "animation". | -| `animated` | `boolean` | If `true`, Ionic will enable all animations and transitions across the app. | -| `backButtonDefaultHref` | `string` | Overrides the default value for the `defaultHref` property in all `` components. | -| `backButtonIcon` | `string` | Overrides the default icon in all `` components. | -| `backButtonText` | `string` | Overrides the default text in all `` components. | -| `hardwareBackButton` | `boolean` | If `true`, Ionic will respond to the hardware back button in an Android device. | -| `infiniteLoadingSpinner` | `SpinnerTypes` | Overrides the default spinner type in all `` components. | -| `loadingEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-loading`, overriding the default "animation". | -| `loadingLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-loading`, overriding the default "animation". | -| `loadingSpinner` | `SpinnerTypes` | Overrides the default spinner for all `ion-loading` overlays. | -| `menuIcon` | `string` | Overrides the default icon in all `` components. | -| `menuType` | `string` | Overrides the default menu type for all `` components. | -| `modalEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-modal`, overriding the default "animation". | -| `modalLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-modal`, overriding the default "animation". | -| `mode` | `Mode` | The mode determines which platform styles to use for the whole application. | -| `navAnimation` | `AnimationBuilder` | Overrides the default "animation" of all `ion-nav` and `ion-router-outlet` across the whole application. | -| `pickerEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-picker`, overriding the default "animation". | -| `pickerLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-picker`, overriding the default "animation". | -| `platform` | [`PlatformConfig`](/docs/angular/platform#customizing-platform-detection-methods) | Overrides the default platform detection methods. | -| `popoverEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-popover`, overriding the default "animation". | -| `popoverLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-popover`, overriding the default "animation". | -| `refreshingIcon` | `string` | Overrides the default icon in all `` components. | -| `refreshingSpinner` | `SpinnerTypes` | Overrides the default spinner type in all `` components. | -| `sanitizerEnabled` | `boolean` | If `true`, Ionic will enable a basic DOM sanitizer on component properties that accept custom HTML. | -| `spinner` | `SpinnerTypes` | Overrides the default spinner in all `` components. | -| `statusTap` | `boolean` | If `true`, clicking or tapping the status bar will cause the content to scroll to the top. | -| `swipeBackEnabled` | `boolean` | If `true`, Ionic will enable the "swipe-to-go-back" gesture across the application. | -| `tabButtonLayout` | `TabButtonLayout` | Overrides the default "layout" of all `ion-bar-button` across the whole application. | -| `toastDuration` | `number` | Overrides the default `duration` for all `ion-toast` components. | -| `toastEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-toast`, overriding the default "animation". | -| `toastLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-toast`, overriding the default "animation". | -| `toggleOnOffLabels` | `boolean` | Overrides the default `enableOnOffLabels` in all `ion-toggle` components. | +``` \ No newline at end of file diff --git a/docs/developing/config.md b/docs/developing/config.md index c1543837ca5..a53643a6c13 100644 --- a/docs/developing/config.md +++ b/docs/developing/config.md @@ -14,6 +14,14 @@ import GlobalExample from '@site/docs/developing/config/global/index.md'; +## Per-Component Config + +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. + +import PerComponentExample from '@site/docs/developing/config/per-component/index.md'; + + + ## Interfaces ### IonicConfig diff --git a/docs/developing/config/per-component/index.md b/docs/developing/config/per-component/index.md new file mode 100644 index 00000000000..64b868a70ee --- /dev/null +++ b/docs/developing/config/per-component/index.md @@ -0,0 +1,143 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + +**Not recommended** + +```ts +window.Ionic = { + config: { + // Not recommended when your app requires reactive values + backButtonText: 'Go Back' + } +} +``` + +**Recommended** + +```html + + + +``` + + + +**Not recommended** + +```ts +import { IonicModule } from '@ionic/angular'; + +@NgModule({ + ... + imports: [ + IonicModule.forRoot({ + // Not recommended when your app requires reactive values + backButtonText: 'Go Back' + }) + ], + ... +}); +``` + +**Recommended** + +```html + +``` + +```ts +@Component(...) +class MyComponent { + /** + * The back button text can be updated + * anytime the locale changes. + */ + backButtonText = 'Go Back'; +} +``` + + + +**Not recommended** + +```tsx +import { setupIonicReact } from '@ionic/react'; + +setupIonicReact({ + // Not recommended when your app requires reactive values + backButtonText: 'Go Back' +}); +``` + +**Recommended** + +```tsx +import { useState } from 'react'; +import { IonBackButton } from '@ionic/react'; + +const ExampleComponent = () => { + const [backButtonText, setBackButtonText] = useState('Go Back'); + return ( + {/* + * The back button text can be updated + * anytime the locale changes. + */} + + ) +} +``` + + + +**Not recommended** + +```ts +import { IonicVue } from '@ionic/vue'; +import { createApp } from 'vue'; + + // Not recommended when your app requires reactive values +createApp(App).use(IonicVue, { + backButtonText: 'Go Back' +}); +``` + +**Recommended** + +```html + + + +``` + + \ No newline at end of file From 85f61b4d8eff9b89cd124aac970c664421ce83d5 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Thu, 26 Jan 2023 20:21:13 +0000 Subject: [PATCH 03/13] docs(config): add per-platform example --- docs/developing/config.md | 11 ++++ docs/developing/config/per-platform/index.md | 54 ++++++++++++++++++++ 2 files changed, 65 insertions(+) create mode 100644 docs/developing/config/per-platform/index.md diff --git a/docs/developing/config.md b/docs/developing/config.md index a53643a6c13..16a5f4bed24 100644 --- a/docs/developing/config.md +++ b/docs/developing/config.md @@ -21,6 +21,17 @@ Ionic Config is not reactive. Updating the config's value after the component ha import PerComponentExample from '@site/docs/developing/config/per-component/index.md'; + + +## Per-Platform Config + +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. + +In the following example, we are disabling all animations in our Ionic app only if the app is running in a mobile web browser. + +import PerPlatformExample from '@site/docs/developing/config/per-platform/index.md'; + + ## Interfaces diff --git a/docs/developing/config/per-platform/index.md b/docs/developing/config/per-platform/index.md new file mode 100644 index 00000000000..5c1d089c35c --- /dev/null +++ b/docs/developing/config/per-platform/index.md @@ -0,0 +1,54 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + + +:::note +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. +::: + +```ts title="app.module.ts" +import { isPlatform, IonicModule } from '@ionic/angular'; + +@NgModule({ + ... + imports: [ + IonicModule.forRoot({ + animated: !isPlatform('mobileweb') + }) + ], + ... +}) +``` + + + +```tsx title="App.tsx" +import { isPlatform, setupIonicReact } from '@ionic/react'; + +setupIonicReact({ + animated: !isPlatform('mobileweb'), +}); +``` + + + +```ts title="main.ts" +import { IonicVue, isPlatform } from '@ionic/vue'; + +createApp(App).use(IonicVue, { + animated: !isPlatform('mobileweb'), +}); +```` + + \ No newline at end of file From 3751c05f916fe6d3ddef0fe6210512a44201d30b Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Thu, 26 Jan 2023 20:30:20 +0000 Subject: [PATCH 04/13] docs(config): add fallbacks and overrides --- docs/developing/config.md | 18 ++++ .../config/per-platform-fallback/index.md | 79 +++++++++++++++++ .../config/per-platform-overrides/index.md | 88 +++++++++++++++++++ 3 files changed, 185 insertions(+) create mode 100644 docs/developing/config/per-platform-fallback/index.md create mode 100644 docs/developing/config/per-platform-overrides/index.md diff --git a/docs/developing/config.md b/docs/developing/config.md index 16a5f4bed24..c5bf139d902 100644 --- a/docs/developing/config.md +++ b/docs/developing/config.md @@ -33,6 +33,24 @@ import PerPlatformExample from '@site/docs/developing/config/per-platform/index. + +### Fallbacks + +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: + +import PerPlatformFallbackExample from '@site/docs/developing/config/per-platform-overrides/index.md'; + + + +### Overrides + +This final example allows you to accumulate a config object based upon different platform requirements. + +import PerPlatformOverridesExample from '@site/docs/developing/config/per-platform-fallback/index.md'; + + + + ## Interfaces ### IonicConfig diff --git a/docs/developing/config/per-platform-fallback/index.md b/docs/developing/config/per-platform-fallback/index.md new file mode 100644 index 00000000000..02a5f27a3c0 --- /dev/null +++ b/docs/developing/config/per-platform-fallback/index.md @@ -0,0 +1,79 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + +```ts title="app.module.ts" +import { isPlatform, IonicModule } from '@ionic/angular'; + +const getConfig = () => { + if (isPlatform('hybrid')) { + return { + tabButtonLayout: 'label-hide' + } + } + + return { + tabButtonLayout: 'icon-top' + }; +} +@NgModule({ + ... + imports: [ + IonicModule.forRoot(getConfig()) + ], + ... +}); +``` + + + +```tsx title="App.tsx" +import { isPlatform, setupIonicReact } from '@ionic/react'; + +const getConfig = () => { + if (isPlatform('hybrid')) { + return { + tabButtonLayout: 'label-hide' + } + } + + return { + tabButtonLayout: 'icon-top' + }; +}; + +setupIonicReact(getConfig()); + +``` + + + +```ts title="main.ts" +import { IonicVue, isPlatform } from '@ionic/vue'; + +const getConfig = () => { + if (isPlatform('hybrid')) { + return { + tabButtonLayout: 'label-hide' + } + } + + return { + tabButtonLayout: 'icon-top' + }; +}; + +createApp(App).use(IonicVue, getConfig()); +```` + + \ No newline at end of file diff --git a/docs/developing/config/per-platform-overrides/index.md b/docs/developing/config/per-platform-overrides/index.md new file mode 100644 index 00000000000..243cfa9c2fc --- /dev/null +++ b/docs/developing/config/per-platform-overrides/index.md @@ -0,0 +1,88 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + +```ts title="app.module.ts" +import { isPlatform, IonicModule } from '@ionic/angular'; + +const getConfig = () => { + let config = { + animated: false + }; + + if (isPlatform('iphone')) { + config = { + ...config, + backButtonText: 'Previous' + } + } + + return config; +} +@NgModule({ + ... + imports: [ + IonicModule.forRoot(getConfig()) + ], + ... +}); +``` + + + +```tsx title="App.tsx" +import { isPlatform, setupIonicReact } from '@ionic/react'; + +const getConfig = () => { + let config = { + animated: false, + }; + + if (isPlatform('iphone')) { + config = { + ...config, + backButtonText: 'Previous', + }; + } + + return config; +}; + +setupIonicReact(getConfig()); + +``` + + + +```ts title="main.ts" +import { IonicVue, isPlatform } from '@ionic/vue'; + +const getConfig = () => { + let config = { + animated: false, + }; + + if (isPlatform('iphone')) { + config = { + ...config, + backButtonText: 'Previous', + }; + } + + return config; +}; + +createApp(App).use(IonicVue, getConfig()); +```` + + \ No newline at end of file From a24499da7df807eee4893fb3cafc15e3d8594918 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Thu, 26 Jan 2023 20:35:00 +0000 Subject: [PATCH 05/13] docs(config): add angular config read --- docs/developing/config.md | 50 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/docs/developing/config.md b/docs/developing/config.md index c5bf139d902..38cc071f341 100644 --- a/docs/developing/config.md +++ b/docs/developing/config.md @@ -50,6 +50,56 @@ import PerPlatformOverridesExample from '@site/docs/developing/config/per-platfo +## Reading the Config (Angular) + +Ionic Angular provides a `Config` provider for accessing the Ionic Config. + +### get + +| | | +| --------------- | -------------------------------------------------------------------------------- | +| **Description** | Returns a config value as an `any`. Returns `null` if the config is not defined. | +| **Signature** | `get(key: string, fallback?: any) => any` | + +#### Examples + +```ts +import { Config } from '@ionic/angular'; + +@Component(...) +class AppComponent { + constructor(config: Config) { + const mode = config.get('mode'); + } +} +``` + +### getBoolean + +| | | +| --------------- | ------------------------------------------------------------------------------------ | +| **Description** | Returns a config value as a `boolean`. Returns `false` if the config is not defined. | +| **Signature** | `getBoolean(key: string, fallback?: boolean) => boolean` | + +#### Examples + +```ts +import { Config } from '@ionic/angular'; + +@Component(...) +class AppComponent { + constructor(config: Config) { + const swipeBackEnabled = config.getBoolean('swipeBackEnabled'); + } +} +``` + +### getNumber + +| | | +| --------------- | ------------------------------------------------------------------------------- | +| **Description** | Returns a config value as a `number`. Returns `0` if the config is not defined. | +| **Signature** | `getNumber(key: string, fallback?: number) => number` | ## Interfaces From 274c6e9845a039f7f3337f6238d554a3936eb20f Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Thu, 26 Jan 2023 20:39:08 +0000 Subject: [PATCH 06/13] docs(): update links to config page --- sidebars.js | 3 --- 1 file changed, 3 deletions(-) diff --git a/sidebars.js b/sidebars.js index de8815476f5..2e7f6c563f1 100644 --- a/sidebars.js +++ b/sidebars.js @@ -88,7 +88,6 @@ module.exports = { 'angular/navigation', 'angular/virtual-scroll', 'angular/slides', - 'angular/config', 'angular/platform', 'angular/testing', 'angular/storage', @@ -122,7 +121,6 @@ module.exports = { 'react/navigation', 'react/virtual-scroll', 'react/slides', - 'react/config', 'react/platform', 'react/pwa', 'react/overlays', @@ -157,7 +155,6 @@ module.exports = { 'vue/virtual-scroll', 'vue/slides', 'vue/utility-functions', - 'vue/config', 'vue/platform', 'vue/pwa', 'vue/storage', From 99d9e6ad2f40a459374dc4e23e2a601e142fa069 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Thu, 26 Jan 2023 15:40:03 -0500 Subject: [PATCH 07/13] chore(): update links --- docs/angular/config.md | 216 -------------------------------- docs/angular/platform.md | 2 +- docs/react/config.md | 118 ----------------- docs/react/platform.md | 2 +- docs/theming/platform-styles.md | 2 +- docs/updating/6-0.md | 6 +- docs/vue/config.md | 119 ------------------ docs/vue/platform.md | 2 +- 8 files changed, 7 insertions(+), 460 deletions(-) delete mode 100644 docs/angular/config.md delete mode 100644 docs/react/config.md delete mode 100644 docs/vue/config.md diff --git a/docs/angular/config.md b/docs/angular/config.md deleted file mode 100644 index 00d73c06d13..00000000000 --- a/docs/angular/config.md +++ /dev/null @@ -1,216 +0,0 @@ ---- -title: Config ---- - - - Config | Ionic Config to Change Component Properties Globally - - - -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. - -## Global Config - -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. - -For example, to disable ripple effects and default the mode to Material Design: - -```tsx title="app.module.ts" -import { IonicModule } from '@ionic/angular'; - -@NgModule({ - ... - imports: [ - IonicModule.forRoot({ - rippleEffect: false, - mode: 'md' - }) - ], - ... -}) -``` - -## Per-Component Config - -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. - -**Not recommended** - -```ts -import { IonicModule } from '@ionic/angular'; - -@NgModule({ - ... - imports: [ - IonicModule.forRoot({ - // Not recommended when your app requires reactive values - backButtonText: 'Go Back' - }) - ], - ... -}) -``` - -**Recommended** - -```html - -``` - -```ts -@Component(...) -class MyComponent { - backButtonText = this.config.get('backButtonText'); - - constructor(private config: Config) { } - - localeChanged(locale: string) { - if (locale === 'es_ES') { - this.backButtonText = 'Devolver'; - } - } - -} -``` - -## Per-Platform Config - -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. - -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. - -In the following example, we are disabling all animations in our Ionic app only if the app is running in a mobile web browser. -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. - -```tsx -import { isPlatform, IonicModule } from '@ionic/angular'; - -@NgModule({ - ... - imports: [ - IonicModule.forRoot({ - animated: !isPlatform('mobileweb') - }) - ], - ... -}) -``` - -**Per-platform config with fallback for unmatched platforms:** - -```tsx -import { isPlatform, IonicModule } from '@ionic/angular'; - -const getConfig = () => { - if (isPlatform('hybrid')) { - return { - backButtonText: 'Previous', - tabButtonLayout: 'label-hide' - } - } - - return { - menuIcon: 'ellipsis-vertical' - } -} -@NgModule({ - ... - imports: [ - IonicModule.forRoot(getConfig()) - ], - ... -}) -``` - -**Per-platform config overrides:** - -```tsx -import { isPlatform, IonicModule } from '@ionic/angular'; - -const getConfig = () => { - let config = { - animated: false - }; - - if (isPlatform('iphone')) { - config = { - ...config, - backButtonText: 'Previous' - } - } - - return config; -} -@NgModule({ - ... - imports: [ - IonicModule.forRoot(getConfig()) - ], - ... -}) -``` - -## Methods - -### get - -| | | -| --------------- | -------------------------------------------------------------------------------- | -| **Description** | Returns a config value as an `any`. Returns `null` if the config is not defined. | -| **Signature** | `get(key: string, fallback?: any) => any` | - -#### Examples - -```ts -import { Config } from '@ionic/angular'; - -@Component(...) -class AppComponent { - constructor(config: Config) { - const mode = config.get('mode'); - } -} -``` - -### getBoolean - -| | | -| --------------- | ------------------------------------------------------------------------------------ | -| **Description** | Returns a config value as a `boolean`. Returns `false` if the config is not defined. | -| **Signature** | `getBoolean(key: string, fallback?: boolean) => boolean` | - -#### Examples - -```ts -import { Config } from '@ionic/angular'; - -@Component(...) -class AppComponent { - constructor(config: Config) { - const swipeBackEnabled = config.getBoolean('swipeBackEnabled'); - } -} -``` - -### getNumber - -| | | -| --------------- | ------------------------------------------------------------------------------- | -| **Description** | Returns a config value as a `number`. Returns `0` if the config is not defined. | -| **Signature** | `getNumber(key: string, fallback?: number) => number` | - -#### Examples - -```ts -import { Config } from '@ionic/angular'; - -@Component(...) -class AppComponent { - constructor(config: Config) { - const keyboardHeight = config.getNumber('keyboardHeight'); - } -} -``` \ No newline at end of file diff --git a/docs/angular/platform.md b/docs/angular/platform.md index ac957693971..9668f3632a1 100644 --- a/docs/angular/platform.md +++ b/docs/angular/platform.md @@ -63,7 +63,7 @@ Below is a table listing all the possible platform values along with correspondi #### Customizing Platform Detection Functions -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. +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. ```tsx import { IonicModule } from '@ionic/angular'; diff --git a/docs/react/config.md b/docs/react/config.md deleted file mode 100644 index b988b0e3925..00000000000 --- a/docs/react/config.md +++ /dev/null @@ -1,118 +0,0 @@ -# Config - -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. - -## Global Config - -To override the initial Ionic config for the app, import the `setupIonicReact` function from `@ionic/react`, and call it before you render any Ionic components (including `IonApp`). - -```tsx -setupIonicReact({ - rippleEffect: false, - mode: 'md', -}); -``` - -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. - -## Per-Platform Config - -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. - -In the following example, we are disabling all animations in our Ionic app only if the app is running in a mobile web browser. -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. - -```tsx -import { isPlatform, setupIonicReact } from '@ionic/react'; - -setupIonicReact({ - animated: !isPlatform('mobileweb'), -}); -``` - -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: - -```tsx -import { isPlatform, setupIonicReact } from '@ionic/react'; - -const getConfig = () => { - if (isPlatform('hybrid')) { - return { - backButtonText: 'Previous', - tabButtonLayout: 'label-hide', - }; - } - - return { - menuIcon: 'ellipsis-vertical', - }; -}; - -setupIonicReact(getConfig()); -``` - -Finally, this example allows you to accumulate a config object based upon different platform requirements: - -```tsx -import { isPlatform, setupIonicReact } from '@ionic/react'; - -const getConfig = () => { - let config = { - animated: false, - }; - - if (isPlatform('iphone')) { - config = { - ...config, - backButtonText: 'Previous', - }; - } - - return config; -}; -setupIonicReact(getConfig()); -``` - -## Interfaces - -### IonicConfig - -Below are the config options that Ionic uses. - -| Config | Type | Description | -| ------------------------ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `actionSheetEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-action-sheet`, overriding the default "animation". | -| `actionSheetLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-action-sheet`, overriding the default "animation". | -| `alertEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-alert`, overriding the default "animation". | -| `alertLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-alert`, overriding the default "animation". | -| `animated` | `boolean` | If `true`, Ionic will enable all animations and transitions across the app. | -| `backButtonDefaultHref` | `string` | Overrides the default value for the `defaultHref` property in all `` components. | -| `backButtonIcon` | `string` | Overrides the default icon in all `` components. | -| `backButtonText` | `string` | Overrides the default text in all `` components. | -| `hardwareBackButton` | `boolean` | If `true`, Ionic will respond to the hardware back button in an Android device. | -| `infiniteLoadingSpinner` | `SpinnerTypes` | Overrides the default spinner type in all `` components. | -| `loadingEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-loading`, overriding the default "animation". | -| `loadingLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-loading`, overriding the default "animation". | -| `loadingSpinner` | `SpinnerTypes` | Overrides the default spinner for all `ion-loading` overlays. | -| `menuIcon` | `string` | Overrides the default icon in all `` components. | -| `menuType` | `string` | Overrides the default menu type for all `` components. | -| `modalEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-modal`, overriding the default "animation". | -| `modalLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-modal`, overriding the default "animation". | -| `mode` | `Mode` | The mode determines which platform styles to use for the whole application. | -| `navAnimation` | `AnimationBuilder` | Overrides the default "animation" of all `ion-nav` and `ion-router-outlet` across the whole application. | -| `pickerEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-picker`, overriding the default "animation". | -| `pickerLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-picker`, overriding the default "animation". | -| `platform` | [`PlatformConfig`](/docs/react/platform#customizing-platform-detection-methods) | Overrides the default platform detection methods. | -| `popoverEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-popover`, overriding the default "animation". | -| `popoverLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-popover`, overriding the default "animation". | -| `refreshingIcon` | `string` | Overrides the default icon in all `` components. | -| `refreshingSpinner` | `SpinnerTypes` | Overrides the default spinner type in all `` components. | -| `sanitizerEnabled` | `boolean` | If `true`, Ionic will enable a basic DOM sanitizer on component properties that accept custom HTML. | -| `spinner` | `SpinnerTypes` | Overrides the default spinner in all `` components. | -| `statusTap` | `boolean` | If `true`, clicking or tapping the status bar will cause the content to scroll to the top. | -| `swipeBackEnabled` | `boolean` | If `true`, Ionic will enable the "swipe-to-go-back" gesture across the application. | -| `tabButtonLayout` | `TabButtonLayout` | Overrides the default "layout" of all `ion-bar-button` across the whole application. | -| `toastDuration` | `number` | Overrides the default `duration` for all `ion-toast` components. | -| `toastEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-toast`, overriding the default "animation". | -| `toastLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-toast`, overriding the default "animation". | -| `toggleOnOffLabels` | `boolean` | Overrides the default `enableOnOffLabels` in all `ion-toggle` components. | diff --git a/docs/react/platform.md b/docs/react/platform.md index a58735d8609..eb391d04795 100644 --- a/docs/react/platform.md +++ b/docs/react/platform.md @@ -47,7 +47,7 @@ Below is a table listing all the possible platform values along with correspondi ## Customizing Platform Detection Functions -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. +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. ```tsx setupIonicReact({ diff --git a/docs/theming/platform-styles.md b/docs/theming/platform-styles.md index f503b107c80..e9c49af3263 100644 --- a/docs/theming/platform-styles.md +++ b/docs/theming/platform-styles.md @@ -14,7 +14,7 @@ Ionic provides platform specific styles based on the device the application is r ## Ionic Modes -Ionic uses **modes** to customize the look of components. Each **platform** has a default **mode**, but this can be overridden through the global [config](../angular/config.md). The following chart displays the default **mode** that is added to each **platform**: +Ionic uses **modes** to customize the look of components. Each **platform** has a default **mode**, but this can be overridden through the global [config](../developing/config.md). The following chart displays the default **mode** that is added to each **platform**: | Platform | Mode | Description | | --------- | ----- | -------------------------------------------------------------------------------------------------------------------------------- | diff --git a/docs/updating/6-0.md b/docs/updating/6-0.md index 3ef03a1a1ca..f3635ca07d6 100644 --- a/docs/updating/6-0.md +++ b/docs/updating/6-0.md @@ -25,7 +25,7 @@ If you are using Ionic Angular Server, be sure to update that as well: npm install @ionic/angular@6 @ionic/angular-server@6 ``` -3. Remove any usage of `Config.set()`. Instead, set your config in `IonicModule.forRoot()`. See the [Angular Config Documentation](../angular/config) for more examples. +3. Remove any usage of `Config.set()`. Instead, set your config in `IonicModule.forRoot()`. See the [Angular Config Documentation](../developing/config) for more examples. 4. Remove any usage of the `setupConfig` function previously exported from `@ionic/angular`. Set your config in `IonicModule.forRoot()` instead. ### React @@ -79,7 +79,7 @@ setupIonicReact({ Developers must import and call `setupIonicReact` even if they are not setting custom config. ::: -See the [React Config Documentation](../react/config) for more examples. +See the [React Config Documentation](../developing/config) for more examples. 5. Update all controller imports from `@ionic/core` to `@ionic/core/components`. As an example, here is a migration for `menuController`: @@ -139,7 +139,7 @@ module.exports = { See the [Testing section below](#testing) for more information. -5. Remove any usage of the `setupConfig` function previously exported from `@ionic/vue`. Set your config when installing the `IonicVue` plugin instead. See the [Vue Config Documentation](../vue/config) for more examples. +5. Remove any usage of the `setupConfig` function previously exported from `@ionic/vue`. Set your config when installing the `IonicVue` plugin instead. See the [Vue Config Documentation](../developing/config) for more examples. 6. Rename the `IonRouter` type for `useIonRouter` to `UseIonRouterResult`. diff --git a/docs/vue/config.md b/docs/vue/config.md deleted file mode 100644 index 98b453cd612..00000000000 --- a/docs/vue/config.md +++ /dev/null @@ -1,119 +0,0 @@ -# Config - -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. - -## Global Config - -To override the initial Ionic config for the app, provide your config object as an additional parameter when installing the `IonicVue` plugin: - -```tsx -createApp(App).use(IonicVue, { - rippleEffect: false, - mode: 'md', -}); -``` - -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. - -## Per-Platform Config - -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. - -In the following example, we are disabling all animations in our Ionic app only if the app is running in a mobile web browser. -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. - -```tsx -import { IonicVue, isPlatform } from '@ionic/vue'; - -createApp(App).use(IonicVue, { - animated: !isPlatform('mobileweb'), -}); -``` - -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: - -```tsx -import { IonicVue, isPlatform } from '@ionic/vue'; - -const getConfig = () => { - if (isPlatform('hybrid')) { - return { - backButtonText: 'Previous', - tabButtonLayout: 'label-hide', - }; - } - - return { - menuIcon: 'ellipsis-vertical', - }; -}; - -createApp(App).use(IonicVue, getConfig()); -``` - -Finally, this example allows you to accumulate a config object based upon different platform requirements: - -```tsx -import { IonicVue, isPlatform } from '@ionic/vue'; - -const getConfig = () => { - let config = { - animated: false, - }; - - if (isPlatform('iphone')) { - config = { - ...config, - backButtonText: 'Previous', - }; - } - - return config; -}; - -createApp(App).use(IonicVue, getConfig()); -``` - -## Interfaces - -### IonicConfig - -Below are the config options that Ionic uses. - -| Config | Type | Description | -| ------------------------ | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `actionSheetEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-action-sheet`, overriding the default "animation". | -| `actionSheetLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-action-sheet`, overriding the default "animation". | -| `alertEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-alert`, overriding the default "animation". | -| `alertLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-alert`, overriding the default "animation". | -| `animated` | `boolean` | If `true`, Ionic will enable all animations and transitions across the app. | -| `backButtonDefaultHref` | `string` | Overrides the default value for the `defaultHref` property in all `` components. | -| `backButtonIcon` | `string` | Overrides the default icon in all `` components. | -| `backButtonText` | `string` | Overrides the default text in all `` components. | -| `hardwareBackButton` | `boolean` | If `true`, Ionic will respond to the hardware back button in an Android device. | -| `infiniteLoadingSpinner` | `SpinnerTypes` | Overrides the default spinner type in all `` components. | -| `loadingEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-loading`, overriding the default "animation". | -| `loadingLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-loading`, overriding the default "animation". | -| `loadingSpinner` | `SpinnerTypes` | Overrides the default spinner for all `ion-loading` overlays. | -| `menuIcon` | `string` | Overrides the default icon in all `` components. | -| `menuType` | `string` | Overrides the default menu type for all `` components. | -| `modalEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-modal`, overriding the default "animation". | -| `modalLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-modal`, overriding the default "animation". | -| `mode` | `Mode` | The mode determines which platform styles to use for the whole application. | -| `navAnimation` | `AnimationBuilder` | Overrides the default "animation" of all `ion-nav` and `ion-router-outlet` across the whole application. | -| `pickerEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-picker`, overriding the default "animation". | -| `pickerLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-picker`, overriding the default "animation". | -| `platform` | [`PlatformConfig`](/docs/vue/platform#customizing-platform-detection-methods) | Overrides the default platform detection methods. | -| `popoverEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-popover`, overriding the default "animation". | -| `popoverLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-popover`, overriding the default "animation". | -| `refreshingIcon` | `string` | Overrides the default icon in all `` components. | -| `refreshingSpinner` | `SpinnerTypes` | Overrides the default spinner type in all `` components. | -| `sanitizerEnabled` | `boolean` | If `true`, Ionic will enable a basic DOM sanitizer on component properties that accept custom HTML. | -| `spinner` | `SpinnerTypes` | Overrides the default spinner in all `` components. | -| `statusTap` | `boolean` | If `true`, clicking or tapping the status bar will cause the content to scroll to the top. | -| `swipeBackEnabled` | `boolean` | If `true`, Ionic will enable the "swipe-to-go-back" gesture across the application. | -| `tabButtonLayout` | `TabButtonLayout` | Overrides the default "layout" of all `ion-bar-button` across the whole application. | -| `toastDuration` | `number` | Overrides the default `duration` for all `ion-toast` components. | -| `toastEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-toast`, overriding the default "animation". | -| `toastLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-toast`, overriding the default "animation". | -| `toggleOnOffLabels` | `boolean` | Overrides the default `enableOnOffLabels` in all `ion-toggle` components. | diff --git a/docs/vue/platform.md b/docs/vue/platform.md index 11afbcf7c11..74900001f5d 100644 --- a/docs/vue/platform.md +++ b/docs/vue/platform.md @@ -47,7 +47,7 @@ Below is a table listing all the possible platform values along with correspondi ## Customizing Platform Detection Functions -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. +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. ```tsx createApp(App).use(IonicVue, { From 9c4e72a18e677132ea4c9c1e3267f988b7f6240b Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Thu, 26 Jan 2023 20:41:37 +0000 Subject: [PATCH 08/13] update extra link --- docs/theming/platform-styles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/theming/platform-styles.md b/docs/theming/platform-styles.md index e9c49af3263..77d0a5665fc 100644 --- a/docs/theming/platform-styles.md +++ b/docs/theming/platform-styles.md @@ -28,7 +28,7 @@ For example, an app being viewed on an Android platform will use the `md` (Mater ``` -_Note: The **platform** and the **mode** are not the same. The platform can be set to use any mode in the [config](../angular/config.md) of an app._ +_Note: The **platform** and the **mode** are not the same. The platform can be set to use any mode in the [config](../developing/config.md) of an app._ ## Overriding Mode Styles From fc6cec7992d49a8d8e143321367422809ee7e038 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Thu, 26 Jan 2023 20:45:35 +0000 Subject: [PATCH 09/13] docs(config): link to platform guide --- docs/developing/config/per-platform/index.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/developing/config/per-platform/index.md b/docs/developing/config/per-platform/index.md index 5c1d089c35c..7d17299d0f8 100644 --- a/docs/developing/config/per-platform/index.md +++ b/docs/developing/config/per-platform/index.md @@ -12,9 +12,10 @@ import TabItem from '@theme/TabItem'; > - :::note 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. + +See the [Angular Platform Documentation](../angular/platform) for the types of platforms you can detect. ::: ```ts title="app.module.ts" @@ -33,6 +34,10 @@ import { isPlatform, IonicModule } from '@ionic/angular'; +:::note +See the [React Platform Documentation](../react/platform) for the types of platforms you can detect. +::: + ```tsx title="App.tsx" import { isPlatform, setupIonicReact } from '@ionic/react'; @@ -43,6 +48,10 @@ setupIonicReact({ +:::note +See the [Vue Platform Documentation](../vue/platform) for the types of platforms you can detect. +::: + ```ts title="main.ts" import { IonicVue, isPlatform } from '@ionic/vue'; From 5ca3b5075b6de157f6e1b49c72c1249b8d069f28 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Tue, 14 Mar 2023 16:25:48 +0000 Subject: [PATCH 10/13] port to v6 docs --- .../{angular => developing}/config.md | 160 +++--------------- .../developing/config/global/index.md | 67 ++++++++ .../developing/config/per-component/index.md | 143 ++++++++++++++++ .../config/per-platform-fallback/index.md | 79 +++++++++ .../config/per-platform-overrides/index.md | 88 ++++++++++ .../developing/config/per-platform/index.md | 63 +++++++ versioned_docs/version-v6/react/config.md | 116 ------------- versioned_docs/version-v6/vue/config.md | 117 ------------- versioned_sidebars/version-v6-sidebars.json | 16 +- 9 files changed, 468 insertions(+), 381 deletions(-) rename versioned_docs/version-v6/{angular => developing}/config.md (77%) create mode 100644 versioned_docs/version-v6/developing/config/global/index.md create mode 100644 versioned_docs/version-v6/developing/config/per-component/index.md create mode 100644 versioned_docs/version-v6/developing/config/per-platform-fallback/index.md create mode 100644 versioned_docs/version-v6/developing/config/per-platform-overrides/index.md create mode 100644 versioned_docs/version-v6/developing/config/per-platform/index.md delete mode 100644 versioned_docs/version-v6/react/config.md delete mode 100644 versioned_docs/version-v6/vue/config.md diff --git a/versioned_docs/version-v6/angular/config.md b/versioned_docs/version-v6/developing/config.md similarity index 77% rename from versioned_docs/version-v6/angular/config.md rename to versioned_docs/version-v6/developing/config.md index 01844cc067c..4feee0a375b 100644 --- a/versioned_docs/version-v6/angular/config.md +++ b/versioned_docs/version-v6/developing/config.md @@ -2,158 +2,57 @@ title: Config --- - - Config | Ionic Config to Change Component Properties Globally - - - 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. ## Global Config -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. +The available config keys can be found in the [`IonicConfig`](#ionicconfig) interface. -For example, to disable ripple effects and default the mode to Material Design: +The following example disables ripple effects and default the mode to Material Design: -```tsx title="app.module.ts" -import { IonicModule } from '@ionic/angular'; +import GlobalExample from './config/global/index.md'; -@NgModule({ - ... - imports: [ - IonicModule.forRoot({ - rippleEffect: false, - mode: 'md' - }) - ], - ... -}) -``` + ## Per-Component Config 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. -**Not recommended** - -```ts -import { IonicModule } from '@ionic/angular'; - -@NgModule({ - ... - imports: [ - IonicModule.forRoot({ - // Not recommended when your app requires reactive values - backButtonText: 'Go Back' - }) - ], - ... -}) -``` - -**Recommended** - -```html - -``` - -```ts -@Component(...) -class MyComponent { - backButtonText = this.config.get('backButtonText'); - - constructor(private config: Config) { } +import PerComponentExample from './config/per-component/index.md'; - localeChanged(locale: string) { - if (locale === 'es_ES') { - this.backButtonText = 'Devolver'; - } - } - -} -``` + + ## Per-Platform Config 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. -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. - In the following example, we are disabling all animations in our Ionic app only if the app is running in a mobile web browser. -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. - -```tsx -import { isPlatform, IonicModule } from '@ionic/angular'; - -@NgModule({ - ... - imports: [ - IonicModule.forRoot({ - animated: !isPlatform('mobileweb') - }) - ], - ... -}) -``` -**Per-platform config with fallback for unmatched platforms:** +import PerPlatformExample from './config/per-platform/index.md'; -```tsx -import { isPlatform, IonicModule } from '@ionic/angular'; + -const getConfig = () => { - if (isPlatform('hybrid')) { - return { - backButtonText: 'Previous', - tabButtonLayout: 'label-hide' - } - } - return { - menuIcon: 'ellipsis-vertical' - } -} -@NgModule({ - ... - imports: [ - IonicModule.forRoot(getConfig()) - ], - ... -}) -``` +### Fallbacks -**Per-platform config overrides:** +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: -```tsx -import { isPlatform, IonicModule } from '@ionic/angular'; +import PerPlatformFallbackExample from './config/per-platform-overrides/index.md'; -const getConfig = () => { - let config = { - animated: false - }; + - if (isPlatform('iphone')) { - config = { - ...config, - backButtonText: 'Previous' - } - } +### Overrides - return config; -} -@NgModule({ - ... - imports: [ - IonicModule.forRoot(getConfig()) - ], - ... -}) -``` +This final example allows you to accumulate a config object based upon different platform requirements. -## Methods +import PerPlatformOverridesExample from './config/per-platform-fallback/index.md'; + + + +## Reading the Config (Angular) + +Ionic Angular provides a `Config` provider for accessing the Ionic Config. ### get @@ -202,19 +101,6 @@ class AppComponent { | **Description** | Returns a config value as a `number`. Returns `0` if the config is not defined. | | **Signature** | `getNumber(key: string, fallback?: number) => number` | -#### Examples - -```ts -import { Config } from '@ionic/angular'; - -@Component(...) -class AppComponent { - constructor(config: Config) { - const keyboardHeight = config.getNumber('keyboardHeight'); - } -} -``` - ## Interfaces ### IonicConfig @@ -254,5 +140,7 @@ Below are the config options that Ionic uses. | `statusTap` | `boolean` | If `true`, clicking or tapping the status bar will cause the content to scroll to the top. | | `swipeBackEnabled` | `boolean` | If `true`, Ionic will enable the "swipe-to-go-back" gesture across the application. | | `tabButtonLayout` | `TabButtonLayout` | Overrides the default "layout" of all `ion-bar-button` across the whole application. | +| `toastDuration` | `number` | Overrides the default `duration` for all `ion-toast` components. | | `toastEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-toast`, overriding the default "animation". | | `toastLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-toast`, overriding the default "animation". | +| `toggleOnOffLabels` | `boolean` | Overrides the default `enableOnOffLabels` in all `ion-toggle` components. | diff --git a/versioned_docs/version-v6/developing/config/global/index.md b/versioned_docs/version-v6/developing/config/global/index.md new file mode 100644 index 00000000000..bbfbaa83a71 --- /dev/null +++ b/versioned_docs/version-v6/developing/config/global/index.md @@ -0,0 +1,67 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + +```javascript title="example.js" +window.Ionic = { + config: { + rippleEffect: false, + mode: 'md' + } +} +``` + + + +```tsx title="app.module.ts" +import { IonicModule } from '@ionic/angular'; + +@NgModule({ + ... + imports: [ + IonicModule.forRoot({ + rippleEffect: false, + mode: 'md' + }) + ], + ... +}) +``` + + + +The `setupIonicReact` function must be called before rendering any Ionic components (including `IonApp`). +```tsx title="App.tsx" +import { setupIonicReact } from '@ionic/react'; + +setupIonicReact({ + rippleEffect: false, + mode: 'md', +}); +``` + + + +```tsx title="main.ts" + +import { IonicVue } from '@ionic/vue'; +import { createApp } from 'vue'; + +createApp(App).use(IonicVue, { + rippleEffect: false, + mode: 'md', +}); +``` + + \ No newline at end of file diff --git a/versioned_docs/version-v6/developing/config/per-component/index.md b/versioned_docs/version-v6/developing/config/per-component/index.md new file mode 100644 index 00000000000..64b868a70ee --- /dev/null +++ b/versioned_docs/version-v6/developing/config/per-component/index.md @@ -0,0 +1,143 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + +**Not recommended** + +```ts +window.Ionic = { + config: { + // Not recommended when your app requires reactive values + backButtonText: 'Go Back' + } +} +``` + +**Recommended** + +```html + + + +``` + + + +**Not recommended** + +```ts +import { IonicModule } from '@ionic/angular'; + +@NgModule({ + ... + imports: [ + IonicModule.forRoot({ + // Not recommended when your app requires reactive values + backButtonText: 'Go Back' + }) + ], + ... +}); +``` + +**Recommended** + +```html + +``` + +```ts +@Component(...) +class MyComponent { + /** + * The back button text can be updated + * anytime the locale changes. + */ + backButtonText = 'Go Back'; +} +``` + + + +**Not recommended** + +```tsx +import { setupIonicReact } from '@ionic/react'; + +setupIonicReact({ + // Not recommended when your app requires reactive values + backButtonText: 'Go Back' +}); +``` + +**Recommended** + +```tsx +import { useState } from 'react'; +import { IonBackButton } from '@ionic/react'; + +const ExampleComponent = () => { + const [backButtonText, setBackButtonText] = useState('Go Back'); + return ( + {/* + * The back button text can be updated + * anytime the locale changes. + */} + + ) +} +``` + + + +**Not recommended** + +```ts +import { IonicVue } from '@ionic/vue'; +import { createApp } from 'vue'; + + // Not recommended when your app requires reactive values +createApp(App).use(IonicVue, { + backButtonText: 'Go Back' +}); +``` + +**Recommended** + +```html + + + +``` + + \ No newline at end of file diff --git a/versioned_docs/version-v6/developing/config/per-platform-fallback/index.md b/versioned_docs/version-v6/developing/config/per-platform-fallback/index.md new file mode 100644 index 00000000000..02a5f27a3c0 --- /dev/null +++ b/versioned_docs/version-v6/developing/config/per-platform-fallback/index.md @@ -0,0 +1,79 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + +```ts title="app.module.ts" +import { isPlatform, IonicModule } from '@ionic/angular'; + +const getConfig = () => { + if (isPlatform('hybrid')) { + return { + tabButtonLayout: 'label-hide' + } + } + + return { + tabButtonLayout: 'icon-top' + }; +} +@NgModule({ + ... + imports: [ + IonicModule.forRoot(getConfig()) + ], + ... +}); +``` + + + +```tsx title="App.tsx" +import { isPlatform, setupIonicReact } from '@ionic/react'; + +const getConfig = () => { + if (isPlatform('hybrid')) { + return { + tabButtonLayout: 'label-hide' + } + } + + return { + tabButtonLayout: 'icon-top' + }; +}; + +setupIonicReact(getConfig()); + +``` + + + +```ts title="main.ts" +import { IonicVue, isPlatform } from '@ionic/vue'; + +const getConfig = () => { + if (isPlatform('hybrid')) { + return { + tabButtonLayout: 'label-hide' + } + } + + return { + tabButtonLayout: 'icon-top' + }; +}; + +createApp(App).use(IonicVue, getConfig()); +```` + + \ No newline at end of file diff --git a/versioned_docs/version-v6/developing/config/per-platform-overrides/index.md b/versioned_docs/version-v6/developing/config/per-platform-overrides/index.md new file mode 100644 index 00000000000..243cfa9c2fc --- /dev/null +++ b/versioned_docs/version-v6/developing/config/per-platform-overrides/index.md @@ -0,0 +1,88 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + +```ts title="app.module.ts" +import { isPlatform, IonicModule } from '@ionic/angular'; + +const getConfig = () => { + let config = { + animated: false + }; + + if (isPlatform('iphone')) { + config = { + ...config, + backButtonText: 'Previous' + } + } + + return config; +} +@NgModule({ + ... + imports: [ + IonicModule.forRoot(getConfig()) + ], + ... +}); +``` + + + +```tsx title="App.tsx" +import { isPlatform, setupIonicReact } from '@ionic/react'; + +const getConfig = () => { + let config = { + animated: false, + }; + + if (isPlatform('iphone')) { + config = { + ...config, + backButtonText: 'Previous', + }; + } + + return config; +}; + +setupIonicReact(getConfig()); + +``` + + + +```ts title="main.ts" +import { IonicVue, isPlatform } from '@ionic/vue'; + +const getConfig = () => { + let config = { + animated: false, + }; + + if (isPlatform('iphone')) { + config = { + ...config, + backButtonText: 'Previous', + }; + } + + return config; +}; + +createApp(App).use(IonicVue, getConfig()); +```` + + \ No newline at end of file diff --git a/versioned_docs/version-v6/developing/config/per-platform/index.md b/versioned_docs/version-v6/developing/config/per-platform/index.md new file mode 100644 index 00000000000..7d17299d0f8 --- /dev/null +++ b/versioned_docs/version-v6/developing/config/per-platform/index.md @@ -0,0 +1,63 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + +:::note +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. + +See the [Angular Platform Documentation](../angular/platform) for the types of platforms you can detect. +::: + +```ts title="app.module.ts" +import { isPlatform, IonicModule } from '@ionic/angular'; + +@NgModule({ + ... + imports: [ + IonicModule.forRoot({ + animated: !isPlatform('mobileweb') + }) + ], + ... +}) +``` + + + +:::note +See the [React Platform Documentation](../react/platform) for the types of platforms you can detect. +::: + +```tsx title="App.tsx" +import { isPlatform, setupIonicReact } from '@ionic/react'; + +setupIonicReact({ + animated: !isPlatform('mobileweb'), +}); +``` + + + +:::note +See the [Vue Platform Documentation](../vue/platform) for the types of platforms you can detect. +::: + +```ts title="main.ts" +import { IonicVue, isPlatform } from '@ionic/vue'; + +createApp(App).use(IonicVue, { + animated: !isPlatform('mobileweb'), +}); +```` + + \ No newline at end of file diff --git a/versioned_docs/version-v6/react/config.md b/versioned_docs/version-v6/react/config.md deleted file mode 100644 index 6df438834cb..00000000000 --- a/versioned_docs/version-v6/react/config.md +++ /dev/null @@ -1,116 +0,0 @@ -# Config - -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. - -## Global Config - -To override the initial Ionic config for the app, import the `setupIonicReact` function from `@ionic/react`, and call it before you render any Ionic components (including `IonApp`). - -```tsx -setupIonicReact({ - rippleEffect: false, - mode: 'md', -}); -``` - -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. - -## Per-Platform Config - -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. - -In the following example, we are disabling all animations in our Ionic app only if the app is running in a mobile web browser. -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. - -```tsx -import { isPlatform, setupIonicReact } from '@ionic/react'; - -setupIonicReact({ - animated: !isPlatform('mobileweb'), -}); -``` - -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: - -```tsx -import { isPlatform, setupIonicReact } from '@ionic/react'; - -const getConfig = () => { - if (isPlatform('hybrid')) { - return { - backButtonText: 'Previous', - tabButtonLayout: 'label-hide', - }; - } - - return { - menuIcon: 'ellipsis-vertical', - }; -}; - -setupIonicReact(getConfig()); -``` - -Finally, this example allows you to accumulate a config object based upon different platform requirements: - -```tsx -import { isPlatform, setupIonicReact } from '@ionic/react'; - -const getConfig = () => { - let config = { - animated: false, - }; - - if (isPlatform('iphone')) { - config = { - ...config, - backButtonText: 'Previous', - }; - } - - return config; -}; -setupIonicReact(getConfig()); -``` - -## Interfaces - -### IonicConfig - -Below are the config options that Ionic uses. - -| Config | Type | Description | -| ------------------------ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `actionSheetEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-action-sheet`, overriding the default "animation". | -| `actionSheetLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-action-sheet`, overriding the default "animation". | -| `alertEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-alert`, overriding the default "animation". | -| `alertLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-alert`, overriding the default "animation". | -| `animated` | `boolean` | If `true`, Ionic will enable all animations and transitions across the app. | -| `backButtonDefaultHref` | `string` | Overrides the default value for the `defaultHref` property in all `` components. | -| `backButtonIcon` | `string` | Overrides the default icon in all `` components. | -| `backButtonText` | `string` | Overrides the default text in all `` components. | -| `hardwareBackButton` | `boolean` | If `true`, Ionic will respond to the hardware back button in an Android device. | -| `infiniteLoadingSpinner` | `SpinnerTypes` | Overrides the default spinner type in all `` components. | -| `loadingEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-loading`, overriding the default "animation". | -| `loadingLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-loading`, overriding the default "animation". | -| `loadingSpinner` | `SpinnerTypes` | Overrides the default spinner for all `ion-loading` overlays. | -| `menuIcon` | `string` | Overrides the default icon in all `` components. | -| `menuType` | `string` | Overrides the default menu type for all `` components. | -| `modalEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-modal`, overriding the default "animation". | -| `modalLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-modal`, overriding the default "animation". | -| `mode` | `Mode` | The mode determines which platform styles to use for the whole application. | -| `navAnimation` | `AnimationBuilder` | Overrides the default "animation" of all `ion-nav` and `ion-router-outlet` across the whole application. | -| `pickerEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-picker`, overriding the default "animation". | -| `pickerLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-picker`, overriding the default "animation". | -| `platform` | [`PlatformConfig`](/docs/react/platform#customizing-platform-detection-methods) | Overrides the default platform detection methods. | -| `popoverEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-popover`, overriding the default "animation". | -| `popoverLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-popover`, overriding the default "animation". | -| `refreshingIcon` | `string` | Overrides the default icon in all `` components. | -| `refreshingSpinner` | `SpinnerTypes` | Overrides the default spinner type in all `` components. | -| `sanitizerEnabled` | `boolean` | If `true`, Ionic will enable a basic DOM sanitizer on component properties that accept custom HTML. | -| `spinner` | `SpinnerTypes` | Overrides the default spinner in all `` components. | -| `statusTap` | `boolean` | If `true`, clicking or tapping the status bar will cause the content to scroll to the top. | -| `swipeBackEnabled` | `boolean` | If `true`, Ionic will enable the "swipe-to-go-back" gesture across the application. | -| `tabButtonLayout` | `TabButtonLayout` | Overrides the default "layout" of all `ion-bar-button` across the whole application. | -| `toastEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-toast`, overriding the default "animation". | -| `toastLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-toast`, overriding the default "animation". | diff --git a/versioned_docs/version-v6/vue/config.md b/versioned_docs/version-v6/vue/config.md deleted file mode 100644 index a8a3ec5129d..00000000000 --- a/versioned_docs/version-v6/vue/config.md +++ /dev/null @@ -1,117 +0,0 @@ -# Config - -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. - -## Global Config - -To override the initial Ionic config for the app, provide your config object as an additional parameter when installing the `IonicVue` plugin: - -```tsx -createApp(App).use(IonicVue, { - rippleEffect: false, - mode: 'md', -}); -``` - -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. - -## Per-Platform Config - -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. - -In the following example, we are disabling all animations in our Ionic app only if the app is running in a mobile web browser. -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. - -```tsx -import { IonicVue, isPlatform } from '@ionic/vue'; - -createApp(App).use(IonicVue, { - animated: !isPlatform('mobileweb'), -}); -``` - -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: - -```tsx -import { IonicVue, isPlatform } from '@ionic/vue'; - -const getConfig = () => { - if (isPlatform('hybrid')) { - return { - backButtonText: 'Previous', - tabButtonLayout: 'label-hide', - }; - } - - return { - menuIcon: 'ellipsis-vertical', - }; -}; - -createApp(App).use(IonicVue, getConfig()); -``` - -Finally, this example allows you to accumulate a config object based upon different platform requirements: - -```tsx -import { IonicVue, isPlatform } from '@ionic/vue'; - -const getConfig = () => { - let config = { - animated: false, - }; - - if (isPlatform('iphone')) { - config = { - ...config, - backButtonText: 'Previous', - }; - } - - return config; -}; - -createApp(App).use(IonicVue, getConfig()); -``` - -## Interfaces - -### IonicConfig - -Below are the config options that Ionic uses. - -| Config | Type | Description | -| ------------------------ | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `actionSheetEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-action-sheet`, overriding the default "animation". | -| `actionSheetLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-action-sheet`, overriding the default "animation". | -| `alertEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-alert`, overriding the default "animation". | -| `alertLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-alert`, overriding the default "animation". | -| `animated` | `boolean` | If `true`, Ionic will enable all animations and transitions across the app. | -| `backButtonDefaultHref` | `string` | Overrides the default value for the `defaultHref` property in all `` components. | -| `backButtonIcon` | `string` | Overrides the default icon in all `` components. | -| `backButtonText` | `string` | Overrides the default text in all `` components. | -| `hardwareBackButton` | `boolean` | If `true`, Ionic will respond to the hardware back button in an Android device. | -| `infiniteLoadingSpinner` | `SpinnerTypes` | Overrides the default spinner type in all `` components. | -| `loadingEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-loading`, overriding the default "animation". | -| `loadingLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-loading`, overriding the default "animation". | -| `loadingSpinner` | `SpinnerTypes` | Overrides the default spinner for all `ion-loading` overlays. | -| `menuIcon` | `string` | Overrides the default icon in all `` components. | -| `menuType` | `string` | Overrides the default menu type for all `` components. | -| `modalEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-modal`, overriding the default "animation". | -| `modalLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-modal`, overriding the default "animation". | -| `mode` | `Mode` | The mode determines which platform styles to use for the whole application. | -| `navAnimation` | `AnimationBuilder` | Overrides the default "animation" of all `ion-nav` and `ion-router-outlet` across the whole application. | -| `pickerEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-picker`, overriding the default "animation". | -| `pickerLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-picker`, overriding the default "animation". | -| `platform` | [`PlatformConfig`](/docs/vue/platform#customizing-platform-detection-methods) | Overrides the default platform detection methods. | -| `popoverEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-popover`, overriding the default "animation". | -| `popoverLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-popover`, overriding the default "animation". | -| `refreshingIcon` | `string` | Overrides the default icon in all `` components. | -| `refreshingSpinner` | `SpinnerTypes` | Overrides the default spinner type in all `` components. | -| `sanitizerEnabled` | `boolean` | If `true`, Ionic will enable a basic DOM sanitizer on component properties that accept custom HTML. | -| `spinner` | `SpinnerTypes` | Overrides the default spinner in all `` components. | -| `statusTap` | `boolean` | If `true`, clicking or tapping the status bar will cause the content to scroll to the top. | -| `swipeBackEnabled` | `boolean` | If `true`, Ionic will enable the "swipe-to-go-back" gesture across the application. | -| `tabButtonLayout` | `TabButtonLayout` | Overrides the default "layout" of all `ion-bar-button` across the whole application. | -| `toastEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-toast`, overriding the default "animation". | -| `toastLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-toast`, overriding the default "animation". | diff --git a/versioned_sidebars/version-v6-sidebars.json b/versioned_sidebars/version-v6-sidebars.json index 3a00763e1bb..ca89fb36f8a 100644 --- a/versioned_sidebars/version-v6-sidebars.json +++ b/versioned_sidebars/version-v6-sidebars.json @@ -72,6 +72,10 @@ { "type": "doc", "id": "version-v6/developing/keyboard" + }, + { + "type": "doc", + "id": "version-v6/developing/config" } ], "collapsible": true @@ -210,10 +214,6 @@ "type": "doc", "id": "version-v6/angular/slides" }, - { - "type": "doc", - "id": "version-v6/angular/config" - }, { "type": "doc", "id": "version-v6/angular/platform" @@ -306,10 +306,6 @@ "type": "doc", "id": "version-v6/react/slides" }, - { - "type": "doc", - "id": "version-v6/react/config" - }, { "type": "doc", "id": "version-v6/react/platform" @@ -410,10 +406,6 @@ "type": "doc", "id": "version-v6/vue/utility-functions" }, - { - "type": "doc", - "id": "version-v6/vue/config" - }, { "type": "doc", "id": "version-v6/vue/platform" From c3b97e32c913a7c38951324d54def731549bc40c Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Tue, 14 Mar 2023 16:37:04 +0000 Subject: [PATCH 11/13] add note on enableHTMLContent --- docs/developing/config.md | 1 + docs/techniques/security.md | 4 ++++ versioned_docs/version-v6/developing/config.md | 1 + versioned_docs/version-v6/techniques/security.md | 4 ++++ 4 files changed, 10 insertions(+) diff --git a/docs/developing/config.md b/docs/developing/config.md index 38cc071f341..556185f86a4 100644 --- a/docs/developing/config.md +++ b/docs/developing/config.md @@ -117,6 +117,7 @@ Below are the config options that Ionic uses. | `backButtonDefaultHref` | `string` | Overrides the default value for the `defaultHref` property in all `` components. | | `backButtonIcon` | `string` | Overrides the default icon in all `` components. | | `backButtonText` | `string` | Overrides the default text in all `` components. | +| `enableHTMLContent` | `boolean` | Relevant Components: `ion-alert`, `ion-infinite-scroll-content`, `ion-loading`, `ion-refresher-content`, `ion-toast`. If `false`, all `innerHTML` usage will be disabled in Ionic, and custom HTML will not be usable in the relevant components. `innerHTML` usage is enabled by default. | | `hardwareBackButton` | `boolean` | If `true`, Ionic will respond to the hardware back button in an Android device. | | `infiniteLoadingSpinner` | `SpinnerTypes` | Overrides the default spinner type in all `` components. | | `loadingEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-loading`, overriding the default "animation". | diff --git a/docs/techniques/security.md b/docs/techniques/security.md index 7a5d8513256..422d643c6e4 100644 --- a/docs/techniques/security.md +++ b/docs/techniques/security.md @@ -62,6 +62,10 @@ Vue does not provide any type of sanitizing methods built in. It is recommended To learn more about the security recommendations for binding to directives such as `v-html`, see the [Vue Syntax Guide](https://vuejs.org/v2/guide/syntax.html#Raw-HTML). +## Disabling Custom HTML Parsing via `innerHTML` + +`ion-alert`, `ion-infinite-scroll-content`, `ion-loading`, `ion-refresher-content`, and `ion-toast` accept custom HTML as strings for certain properties. These strings are added to the DOM using `innerHTML` and must be properly sanitized by the developer. Developers can disable this functionality by setting `enableHTMLContent: false` in the [IonicConfig](../developing/config#ionicconfig). When `enableHTMLContent` is `false`, the values passed to the affected components will always be interpreted as strings. + ## Ejecting from the built-in sanitizer For developers who wish to add complex HTML to components such as `ion-toast`, they will need to eject from the sanitizer that is built into Ionic Framework. Developers can either disable the sanitizer across their entire app or bypass it on a case-by-case basis. diff --git a/versioned_docs/version-v6/developing/config.md b/versioned_docs/version-v6/developing/config.md index 4feee0a375b..4a702c3c041 100644 --- a/versioned_docs/version-v6/developing/config.md +++ b/versioned_docs/version-v6/developing/config.md @@ -117,6 +117,7 @@ Below are the config options that Ionic uses. | `backButtonDefaultHref` | `string` | Overrides the default value for the `defaultHref` property in all `` components. | | `backButtonIcon` | `string` | Overrides the default icon in all `` components. | | `backButtonText` | `string` | Overrides the default text in all `` components. | +| `enableHTMLContent` | `boolean` | Relevant Components: `ion-alert`, `ion-infinite-scroll-content`, `ion-loading`, `ion-refresher-content`, `ion-toast`. If `false`, all `innerHTML` usage will be disabled in Ionic, and custom HTML will not be usable in the relevant components. `innerHTML` usage is enabled by default. | | `hardwareBackButton` | `boolean` | If `true`, Ionic will respond to the hardware back button in an Android device. | | `infiniteLoadingSpinner` | `SpinnerTypes` | Overrides the default spinner type in all `` components. | | `loadingEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-loading`, overriding the default "animation". | diff --git a/versioned_docs/version-v6/techniques/security.md b/versioned_docs/version-v6/techniques/security.md index 7a5d8513256..422d643c6e4 100644 --- a/versioned_docs/version-v6/techniques/security.md +++ b/versioned_docs/version-v6/techniques/security.md @@ -62,6 +62,10 @@ Vue does not provide any type of sanitizing methods built in. It is recommended To learn more about the security recommendations for binding to directives such as `v-html`, see the [Vue Syntax Guide](https://vuejs.org/v2/guide/syntax.html#Raw-HTML). +## Disabling Custom HTML Parsing via `innerHTML` + +`ion-alert`, `ion-infinite-scroll-content`, `ion-loading`, `ion-refresher-content`, and `ion-toast` accept custom HTML as strings for certain properties. These strings are added to the DOM using `innerHTML` and must be properly sanitized by the developer. Developers can disable this functionality by setting `enableHTMLContent: false` in the [IonicConfig](../developing/config#ionicconfig). When `enableHTMLContent` is `false`, the values passed to the affected components will always be interpreted as strings. + ## Ejecting from the built-in sanitizer For developers who wish to add complex HTML to components such as `ion-toast`, they will need to eject from the sanitizer that is built into Ionic Framework. Developers can either disable the sanitizer across their entire app or bypass it on a case-by-case basis. From 08a0c13baa4ec2b72a31cf7eae926c3dad68d278 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Wed, 22 Mar 2023 18:14:38 +0000 Subject: [PATCH 12/13] update config name --- docs/developing/config.md | 2 +- docs/techniques/security.md | 2 +- versioned_docs/version-v6/developing/config.md | 2 +- versioned_docs/version-v6/techniques/security.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/developing/config.md b/docs/developing/config.md index 556185f86a4..39cd0f1e632 100644 --- a/docs/developing/config.md +++ b/docs/developing/config.md @@ -117,7 +117,7 @@ Below are the config options that Ionic uses. | `backButtonDefaultHref` | `string` | Overrides the default value for the `defaultHref` property in all `` components. | | `backButtonIcon` | `string` | Overrides the default icon in all `` components. | | `backButtonText` | `string` | Overrides the default text in all `` components. | -| `enableHTMLContent` | `boolean` | Relevant Components: `ion-alert`, `ion-infinite-scroll-content`, `ion-loading`, `ion-refresher-content`, `ion-toast`. If `false`, all `innerHTML` usage will be disabled in Ionic, and custom HTML will not be usable in the relevant components. `innerHTML` usage is enabled by default. | +| `innerHTMLTemplatesEnabled` | `boolean` | Relevant Components: `ion-alert`, `ion-infinite-scroll-content`, `ion-loading`, `ion-refresher-content`, `ion-toast`. If `false`, all `innerHTML` usage will be disabled in Ionic, and custom HTML will not be usable in the relevant components. `innerHTML` usage is enabled by default. | | `hardwareBackButton` | `boolean` | If `true`, Ionic will respond to the hardware back button in an Android device. | | `infiniteLoadingSpinner` | `SpinnerTypes` | Overrides the default spinner type in all `` components. | | `loadingEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-loading`, overriding the default "animation". | diff --git a/docs/techniques/security.md b/docs/techniques/security.md index 14c78ab5cfe..e500e83939f 100644 --- a/docs/techniques/security.md +++ b/docs/techniques/security.md @@ -64,7 +64,7 @@ To learn more about the security recommendations for binding to directives such ## Disabling Custom HTML Parsing via `innerHTML` -`ion-alert`, `ion-infinite-scroll-content`, `ion-loading`, `ion-refresher-content`, and `ion-toast` accept custom HTML as strings for certain properties. These strings are added to the DOM using `innerHTML` and must be properly sanitized by the developer. Developers can disable this functionality by setting `enableHTMLContent: false` in the [IonicConfig](../developing/config#ionicconfig). When `enableHTMLContent` is `false`, the values passed to the affected components will always be interpreted as strings. +`ion-alert`, `ion-infinite-scroll-content`, `ion-loading`, `ion-refresher-content`, and `ion-toast` accept custom HTML as strings for certain properties. These strings are added to the DOM using `innerHTML` and must be properly sanitized by the developer. Developers can disable this functionality by setting `innerHTMLTemplatesEnabled: false` in the [IonicConfig](../developing/config#ionicconfig). When `innerHTMLTemplatesEnabled` is `false`, the values passed to the affected components will always be interpreted as strings. ## Ejecting from the built-in sanitizer diff --git a/versioned_docs/version-v6/developing/config.md b/versioned_docs/version-v6/developing/config.md index 4a702c3c041..662e790864d 100644 --- a/versioned_docs/version-v6/developing/config.md +++ b/versioned_docs/version-v6/developing/config.md @@ -117,7 +117,7 @@ Below are the config options that Ionic uses. | `backButtonDefaultHref` | `string` | Overrides the default value for the `defaultHref` property in all `` components. | | `backButtonIcon` | `string` | Overrides the default icon in all `` components. | | `backButtonText` | `string` | Overrides the default text in all `` components. | -| `enableHTMLContent` | `boolean` | Relevant Components: `ion-alert`, `ion-infinite-scroll-content`, `ion-loading`, `ion-refresher-content`, `ion-toast`. If `false`, all `innerHTML` usage will be disabled in Ionic, and custom HTML will not be usable in the relevant components. `innerHTML` usage is enabled by default. | +| `innerHTMLTemplatesEnabled` | `boolean` | Relevant Components: `ion-alert`, `ion-infinite-scroll-content`, `ion-loading`, `ion-refresher-content`, `ion-toast`. If `false`, all `innerHTML` usage will be disabled in Ionic, and custom HTML will not be usable in the relevant components. `innerHTML` usage is enabled by default. | | `hardwareBackButton` | `boolean` | If `true`, Ionic will respond to the hardware back button in an Android device. | | `infiniteLoadingSpinner` | `SpinnerTypes` | Overrides the default spinner type in all `` components. | | `loadingEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-loading`, overriding the default "animation". | diff --git a/versioned_docs/version-v6/techniques/security.md b/versioned_docs/version-v6/techniques/security.md index 14c78ab5cfe..e500e83939f 100644 --- a/versioned_docs/version-v6/techniques/security.md +++ b/versioned_docs/version-v6/techniques/security.md @@ -64,7 +64,7 @@ To learn more about the security recommendations for binding to directives such ## Disabling Custom HTML Parsing via `innerHTML` -`ion-alert`, `ion-infinite-scroll-content`, `ion-loading`, `ion-refresher-content`, and `ion-toast` accept custom HTML as strings for certain properties. These strings are added to the DOM using `innerHTML` and must be properly sanitized by the developer. Developers can disable this functionality by setting `enableHTMLContent: false` in the [IonicConfig](../developing/config#ionicconfig). When `enableHTMLContent` is `false`, the values passed to the affected components will always be interpreted as strings. +`ion-alert`, `ion-infinite-scroll-content`, `ion-loading`, `ion-refresher-content`, and `ion-toast` accept custom HTML as strings for certain properties. These strings are added to the DOM using `innerHTML` and must be properly sanitized by the developer. Developers can disable this functionality by setting `innerHTMLTemplatesEnabled: false` in the [IonicConfig](../developing/config#ionicconfig). When `innerHTMLTemplatesEnabled` is `false`, the values passed to the affected components will always be interpreted as strings. ## Ejecting from the built-in sanitizer From d3206ceae3477b005905f9407aff67514ff89fea Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Wed, 22 Mar 2023 18:17:57 +0000 Subject: [PATCH 13/13] clarify copy --- docs/developing/config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developing/config.md b/docs/developing/config.md index 39cd0f1e632..c9796a19bee 100644 --- a/docs/developing/config.md +++ b/docs/developing/config.md @@ -117,7 +117,7 @@ Below are the config options that Ionic uses. | `backButtonDefaultHref` | `string` | Overrides the default value for the `defaultHref` property in all `` components. | | `backButtonIcon` | `string` | Overrides the default icon in all `` components. | | `backButtonText` | `string` | Overrides the default text in all `` components. | -| `innerHTMLTemplatesEnabled` | `boolean` | Relevant Components: `ion-alert`, `ion-infinite-scroll-content`, `ion-loading`, `ion-refresher-content`, `ion-toast`. If `false`, all `innerHTML` usage will be disabled in Ionic, and custom HTML will not be usable in the relevant components. `innerHTML` usage is enabled by default. | +| `innerHTMLTemplatesEnabled` | `boolean` | Relevant Components: `ion-alert`, `ion-infinite-scroll-content`, `ion-loading`, `ion-refresher-content`, `ion-toast`. If `false`, custom HTML passed to the relevant components will be parsed as a string instead of HTML. Defaults to `true`. | | `hardwareBackButton` | `boolean` | If `true`, Ionic will respond to the hardware back button in an Android device. | | `infiniteLoadingSpinner` | `SpinnerTypes` | Overrides the default spinner type in all `` components. | | `loadingEnter` | `AnimationBuilder` | Provides a custom enter animation for all `ion-loading`, overriding the default "animation". |