diff --git a/web/docs/engine/guide/adding-keyboards.md b/web/docs/engine/guide/adding-keyboards.md index 221f495de1b..3543670493c 100644 --- a/web/docs/engine/guide/adding-keyboards.md +++ b/web/docs/engine/guide/adding-keyboards.md @@ -4,57 +4,80 @@ title: Adding Keyboards There are multiple ways to add and install keyboards into your KeymanWeb installation. -## Directly linking a local copy +## Requesting from the Keyman cloud (CDN) -The most efficient way to utilize a keyboard is to obtain a local copy of it and place this copy in a static location on your website. Once this is done, it can be directly linked into KeymanWeb as follows. - -```c -keyman.addKeyboards({ - id:'us', // The keyboard's unique identification code. - name:'English', // The keyboard's user-readable name. - language:{ - id:'en', // A BCP 47 code uniquely identifying the language. - name:'English (US)' // The language's name. - }, - filename:'./us-1.0.js' // A valid path to the compiled *.js file representing the keyboard. -}); -``` +The easiest way to utilize a keyboard is to request it from the Keyman cloud. -Custom fonts may also be utilized via the `language.font` property. For example: +### Requested from the CDN by keyboard name -```c -font:{ - family:'LaoWeb', - source:['../font/saysettha_web.ttf','../font/saysettha_web.woff','../font/saysettha_web.eot'] -} +To obtain a specific keyboard by name or by keyboard name and language code as a pair, see the +following: + +```typescript +await keyman.addKeyboards('khmer_angkor','sil_euro_latin@sv','sil_euro_latin@no') ``` -## Requested from the CDN by language name +This will install three keyboards - the Khmer Angkor one for Khmer and two copies +of the EuroLatin keyboard - one for Swedish and one for Norwegian. -To obtain the default Keyman keyboard for a given language, call the following function. +### Requested from the CDN by language name -```c -keyman.addKeyboardsForLanguage('Dzongkha'); +To obtain the default Keyman keyboard for a given language, call the following function: + +```typescript +await keyman.addKeyboardsForLanguage('Dzongkha'); ``` -This example would find the default keyboard for the Dzongkha language. This method will fail if the name doesn't perfectly match any language found in the CDN's repository. +This example would find the default keyboard for the Dzongkha language. This method will fail if +the name doesn't perfectly match any language found in the CDN's repository. Alternatively, languages may be looked up via their BCP 47 language code as follows: -```c -keyman.addKeyboards('@he') +```typescript +await keyman.addKeyboards('@he') ``` -The `@` prefix indicates the use of the BCP 47 language code, which in this case corresponds with Hebrew. +The `@` prefix indicates the use of the BCP 47 language code, which in this case corresponds with +Hebrew. -## Requested from the CDN by keyboard name +To add all keyboards for a language at once, `$` can be appended to the language +name or language code: -To obtain a specific keyboard by name or by keyboard name and language code as a pair, see the following: +```typescript +await keyman.addKeyboards('@fr$'); +// or +await keyman.addKeyboardsForLanguage('French$'); +``` -```c -keyman.addKeyboards('french','sil_euro_latin@sv','sil_euro_latin@no') +## Directly linking a local copy + +The most efficient way to utilize a keyboard is to obtain a local copy of it and place this copy +in a static location on your website. Once this is done, it can be directly linked into KeymanWeb +as follows: + +```typescript +await keyman.addKeyboards({ + id: 'us', // The keyboard's unique identification code. + name: 'English', // The keyboard's user-readable name. + languages: { + id: 'en', // A BCP 47 code uniquely identifying the language. + name: 'English (US)' // The language's name. + }, + filename: './us.js' // A valid path to the compiled *.js file representing the keyboard. +}); ``` -This will install three keyboards - one for French (named, quite simply, "French") and two copies of the EuroLatin keyboard - one for Swedish and one for Norwegian. +Custom fonts may also be utilized via the `languages.font` property. For example: + +```typescript +languages:{ + id:'lo', + name:'Lao', + font:{ + family:'LaoWeb', + source:['../font/saysettha_web.ttf','../font/saysettha_web.woff'] + } +} +``` [Previous: What is a Keyboard?](what-is-a-keyboard) | [Next: Additional Examples](examples/) diff --git a/web/docs/engine/reference/core/addKeyboards.md b/web/docs/engine/reference/core/addKeyboards.md index 0f312bee4ce..9c08d8620e5 100644 --- a/web/docs/engine/reference/core/addKeyboards.md +++ b/web/docs/engine/reference/core/addKeyboards.md @@ -4,12 +4,12 @@ title: addKeyboards function ## Summary -Adds keyboards to KeymanWeb. +Adds keyboards to KeymanWeb. Note that this is an asynchronous operation. ## Syntax ```js -keyman.addKeyboards(spec[, spec...]) +await keyman.addKeyboards(spec[, spec...]) ``` ### Parameters @@ -54,6 +54,9 @@ The string format is one of the following: The keyboard catalogue is online at [https://keyman.com/developer/keymanweb/keyboards](https://keyman.com/developer/keymanweb/keyboards). +If the BCP47 language code is suffixed with `$` (e.g. `@fr$`) and no specific keyboard is +requested, all keyboards for that language code will be loaded. + ### Using an `object` When keyboard spec is an object, then more parameters can be specified, diff --git a/web/docs/engine/reference/core/addKeyboardsForLanguage.md b/web/docs/engine/reference/core/addKeyboardsForLanguage.md index 5e8ed92c9e0..8f6e645e313 100644 --- a/web/docs/engine/reference/core/addKeyboardsForLanguage.md +++ b/web/docs/engine/reference/core/addKeyboardsForLanguage.md @@ -4,12 +4,13 @@ title: addKeyboardsForLanguage function ## Summary -Add default or all keyboards for a given language to KeymanWeb. +Add default or all keyboards for a given language to KeymanWeb. Note that this is an asynchronous +operation. ## Syntax ```js -keyman.addKeyboardsForLanguage(spec[, spec...]) +await keyman.addKeyboardsForLanguage(spec[, spec...]) ``` ### Parameters @@ -31,6 +32,7 @@ The promise is an array containing the following: * successfully registered keyboard objects which define some or all of these [properties](../keyboard_properties) +* [ErrorStub](../keyboard_registration_errors) objects for keyboards that failed to register ## Description diff --git a/web/src/app/browser/src/keymanEngine.ts b/web/src/app/browser/src/keymanEngine.ts index 59987035ccf..80530e5bac8 100644 --- a/web/src/app/browser/src/keymanEngine.ts +++ b/web/src/app/browser/src/keymanEngine.ts @@ -345,7 +345,7 @@ export class KeymanEngine extends KeymanEngineBase { + public async addKeyboards(...args: any[]): Promise<(KeyboardStub|ErrorStub)[]> { return this.config.deferForInitialization.then(() => { if (!args || !args[0] || args[0].length == 0) { // Get the cloud keyboard catalog @@ -373,7 +373,7 @@ export class KeymanEngine extends KeymanEngineBase { + public async addKeyboardsForLanguage(arg: string[]|string) : Promise<(KeyboardStub|ErrorStub)[]> { return this.config.deferForInitialization.then(() => { if (typeof arg === 'string') { return this.keyboardRequisitioner.addLanguageKeyboards(arg.split(',').map(item => item.trim())); @@ -497,7 +497,7 @@ export class KeymanEngine extends KeymanEngineBase