init function

---

Summary

Initializes KeymanWeb and configures KeymanWeb Options.

Note that this is an asynchronous operation.

keyman.init() is automatically called after the page loads, with default options, if it has not already been called by scripts on the page. It is safe to call keyman.init() once more in this situation, in order to set additional options.

The keyman.initialized property may be checked to determine the current initialization state of Keyman Engine for Web.

You should not call functions other than keyman.init() until Keyman initialization is complete. As keyman.init() returns a Promise, the Promise fulfilment callback is the appropriate place to perform post-init steps.

Syntax

keyman.init(initOptions);

Parameters

initOptions

Type: Object.

See the Description section below for the necessary object specification.

Return Value

Promise: A JavaScript Promise fulfilled upon full initialization.

Initialization Options

The initOptions object may contain the following members:

ui

string|object optional

The user interface to be used on desktop devices. Default value: 'float'. Please see below for the specification of this parameter if using an object value.

root

string optional

The folder KeymanWeb should consider root. Default value: undefined, which sets root to the base folder where keymanweb.js is located.

resources

string optional

The image folder URL for UI resources. Default value: [root]/resources.

keyboards

string optional

The folder containing local keyboard resources if utilized. Default value: [root]/keyboards.

fonts

string optional

Folder containing any embedded fonts required for keyboards or the OSK. Default value: [root].

attachType

string optional

Must be undefined, 'auto', or 'manual'. Specifies the default behavior for attaching KeymanWeb to any input elements on the webpage.

• If undefined, KeymanWeb will default to 'manual' for mobile devices and 'auto' for other devices.
• If 'auto', KeymanWeb will automatically attach to every non-disabled control, even those added after page initialization.
• If 'manual', KeymanWeb must be instructed to attached manually to each control it should handle input for.

setActiveOnRegister

boolean optional

Specifies whether KeymanWeb will set the newly registered keyboard as active. Default value true.

• If true, KeymanWeb will automatically activate a keyboard when registered.
• If false, KeymanWeb will not activate a keyboard when registered.

Note: Changed from string type to boolean type in KeymanWeb 17.0 (#8458).

useAlerts

boolean optional

Specifies whether KeymanWeb's alert feedback should be enabled. Default value true.

• If true, KeymanWeb will display its default alerts.
• If false, KeymanWeb will not display its default alerts. Choose this if you wish to disable them or would prefer to customize your site's error feedback.
• In either case, any calls your page makes to keyman.util.alert() will not be blocked. This only affects calls built into KeymanWeb itself.

spacebarText

com.keyman.SpacebarText optional

If present, must be one of the following four constants:

• KEYBOARD /*'keyboard'*/ - show the keyboard name in the spacebar
• LANGUAGE /*'language'*/ - show the language name in the spacebar
• LANGUAGE_KEYBOARD /*'languageKeyboard'*/ - show both language and keyboard name in the spacebar, separated by hyphen
• BLANK /*'blank'*/ - keep the spacebar blank

Note that this may be overridden on a per-keyboard basis with the registration property displayName.

Default value: LANGUAGE_KEYBOARD.

---

If setting initOptions.ui with an object value, it should be specified as follows:

name

string

The name of the ui to utilize for non-mobile devices.

right

boolean optional

A Float-UI-only option. Sets right-alignment of the UI. Defaults to false.