GitHub - benjamincharity/angular-keypad: :iphone:🔢 A numerical keypad built for mobile devices. (original) (raw)

angular-keypad

angular-keypad

MIT License Coverage Status NPM version

📱🔢 An Angular directive that creates a numeric keypad.

📺 All Demos

Comments and Pull Requests welcome!

Contents

Installation

NPM

npm install angular-keypad --save

Bower

bower install angular-keypad --save

Manually

Add the script and styles to your HTML:

Dependencies

Usage

Include bc.AngularKeypad as a dependency in your project:

angular.module('YourModule', ['bc.AngularKeypad']);

Use the directive anywhere in your HTML. The keypad will expand to fill the width of it's container while maintaining the aspect ratio of the keypad buttons.

{{ vm.numbers }}

📺 Simple demo

bc-number-model

Required: String

The directive will store the current string of numbers here. This is the only required attribute.

bc-max-length

Optional: Integer

The directive will use this number to set a hard limit on how many characters are allowed in the number model (vm.numbers in the example below).

📺 Demo for max-length

<bc-keypad bc-number-model="vm.numbers" bc-max-length="4"

bc-left-button

Optional: String

You can define a custom Plug'n'Play button type by passing in the name of any valid (PnP) button.

📺 Demo for Plug'n'Play button types with custom methods

<bc-keypad bc-number-model="vm.numbers" bc-left-button="backspace"

bc-right-button

Optional: String

You can define a custom Plug'n'Play button type by passing in the name of any valid (PnP) button.

📺 Demo for Plug'n'Play button types with custom methods

<bc-keypad bc-number-model="vm.numbers" bc-right-button="submit"

Custom Methods

bc-left-button-method

Optional: method

You can pass in a custom method that will be called each time the button is interacted with. This allows you to track interaction or handle custom validation in your controller.

Available Parameters:

Param Type Details
$event Object The original event object from the ng-click
numbers String The current value of bc-number-model

📺 Demo for Plug'n'Play button types with custom methods

<bc-keypad bc-number-model="vm.numbers" bc-left-button="backspace" bc-left-button-method="vm.doSomething($event, numbers)"

export class YourController {

constructor() {
    this.numbers = '';
}

// I will be called each time the left (backspace) button is interacted with
doSomething($event, numbers) {
    console.log('The backspace button on the left was clicked!');
    console.log('Original click event object: ', $event);
    console.log('Current number model value: ', numbers);
}

}

bc-right-button-method

Optional: method

You can pass in a custom method that will be called each time the button is interacted with. This allows you to track interaction or handle custom validation in your controller.

Available Parameters:

Param Type Details
$event Object The original event object from the ng-click
numbers String The current value of bc-number-model

📺 Demo for Plug'n'Play button types with custom methods

<bc-keypad bc-number-model="vm.numbers" bc-right-button="submit" bc-right-button-method="vm.doSomething($event, numbers)"

export class YourController {

constructor() {
    this.numbers = '';
}

// I will be called each time the right (submit) button is interacted with
doSomething($event, numbers) {
    console.log('The submit button on the right was clicked!');
    console.log('Original click event object: ', $event);
    console.log('Current number model value: ', numbers);
}

}

bc-empty-backspace-method

Optional: method

You can pass in a custom method that will be called when the backspace button is interacted with and bc-number-model is already empty. This can be useful for allowing users to step backwards through a multi-part form.

📺 Demo for bc-empty-backspace-method

<bc-keypad bc-number-model="vm.numbers" bc-right-button="backspace" bc-empty-backspace-method="vm.backspaceWhenEmpty()"

export class YourController {

constructor() {
    this.numbers = '';
}

// I will be called when the backspace button is clicked and the numbers
// model is empty
backspaceWhenEmpty() {
    console.log('Backspace clicked, but "vm.numbers" is empty!');
}

}

Plug'n'Play Buttons

Plug'n'Play buttons

This directive now supports Plug'n'Play (PnP) button types to the left and right of the final digit. These button types can be used on either side (or both if you really wanted to).

📺 Demo for Plug'n'Play button types with custom methods

Available (PnP) Button Types

Even when using a (PnP) button, any defined custom methods will still be called.

Any (PnP) button template can be overwritten using methods exposed via the provider.

<bc-keypad bc-number-model="vm.numbers" bc-left-button="backspace" bc-right-button="submit" bc-right-button-method="vm.submitMyData($event, numbers)"

Backspace

<bc-keypad bc-number-model="vm.numbers" bc-right-button="backspace"

This will create a backspace button with styles and functionality already wired together.

Functionality

Each time a backspace button instance is interacted with, the last number will be removed frombc-number-model.

If a custom method was passed to bc-empty-backspace-method it will be called when the backspace button is interacted with and bc-number-modelis already empty. This can be useful for allowing users to step backwards through a multi-part form.

Any defined custom methods will still be called.

Style

By default the button is using a raw SVG version of ion-backspace-outlinefrom ionicons since this allows you to customize the SVG styles with your project's CSS.

📺 Demo for custom button CSS

Ionicons backspace icon

A special class is added to the backspace button which can be used to target specific styles:

.bc-keypad__key-button--backspace { fill: #DE1E7E; }

Submit

<bc-keypad bc-number-model="vm.numbers" bc-right-button="submit"

This is a purely aesthetic (PnP) button type. No functionality is attached, but any defined custom methods will still be called.

Style

By default the button is using a raw SVG version of ion-log-in fromionicons since this allows you to customize the SVG styles with your project's CSS.

📺 Demo for custom button CSS

Ionicons submit icon

A special class is added to the submit button which can be used to target specific styles:

.bc-keypad__key-button--submit { fill: #101CA7; }

bcKeypadConfigProvider

This module exposes bcKeypadConfigProvider which can be used to set custom defaults for the directive. Setting options here will overwrite the directive's default options for all instances within your module.

📺 Demo for bcKeypadConfigProvider

// ES6 Config Example export function config(bcKeypadConfigProvider) { 'ngInject';

// Set a default of '7' for the max length of all keypads within your module
bcKeypadConfigProvider.setMaxLength(7);

}

// ES5 Config Example angular.module('myModule') .config((bcKeypadConfigProvider) => { 'ngInject';

    bcKeypadConfigProvider.setMaxLength(7);

})

;

setBackspaceTemplate

This allows you to specify a custom template for the backspace key.

By default it is using a raw SVG version of ion-backspace-outline fromionicons since this allows you to overwrite the SVG styles with CSS.

📺 Demo for bcKeypadConfigProvider

Ionicons backspace icon

bcKeypadConfigProvider.setBackspaceTemplate('↩');

setSubmitTemplate

This allows you to specify a custom template for the submit key.

By default it is using a raw SVG version of ion-log-in fromionicons since this allows you to overwrite the SVG styles with CSS.

📺 Demo for bcKeypadConfigProvider

Ionicons log in icon

bcKeypadConfigProvider.setSubmitTemplate('Go');

setMaxLength

The directive will use this number to impose a hard limit on how many characters the model can hold. This is useful for specific data items such as a phone number:

📺 Demo for bcKeypadConfigProvider

max-length demo

bcKeypadConfigProvider.setMaxLength(10);

Styles

The included styles are 99% layout with just enough style to work out of the box. The true styles should be written at your project level using the associated classes.

Your project CSS should always be included after any library CSS files. This makes it easy for you to override or add to any styles defined by this module. Below are the classes available for styling.

Class Element Details
.bc-keypad
Primary container (
) around the keypad.
.bc-keypad__key
Individual wrapper for each key.
.bc-keypad__key--left
Target the left customizable key.
.bc-keypad__key--center
Target the last number key (between the two customizable keys).
.bc-keypad__key--right
Target the right customizable key.
.bc-keypad__key-button The button inside each key.
.bc-keypad__key-button--backspace Target the backspace key (if used)
.bc-keypad__key-button--submit Target the submit key (if used)

📺 Demo for custom theming

angular-ripple

The bc-keypad directive was written primarily for mobile so it supports the Google Material 'ripple' style feedback via a module called angular-ripple. As not everyone may want that style of interaction, this project does not automatically install theangular-ripple library, but is however built to support it out of the box.

📺 Demo for angular-ripple integration

Just install the angular-ripple library:

$ npm install nelsoncash/angular-ripple --save

or

$ bower install angular-ripple --save

Include it as a dependency in your primary project:

angular.module('YourModule', ['bc.AngularKeypad', 'angularRipple']);

And you should see it working!

Development