docs(config): add examples on overriding config per-platform

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",
 

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".
+| `toastLeave`             | `AnimationBuilder` | Provides a custom leave animation for all `ion-toast`, overriding the default "animation".

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                              |
 | ------------- | -------------------------------------    |

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'
 });
-
-<IonApp>
-  // more components
-</IonApp>
 ```
 
 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".
+| `toastLeave`             | `AnimationBuilder` | Provides a custom leave animation for all `ion-toast`, overriding the default "animation".

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                          |