@donjohnston/cowriter-sdk-web

1.1.7-beta.8 • Public • Published

Co:Writer® SDK for Web

Add accessibility/accommodation tools for writing quickly and easily.

Use speech-to-text and/or word prediction to support writers' needs. Runs on any Chromium, Safari, or Firefox based browser that supports WebAssembly.

Where is Co:Writer SDK hosted

Co:Writer SDK can be used directly from Don Johnston Inc. CDN, or it can be hosted on integrator's CDN.

Snippet for Don Johnston Inc. CDN:

<script src="https://cdn.donjohnston.net/cowriter/sdk/1.1.7-beta.8/cowriter.js"></script>

Snippet for integrator's CDN:

<script src="<YOUR-CUSTOM-PATH>/cowriter.js""></script>

Example of Co:Writer SDK basic integration into a web page

<script src="<YOUR-CUSTOM-PATH>/cowriter.js"></script>

<script>
    dji.cowriter.setLicenseKey("...");

    dji.cowriter.initialize({
        sdkMode: true
    });
    
    dji.cowriter.enable();
</script>

Example of Co:Writer SDK basic integration without DOM scanning

<script src="<YOUR-CUSTOM-PATH>/cowriter.js"></script>

<script>
    const Config = {
        sdkMode: true,
        features: {
            autoScan: false,            // Auto detect the editable fields by scanning the DOM. Default value is true.
        }
    };

    async function runWorkflow() {
        dji.cowriter.setLicenseKey("...");

        await dji.cowriter.initialize(Config);

        await dji.cowriter.enable();

        await dji.cowriter.attach(document.querySelector("#some-editor-id"));

        // ... and later

        await dji.cowriter.detach(document.querySelector("#some-editor-id"));

        await dji.cowriter.disable();
    }
    
    runWorkflow();
</script>

Example of Co:Writer SDK integration using all config parameters

<script src="<YOUR-CUSTOM-PATH>/cowriter.js"></script>

<script>
    const Config = {
        sdkMode: true,
        language: "en-US",  // Prediction and TTS language. Possible values are: "en-US", "es-ES". Default value is "en-US".
        features: {
            autoScan: true,             // Auto detect the editable fields by scanning the DOM. Default value is true.
            prediction: true,           // Activate or deactivate the Word Prediction feature. Possible values are: true, false. Default value is true.
            tts: true,                  // Activate or deactivate the TTS feature. Possible values are: true, false. Default value is true.
            speechRecognition: true     // Activate or deactivate the Speech Recognition feature. Possible values are: true, false. Default value is true.
        },
        settings: {
            prediction: {
                mode:               "advanced", // Prediction mode. Possible values are: "basic", "advanced". Default value is "advanced".
                mainDictionary:     "40k",      // Prediction main dictionary. Possible values are "40k", "12k", "6k", "3k", "1k", "0k". Default value is "40k".
                guesses:            5,          // The maximum number of displayed guesses. Possible values are between 1 and 9. Default value is 5.
                momentaryTopic:     true,       // Predict from page. Default value is true.
                ahead:              true,       // Predict ahead. Default value is true.
                flexibleSpelling:   true,       // Flexible spelling. Default value is true.
                grammar:            true,       // Grammar. Default value is true.
                autoCapitalization: false       // Auto capitalization. Default value is false.
            },
            predictionWindow: {
                fontFamily:         "Verdana",  // Font family. Default value is "Verdana".
                fontSize:           24,         // Font size, in percents. Possible values are between 0% and 100%. Default value is 24%.
                textColor:          "#000000",  // Text color, in hexadecimal format. Default value is "#000000" (white).
                backgroundColor:    "#FFFFFF"   // Background color, in hexadecimal format. Default value is "#FFFFFF" (black).
            },
            speech: {
                voice:      null,   // Voice name. Can be any supported voice name. Default is null.
                volume:     100,    // Speech volume, in percents. Possible values are between 0% and 100%. Default value is 100%.
                rate:       50,     // Speech rate, in percents. Possible values are between 0% and 100%. Default value is 50%.
                pitch:      50,     // Speech pitch, in percents. Possible values are between 0% and 100%. Default value is 50%.
                letters:    false,  // Speak the typed letter. Default value is false.
                words:      true,   // Speak the typed word. Default value is true.
                sentences:  true,   // Speak the typed sentence. Default value is true.
            }
        }
    };

    async function runWorkflow() {
        dji.cowriter.setLicenseKey("...");

        await dji.cowriter.initialize(Config);

        await dji.cowriter.enable();

        // If you set Config.features.autoScan to false, you can programmatically attach Co:Writer to text editors.
        // await dji.cowriter.attach(document.querySelector("#some-editor-id"));

        // ... and later

        // If you set Config.features.autoScan to false, you can programmatically detach Co:Writer from text editors.
        // await dji.cowriter.detach(document.querySelector("#some-editor-id"));

        await dji.cowriter.disable();
    }

    runWorkflow();
</script>

Co:Writer SDK API

dji.cowriter.setLicenceKey(licenseKey)

Set the license key for Co:Writer SDK.

Parameter Type Optional Description Possible values Default value
licenseKey String No The license key. - -

Notes:

  • dji.cowriter.initialize(...) must be called before with features.autoScan set to false.

async dji.cowriter.initialize(config)

Initialize Co:Writer SDK with the desired configuration.

Parameter Type Optional Description Possible values Default value
config Object No An object with one or more of the following properties: - -
config.sdkMode Boolean No Initialize Co:Writer SDK to work as a standalone SDK. - false
config.sdkRoot String Yes* The location of Co:Writer SDK. It can be an absolute location or a relative location to the current web page.
* If cowriter.js is loaded using eval, than this parameter must be set.
Example: "https://cdn.donjohnston.net/cowriter/sdk/1.1.7-beta.8/"
- undefined
[config.language] String Yes Prediction and TTS language. en-US, es-ES en-US
[config.features] Object Yes Co:Writer main features. - undefined
[config.features.autoScan] Boolean Yes Auto detect the editable fields by scanning the DOM. - true
[config.features.showIconForAttachedEditors] Boolean Yes When autoScan is set to false, this flag controls the CoWriter icon visibility when attached editors gain focus. When autoScan is set to true, this flag is ignored. - false
[config.features.prediction] Boolean Yes Activate or deactivate the Word Prediction feature. - true
[config.features.tts] Boolean Yes Activate or deactivate the TTS feature. - true
[config.features.speechRecognition] Boolean Yes Activate or deactivate the Speech Recognition feature. - true
[config.settings] Object Yes Co:Writer main settings. - undefined
[config.settings.prediction] Object Yes Co:Writer prediction settings. - undefined
[config.settings.prediction.mainDictionary] String Yes Prediction mode. The basic mode is available only for English. basic, advanced advanced
[config.settings.prediction.mode] String Yes Prediction main dictionary. 40k, 12k, 6k, 3k, 1k, 0k 40k
[config.settings.prediction.guesses] Number Yes The maximum number of displayed guesses. [1..9] 5
[config.settings.prediction.momentaryTopic] Boolean Yes Predict from page. - true
[config.settings.prediction.ahead] Boolean Yes Predict ahead. - true
[config.settings.prediction.flexibleSpelling] Boolean Yes Flexible spelling. - true
[config.settings.prediction.grammar] Boolean Yes Grammar. - true
[config.settings.prediction.autoCapitalization] Boolean Yes Auto capitalization. - true
[config.settings.predictionWindow] Object Yes Co:Writer prediction window settings. - undefined
[config.settings.predictionWindow.fontFamily] String Yes Font family. Any supported font family. Verdana
[config.settings.predictionWindow.fontSize] Number Yes Font size, in percents. [0%..100%] 24%
[config.settings.predictionWindow.textColor] String Yes Text color, in hexadecimal format. Any supported color. #000000
[config.settings.predictionWindow.backgroundColor] String Yes Background color, in hexadecimal format. Any supported color. #FFFFFF
[config.settings.speech] Object Yes Co:Writer speech settings. - undefined
[config.settings.speech.voice] String Yes Voice name. Any supported voice name. No default value. We used whatever the default voice is.
[config.settings.speech.volume] Number Yes Speech volume, in percents. [0%..100%] 100%
[config.settings.speech.rate] Number Yes Speech rate, in percents. [0%..100%] 50%
[config.settings.speech.pitch] Number Yes Speech pitch, in percents. [0%..100%] 50%
[config.settings.speech.letters] Boolean Yes Speak the typed letter. - false
[config.settings.speech.words] Boolean Yes Speak the typed word. - true
[config.settings.speech.sentences] Boolean Yes Speak the typed sentence. - true
returns Promise

async dji.cowriter.enable()

Enable Co:Writer in a web page.

When Co:Writer is enabled, its icon will be displayed when an editor has focus, and the users can turn it on/off.

Notes:

  • dji.cowriter.initialize(...) must be called before.
  • if Co:Writer has been initialized with features.autoScan set to false, the icon will not appear.

async dji.cowriter.disable()

Disable Co:Writer in a web page.

When Co:Writer is disabled, its icon will NOT be displayed, and the users don't have access to it. Also, its Web Worker is not running.

Notes:

  • dji.cowriter.initialize(...) must be called before.

async dji.cowriter.attach(targets)

Attach Co:Writer to some editors in the current web page.

Parameter Type Optional Description Possible values Default value
targets HTMLElement,String,[HTMLElement,string] No The targets can be a HTMLElement, a selector, or an array of HTMLElements and selectors. - -
returns Promise

Notes:

  • dji.cowriter.initialize(...) must be called before with features.autoScan set to false.

async dji.cowriter.detach(targets)

Detach Co:Writer from some editors, or all editors, in the current web page.

Parameter Type Optional Description Possible values Default value
[targets] HTMLElement,String,[HTMLElement,string] Yes The targets can be a HTMLElement, a selector, or an array of HTMLElements and selectors. If not specified, Co:writer will be detached from all attached editors. - -
returns Promise

Notes:

  • dji.cowriter.initialize(...) must be called before with features.autoScan set to false.

async dji.cowriter.resetState()

Reset the state of the prediction engine.

Notes:

  • dji.cowriter.initialize(...) must be called before.

dji.cowriter.updateFeatures(features)

Update Co:Writer features.

Parameter Type Optional Description Possible values Default value
features Object No An object with one or more of the following properties: - -
[features.prediction] Boolean Yes Activate or deactivate the Word Prediction feature. - true
[features.tts] Boolean Yes Activate or deactivate the TTS feature. - true
[features.speechRecognition] Boolean Yes Activate or deactivate the Speech Recognition feature. - true
returns Promise

Notes:

  • dji.cowriter.initialize(...) must be called before.

Customize the position of the Co:Writer icon

The position of the Co:Writer icon can be customized using the CSS variables in the example below.

:root {
    --dji-cowriter-sdk-position-bottom: 20px;
    --dji-cowriter-sdk-position-right: 20px;
}

Terms and Conditions

See Terms and Conditions: Co:Writer® SDK for Web in TERMS-AND-CONDITIONS.md file.

License

Co:Writer SDK is a commercial product, and licensing arrangements can be made through Don Johnston Incorporated. We're happy to work with you to evaluate the integration into your product(s). Please email developer@donjohnston.com with the subject line of "CW SDK" to get started.

© 2022 Don Johnston Inc.

Package Sidebar

Install

npm i @donjohnston/cowriter-sdk-web

Weekly Downloads

7

Version

1.1.7-beta.8

License

SEE LICENSE IN LICENSE.md

Unpacked Size

109 MB

Total Files

14

Last publish

Collaborators

  • bbogdan-texthelp
  • ryangr-texthelp
  • donjohnstoninc