soixantecircuits / piano

Desktop browser based on screen keyboard for touch screens

⌨ 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

• Table of contents
• Installation
  • Installation with module bundler
  • Installation without module
• Usage
  • Positionning / styling
  • Submit
  • Animations
  • Touch events
• 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')

or

<!-- 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).

piano's Issues

Add scale option to the keyboard default layout thru : data-scale, or option.scale

This should dynamically add :

-webkit-transform: scale(2);

keyboard scale can't be inferior to 1

In order to reduce the size of the keyboard, we might want to provide value inferior to 1

Add test example

Add a onHidden function option

The init param should always be an option object. The config, should always been an object.

I can see here : https://github.com/soixantecircuits/piano/blob/master/piano.js#L15 that the option is a string.

⛔ Using string as an option is lame for several reason and has to be avoided : ⛔

First, you never know if you might need more options.
Second, if you need more options, you'll have to rewrite a code to handle multiple option. This will also apply if you us an array instead of an object.
Third, it's easier to read in a separate file a option object than a string alone.

Thanks !

Add original fork origin

What this project is based on ?

Implement event creation the right way

See https://developer.mozilla.org/en-US/docs/Web/Guide/Events/Creating_and_triggering_events

Add a debounce to the touch / click event

Currently the keyboard is super-sentive. We should add a classic debounce on the event. Such as :

https://john-dugan.com/javascript-debounce/

👍

Development logic

Hey,

I don't understand development logic, which command should I use to run a simple server that serve a HTML file and js, or just a webpack bundle ?

Backspace does not delete from cursor position

It's due to the k.currentTarget.value = k.currentTarget.value.substr(0, k.currentTarget.value.length - 1); handler.
Need to do this right.

Add a beforeHide function to options

demo doesn't work

When I open the demo page http://soixantecircuits.github.io/piano/ and click inside some text box, nothing happens.
The console logs:
Uncaught ReferenceError: Piano is not defined at HTMLDocument.<anonymous> (index.js:18)

autohide keyboard managing

For now if you click somewhere on the document and the keyboard hides. https://github.com/soixantecircuits/piano/blob/master/src/piano.js#L26
It would be better to add some flag to turn off this autohide. Sometimes the keyboard should be all the time on the screen, no matter where the user press.

When you set multiple trigger, the click is triggered multiple times

For example, if you initialize piano with piano.init({triggers: ['click', 'touchstart'],}), when you tape in the keyboard, each button is taped twice.

Sometime on the edges, the touch input seems not to be propagate correctly

Missing azerty-email layout when installing using npm

run npm i piano.js
look in your node_modules/piano.js/layouts
you won't find azerty-email.js layout

Pure JSON layout and autoload

I would recommand to use pure json layout and autoload layout

Animate.css transitions has no callback and leads to bug with specific positions settings

For example:
Take an element with data-position="top" and piano initialized with slideContent: true.
When it appears, it goes on the top of the screen. When click out the keyboard container, the whole container slides down, but not behind visible part of the screen: it's still here, with its opacity to 0 but in the foreground so you can click on the keys and change the input.

PRO TIP: answer's here: https://github.com/daneden/animate.css#usage

Remove gulp dependencies and all transpiling

Regarding https://caniuse.com/#feat=es6-class, and recent browser usage statistics, plus the fact that most of the time the lib is used in a Chrome like environment, we should drop the transpilling and the gulp script in favor of a plain es6 export.

The options init should extend the option object

https://github.com/soixantecircuits/piano/blob/master/piano.js#L20

can't read selectionStart property on input type ('email')

Add a dev script to allow dev with a standard way.

Currently while developing, I'm using budo or a simple alias to php serve. Currently the only way to test in the demo folder is using the file protocole. Which is slow : no auto-reload mostly and not standard.

Update demo after build

When you complete build you have to manually copy built file from dist into demo/src