TextSync JavaScript Reference

Constructor

new TextSync(instanceConfig);

Takes a single instanceConfig argument - an options argument with the following keys:

  • instanceLocator : string (required) - Unique ID of your TextSync service instance. Get this from yourdashboard.

  • debug: boolean(default: false) - Enable more verbose logging
const textSyncInstance = new TextSync({
  instanceLocator: "YOUR_INSTANCE_LOCATOR",
});

TextSync Instance

A connected instance of TextSync. Includes the following methods:

createEditor

Creates an instance of the TextSync editor and injects it into the DOM.

createEditor(editorConfig)

Returns

A promise which resolves to a TextSync editor instance.

Arguments

Takes a single editorConfig argument - an options object with the following keys

Required Keys

  • element: string orHTMLElement - DOM element that will contain the editor. May be either a CSS selector or a reference to the element object.
  • docId: string - The ID of the document that should be loaded into the editor on creation.
  • authEndpoint: string - The URL of the endpoint on the customer server where the library can obtain authorization tokens. See authorization for more information.

Optional Keys

  • userName: string - User's name, to be displayed to other users in the same editing session. If not provided, the system will generate a random name to represent the user.

  • userEmail: string - User's email address.

  • richText: boolean (default:true) - Enable rich text features and the editor toolbar. If false, only plain text may be entered in to the editor.

  • cursors: boolean (default:true) - Display the cursor positions of other users who are editing the same document.

  • cursorLabelsAlwaysOn: boolean (default:false) - Always display the full cursor label above other users' cursors. When false, the full label is only displayed on mouse hover.

  • collaboratorBadges: boolean (default: true) - Display a bar of badges above the editor, one for each user connected to the document.

  • errorNotifications: boolean (default: true) - Display error notifications (e.g. connection status) using toasts in the top right of the browser window.

  • defaultText: string - If provided, and the document loaded in to the editor is empty, this text will be used to initialise the contents of the document.

  • onCollaboratorsJoined: ([user]) => { ... } - Called when new user(s) joins the document session. See callback arguments for a description of the arguments passed to the function.

  • onCollaboratorsLeft: ([user]) => { ... } - Called whenever user(s) leave the document session. See callback arguments for a description of the arguments passed to the function.

  • onError: (error) => { ... } - Called whenever an error occurs with the TextSync editor or connection. See callback arguments for a description of the arguments passed to the function.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
const textSyncInstance = new TextSync({
  instanceLocator: "YOUR_INSTANCE_LOCATOR",
});

textSyncInstance.createEditor({
  docId: "DOCUMENT_ID",
  element: "#editor",
  authEndpoint: "http://example.com/textsync/tokens",
  userName: "Ada Lovelace",
  userEmail: "ada@lovelace.com"
})
.then(editor => {
  console.log("Ready to TextSync!");
});

Editor Instance

An instance of a TextSynceditor which allows you to interact with the TextSync editor programatically. Includes the following methods:

getText

Retrieve characters from the document as a string

getText(index, length)

Returns

A string representation of the document content.

Optional Arguments

  • index : number: (default: 0) - the character index from which you want to retrieve from.
  • length : number: (default: the length of the document) - the number of characters to retrieve

getContents

Retrieve contents of the document, including styles

getContents(index, length)

Returns

An array of objects representing document content and styles. Each object contains the following keys:

  • text: string - a string representation of a section of the document

  • attributes: object - an object representing the styling attributes applied to the section of the document contained in text.

    Each attributes object can contain the following keys:

    • underline: boolean

    • strikethrough: boolean

    • bold: boolean

    • italic: boolean

Optional Arguments

  • index : number: (default: 0) - the character index from which you want to retrieve from.
  • length : number: (default: the length of the document) - the number of characters to retrieve

Destroy

Remove the editor instance from the DOM and close the subscription

destroy()

Callback Arguments

User

When supplying onCollaboratorsJoined or onCollaboratorsLeft to createEditor, the callback functions provided will be called with a single argument - an array of one or more user objects, each with the following keys:

  • name: string - Display name of the user, only given when the user has just joined.

  • avatar: string - URL for the user's avatar, only given when the user has just joined.

  • siteId: number - Unique identifier for the user's session.

  • timestamp: string - ISO 8601 specifying the time when the user joined the document.

Error

When supplying an onError function to createEditor, the callback functions the function will be called with a single argument - an error object including the following keys:

  • notificationType: string - Severity of the notification to be displayed. May be error, warning or info.

  • message: string - Human readable string to be displayed to the user by the notification.

Did you find this document useful?

We are always striving to create the most accurate and informative docs as possible. If there is something especially wrong (or right) here then please let us know.