Contributing

Sections: Map | Language

Layout file

Layouts are stored as JavaScript files. When you download the source code, you will find all of the current layouts in the Keyboard/layouts/ folder

Each layout file can include any number of layouts grouped by a common language.

The file should contain two sections:

1. Map - A template for the keyboard layout.
2. Language

• Defines the language displayed within the keys or tooltips.
• If the layout does not require a language (e.g. number pad or symbols), then this section is not required.
• If you are adding a layout to an already existing file, then the language section may already exist and may not need to be modified.

You can look at the _template.js file and use it as a template.

Keyboard layout object map

This map contains the following keys:

• 'name' [String] (optional)

  • The layout name.
  • In the future, this will be the name displayed to the user so that they can select a keyboard layout.

• 'lang' [Array] (optional)

  • The language of the layout.
  • This is currently (as of v1.19.0) set to use the ISO 639-1 code, but there is no strict requirement. Everything will work as long as the layout 'lang' setting has a matching jQuery.keyboard.language.
  • If the layout is independent of a language (e.g. number pad or symbols), then this setting is not required.

• 'default' [Array] (required)

  • This is the only required layout keyset.
  • Please note that default (without quotes) is a reserved javascript word, so make sure to INCLUDE quotes ('default')
  • By convention, the default keyset usually contains the lower case keyset; but again this is completely customizable.
  • The keyset follows the same formatting as the customLayout option.
    • This definition contains an array of strings, each one defines a keyboard row.
    • Each key that is defined within the string must be separated from other keys with a space.
    • Special action keys must have curly brackets wrapping them ( e.g. {a} defines an accept key ).
    • For more details, see the customLayout option documenation

• 'shift', 'alt', 'alt-shift' and 'meta#' [Array] (optional)

  • These definitions contains other keyset for the keyboard.
  • By convention,
    • 'shift' contains the upper case keyset.
    • 'alt' contains the keys that are available when the user presses AltGr (Windows) or the Option key (Macintosh).
    • 'alt-shift' contains the keys that are available when the user presses both the AltGr/Option and Shift key.
    • 'meta#' can contain even more alternate keysets (e.g. meta1 or meta9999); there is no limit to the number of alternate keysets, but it must be named "meta" followed by a number.

Example layout:

jQuery.keyboard.layouts['albanian-qwertz'] = {
  'name' : 'Albanian-qwertz',
  'lang' : ['sq'],
  'default' : [
    "\\ 1 2 3 4 5 6 7 8 9 0 - = {bksp}",
    "{tab} q w e r t z u i o p \u00e7 '",
    "a s d f g h j k l \u00eb [ ] {enter}",
    "{shift} < y x c v b n m , . / {shift}",
    "{accept} {alt} {space} {alt} {cancel}"
  ],
  'shift' : [
    '| ! " # $ % ^ & * ( ) _ + {bksp}',
    "{tab} Q W E R T Z U I O P \u00c7 @",
    "A S D F G H J K L \u00cb { } {enter}",
    "{shift} > Y X C V B N M ; : ? {shift}",
    "{accept} {alt} {space} {alt} {cancel}"
  ],
  'alt' : [
    "\\ ~ \u02c7 ^ \u02d8 \u00b0 \u02db ` \u02d9 \u00b4 \u02dd \u00a8 \u00b8 {bksp}",
    "{tab} q w \u20ac r t z u i o p \u00f7 \u00d7",
    "\u00e4 \u0111:Shortcut_(\/d) \u0110:Shortcut_(\/D) f g h j \u0142:Shortcut_(\/l) \u0141:Shortcut_(\/L) $ \u00df \u00a4 {enter}",
    "{shift} < y x c @ { } \u00a7 < > / {shift}",
    "{accept} {alt} {space} {alt} {cancel}"
  ]
};

Notes

• The layout name must be unique ('albanian-qwertz' in the example above). If not, it will over-write another named layout.

• There must be whitespace between each key; any extra whitespace is ignored.

• Escaping single or double quotes using a backslash. For example, to include the double-quote character, you can:

  • Use a backslash to escape the double quote when it is enclosed within double-quotes ( " ... \" ..." )
  • Or, use single-quotes to enclose the double quote: ( ' ... " ... ' )

• If the backslash character appears within a row, then you must double the backslash to escape it ( " ... \\" ).

• To include tooltips with a key, separate the key from the tooltip using a colon (:), then enter any text, but replace all spaces with an underscore (_)

  // this shows a tooltip on the Đ key showing that it has a built-in shortcut combo of "/ + D"
  "\u0110:Shortcut_(\/D)"

• Special keys have names enclosed in curly brackets, e.g. '{bksp} {tab} {enter} {shift} {alt} {space}'

• There are two extra buttons – {accept} and {cancel} – which are not part of the standard keyboard. These are included to allow the user to close the virtual keyboard and either confirm the changes made or delete them.

• Optimally, if you use a character that isn't standard on most keyboards, then it should be converted to a unicode value.

  • For example, if your layout includes the letter Ж, then it should be converted to \u0416.

  • The easiest way to do this conversion is to use Google's closure compiler.

  • Click the reset button, then enter

    var x = "Ф Ы В А П Р О Л Д Ж Э {enter}"

  • Press the "Compile" button and you should see this result in the right panel:

    var x="\u0424 \u042b \u0412 \u0410 \u041f \u0420 \u041e \u041b \u0414 \u0416 \u042d {enter}";

  • Then simply copy & paste the result inside the quotes into your layout.

  • The real reason this is needed is that when saving a file, it should be saved with "UTF-8 No-BOM" encoding. If this doesn't happen automatically, the characters may end up as boxes, question marks, or other odd characters.

  • If you want to see what an encoded character looks like, copy it into your browser developer tools window

    x="\u0424 \u042b \u0412 \u0410 \u041f \u0420 \u041e \u041b \u0414 \u0416 \u042d {enter}"
    > "Ф Ы В А П Р О Л Д Ж Э {enter}"

Language

• This section defines the displayed language.
• Action keys such as "Accept" and "Cancel" can be changed to display the set language.
• This language definition is automatically set when the keyboard layout is set.
• If you define the language option, it will override the layout language.
• If the language for the layout is undefined, it defaults to english ("en")

Language Object

• If defined, it should include any changes to the following settings (i.e. setting that don't change can be left out of this section). See the Language page for more details.

  • display
  • wheelMessage
  • comboRegex
  • combos

• This is an example from the _template.js file:

  jQuery.keyboard.language.all = {
    display : {
      'a'      : '\u2714:Accept (Shift-Enter)', // check mark - same action as accept
      'accept' : 'Accept:Accept (Shift-Enter)',
      'alt'    : 'AltGr:Alternate Graphemes',
      'b'      : '\u2190:Backspace',    // Left arrow (same as ←)
      'bksp'   : 'Bksp:Backspace',
      'c'      : '\u2716:Cancel (Esc)', // big X, close - same action as cancel
      'cancel' : 'Cancel:Cancel (Esc)',
      'clear'  : 'C:Clear',             // clear num pad
      'combo'  : '\u00f6:Toggle Combo Keys',
      'dec'    : '.:Decimal',           // decimal point for num pad (optional), change '.' to ',' for European format
      'e'      : '\u21b5:Enter',        // down, then left arrow - enter symbol
      'enter'  : 'Enter:Enter',
      'lock'   : '\u21ea Lock:Caps Lock', // caps lock
      's'      : '\u21e7:Shift',        // thick hollow up arrow
      'shift'  : 'Shift:Shift',
      'sign'   : '\u00b1:Change Sign',  // +/- sign for num pad
      'space'  : ' :Space',
      't'      : '\u21e5:Tab',          // right arrow to bar (used since this virtual keyboard works with one directional tabs)
      'tab'    : '\u21e5 Tab:Tab',      // \u21b9 is the true tab symbol (left & right arrows)
      'toggle' : ' ',                   // replaced by an image
    },
    // Message added to the key title while hovering, if the mousewheel plugin exists
    wheelMessage : 'Use mousewheel to see other keys',
  
    // include changes to the comboRegex here - no need to include this if nothing changed
    comboRegex : /([`\'~\^\"ao])([a-z])/mig,
  
    // include any changes to the combos option here - no need to include this if nothing changed
    combos : {
      // grave
      '`' : { a:"\u00e0", A:"\u00c0", e:"\u00e8", E:"\u00c8", i:"\u00ec", I:"\u00cc", o:"\u00f2", O:"\u00d2",
          u:"\u00f9", U:"\u00d9", y:"\u1ef3", Y:"\u1ef2" },
      // acute & cedilla
      "'" : { a:"\u00e1", A:"\u00c1", e:"\u00e9", E:"\u00c9", i:"\u00ed", I:"\u00cd", o:"\u00f3", O:"\u00d3",
          u:"\u00fa", U:"\u00da", y:"\u00fd", Y:"\u00dd" },
      // umlaut/trema
      '"' : { a:"\u00e4", A:"\u00c4", e:"\u00eb", E:"\u00cb", i:"\u00ef", I:"\u00cf", o:"\u00f6", O:"\u00d6",
          u:"\u00fc", U:"\u00dc", y:"\u00ff", Y:"\u0178" },
      // circumflex
      '^' : { a:"\u00e2", A:"\u00c2", e:"\u00ea", E:"\u00ca", i:"\u00ee", I:"\u00ce", o:"\u00f4", O:"\u00d4",
          u:"\u00fb", U:"\u00db", y:"\u0177", Y:"\u0176" },
      // tilde
      '~' : { a:"\u00e3", A:"\u00c3", e:"\u1ebd", E:"\u1ebc", i:"\u0129", I:"\u0128", o:"\u00f5", O:"\u00d5",
          u:"\u0169", U:"\u0168", y:"\u1ef9", Y:"\u1ef8", n:"\u00f1", N:"\u00d1" }
    }
  };

Saving & Using your file

• As mentioned previously, make sure to save the file using "UTF-8 NO BOM" encoding. The "NO BOM" part is only important for Windows users.
• You can name the file anything you want, just make sure to load it after the keyboard plugin is loaded:

<!-- jQuery (required) -->
<script src="jquery.js"></script>

<!-- keyboard widget css & script (required) -->
<link href="css/keyboard.css" rel="stylesheet">
<script src="js/jquery.keyboard.js"></script>

<!-- jQuery UI position utility + theme (optional) -->
<link href="jquery-ui.css" rel="stylesheet">
<script src="jquery-ui.min.js"></script>

<!-- keyboard extensions (optional) -->
<script src="js/jquery.mousewheel.js"></script>
<script src="js/jquery.keyboard.extension-typing.js"></script>

<!-- keyboard layouts -->
<script src="layouts/albanian.js"></script>

---

Wiki Pages: Home | FAQ | Setup | Usage | Options ( Layout, Language, Usability, Actions ) | Methods | Theme | Log