npm package: @pxlwidgets/ionic4-toolkit
Description: Useful tools for Ionic Framework v4 projects.
Latest version: 0.0.8

# Ionic 4 Toolkit

Useful tools for Ionic Framework v4 projects.

## Features
- [`ExitOnBackButton`](#ExitOnBackButton) decorator + service for page components.
- [`Theme`](#Theme) decorator + service for app components / page components.
- [`NativeBackButtonService`](#NativeBackButtonService) service for Android back button.
- [`InputFocusService`](#InputFocusService) service for forms.


## Installation
`npm i @pxlwidgets/ionic4-toolkit`



## ExitOnBackButton decorator
<a name="ExitOnBackButton"></a>

> **NOTE**<br>
> The [`NativeBackButtonService`](#NativeBackButtonService) might be more useful for some use-cases.
> Make sure to check that service out as well before using the ExitOnBackButton decorator.

A page component decorator which sets whether pressing the back button on Android will exit the app.

Add the `@ExitOnBackButton()` decorator to all page components which you want to be able to exit the app from.

To enable the decorator functionality:
- Add the `ExitOnBackButtonService` to the `providers` array in your module. (e.g. in your main `app.module.ts`)
- Include the `ExitOnBackButtonService` in your component (e.g. in your main `app.component.ts`).
- Initialize it using the `initialize()` method.
- Optionally, add one or more pages to the `ignoredPages` property when calling `initialize()`.
  This prevents the app from closing when a page with the `ExitOnBackButton` decorator is loaded inside another page. 
  This is especially useful for tab pages.

## Example

`app.component.ts`
```typescript
import { Component } from '@angular/core';
import { ExitOnBackButtonService } from '@pxlwidgets/ionic4-toolkit/services';

@Component({
    selector: 'app-root',
    templateUrl: 'app.component.html'
})
export class AppComponent {
    
    constructor(private exitOnBackButtonService: ExitOnBackButtonService) {
        this.exitOnBackButtonService.initialize({
            // ignoredPages: [TabsPage]
        });
    }
}
```

`my-page.page.ts`
```typescript
import { Component } from '@angular/core';
import { ExitOnBackButton } from '@pxlwidgets/ionic4-toolkit/decorators';

@Component({
    selector: 'app-my-page',
    templateUrl: 'my-page.page.html',
    styleUrls: ['my-page.page.scss']
})
@ExitOnBackButton()
export class MyPage {
}
```


## Theme decorator
<a name="Theme"></a>
A component decorator which sets which theme to use for the status bar (and Android navigation bar).

This decorator depends on the Ionic native [`status-bar`](https://ionicframework.com/docs/native/status-bar) plugin and/or [`navigationbar-color`](https://www.npmjs.com/package/cordova-plugin-navigationbar-color) Cordova plugin.

Add the `@Theme()` decorator to your main app component (`app.component.ts`) to set the default theme.
You can also add the `@Theme()` decorator to any other pages of your app, in case you want to use a different theme for that page(s).

For example: If you want to display a different status bar theme on your login page, you can set a default theme and override it in your `LoginPage` component.

To enable the decorator functionality:
- Add the `ThemeService` to the `providers` array in your module. (e.g. in your main `app.module.ts`)
- Include the `ThemeService` in your component (e.g. in your main `app.component.ts`).
- Initialize it using the `initialize()` method, passing the component which contains the default theme in the `appComponent` property.
- Optionally, add one or more pages to the `ignoredPages` property when calling `initialize()`.
  This prevents the wrong theme from being applied when a page with the `Theme` decorator is loaded inside another page. 
  This is especially useful for tab pages.

## Example

`app.component.ts`
```typescript
import { Component } from '@angular/core';
import { Theme, STATUS_BAR_STYLE } from '@pxlwidgets/ionic4-toolkit/decorators';
import { ThemeService } from '@pxlwidgets/ionic4-toolkit/services';

@Component({
    selector: 'app-root',
    templateUrl: 'app.component.html'
})
@Theme({
    navigationBarColor: '#FFFFFF',
    statusBarColor: '#DDDDDD',
    statusBarStyle: STATUS_BAR_STYLE.styleDefault
})
export class AppComponent {
    constructor(private themeService: ThemeService) {
        this.themeService.initialize({
            appComponent: this,
            // ignoredPages: [TabsPage]
        });
    }
}
```

`login.page.ts`
```typescript
import { Component } from '@angular/core';
import { Theme, STATUS_BAR_STYLE } from '@pxlwidgets/ionic4-toolkit/decorators';

@Component({
    selector: 'app-login',
    templateUrl: 'login.page.html',
    styleUrls: ['login.page.scss']
})
@Theme({
    navigationBarColor: '#FF6600',
    statusBarColor: '#CC4E00',
    statusBarStyle: STATUS_BAR_STYLE.styleLightContent
})
export class MyPage {
}
```




## NativeBackButton service
<a name="NativeBackButtonService"></a>
A service that overrides the default (Android) back button listener.
When the back button is pressed, it will execute one of below, in order:
- Close the `ion-menu` if (it exists and) is open.
- 'press' the `ion-back-button` if it exists on the current page.

To enable the service:
- Add the `NativeBackButtonService` to the `providers` array in your module. (e.g. in your main `app.module.ts`)
- Include the `NativeBackButtonService` in your component (e.g. in your main `app.component.ts`).
- Initialize it using the `initialize()` method.


## Example

`app.component.ts`
```typescript
import { Component } from '@angular/core';
import { NativeBackButtonService } from '@pxlwidgets/ionic4-toolkit/services';

@Component({
    selector: 'app-root',
    templateUrl: 'app.component.html'
})
export class AppComponent {
    constructor(private backButtonService: NativeBackButtonService) {
        this.backButtonService.initialize();
    }
}
```




## InputFocusService
<a name="InputFocusService"></a>
A service to help scrolling focused form fields into view.

In some cases, especially when the software keyboard opens, focused form fields are not scrolled into view.
This service will fix that in most cases.

Also, it will force iOS to focus the next (invalid) field when pressing `Go` on the keyboard. 

To enable the service:
- Add the `InputFocusService` to the `providers` array in your module. (e.g. in your main `app.module.ts`)
- Include the `InputFocusService` in your component (e.g. in your main `app.component.ts`).
- Initialize it using the `initialize()` method.

To allow iOS form submission using the `Go` button (optional):
- Make sure your `<form>` has an `action` attribute.
- Add an `<input type="submit">` submit button to your form.
- Optionally, hide the submit button using CSS, e.g.:
```
input[type=submit] {
  position: fixed;
  left: -100vw;
  pointer-events: none;
  visibility: hidden;
}
```

## Example

`app.component.ts`
```typescript
import { Component } from '@angular/core';
import { InputFocusService } from '@pxlwidgets/ionic4-toolkit/services';

@Component({
    selector: 'app-root',
    templateUrl: 'app.component.html'
})
export class AppComponent {
    constructor(private inputFocusService: InputFocusService) {
        this.inputFocusService.initialize();
    }
}
```

`login.page.html`
```angular2html
<form action [formGroup]="myFormGroup" (ngSubmit)="soSomething()">
    
    <ion-input type="text" formControlName="username"></ion-input>
    <ion-input type="password" formControlName="password"></ion-input>

    <input type="submit">
    
    <ion-button type="submit">Submit</ion-button>

</form>
```