addKeyboards function
Summary
Adds keyboards to KeymanWeb.
Syntax
keyman.addKeyboards(spec[, spec...])Parameters
spec
: Type: string|Object
keyboard name string or keyboard metadata JSON object
Return Value
Promise: A JavaScript Promise
fulfilled upon adding keyboards.
The promise is an array containing a combination of the following:
- successfully registered keyboard objects which define some or all of these properties
- ErrorStub objects for keyboards that failed to register
Description
The keyboard spec can be a string or an object. Multiple keyboard specs can be specified in a single call, which can reduce the round-trip cost of multiple calls to Keyman Cloud servers (when using Keyman Cloud).
For general information and example uses of this method, please see the Adding Keyboards page from the guide section.
Using a string
When keyboard spec is a string, the Keyman Cloud is used to source the keyboard file. Keymanweb will load webfonts and keyboard file automatically on demand. The string format is one of the following:
'keyboardID': Adds a specific keyboard, linking it to the default language for the keyboard'@languageID': Adds the default keyboard for the specified BCP 47 language code'keyboardID@languageID': Loads a specific keyboard + language combination
The keyboard catalogue is online at http://keyman.com/developer/keymanweb/keyboards.
Using an object
When keyboard spec is an object, then more parameters can be specified, including sourcing the keyboard from locations other than the Keyman Cloud. The specification of the object is related to the Keyman Cloud JSON API (formerly known as KeymanWeb Server Data API):
The spec object contains the following members:
name
: string
Name of the keyboard.
id
: string
ID (internal name) of keyboard, together with version always matches the filename of the keyboard
filename
: string
url of keyboard *.js file, relative (to page) or absolute
languages
: array|object
An array of objects (see definition below) or single object linked to the keyboard.
rtl
: boolean optional
true if the keyboard targets a right-to-left script. May be set to false
or left undefined otherwise.
version
: string optional
Version of keyboard *.js file
displayName
: string optional
A name to display in the spacebar of the keyboard; if omitted, use the
default spacebarText option.
The spec.languages object contains the following members:
name
: string
Name of the language.
id
: string
BCP 47 language code.
region
: string optional
Required when using the Toolbar UI. May be set with one of the following region names:
'World'('un')'Africa'('af')'Asia'('as')'Europe'('eu')'South America'('sa')'North America'('na')'Oceania'('oc')'Central America'('ca')'Middle East'('me')
font
: array|object optional
An array of Font objects (see definition below) or single object describing
fonts for input fields and the OSK (if oskFont is not present.)
oskFont
: array|object optional
An array of Font objects (see font definition below) or single object
describing fonts for the OSK.
The spec.languages.font object contains the following members:
family
: string
Font family that KeymanWeb will provide for this font.
filename
: array
Array of URLs where font resources can be accessed, relative to the fonts
initialization property. Multiple font resources can be specified as
platform font format support varies and KeymanWeb will pick the most
appropriate for the platform.
size
: string optional
Font size (in CSS dimensions). If not specified, then 1em is used.
