https://github.com/framework7io/framework7-plugin-keypad
Keypad plugin extends Framework7 with additional custom keyboards
https://github.com/framework7io/framework7-plugin-keypad
app cordova custom-keyboard framework7 keypad mobile plugin
Last synced: about 1 month ago
JSON representation
Keypad plugin extends Framework7 with additional custom keyboards
- Host: GitHub
- URL: https://github.com/framework7io/framework7-plugin-keypad
- Owner: framework7io
- License: mit
- Created: 2015-02-01T12:13:54.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2023-01-08T15:40:31.000Z (over 2 years ago)
- Last Synced: 2025-03-10T03:10:10.435Z (about 1 month ago)
- Topics: app, cordova, custom-keyboard, framework7, keypad, mobile, plugin
- Language: JavaScript
- Homepage: http://framework7.io/plugins/
- Size: 2.76 MB
- Stars: 75
- Watchers: 10
- Forks: 42
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# 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:
```
...
```
## Usage
### Install & Enable Plugin
After you included plugin script file, you need to install plugin before you init app:
```js
// install plugin to Framework7
Framework7.use(Framework7Keypad);
// init app
var app = new Framework7({
...
})
```
### ES Module
This plugin comes with ready to use ES module:
```js
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:
```js
app.keypad.create(parameters)
```
Where parameters - *object* - object with Keypad parameters. Required
This method returns initialized Keypad instance
For example
```js
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:
```html
```
## 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:
```js
var myKeypad = $$('.keypad-inline')[0].f7Keypad;
```
## CSS Custom Properties
The following CSS custom properties available to customize it:
```css
: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/