Ionic 4 Toolkit

Useful tools for Ionic Framework v4 projects.

Features

• ExitOnBackButton decorator + service for page components.
• Theme decorator + service for app components / page components.
• NativeBackButtonService service for Android back button.
• InputFocusService service for forms.

Installation

npm i @pxlwidgets/ionic4-toolkit

ExitOnBackButton decorator

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

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

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 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 plugin and/or 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

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

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

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

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

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