Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(config): move framework config guides to unified config guide #2727

Merged
merged 10 commits into from
Mar 22, 2023
Merged

docs(config): move framework config guides to unified config guide #2727

Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
f9596a2
docs(config): create consolidated config page
liamdebeasi Jan 26, 2023
cbe176b
docs(config): add per-component config
liamdebeasi Jan 26, 2023
85f61b4
docs(config): add per-platform example
liamdebeasi Jan 26, 2023
3751c05
docs(config): add fallbacks and overrides
liamdebeasi Jan 26, 2023
a24499d
docs(config): add angular config read
liamdebeasi Jan 26, 2023
274c6e9
docs(): update links to config page
liamdebeasi Jan 26, 2023
99d9e6a
chore(): update links
liamdebeasi Jan 26, 2023
9c4e72a
update extra link
liamdebeasi Jan 26, 2023
fc6cec7
docs(config): link to platform guide
liamdebeasi Jan 26, 2023
5ca3b50
port to v6 docs
liamdebeasi Mar 14, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/angular/platform.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down
158 changes: 22 additions & 136 deletions docs/angular/config.md → docs/developing/config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,158 +2,57 @@
title: Config
liamdebeasi marked this conversation as resolved.
Show resolved Hide resolved
---

<head>
<title>Config | Ionic Config to Change Component Properties Globally</title>
<meta
name="description"
content="Ionic Config provides a way to change the properties of components globally across an app. Config can set the app mode, tab button layout, animations, and more."
/>
</head>

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'
})
],
...
})
```
<GlobalExample />

## 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
<ion-back-button [text]="backButtonText"></ion-back-button>
```

```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';
}
}

}
```
<PerComponentExample />


## 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';
<PerPlatformExample />

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
};
<PerPlatformFallbackExample />

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

<PerPlatformOverridesExample />

## Reading the Config (Angular)

Ionic Angular provides a `Config` provider for accessing the Ionic Config.

### get

Expand Down Expand Up @@ -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');
}
}
```

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was this example removed intentionally? I know the info is fairly redundant, but it seems strange to have an example on the other two but not this one. Maybe one example for the whole provider would be easier?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was moved to config#getnumber. React and Vue currently do not provide this kind of API which is why I made it Angular-only.

## Interfaces

### IonicConfig
Expand Down
67 changes: 67 additions & 0 deletions docs/developing/config/global/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs
groupId="global-config"
defaultValue="javascript"
values={[
{ value: 'javascript', label: 'JavaScript' },
{ value: 'angular', label: 'Angular' },
{ value: 'react', label: 'React' },
{ value: 'vue', label: 'Vue' },
]}
>
<TabItem value="javascript">

```javascript title="example.js"
window.Ionic = {
config: {
rippleEffect: false,
mode: 'md'
}
}
```
</TabItem>
<TabItem value="angular">

```tsx title="app.module.ts"
import { IonicModule } from '@ionic/angular';

@NgModule({
...
imports: [
IonicModule.forRoot({
rippleEffect: false,
mode: 'md'
})
],
...
})
```
</TabItem>
<TabItem value="react">

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',
});
```
</TabItem>
<TabItem value="vue">

```tsx title="main.ts"

import { IonicVue } from '@ionic/vue';
import { createApp } from 'vue';

createApp(App).use(IonicVue, {
rippleEffect: false,
mode: 'md',
});
```
</TabItem>
</Tabs>
Loading