If you need to capture user text input and don't have your own onscreen keyboard control, the X1 Platform provides a basic soft keyboard for your convenience.

Lightning App

Documentation: https://rdkcentral.github.io/Lightning-UI-Components/?path=/docs/keyboard--basic

Source Code: https://github.com/rdkcentral/Lightning-UI-Components/tree/master/components/Keyboard

HTML5 App

This keyboard can be embedded in your HTML5 app with a few lines of code. It runs in a separate canvas that overlays the keyboard on your app.

Beta Product

The keyboard control is a beta product. Please use at your discretion.

Get Started

Download the keyboard source code: http://cdn.thor.comcast.com/sdk/keyboard/keyboard-1.0.1-beta.zip

Unzip the contents into your html app folder.

See example.html in the zip file OR follow the usage instructions in this document.

Examples

In these examples we will provide 2 ways to integrate the keyboard:

1. Basic usage

2. Advanced usage

Both integrations start with including the library in your app.

Include the following line in the HEAD of of your HTML document (note - change the src path to wherever you have downloaded the keyboard):

<script src="js/init-1.0.1-beta.js"></script>

Basic Usage

The most basic integration is via adding a data-keyboard to a valid HTML input element:

<input type="text" placeholder="Username" 
       data-keyboard="title:Username;message:Type your username;maxlength:30">

After adding the data attribute you only need to add a small script to HTML document:

window.onload = () => {
    const elements = document.querySelectorAll("[data-keyboard]");
    if(elements.length){
        $__OTT_KEYBOARD.attach(elements, "click");
    }
};

On window load we search for all elements with the data-keyboard attribute, and if we find some elements we attach the keyboard to them and make sure the keyboard will be shown on "click" event. So you can change the second element to any other valid event to match your need.

The value inside the data-attribute is the configuration that will be handed over to the keyboard when it becomes visible via the configured event.

Advanced Usage

The advanced integration provides the option to gain more control over the keyboard output and the way of showing / hiding the keyboard.

This example will use a input element but it's not required.

First we add an element to the DOM:

<input type="text" placeholder="Click to search" 
       data-title="Find" data-max-length=40 
       data-message="At least 3 characters" id="inputElement">

Then we store a reference to the HTML element:

const inputField = document.getElementById("inputElement");

Next we reference the actual keyboard:

const keyboard = window.$__OTT_KEYBOARD;

and reference the stage (for now the stage will emit the events):

const stage = keyboard.stage;

and reference to the canvas (so you can toggle visibility / change position):

const canvas = window.$__OTT_KEYBOARD_CANVAS;

Then setup some functions for showing/hiding:

const showKeyboard = () => {
    canvas.style.display = "block";
};

const hideKeyboard = () => {
    canvas.style.display = "none";
};

Finally, we add an event listener to the input element which will spawn the keyboard on click, collect the configuration data for the keyboard and emit a keyboardConfig event to the stage (keyboard is listening to keyboardConfig event):

inputField.addEventListener("click", () => {
    // grab config from inputfield
    const title = inputField.getAttribute("data-title");
    const message = inputField.getAttribute("data-message");
    const maxlength = inputField.getAttribute("data-max-length");

    // emit changes to stage so keyboard can listen
    // this way you can change title / message per element
    stage.emit("keyboardConfig",{
        title,message, maxlength
    });

    // show keyboard
    showKeyboard();
});

Events

You can listen to the keyboard change event. This event will fire after every keypress and the parameter is an object with the properties char (last types char) and value (complete typed value):

stage.on("change", ({char: lastChar, value}) => {
    console.log("keyboard change:", lastChar, value);
});

You can listen to the done event. This event will click on the done button:

stage.on("done", ({value}) => {
    // first hide keyboard
    hideKeyboard();

    // update input element
    inputField.value = value;
});