README

⌨ Piano.js

Customizable virtual keyboard written in plain JavaScript. See the demo.

The easiest way to put a keyboard in front of your users. Piano is a simple and extensible On-Screen keyboard. It allows to provide elegant solution for virtual keyboard in a touch application.

Tested in Electron and Chrome kiosk.

Piano is still under active development (but has successfully been used in production work).

Table of contents
Installation
- Installation with module bundler
- Installation without module
Usage
Options
Demo
Layouts
Development
To Do

Installation

Get the packages

npm i -S piano.js
# or
yarn add piano.js

Or download piano and at least the default layout .

Load the library

// Add the CSS
require('piano.js/piano.css')

// Require piano wherever you want to use it
const Piano = require('piano.js')

// Choose the layouts you want
const azerty = require('piano.js/layouts/azerty')
const qwerty = require('piano.js/layouts/qwerty')

<!-- Load the library -->
<script src="path/to/piano.js"></script>
<!-- And at least the default layout -->
<script src="path/to/layouts/default.js"></script>

Use it

// Instantiate Piano
const keyboard = new Piano({
  layouts: {
    'azerty': azerty,
    'qwerty': qwerty
  },
  slideContent: true
})
// See the 'Options' section for more details about this

<input type="text"
  data-piano data-piano-scale="1.5"
  data-piano-layout="azerty"
/>

Optionally, you can listen to piano events in your code

<input type="text"
  data-piano-event-id="do-stuff"
/>

document
  .querySelector('[data-piano-event-id="do-stuff"]')
  .addEventListener('do-stuff', doStuffCallback)

Method

addTarget()

addTarget method allow to dynamically add an input trigger for your on screen screen keyboard.

addTarget(element, options)

You need to provide a domElement and basic options object :

{
  layout: 'azerty',
  animationIn: 'bounceInUp',
  animationOut: 'fadeOutUp',
  scale: 1.0
}

So if you already have your keyboard instance and an element in the DOM namde #dynamic-piano you can:

let options = {
    layout: 'azerty',
    animationIn: 'bounceInUp',
    animationOut: 'fadeOutUp',
    scale: 1.0
  }
keyboard.addTarget(document.querySelector('#dynamic-piano'), options)

Usage

Positionning / styling

You can define positionning with the data-piano-position attribute. You can use the following:

'left', 'center', 'right' -> x axis
'top', 'middle', 'bottom' -> y axis

For example:

<input type="text" data-piano data-piano-position="left, center" />

Or, with the absolute keyword, you can define absolute x and y positions:

<input type="text" data-piano data-piano-position="absolute, 100, 150" />

Default positions are 'center, bottom'.

Submit

You can define a data-piano-event-id attribute on your element and then listen to it. For example, if you have a data-piano-event-id="input-event":

element.addEventListener('input-event', function (event) {
  console.log('element with id "%s" submitted.', event.target.id)
})

Animations

Piano provide has built-in but yet optionnal support for Animate.css.

By default, it will add fadeInUp and fadeOutDown classes to your container. Just load the animate.css stylesheet and you'll have nice animations. You can also use the data-piano-animation-in and data-piano-animation-out attributes to define custom classes to toggle on hide/show.

You can also choose to create your own animations, and thus just use the classes toggled by piano to trigger them.

Touch events

By default, Piano uses click events, even for touch devices. This is because any decent browser will emulate touch events into click, and touch events make an approximation of the pointer's contact position. Of course, you can override this in the options.

Options

You can pass options to your new Piano() call. Here they are:

triggerEvents: Array of event triggers you want Piano to react (see Touch events)
slideContent: bool [true, false], default to false. Allow to define if the content should slide
slideContainer: string ['.demo-container'], no default. Allow to define the part of the DOM you want to slide
onHidden: function, default to empty function. Allow to call a function when the keyboard is hidden
onBeforeHidden: function, default to empty function. Allow to call a function before the keyboard is hidden

Layouts

Soon.

Development

We use gulp to develop, to contribute to piano, just use gulp develop. It will watch src/piano and serve it over localhost on port 8080.

Create a feature-[name-of-the-feature] branch and make PR on the dev branch. Please use the standard js coding style.

To Do

Support accentuation. (partial support for now).

Usage no npm install needed!