framework7io / framework7-plugin-keypad

Keypad plugin extends Framework7 with additional custom keyboards

Framework7 Keypad Plugin

Keypad plugin extends Framework7 with additional custom keyboards. By default it comes with predefined Numpad and Calculator keyboards, but it also can be used to create custom keyboards with custom buttons.

Installation

Just grab plugin files from dist/ folder or using npm:

npm install framework7-plugin-keypad

And link them to your app right AFTER Framework7's scripts and styles:

<link rel="stylesheet" href="path/to/framework7.bundle.min.css">
<link rel="stylesheet" href="path/to/framework7-keypad.min.css">
...
<script src="path/to/framework7.bundle.min.js"></script>
<script src="path/to/framework7-keypad.min.js"></script>

Usage

Install & Enable Plugin

After you included plugin script file, you need to install plugin before you init app:

// install plugin to Framework7
Framework7.use(Framework7Keypad);

// init app
var app = new Framework7({
  ...
})

ES Module

This plugin comes with ready to use ES module:

import Framework7 from 'framework7';
import Framework7Keypad from 'framework7-plugin-keypad';

// install plugin
Framework7.use(Framework7Keypad);

// init app
var app = new Framework7({
  ...
})

API

Plugin extends initiliazed app instance with new methods:

• app.keypad.create(parameters) - init Keypad. This method returns initialized Keypad instance.
• app.keypad.get(keypadEl) - get Keypad instance by HTML element. Method returns initialized Keypad instance.
• app.keypad.destroy(keypadEl) - destroy Keypad instance

Keypad Instance

Keypad can be created and initialized only using JavaScript. We need to use related App's method:

app.keypad.create(parameters)

Where parameters - object - object with Keypad parameters. Required This method returns initialized Keypad instance

For example

var myKeypad = app.keypad.create({
  inputEl: '#demo-numpad-limited',
  valueMaxLength: 2,
  dotButton: false
});

Keypad Parameters

Let's look on list of all available parameters:

Parameter	Type	Default	Description
openIn	string	auto	Can be auto, popover (to open keypad in popover) or sheet (to open in sheet modal). In case of auto will open in sheet modal on small screens and in popover on large screens.
backdrop	boolean		Allows enable/disable backdrop. If not specified then it will be enabled when it opened in Popover.
containerEl	string or HTMLElement		String with CSS selector or HTMLElement where to place generated Keypad HTML. Use only for inline keypad
containerEl	string or HTMLElement		String with CSS selector or HTMLElement where to place generated Keypad HTML. Use only for inline keypad
inputEl	string or HTMLElement		String with CSS selector or HTMLElement with related input element
scrollToInput	boolean	true	Scroll viewport (page-content) to input when keypad opened
inputReadOnly	boolean	true	Sets "readonly" attribute on specified input
cssClass	string		Additional CSS class name to be set on keypad modal
toolbar	boolean	true	Enables keypad modal toolbar
toolbarCloseText	string	Done	Text for Done/Close toolbar button
value	string		Initial Keypad value
formatValue	function (value)		Function to format input value, should return new/formatted string value. value is the current keypad value
type	string	numpad	Keypad type, could be 'numpad', 'calculator' or 'custom'
valueMaxLength	number	null	Limit value by selected number of characters
dotButton	boolean	true	Only for 'numpad' type. Show or hide "dot" button
dotCharacter	string	'.'	Dot character symbol. Only for 'numpad' and 'calculator' types
buttons	array		Array with keypad buttons, by default it is predefined for numpad and calculator, but can be used for custom keypad. Each button should be presented as object with the following properties: html - string - button inner HTML value - string/number - button value cssClass - string - additional CSS class on button dark - boolean - defines "dark" color button onClick - function (keypad, button) - callback function that will be executed when you click on button As a reference look at source code to see how buttons defined for Numpad and Calculator For example: ... buttons: [ { html:'1', value: 1, onClick: function () { console.log('Button 1 clicked') } }, { html:'A', value: 'a', }, ... ]
Render functions
renderToolbar	function (keypad)		Function to render toolbar. Must return toolbar HTML string
renderPopover	function (keypad)		Function to render popover. Must return popover HTML string
renderSheet	function (keypad)		Function to render sheet modal. Must return sheet modal HTML string
renderInline	function (keypad)		Function to render inline keypad modal. Must return full keypad HTML string

Keypad Methods & Properties

After we initialize Keypad we have its initialized instance in variable (like myKeypad variable in example above) with helpful methods and properties:

Properties
myKeypad.params	Object with passed initialization parameters
myKeypad.value	Current keypad value
myKeypad.opened	true if Keypad is currently opened
myKeypad.inline	true if Keypad is inline Keypad
myKeypad.$el	Dom7 instance with Keypad container HTML element
myKeypad.$inputEl	Dom7 instance with Keypad input HTML element
Methods
myKeypad.setValue(value)	Set new keypad value.
myKeypad.getValue(value)	Get keypad value.
myKeypad.open()	Open Keypad
myKeypad.close()	Close Keypad
myKeypad.destroy()	Destroy Keypad instance and remove all events

Keypad Events

Event	Target	Arguments	Description
change	keypad	(keypad, value)	Event will be triggered when Keypad value changed
keypadChange	app	(keypad, value)	Event will be triggered when Keypad value changed
buttonClick	keypad	(keypad, button)	Event will be triggered on Keypad button click
keypadButtonClick	app	(keypad, button)	Event will be triggered on Keypad button click
open	keypad	(keypad)	Event will be triggered when Keypad item starts its opening animation (modal open transition)
keypadOpen	app	(keypad)	Event will be triggered when Keypad item starts its opening animation (modal open transition)
opened	keypad	(keypad)	Event will be triggered after Keypad item completes its opening animation (modal open transition)
keypadOpened	app	(keypad)	Event will be triggered after Keypad item completes its opening animation (modal open transition)
close	keypad	(keypad)	Event will be triggered when Keypad item starts its closing animation (modal close transition)
keypadClose	app	(keypad)	Event will be triggered when Keypad item starts its closing animation (modal close transition)
closed	keypad	(keypad)	Event will be triggered after Keypad item completes its closing animation (modal close transition)
keypadClosed	app	(keypad)	Event will be triggered after Keypad item completes its closing animation (modal close transition)

Automatic initialization

Such predefined Numpad and Calculator keypads could be initialized automatically. Just use usual inputs but with special type attribute:

<input type="numpad">
<input type="calculator">

Access to Keypad's Instance

If you initialize Keypad as inline Keypad or using automatic initialization, it is still possible to access to Keypad's instance from its HTML container:

var myKeypad = $$('.keypad-inline')[0].f7Keypad;

CSS Custom Properties

The following CSS custom properties available to customize it:

:root {
  --f7-keypad-height: 260px;
  --f7-keypad-landscape-height: 200px;
  --f7-keypad-inline-height: 200px;
  --f7-keypad-inline-calc-height: 260px;
  --f7-keypad-popover-width: 300px;

  --f7-keypad-button-bg-color: #fcfcfd;
  --f7-keypad-button-text-color: #000;
  --f7-keypad-button-border-color: rgba(0,0,0,0.1);
  --f7-keypad-button-pressed-bg-color: #bcc0c5;
  --f7-keypad-button-dark-bg-color: #ddd;
  --f7-keypad-button-dark-pressed-bg-color: #fcfcfd;

  --f7-keypad-button-number-font-size: 28px;
  --f7-keypad-button-number-letters-size: 11px;

  --f7-keypad-calc-button-text-color: #fff;
  --f7-keypad-calc-button-bg-color: #ff9500;
  --f7-keypad-calc-button-pressed-bg-color: #e0750e;
  --f7-keypad-calc-button-active-border-color: rgba(0,0,0,0.4);
  --f7-keypad-calc-button-active-border-width: 1px;
}

Demo

Plugin comes with demo example to see how it works and looks. To make demo works you need to run in terminal:

$ npm run prod

Contribute

All changes should be done only in src/ folder. This project uses gulp to build a distributable version.

First you need to install all dependencies:

$ npm install

Then to build plugin's files for testing run:

$ npm run build:dev

If you need a local server while you developing you can run:

$ gulp server

or

$ npm run dev

And working demo will be available at http://localhost:3000/demo/

Live Preview

https://framework7io.github.io/framework7-plugin-keypad/