erabo/spiegel-keyman
1
0
Fork 0
mirror of https://github.com/keymanapp/keyman.git synced 2026-08-05 00:15:32 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 9

docs(web): improve documentation on addKeyboards/addKeyboardsForLanguage

Browse source 
Also improve types on signature of those functions.

Fixes: keymanapp/help.keyman.com#365
Build-bot: skip build:web
Test-bot: skip
This commit is contained in:
Eberhard Beilharz 2026-05-27 19:56:02 +02:00
parent 78ea935fe5
commit 47ec50bc2c
No known key found for this signature in database
GPG key ID: E9140597606020D3
4 changed files with 71 additions and 43 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

95
web/docs/engine/guide/adding-keyboards.md
View file

@ -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.
The easiest way to utilize a keyboard is to request it from the Keyman cloud.
```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.
});
### Requested from the CDN by keyboard name
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')
```
Custom fonts may also be utilized via the `language.font` property. For example:
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.
```c
font:{
family:'LaoWeb',
source:['../font/saysettha_web.ttf','../font/saysettha_web.woff','../font/saysettha_web.eot']
}
### Requested from the CDN by language name
To obtain the default Keyman keyboard for a given language, call the following function:
```typescript
await keyman.addKeyboardsForLanguage('Dzongkha');
```
## Requested from the CDN by language name
To obtain the default Keyman keyboard for a given language, call the following function.
```c
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:
```c
keyman.addKeyboards('french','sil_euro_latin@sv','sil_euro_latin@no')
```typescript
await keyman.addKeyboards('@fr$');
// or
await keyman.addKeyboardsForLanguage('French$');
```
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.
## 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-1.0.js' // A valid path to the compiled *.js file representing the keyboard.
});
```
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','../font/saysettha_web.eot']
}
}
```
[Previous: What is a Keyboard?](what-is-a-keyboard) | [Next: Additional Examples](examples/)

7
web/docs/engine/reference/core/addKeyboards.md
View file

@ -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...])
async 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,

6
web/docs/engine/reference/core/addKeyboardsForLanguage.md
View file

@ -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...])
async 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

6
web/src/app/browser/src/keymanEngine.ts
View file

@ -345,7 +345,7 @@ export class KeymanEngine extends KeymanEngineBase<BrowserConfiguration, Context
*
* See https://help.keyman.com/developer/engine/web/current-version/reference/core/addKeyboards
*/
public addKeyboards(...args: any[]): Promise<(KeyboardStub|ErrorStub)[]> {
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<BrowserConfiguration, Context
*
* See https://help.keyman.com/developer/engine/web/current-version/reference/core/addKeyboardsForLanguage
**/
public addKeyboardsForLanguage(arg: string[]|string) : Promise<(KeyboardStub|ErrorStub)[]> {
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<BrowserConfiguration, Context
*
* See https://help.keyman.com/developer/engine/web/current-version/reference/core/removeKeyboards
*/
public removeKeyboards(...x: string[]) {
public removeKeyboards(...x: string[]): boolean {
for(let i=0; i < x.length; i++) {
// This will completely forget the keyboard, requiring an async load operation to restore it again.
// `true` is responsible for this & is required to pass a variable-store unit test.