EditorClient

---

Constructors

new EditorClient()

ts

new EditorClient(): EditorClient

Returns

EditorClient

---

Properties

callbacks

ts

protected readonly callbacks: Map<string, (value) => void | JsonSerializable | Promise<any>>;

---

Methods

actionExists()

ts

actionExists(name): boolean

Parameters

Parameter	Type	Description
name	string	name of the action to check

Returns

boolean

true if a callback has been registered for this action; false otherwise

---

alert()

ts

alert(
   text, 
   title?, 
   buttonText?): AlertResult

Display an alert modal to the user

Parameters

Parameter	Type	Description
text	string	Body text to display in the alert modal
title?	string	Title of the alert modal; defaults to the extension title specified in manifest.json
buttonText?	string	Text for the OK button; defaults to "OK" (or a translation)

Returns

AlertResult

a Promise that resolves true if the user clicks OK, false if they otherwise dismiss the modal

---

asyncOAuthXhr()

asyncOAuthXhr(providerName, request)

ts

asyncOAuthXhr(providerName, request): Promise<TextXHRResponse>

Make an asyncronous OAuth network request. The request is enqueued to eventually execute. The request may be attempted multiple times with
an overall timeout of 120 seconds.

Parameters

Parameter	Type	Description
providerName	string	Name of the OAuth provider
request	OAuthXHRRequest & object	Settings for the request

Returns

Promise<TextXHRResponse>

A promise that will either resolve or reject with an XHRResponse. If the HTTP status
code is not 2xx, the promise will reject.

asyncOAuthXhr(providerName, request)

ts

asyncOAuthXhr(providerName, request): Promise<BinaryXHRResponse>

Parameters

Parameter	Type
providerName	string
request	OAuthXHRRequest & object

Returns

Promise<BinaryXHRResponse>

asyncOAuthXhr(providerName, request)

ts

asyncOAuthXhr(providerName, request): Promise<XHRResponse>

Parameters

Parameter	Type
providerName	string
request	OAuthXHRRequest

Returns

Promise<XHRResponse>

---

awaitDataImport()

ts

awaitDataImport(
   dataConnectorName, 
   syncDataSourceId, 
   syncCollectionId, 
   primaryKeys, 
timeout): Promise<CollectionProxy>

Parameters

Parameter	Type	Default value
dataConnectorName	string	undefined
syncDataSourceId	undefined | string	undefined
syncCollectionId	string	undefined
primaryKeys	string[]	undefined
timeout	number	30000

Returns

Promise<CollectionProxy>

---

canEditPackageSettings()

ts

canEditPackageSettings(): Promise<boolean>

Returns

Promise<boolean>

True if the current user is allowed to edit package settings on this installation
of this extension (if any settings exist), or false otherwise.

---

confirm()

ts

confirm(
   text, 
   title?, 
   okText?, 
   cancelText?): ConfirmResult

Display a confirm modal to the user

Parameters

Parameter	Type	Description
text	string	Body text to display in the alert modal
title?	string	Title of the alert modal; defaults to the extension title specified in manifest.json
okText?	string	Text for the OK button; defaults to "OK" (or a translation)
cancelText?	string	Text for the Cancel button; defaults to "Cancel" (or a translation)

Returns

ConfirmResult

a Promise that resolves true if the user clicks OK, false if they click Cancel or otherwise dismiss the modal

---

createUserImage()

ts

createUserImage(mediaType, data): Promise<string>

Upload an image and return a URL that can be used for displaying that image on the canvas. Note: the URL is
public - anyone with the URL can access the image.

Parameters

Parameter	Type	Description
mediaType	string	The media type, e.g. 'image/png'
data	string | Uint8Array	The binary image contents, or a base64-encoded string

Returns

Promise<string>

A promise that resolves with the URL of the created image.

---

deleteAction()

ts

deleteAction(name): void

Remove the callback for a given action. If the action is later invoked, nothing will happen.

Parameters

Parameter	Type	Description
name	string	name of the action to unregister

Returns

void

---

download()

ts

download(
   filename, 
   data, 
   mime, 
   base64): void

Initiate a browser file download of custom content

Parameters

Parameter	Type	Description
filename	string	Filename of the downloaded file
data	string	The content to put into the file, either in plain text or as base64-encoded binary data
mime	string	The MIME type to tell the browser it is downloading
base64	boolean	If true, base64 decode the data before downloading it

Returns

void

---

duplicatePages()

ts

duplicatePages(pageNums): Promise<void>

Duplicates one or more pages of the current document as new pages.

Parameters

Parameter	Type	Description
pageNums	number[]	An array of zero-indexed page indices to duplicate from the current document

Returns

Promise<void>

a promise that resolves to void when the pages have been duplicated or the
the duplication failed

---

getBlockProxy()

ts

getBlockProxy(id): BlockProxy

Create and return a proxy for accessing a block with the given ID. If the block is of a type that has a specific
proxy implementation (e.g. an ERD block) then a specialized subclass of BlockProxy may be returned.

Parameters

Parameter	Type	Description
id	string	ID of the block to create a proxy for

Returns

BlockProxy

the given block

---

getCustomShapeDefinition()

ts

getCustomShapeDefinition(library, shape): Promise<undefined | BlockDefinition>

Load the requested shape library's content, and if it was found, return a block definition ready to be
created.

Example usage:

inline:typescript

const client = new EditorClient();
const viewport = new Viewport(client);

const page = viewport.getCurrentPage();
if (page) {
    const def = await page.getCustomShapeDefinition('libraryName', 'shapeName');
    if (def) {
        //Customize the shape about to be created
        def.boundingBox.x = 500;
        def.boundingBox.y = 500;

        //Create the shape itself
        const block = page.addBlock(def);

        //Set any data fields on the shape as needed
        block.shapeData.set('Value', 50);
    }
}

Parameters

Parameter	Type	Description
library	string	Name of the shape library in this extension to search for
shape	string	Name of the shape within that library to search for

Returns

Promise<undefined | BlockDefinition>

---

getElementProxy()

ts

getElementProxy(id): ElementProxy

Parameters

Parameter	Type	Description
id	string	ID of the element to create a proxy for

Returns

ElementProxy

the given element

---

getItemProxy()

ts

getItemProxy(id): BlockProxy | LineProxy | GroupProxy

Parameters

Parameter	Type	Description
id	string	ID of the item to create a proxy for

Returns

BlockProxy | LineProxy | GroupProxy

the given item

---

getLineProxy()

ts

getLineProxy(id): LineProxy

Parameters

Parameter	Type	Description
id	string	ID of the line to create a proxy for

Returns

LineProxy

the given line

---

getOAuthClientId()

ts

getOAuthClientId(providerName): Promise<undefined | string>

Fetch the OAuth Client Id if there is one

Parameters

Parameter	Type	Description
providerName	string	Name of the OAuth provider

Returns

Promise<undefined | string>

A oauth client id or undefined if it doesn't exist

---

getOAuthToken()

ts

getOAuthToken(providerName): Promise<undefined | string>

Returns an OAuth token for the given provider, prompting the user to grant access if necessary

Parameters

Parameter	Type	Description
providerName	string	Name of the OAuth provider

Returns

Promise<undefined | string>

An oauth token, or undefined if a valid token cannot be obtained

---

getPackageSettings()

ts

getPackageSettings(): Promise<Map<string, JsonSerializable>>

If the extension package containing this editor extension has configurable settings,
fetch the current values of those settings for this installation of this extension.

Only settings that have been set by the installing user will have a value in the map,
other settings will be missing.

Returns

Promise<Map<string, JsonSerializable>>

A promise that resolves to a map of setting names to current setting values

---

getPageProxy()

ts

getPageProxy(id): PageProxy

Parameters

Parameter	Type	Description
id	string	ID of the page to create a proxy for

Returns

PageProxy

the given page

---

getProduct()

ts

getProduct(): LucidProduct

Get which Lucid product this editor extension has been loaded in.

Returns

LucidProduct

---

importPage()

ts

importPage(documentId, pageNums): Promise<void>

Import one or pages of the specified document or template into the current document
as new pages.
NOTE: The indices of the pages to import will change if the pages are rearranged
on the source document or template.

Parameters

Parameter	Type	Description
documentId	string	The ID of the document or template to import
pageNums	number[]	An array of zero-indexed page indices to import from the document or template

Returns

Promise<void>

a promise that resolves to void when the pages have been imported or the
the import failed

---

killExtension()

ts

killExtension(): void

Unload this extension immediately, removing any custom menu items etc., until the user refreshes the browser tab.

Returns

void

---

loadBlockClasses()

ts

loadBlockClasses(classNames): Promise<undefined>

Because code for block classes are loaded incrementally, you MUST call
loadBlockClasses with the given block class name (and wait for it to
resolve) before attempting to create a block. If you don't, an error
will be thrown.

Parameters

Parameter	Type	Description
classNames	string[]	the block classes to load

Returns

Promise<undefined>

a promise that resolves when the block classes can be used to create new blocks on the document

---

oauthXhr()

oauthXhr(providerName, request)

ts

oauthXhr(providerName, request): Promise<TextXHRResponse>

Make an OAuth network request. Make the request immediately and only once with a 10 second timeout.

Parameters

Parameter	Type	Description
providerName	string	Name of the OAuth provider
request	OAuthXHRRequest & object	Settings for the request

Returns

Promise<TextXHRResponse>

A promise that will either resolve or reject with an XHRResponse. If the HTTP status
code is not 2xx, the promise will reject.

oauthXhr(providerName, request)

ts

oauthXhr(providerName, request): Promise<BinaryXHRResponse>

Parameters

Parameter	Type
providerName	string
request	OAuthXHRRequest & object

Returns

Promise<BinaryXHRResponse>

oauthXhr(providerName, request)

ts

oauthXhr(providerName, request): Promise<XHRResponse>

Parameters

Parameter	Type
providerName	string
request	OAuthXHRRequest

Returns

Promise<XHRResponse>

---

performDataAction()

ts

performDataAction(options): Promise<DataActionResponse>

Parameters

Parameter	Type
options	DataActionOptions

Returns

Promise<DataActionResponse>

---

permanentTokenXhr()

permanentTokenXhr(providerName, request)

ts

permanentTokenXhr(providerName, request): Promise<BinaryXHRResponse>

Parameters

Parameter	Type
providerName	string
request	XHRRequest & object

Returns

Promise<BinaryXHRResponse>

permanentTokenXhr(providerName, request)

ts

permanentTokenXhr(providerName, request): Promise<XHRResponse>

Parameters

Parameter	Type
providerName	string
request	XHRRequest

Returns

Promise<XHRResponse>

---

processAndClearBootstrapData()

ts

processAndClearBootstrapData(callback, markExtensionAsRequired?): Promise<void>

Parameters

Parameter	Type	Description
callback	(data) => void | Promise<void>	A callback that processes the bootstrap data, if any, stored on the document and associated with this editor extension. If this callback is async (returns a promise), then the bootstrap data is not cleared off of the document until that promise resolves.
markExtensionAsRequired?	boolean	If bootstrap data is available for this editor extension, this will mark the document as requiring the extension. Once marked, if the extension is not installed the user will be notified about the extension being required on document load. The minimum extension version required by the document is the version provided in the request body when creating the document.

Returns

Promise<void>

a promise that resolves immediately if there is no available bootstrap data, or else after
the callback successfully completes. This promise will reject/throw if the callback throws or
returns a promise that rejects, or if there is another editor session processing the same bootstrap
data at the same time.

---

prompt()

ts

prompt(text, title?): PromptResult

Display a prompt modal to the user

Parameters

Parameter	Type	Description
text	string	Body text to display in the alert modal
title?	string	Title of the alert modal; defaults to the extension title specified in manifest.json

Returns

PromptResult

a Promise that resolves to a string if a user enters one, or undefined if they cancel

---

registerAction()

ts

registerAction(name, callback): void

Register a named action. These actions can be triggered from custom UI, for example as the action of a
custom menu item.

Some actions may return a value that is used by the core application, e.g. a visibleAction for a menu
item. However, if you return a Promise from your callback, that value will be discarded and your
action will return undefined instead. The ability to provide a callback that returns a Promise is only
a convenience so that you can register actions with async callbacks for easy async/await.

Throws an error if the same action name is registered multiple times.

Parameters

Parameter	Type	Description
name	string	name of the action
callback	(value) => void | JsonSerializable | Promise<any>	function to execute when this action is invoked

Returns

void

---

registerFileUploadAction()

ts

registerFileUploadAction(name, callback): void

Register a named action that receives file upload data. These callbacks can be used in
Menu.addMenuItem as the file action.

Parameters

Parameter	Type	Description
name	string	The name of the action
callback	(files) => void	Function to execute when this action is invoked

Returns

void

---

registerUnfurlHandler()

ts

registerUnfurlHandler(domain, callbacks): void

Registers a handler for link unfurling.

Parameters

Parameter	Type	Description
domain	string	The domain
callbacks	UnfurlCallbacks	The callbacks to call when a link matching the domain is pasted.

Returns

void

---

reloadExtension()

ts

reloadExtension(): void

Unload this extension, and then re-execute it.

Returns

void

---

sendCommand()

ts

sendCommand<C>(name, params): CommandArgs[C]["result"]

Execute an API command. This is the low-level API that most of this SDK wraps. It is not expected that you should
ever need to use this directly.

Type parameters

Type parameter
C extends CommandName

Parameters

Parameter	Type	Description
name	C	name of the API command to execute
params	UnionToIntersection<CommandArgs[C]["query"]>	data to pass to the API command

Returns

CommandArgs[C]["result"]

the output of the given API command

---

setPackageSettings()

ts

setPackageSettings(settings): Promise<undefined>

If the extension package containing this editor extension has configurable settings, set the
value of those settings for this installation of this extension. A subset of setting values
can be provided to update those values while leaving others unchanged.

If the user does not have permission to change settings on this installation of this
extension, or if no settings exist, an error is thrown.

Parameters

Parameter	Type
settings	Record<string, string> | Map<string, string>

Returns

Promise<undefined>

---

showPackageSettingsModal()

ts

showPackageSettingsModal(): Promise<void>

If the extension package containing this editor extension has configurable settings,
show a standard modal allowing the user to view or change those settings.

If the user does not have permission to change settings on this installation of this
extension, or if no settings exist, an error is thrown.

Returns

Promise<void>

A promise that resolves when the user closes the settings modal.

---

triggerAuthFlow()

ts

triggerAuthFlow(providerName): TriggerAuthFlowResult

Parameters

Parameter	Type
providerName	string

Returns

TriggerAuthFlowResult

---

tryGetItemProxy()

ts

tryGetItemProxy(id): undefined | BlockProxy | LineProxy | GroupProxy

Parameters

Parameter	Type	Description
id	string	ID of the item to create a proxy for

Returns

undefined | BlockProxy | LineProxy | GroupProxy

the given item, or undefined if the item does not exist or an error occurs

---

withIntraDocumentMutex()

ts

withIntraDocumentMutex(name, callback): Promise<boolean>

Executes the given callback within a mutex scoped to the current document, extension, and the given name.
If another editor session currently has the given mutex name locked within the same extension package ID
on this same document, this function's returned promise will resolve to false. Otherwise, the mutex will
be locked for the duration of the callback and the returned promise will resolve to true.

Parameters

Parameter	Type	Description
name	string	Name of the intra-document mutex to attempt to lock
callback	() => void | Promise<void>	Code to execute while the mutex is locked, if it is successfully locked

Returns

Promise<boolean>

A promise resolving to a boolean indicating whether the mutex was successfully locked

---

withSilentActions()

ts

withSilentActions(callback): void

Parameters

Parameter	Type	Description
callback	() => void	Callback that will be executed with the user's local undo/redo history suppressed. This is useful when you want to make changes to a document that will not be erased if the user uses undo or redo, for example adding shape data onto shapes as a result of a background process that collects data from a remote API.

Returns

void

---

xhr()

xhr(request)

ts

xhr(request): Promise<TextXHRResponse>

Make a network request

Parameters

Parameter	Type	Description
request	XHRRequest & object	Settings for the network request

Returns

Promise<TextXHRResponse>

A promise that will either resolve or reject with an XHRResponse. If the HTTP status
code is not 2xx, the promise will reject.

xhr(request)

ts

xhr(request): Promise<BinaryXHRResponse>

Parameters

Parameter	Type
request	XHRRequest & object

Returns

Promise<BinaryXHRResponse>

xhr(request)

ts

xhr(request): Promise<XHRResponse>

Parameters

Parameter	Type
request	XHRRequest

Returns

Promise<XHRResponse>