Contributing

Sections: Layout File | Map | Language | Set a License | Saving & Using

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:

Map - A template for the keyboard layout.
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.
'normal' [Array] (required; previously 'default')
- This is the only required layout keyset.
- Please note that the name default (deprecated ketset name; without quotes) is a reserved javascript word, so use 'normal' instead.
- 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. As of v1.26.8, the # can include any letter, underscore or dash (e.g. meta_symbols or meta-greek)

Example layout:

jQuery.keyboard.layouts['albanian-qwertz'] = {
  'name' : 'Albanian-qwertz',
  'lang' : ['sq'],
  'normal' : [
    "\\ 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 &larr;)
    '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'  : '&nbsp;: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" }
  }
};

Set a License

Add the license you wish to set on your contributed layout and/or language files.
If one is not set, it will be assumed to be set as WTFPL, as is set with almost all of the other layout and language files.

Please note that the keyboard plugin itself has an MIT license set on it.

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>

Home
Installation
FAQ
Setup
Usage
Options
- Layout
- Language
- Usability
- Actions
Extensions
- AltKeysPopup
- Autocomplete
- Caret
- Extender
- Mobile
- Navigation
- PreviewKeySet
- Scramble
- Typing
Methods
Contenteditable
Theme
Contributing
Log

Provide feedback

Saved searches

Use saved searches to filter your results more quickly