Skip to main content

Frontend Documentation

The Sapling JavaScript SDK enables easy integration of Sapling's functionality -- such as grammar/spell checking and autocomplete -- in any web application.

SDK Demo

Sapling.init​

Sapling.init({
    endpointHostname: 'https://localhost:3000',
    lang: 'en',
    mode: 'prod'
});

init instantiates the SDK.

key - String

Sapling API key. DO NOT set this in JavaScript except for internal development.

mode - String

One of dev (during which the API key can be set inline) or prod (where API key should be set in backend). Refer to the JavaScript quickstart for a more detailed explanation of this parameter.

userId - Optional String

This allows you to see accurate counts of your end users on Sapling dashboards. If not passed in, Sapling will assign an anonymized ID for this browser.

isAnonUser - Optional Boolean

If you wish to explicitly assign your own anonymous IDs for logged out users, you can set this argument to true. By default, this will be set to false if you're passing in a userId.

endpointHostname - String

Use your own backend hostname like the example in Quickstart.

saplingPathPrefix - String

If your backend handles other routes, you can prefix the SDK endpoints with a path. For example, for the following init call,

 Sapling.init({
    endpointHostname: 'http://127.0.0.1:5000',
    saplingPathPrefix: '/sapling',
  });

edit requests will be routed to http://127.0.0.1:5000/sapling/api/v1/edits

editPathname - String

Use your own backend endpoint pathname like the example in Quickstart. Note that this does not have to be a full edits endpoint; you can also use a Sapling spellcheck endpoint to only display spellcheck edits.

statusBadge - Boolean

When set to true, will display a small blue status dot in the bottom right corner of observed text fields. The badge will spin to indicate that the text is being processed. We recommend turning this on for a better user experience, except when there are many (such as 10 or more) text fields on a single page and that many badges might be distracting.

See additional information for style customization here.

lang - String

Supported Languages

Specifies language for grammar and spell checking. Defaults to English, or the language specified in the dashboard.

Supported languages:

  • auto: Autodetect language
  • de: German (Deutsch)
  • el: Greek (Ελληνικά)
  • en: English (US/UK/CA/AU)
  • es: Spanish (Español)
  • fr: French (Français) (fr-fr and fr-ca coming soon)
  • it: Italian (Italiano)
  • jp: Japanese (日本語)
  • ko: Korean (한국어)
  • nl: Dutch (Nederlands)
  • pl: Polish (Polski)
  • pt: Portuguese (Português) (pt-pt and pt-br coming soon)
  • sv: Swedish (Svenska)
  • tl: Tagalog
  • zh: Chinese (中文)

variety - String

Supported Varieties

This option is currently available for: English, Chinese (中文). Specifies regional English/Chinese spelling options. The setting defaults to the configuration in the Sapling dashboard.

Supported varieties:

English:

  • us-variety: American English
  • gb-variety: British English
  • au-variety: Australian English
  • ca-variety: Canadian English
  • null-variety: Don’t suggest any changes based on English variety

Chinese (中文)

  • s-variety: Simplified Chinese
  • t-variety: Traditional Chinese

neuralSpellcheck - Optional Boolean

Default is false. If true, system will also apply more aggressive spellcheck to catch more spelling errors than the base system alone.

operations - Optional List of Strings

Default is []. Possible operations are described in the Postprocess documentation. This will run postprocessing on outputs before returning results so you can enforce stricter capitalization, punctuation, and whitespace removal.

medical - Optional Boolean

Default is false. If true, the backend will apply Sapling's medical dictionary. You can test the medical spellcheck system here.

autocomplete - Boolean

When set to true, will use Sapling's autocomplete language model to suggest sentence autocompletions as a user is typing.

ignoreText - String

String to use in place of Ignore in Sapling's inline edit suggestions.

headers - Dictionary

Use this argument to specify custom headers for calls to your own backend. The dictionary should consist of key-value mappings ({"key": "value"}).

  • key: request header name (e.g., Authorization)
  • value: header value (e.g., Bearer xxxxxxxxxxx)

advancedEdits - Dictionary

Examples of advanced edits can be found here

Advanced Edit Options

Options for advanced edits. Option keys are String, and option values are Boolean.

  • advanced_edits: Group setting, covering all the options below

  • adverbs

  • simplifications

  • hard_to_read

  • qualifiers

  • voice

  • dei: Group setting, covering all DEI options below

  • gender: Group setting, covering gender_pronoun, gender_noun, and gender_id

  • gender_pronoun

  • gender_noun

  • gender_id

  • sensitivity

  • disability

  • age

  • race

  • social_class

  • violence

A group setting marked false will disable all categories it covers.

autoShowAnnotations - Boolean

When set to true, will show advanced edits by default. Otherwise, the edits will only appear after toggling them on from the status badge.

Sapling.observe​

const editable = document.getElementById('editor');
Sapling.observe(editable);

observe takes a single argument, a textarea or contenteditable. The SDK will check text in the dom element in real time and apply edit suggestions.

Mark elements that will be observed by the JavaScript SDK with the attribute sapling-ignore="true" to prevent duplicate interactions with the Sapling browser extension. Mark elements inside a contenteditable with data-sapling-ignore="true" to prevent the dom node from being processed by Sapling.

Sapling.unobserve​

const editable = document.getElementById('editor');
Sapling.unobserve(editable);

unobserve takes a single argument, a textarea or contenteditable. This will remove edit suggestions and stop any checking on a previously observed element.

Sapling.checkOnce​

const editable = document.getElementById('editor');
Sapling.checkOnce(editable);

checkOnce takes a single argument, a textarea or contenteditable.

This function is only recommended for internal use.

Sentences that have not been changed are cached locally and do not count towards bandwidth and API usage more than once. However, SDK users may choose not to trigger text checks in real time for additional bandwidth or API usage savings.

note

Edit markup is applied to the text using DOM Range objects. While they typically update in location with text, depending on changes in text, individual edits may no longer be accurate after the text has been changed, and may result in a confusing user experience.

Deploying to Production​

There are several methods of deploying Sapling's SDK without exposing your private API Key. These can be found here:

  1. Proxying requests through your backend
  2. Authentication with a JWT key