DOCSEARCHbyAlgolia
Submit Docs

KioskBoard

repository·main·Indexed 18 days ago

https://github.com/furcan/kioskboard

A pure JavaScript library for providing virtual keyboards in web applications, specifically designed for kiosk environments and touch-based interfaces. It supports customizable layouts via JSON or JavaScript objects, multiple visual themes, and configurable keyboard types including full keyboards and numpads. Version 2.3.0 features include automatic scrolling to focused inputs, mobile keyboard suppression, and configuration via HTML data attributes.

Tokens
3.5K
Snippets
12
Records
13
Agent score
13%

What's inside kioskboard

  3. Add KioskBoard via HTML Script Tags

    main

    If you are not using a module bundler, you can include KioskBoard directly in your HTML. You have two options:

    1. Standard: Include both the CSS and the JS files.
    2. All-in-One (AIO): Include a single JS file that contains the internal CSS.
    <!-- Option 1: CSS and JS -->
<link rel="stylesheet" href="dist/kioskboard-2.3.0.min.css" />
<script src="dist/kioskboard-2.3.0.min.js"></script>

<!-- Option 2: All in One (Internal CSS) -->
<script src="dist/kioskboard-aio-2.3.0.min.js"></script>

  4. Configure KioskBoard using HTML data attributes

    main

    You can configure individual input or textarea elements using data-* attributes. This allows different elements to have different keyboard behaviors.

    Supported attributes:

    • data-kioskboard-type: Keyboard type (all, keyboard, or numpad). Default is all.
    • data-kioskboard-placement: Keyboard position (top or bottom). Default is bottom.
    • data-kioskboard-specialcharacters: Whether to show special characters (true or false).

    Example usage:

    <!-- Textarea: all type, top placement, special characters enabled -->
<textarea class="js-virtual-keyboard" data-kioskboard-type="all" data-kioskboard-placement="top" data-kioskboard-specialcharacters="true" placeholder="Your Address"></textarea>

<!-- Input: keyboard type, bottom placement, special characters disabled -->
<input class="js-virtual-keyboard" data-kioskboard-type="keyboard" data-kioskboard-placement="bottom" data-kioskboard-specialcharacters="false" placeholder="Your Name" />

<!-- Input: numpad type, bottom placement (special characters are not allowed for numpad) -->
<input class="js-virtual-keyboard" data-kioskboard-type="numpad" data-kioskboard-placement="bottom" placeholder="Your Number" />

  5. How KioskBoard handles input focus and visibility

    main

    KioskBoard manages the relationship between the virtual keyboard and HTML input elements through several automated behaviors:

    • Automatic Scrolling: When an input is focused, the library calculates the input's position and scrolls the window so the input is not obscured by the keyboard. It uses different thresholds for top-placed vs. bottom-placed keyboards.
    • Body Padding: To prevent the keyboard from overlapping content or causing layout issues, KioskBoard may inject a <style id="KioskboardBodyPadding"> element into the <head> and add a .kioskboard-body-padding class to the <body>. This adds padding to the top or bottom of the document to accommodate the keyboard height.
    • Click Outside to Close: The library adds a document-level click listener. If a user clicks anywhere outside of the focused input and the virtual keyboard itself, the keyboard is automatically removed.
    • Mobile Keyboard Handling: If allowMobileKeyboard is set to false, the library manages the readonly attribute of inputs during focus/blur cycles to prevent the native mobile keyboard from appearing simultaneously with the KioskBoard.

  6. Initialize and Run KioskBoard via JavaScript

    main

    KioskBoard can be initialized and run using two main patterns in JavaScript.

    Pattern 1: Run with Selector

    Use KioskBoard.run(selector, options) to immediately target elements matching a CSS selector and apply configuration.

    KioskBoard.run('.js-virtual-keyboard', {
   // ...init options
});

    Pattern 2: Two-Step Initialization

    Use KioskBoard.init(options) to set global configurations first, then use KioskBoard.run(selector) to activate it on specific elements.

    // Step 1: Initialize with global settings
KioskBoard.init({
  keysArrayOfObjects: [...],
  theme: 'light',
  // ...other options
});

// Step 2: Run on specific elements
KioskBoard.run('.js-virtual-keyboard');
    KioskBoard.run('.js-virtual-keyboard', { /* options */ });

// OR

KioskBoard.init({ /* options */ });
KioskBoard.run('.js-virtual-keyboard');

  7. Configure Enter key behavior

    main

    When initializing KioskBoard, you can control what happens when the 'Enter' key is pressed on the virtual keyboard using the following options:

    • keysEnterCanClose: If set to true, clicking the Enter key will automatically remove (close) the virtual keyboard.
    • keysEnterCallback: A function that is executed when the Enter key is clicked. This is useful for triggering form submissions or other logic.
    // Example configuration
KioskBoard({
  keysEnterCanClose: true,
  keysEnterCallback: function() {
    console.log('Enter key pressed!');
  }
});

  8. Configure auto-scrolling behavior

    main

    KioskBoard can automatically scroll the window to ensure the focused input remains visible when the keyboard appears. Use these options to control it:

    • autoScroll: Set to true to enable automatic scrolling.
    • cssAnimations: Set to true to use smooth scrolling behavior instead of auto (instant).
    • cssAnimationsDuration: A number representing the duration of the scroll animation (used when cssAnimations is true).
    KioskBoard({
  autoScroll: true,
  cssAnimations: true,
  cssAnimationsDuration: 300
});

  9. Load keyboard layouts from a JSON URL

    main

    Instead of providing keys directly in the configuration, you can instruct KioskBoard to fetch keyboard layouts from a remote JSON file using the keysJsonUrl option.

    KioskBoard uses XMLHttpRequest to fetch the data. The fetched JSON must be an array of objects representing the keys. The library caches these keys internally to avoid redundant network requests if multiple inputs are used.

    KioskBoard({
  keysJsonUrl: 'https://example.com/path/to/keyboard-layout.json'
});

  10. Define Custom Keys via JSON

    main

    If you use the keysJsonUrl option, your JSON file must follow a specific structure where each object in the array represents a row on the keyboard. The keys in the object act as indices, and the values are the text displayed on the keys.

    Example JSON structure:

    [
   {
      "0": "Q",
      "1": "W",
      "2": "E"
   },
   {
      "0": "A",
      "1": "S",
      "2": "D"
   }
]
    [
   {
      "0": "Q",
      "1": "W",
      "2": "E",
      "3": "R",
      "4": "T",
      "5": "Y",
      "6": "U",
      "7": "I",
      "8": "O",
      "9": "P"
   },
   {
      "0": "A",
      "1": "S",
      "2": "D",
      "3": "F",
      "4": "G",
      "5": "H",
      "6": "J",
      "7": "K",
      "8": "L"
   },
   {
      "0": "Z",
      "1": "X",
      "2": "C",
      "3": "V",
      "4": "B",
      "5": "N",
      "6": "M"
   }
]

  11. Configure KioskBoard Initialization Options

    main

    When calling KioskBoard.init() or KioskBoard.run(), you can pass an options object to customize the keyboard behavior.

    Required Options

    One of the following must be provided to define the keyboard layout:

    • keysArrayOfObjects: An array of objects where each object represents a row. Example: [{"0":"A","1":"B"}, {"0":"C","1":"D"}].
    • keysJsonUrl: A string path to a JSON file containing the keys (used via XMLHttpRequest). The JSON format must match the keysArrayOfObjects structure.

    Keyboard Customization

    • language: ISO 639-1 language code (e.g., 'en', 'de', 'fr').
    • theme: 'light', 'dark', 'flat', 'material', or 'oldschool'.
    • keysSpecialCharsArrayOfStrings: Array of strings to override built-in special characters.
    • keysNumpadArrayOfNumbers: Array of numbers (0-9) to override numpad keys.
    • keysSpacebarText: Text for the space key (defaults to ' ').
    • keysEnterText: Text for the Enter key.
    • keysEnterCallback: Function called when the Enter key is clicked.
    • keysEnterCanClose: Boolean; if false, the Enter key won't close the keyboard.

    Visual & Animation Options

    • cssAnimations: Boolean to enable/disable animations.
    • cssAnimationsStyle: 'slide' or 'fade'.
    • cssAnimationsDuration: Duration in milliseconds.
    • keysFontFamily: CSS font family string.
    • keysFontSize: CSS font size string (e.g., '22px').
    • keysFontWeight: CSS font weight string.
    • keysIconSize: CSS icon size string.

    Behavior Options

    • autoScroll: Boolean; scrolls the document to the input element's position.
    • capsLockActive: Boolean; starts the keyboard in uppercase if true.
    • allowRealKeyboard: Boolean; allows/prevents physical keyboard usage.
    • allowMobileKeyboard: Boolean; allows/prevents mobile system keyboard usage.
    • keysAllowSpacebar: Boolean; enables/disables spacebar functionality.
    KioskBoard.init({
  keysArrayOfObjects: null, // or keysJsonUrl
  language: 'en',
  theme: 'light',
  autoScroll: true,
  capsLockActive: true,
  allowRealKeyboard: false,
  allowMobileKeyboard: false,
  cssAnimations: true,
  cssAnimationsDuration: 360,
  cssAnimationsStyle: 'slide',
  keysAllowSpacebar: true,
  keysSpacebarText: 'Space',
  keysFontFamily: 'sans-serif',
  keysFontSize: '22px',
  keysFontWeight: 'normal',
  keysIconSize: '25px',
  keysEnterText: 'Enter',
  keysEnterCallback: undefined,
  keysEnterCanClose: true,
});

  12. Run KioskBoard on an input element

    main

    To attach the virtual keyboard to an input or textarea, use KioskBoard.run(selectorOrElement, options).

    selectorOrElement can be:

    1. A direct reference to an HTMLInputElement or HTMLTextAreaElement.
    2. A CSS selector string (e.g., '#my-input').

    options (optional) allows you to override or extend the global configuration specifically for this instance.

    Keyboard Types via Data Attributes: You can control the keyboard type and placement for specific inputs using data-* attributes on the HTML element:

    • data-kioskboard-type: Set to 'all', 'keyboard', or 'numpad'.
    • data-kioskboard-placement: Set to 'top' or 'bottom'.
    • data-kioskboard-specialcharacters: Set to 'true' to enable the special characters button.
    // Using a selector
KioskBoard.run('#my-input');

// Using a direct element with specific overrides
const myInput = document.querySelector('input');
KioskBoard.run(myInput, {
  theme: 'material'
});