@donjohnston/cowriter-sdk-web

Co:Writer® SDK for Web

• Add accessibility/accommodation tools for writing quickly and easily.
• Where is Co:Writer SDK hosted
• Example of Co:Writer SDK basic integration into a web page
• Example of Co:Writer SDK basic integration without DOM scanning
• Example of Co:Writer SDK integration using all config parameters
• Co:Writer SDK API
  • dji.cowriter.setLicenceKey(licenseKey)
  • async dji.cowriter.initialize(config)
  • async dji.cowriter.enable()
  • async dji.cowriter.disable()
  • async dji.cowriter.attach(targets)
  • async dji.cowriter.detach(targets)
  • async dji.cowriter.resetState()
  • dji.cowriter.updateFeatures(features)
  • Customize the position of the Co:Writer icon
• Terms and Conditions
• License

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 [e-mail] with the subject line of "CW SDK" to get started.

© 2022 Don Johnston Inc.