ionic-angular-utilities v1.1.6

Ionic Angular Utilities

The library contains some Ionic and Angular utilities usable in a own project.

Overview

The project contains following libraries:

• Ionic Angular Utilities

Ionic Angular Utilities

The libraries includes some common facilities tipically used during an app development. They will be described in following paragraphs.

Directives

Debounce click

The debounce click directive lets to bind click events to components using a rxjs debounce time operator. In this way multiple sequential clicks on components are prevented and triggered as a single click.

To use it on a component or tag, provide the debounceClick identifier.

Properties

Events

Example usage

First import DebounceClickDirective into the module declarations of the page or componenent where the centralizer will be used.

Then:

<div debounceClick debounceTime="800" (debounceClick)="onDebounceClickCallback($event)">
    Debounced click div
</div>

Components

Debounce button

It wraps an ion-button component with a different click behaviour, based on debounce click directive. The button doesn't trigger a callback immediately on user click. The click happens after a debounce time. During this time a scale animation on button is rendered.

Properties

Events

CSS Custom Properties

Example usage

First import BrowserAnimationsModule into the app module of the project (its a module of @angular/platform-browser/animations package). Then import DebounceButtonModule into the module imports of the page or componenent where the centralizer will be used.

Finally insert the component into you html source:

<debounce-button cssClass="globalClass" debounce="700" (debounceClick)="debounceClickCallback($event)">
    Button content
</debounce-button>

Centralizer

It let the developer to centralize tags and other components horizontally and vertically. It needs a container with a specified css position; centralizer content is centralized into this container.

Example usage

First import CentralizerModule into the module imports of the page or componenent where the centralizer will be used.

Then component can be used as a stand-alone component with an own content:

<div class="containerWithDefinedPosition">
    <centralizer>
        <div class="tagToCentralize">
            ...
        </div>
    </centralizer>
</div>

Or use the component as directive style:

<div centralizer class="centralizerContainerWithDefinedPosition">
    <div class="tagToCentralize">
        ...
    </div>
</div>

Error Container

Its a container that shows and error message and optionally a retry button with a own callback. It's provided for that situations in which an api call should be relanched by user after a previous error. It's used in ws-data and ws-data-list components (see below).

Properties

Events

CSS Custom Properties

Example usage

First import ErrorContainerModule into the module imports of the page or componenent where the error container will be used.

Then:

<error-container message="An error occured" retryButtonLabel="Retry">
</error-container>

The container admits also a custom definition of its inner parts. It's useful in cases of other error-container sorrounding components.

Spinner

A loading custom component with some spinner types usable only specifing their name.

Properties

CSS Custom Properties

Example usage

First import SpinnerModule into the module imports of the page or componenent where the spinner will be used.

Then:

<spinner name="chasingDot">
</spinner>

The container admits also a custom definition of its inner parts. It's useful in cases of other error-container sorrounding components.

Ws Data

It let the developer to visualize data that will be available in the future (such as web service data available only after a call over http). It wraps previous described spinner and error-container components to show a loading spinner during waiting data state, and to show an error message when an error occurs during data retrieve. It uses rxjs Observables to trace these loading and error states. It's a good practice to bind these states to a Redux substate.

Properties

WsDataOptions

Events

CSS Custom Properties

Example usage

Please refer to Ionic Angular Template repository as example for ws-data component usage.

Ws Data List

Really similar to previous Ws Data component, it let the developer to visualize array data that will be available in the future (such as web service data available only after a call over http). It wraps previous described spinner and error-container components to show a loading spinner during waiting data state, and to show an error message when an error occurs during data retrieve. It uses rxjs Observables to trace these loading, error and data available states. It's a good practice to bind these states to a Redux substate.

Properties

WsDataListOptions

The interface extends WsDataOptions and all its data are available on ws-data-list component too. In addition it expose also these parameters:

Events

CSS Custom Properties

Example usage

Please refer to Ionic Angular Template repository as example for ws-data-list component usage.

Styles

The library defines some global styles utilities into styles directory that can be imported from scss files of a project. There are some classes and facility mixins relative to fonts, layout, and responsiveness topics, and also a source scss with some ionic override rules.

To import them in a Ionic project .scss file, simply add an @import statement:

@import '~ionic-angular-utilities/lib/styles/override-ionic';
@import '~ionic-angular-utilities/lib/styles/mixins';
@import '~ionic-angular-utilities/lib/styles/responsive';

Please refer to Ionic Angular Template repository for a complete integration and global styling.

Ionic Native mocks

During a Ionic app development with ionic serve web execution all specific to platform Cordova plugins are unavailable. So, to ease the development with this type of dev execution, all @ionic-native wrappers of Cordova plugins should be mocked, to simulate the plugin behaviour. The repository includes some of these wrapper mocks importable into the app module of the application. Some of them are configurable with some values to use when they can't be retrieved from a web environment.

To import a simple mock without parameter such as the @ionic-native/http mock wrappaer (normally based on cordova-plugin-advanced-http) in the app module providers add a line like:

...
import { HTTP } from '@ionic-native/http/ngx';
import{ getHTTP } from 'ionic-angular-utilities';
...
...
    providers: [
        ...
        { provide: HTTP, useClass: getHTTP() },
        ...
    ]
...

To configure a mock provider, you can provide mock desired mock values into library import in the app module in this way (example based on @ionic-native/device wrapper):

...
import { Device } from '@ionic-native/device/ngx';
import{ getDevice, IonicAngularUtilitiesModule } from 'ionic-angular-utilities';
...
    ...
    imports: [
        ...
        IonicAngularUtilitiesModule.forRoot({
            ionicMock: {
                ...
                device: {
                    cordova: 'not available',
                    isVirtual: false,
                    manufacturer: 'not available',
                    model: 'not available',
                    platform: 'web',
                    serial: 'not available',
                    uuid: 'not available',
                    version: 'not available'
                },
                ...
            }
        }),
        ...
    ]
    ...
    providers: [
        ...
        { provide: Device, useClass: getDevice() },
        ...
    ]
    ...
...

Linking and packaging instructions

These few lines explain how to link, or publish or export as archive the ionic-angular-utilities code, after a ionic-angular-libraries main project build.

Link the library (only for dev purpose)

From the main ionic-angular-libraries directory go with a terminal into dist/ionic-angular-utilities and link globally the library with related npm command: cd dist/ionic-angular-utilities npm link

(package.json has a shortcut to build and link all internal libraries. From the main library project directory, run the command: npm run build-link)

Now inside your project, you can simply link it with the command: npm link ionic-angular-utilities

In your code you can now import its modules at the same way of a normal npm package installation:

import { ... } from 'ionic-angular-utilities';

To use this linking method, into your project angular.json file, you ave to set a preserveSymlinks flag following this structure:

"projects": { "app": { "architect": { "build": { "options": { "preserveSymlinks": true,

Note that in your package.json nothing was added. The link process is for test purpose only.

Unlink

To unlink the app use the npm unlink command:

• inside your project do npm unlink ionic-angular-utilities
• then inside the library dist/ionic-angular-utilities folder do npm unlink

Pack and export the library as an archive

From the main ionic-angular-libraries directory go with a terminal into dist/ionic-angular-utilities and pack the library with related npm command: cd dist/ionic-angular-utilities npm pack

(package.json has a shortcut to build and pack all internal libraries. From the main library project directory, run the command: npm run build-pack)

Into the same direcotory an ionic-angular-utilities tgz file was created (the name contains also the current version of the library taken from its package.json). Put this archive in any folder of your computer (also in the main directory of your project).

Inside your project install it as a normal dependency, but providing its relative or absolute path: npm install /path/to/archive.