diff --git a/src/assets/locales/en/messages.json b/src/assets/locales/en/messages.json index 63c2aa7fce7..75ab21f0d46 100644 --- a/src/assets/locales/en/messages.json +++ b/src/assets/locales/en/messages.json @@ -78,7 +78,7 @@ "menu-react-lifecycle": "Lifecycle", "menu-react-navigation": "Navigation/Routing", "menu-react-config": "Config", - "menu-react-platform": "Platform Utils", + "menu-react-platform": "Platform", "menu-react-pwa": "Progressive Web Apps", "menu-react-testing": "Testing", diff --git a/src/pages/angular/config.md b/src/pages/angular/config.md index 23a033e1d78..25b41e5892c 100755 --- a/src/pages/angular/config.md +++ b/src/pages/angular/config.md @@ -12,9 +12,7 @@ contributors: 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. -## Usage - -### Global +## Global Config To override the initial Ionic config for the app, provide a config in `IonicModule.forRoot` in the `app.module.ts` file. @@ -38,12 +36,12 @@ import { IonicModule } from '@ionic/angular'; 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. -### By Component +## Per-Component Config Ionic Config is not reactive, so it is recommended to use a component's properties when you want to override its default behavior rather than set its config globally. ```typescript -import { createAnimation, IonicModule } from '@ionic/angular'; +import { IonicModule } from '@ionic/angular'; @NgModule({ ... @@ -66,6 +64,89 @@ This will set the default text for `ion-back-button` to `Go Back`. However, if y In this example we have used our `ion-back-button` in such a way that the text can be dynamically updated if there were to be a change that warranted it, such as a language or locale change. The `getBackButtonText` method would be responsible for returning the correct text. +## 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#platforms) for a list of possible values. + + +```typescript +import { isPlatform, IonicModule } from '@ionic/angular'; + +@NgModule({ + ... + imports: [ + BrowserModule, + IonicModule.forRoot({ + animated: !isPlatform('mobileweb') + }), + AppRoutingModule + ], + ... +}) +``` + +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: + +```typescript +import { isPlatform, IonicModule } from '@ionic/angular'; + +const getConfig = () => { + if (isPlatform('hybrid')) { + return { + backButtonText: 'Previous', + tabButtonLayout: 'label-hide' + } + } + + return { + menuIcon: 'ellipsis-vertical' + } +} +@NgModule({ + ... + imports: [ + BrowserModule, + IonicModule.forRoot(getConfig()), + AppRoutingModule + ], + ... +}) +``` + +Finally, this example allows you to accumulate a config object based upon different platform requirements: + +```typescript +import { isPlatform, IonicModule } from '@ionic/angular'; + +const getConfig = () => { + let config = { + animated: false + }; + + if (isPlatform('iphone')) { + config = { + ...config, + backButtonText: 'Previous' + } + } + + return config; +} +@NgModule({ + ... + imports: [ + BrowserModule, + IonicModule.forRoot(getConfig()), + AppRoutingModule + ], + ... +}) +``` ## Config Options @@ -103,4 +184,4 @@ Below is a list of config options that Ionic uses. | `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". \ No newline at end of file +| `toastLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-toast`, overriding the default "animation". diff --git a/src/pages/angular/platform.md b/src/pages/angular/platform.md index 09ca9acab97..1df71a7d108 100755 --- a/src/pages/angular/platform.md +++ b/src/pages/angular/platform.md @@ -39,7 +39,7 @@ Depending on the platform the user is on, `is(platformName)` will return true or #### Platforms -Below is a table listing all the possible `Platforms` values along with corresponding descriptions. +Below is a table listing all the possible platform values along with corresponding descriptions. | Platform Name | Description | | ------------- | ------------------------------------- | diff --git a/src/pages/react/config.md b/src/pages/react/config.md index 395724c5e05..09f87dae98b 100644 --- a/src/pages/react/config.md +++ b/src/pages/react/config.md @@ -9,23 +9,79 @@ nextUrl: '/docs/react/platform' 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. -## Usage +## Global Config -To override the initial Ionic config for the app, import the `setupConfig` method from `@ionic/react` and call it before you render any Ionic components: +To override the initial Ionic config for the app, import the `setupConfig` method from `@ionic/react`, and call it before you render any Ionic components (including `IonApp`). ```typescript setupConfig({ rippleEffect: false, mode: 'md' }); - - - // more components - ``` 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#platforms) for a list of possible values. + + +```typescript +import { isPlatform, setupConfig } from '@ionic/react'; + +setupConfig({ + 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: + +```typescript +import { isPlatform, setupConfig } from '@ionic/react'; + +const getConfig = () => { + if (isPlatform('hybrid')) { + return { + backButtonText: 'Previous', + tabButtonLayout: 'label-hide' + } + } + + return { + menuIcon: 'ellipsis-vertical' + } +} + +setupConfig(getConfig()); +``` + +Finally, this example allows you to accumulate a config object based upon different platform requirements: + + +```typescript +import { isPlatform, setupConfig } from '@ionic/react'; + +const getConfig = () => { + let config = { + animated: false + }; + + if (isPlatform('iphone')) { + config = { + ...config, + backButtonText: 'Previous' + } + } + + return config; +} +setupConfig(getConfig()); +``` + ## Config Options Below is a list of config options that Ionic uses. @@ -62,4 +118,4 @@ Below is a list of config options that Ionic uses. | `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". \ No newline at end of file +| `toastLeave` | `AnimationBuilder` | Provides a custom leave animation for all `ion-toast`, overriding the default "animation". diff --git a/src/pages/react/platform.md b/src/pages/react/platform.md index 9f1e7f2e0a5..819d047a741 100644 --- a/src/pages/react/platform.md +++ b/src/pages/react/platform.md @@ -5,7 +5,7 @@ nextText: 'Progressive Web Apps in React' nextUrl: '/docs/react/pwa' --- -# Platform Utils +# Platform ## isPlatform @@ -30,3 +30,24 @@ getPlatforms(); // returns ["iphone", "ios", "mobile", "mobileweb"] from an iPho ``` Depending on what device you are on, `getPlatforms` can return multiple values. Each possible value is a hierarchy of platforms. For example, on an iPhone, it would return mobile, ios, and iphone. + +## Platforms + +Below is a table listing all the possible platform values along with corresponding descriptions. + +| Platform Name | Description | +|---------------|------------------------------------------| +| android | a device running Android | +| capacitor | a device running Capacitor | +| cordova | a device running Cordova | +| desktop | a desktop device | +| electron | a desktop device running Electron | +| hybrid | a device running Capacitor or Cordova | +| ios | a device running iOS | +| ipad | an iPad device | +| iphone | an iPhone device | +| mobile | a mobile device | +| mobileweb | a web browser running in a mobile device | +| phablet | a phablet device | +| pwa | a PWA app | +| tablet | a tablet device |