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/versioned_docs/version-v6/angular/config.md b/docs/developing/config.md similarity index 77% rename from versioned_docs/version-v6/angular/config.md rename to docs/developing/config.md index 01844cc067c..38cc071f341 100644 --- a/versioned_docs/version-v6/angular/config.md +++ b/docs/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 '@site/docs/developing/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 '@site/docs/developing/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 '@site/docs/developing/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 '@site/docs/developing/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 '@site/docs/developing/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/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/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 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 diff --git a/docs/developing/config/per-platform/index.md b/docs/developing/config/per-platform/index.md new file mode 100644 index 00000000000..7d17299d0f8 --- /dev/null +++ b/docs/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/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..77d0a5665fc 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 | | --------- | ----- | -------------------------------------------------------------------------------------------------------------------------------- | @@ -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 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, { diff --git a/sidebars.js b/sidebars.js index e9610cbdb0d..2e7f6c563f1 100644 --- a/sidebars.js +++ b/sidebars.js @@ -30,6 +30,7 @@ module.exports = { 'developing/tips', 'developing/hardware-back-button', 'developing/keyboard', + 'developing/config' ], }, { @@ -87,7 +88,6 @@ module.exports = { 'angular/navigation', 'angular/virtual-scroll', 'angular/slides', - 'angular/config', 'angular/platform', 'angular/testing', 'angular/storage', @@ -121,7 +121,6 @@ module.exports = { 'react/navigation', 'react/virtual-scroll', 'react/slides', - 'react/config', 'react/platform', 'react/pwa', 'react/overlays', @@ -156,7 +155,6 @@ module.exports = { 'vue/virtual-scroll', 'vue/slides', 'vue/utility-functions', - 'vue/config', 'vue/platform', 'vue/pwa', 'vue/storage', diff --git a/docs/angular/config.md b/versioned_docs/version-v6/developing/config.md similarity index 78% rename from docs/angular/config.md rename to versioned_docs/version-v6/developing/config.md index 9e6849a3729..4feee0a375b 100644 --- a/docs/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 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"