EditorClient

Constructors

new EditorClient()

new EditorClient(): EditorClient

Returns

EditorClient

Properties

callbacks

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

Methods

actionExists()

actionExists(name): boolean

Parameters

Returns

boolean

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

alert()

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

Display an alert modal to the user

Parameters

Returns

AlertResult

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

asyncOAuthXhr()

asyncOAuthXhr(providerName, request)

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

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)

asyncOAuthXhr(providerName, request): Promise<BinaryXHRResponse>

Parameters

Returns

Promise<BinaryXHRResponse>

asyncOAuthXhr(providerName, request)

asyncOAuthXhr(providerName, request): Promise<XHRResponse>

Parameters

Returns

Promise<XHRResponse>

awaitDataImport()

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

Parameters

Returns

Promise<CollectionProxy>

canEditPackageSettings()

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()

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

Display a confirm modal to the user

Parameters

Returns

ConfirmResult

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

createUserImage()

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

Returns

Promise<string>

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

deleteAction()

deleteAction(name): void

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

Parameters

Returns

void

download()

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

Initiate a browser file download of custom content

Parameters

Returns

void

duplicatePages()

duplicatePages(pageNums): Promise<void>

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

Parameters

Returns

Promise<void>

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

getBlockProxy()

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

Returns

BlockProxy

the given block

getCustomShapeDefinition()

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:

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

Returns

Promise<undefined | BlockDefinition>

getElementProxy()

getElementProxy(id): ElementProxy

Parameters

Returns

ElementProxy

the given element

getItemProxy()

getItemProxy(id): BlockProxy | LineProxy | GroupProxy

Parameters

Returns

BlockProxy | LineProxy | GroupProxy

the given item

getLineProxy()

getLineProxy(id): LineProxy

Parameters

Returns

LineProxy

the given line

getOAuthClientId()

getOAuthClientId(providerName): Promise<undefined | string>

Fetch the OAuth Client Id if there is one

Parameters

Returns

Promise<undefined | string>

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

getOAuthToken()

getOAuthToken(providerName): Promise<undefined | string>

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

Parameters

Returns

Promise<undefined | string>

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

getPackageSettings()

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()

getPageProxy(id): PageProxy

Parameters

Returns

PageProxy

the given page

getProduct()

getProduct(): LucidProduct

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

Returns

LucidProduct

importPage()

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

Returns

Promise<void>

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

killExtension()

killExtension(): void

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

Returns

void

loadBlockClasses()

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

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)

oauthXhr(providerName, request): Promise<TextXHRResponse>

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

Parameters

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)

oauthXhr(providerName, request): Promise<BinaryXHRResponse>

Parameters

Returns

Promise<BinaryXHRResponse>

oauthXhr(providerName, request)

oauthXhr(providerName, request): Promise<XHRResponse>

Parameters

Returns

Promise<XHRResponse>

performDataAction()

performDataAction(options): Promise<DataActionResponse>

Parameters

Returns

Promise<DataActionResponse>

permanentTokenXhr()

permanentTokenXhr(providerName, request)

permanentTokenXhr(providerName, request): Promise<BinaryXHRResponse>

Parameters

Returns

Promise<BinaryXHRResponse>

permanentTokenXhr(providerName, request)

permanentTokenXhr(providerName, request): Promise<XHRResponse>

Parameters

Returns

Promise<XHRResponse>

processAndClearBootstrapData()

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

Parameters

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()

prompt(text, title?): PromptResult

Display a prompt modal to the user

Parameters

Returns

PromptResult

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

registerAction()

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

Returns

void

registerFileUploadAction()

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

Returns

void

registerUnfurlHandler()

registerUnfurlHandler(domain, callbacks): void

Registers a handler for link unfurling.

Parameters

Returns

void

reloadExtension()

reloadExtension(): void

Unload this extension, and then re-execute it.

Returns

void

sendCommand()

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

Parameters

Returns

CommandArgs[C]["result"]

the output of the given API command

setPackageSettings()

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

Returns

Promise<undefined>

showPackageSettingsModal()

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()

triggerAuthFlow(providerName): TriggerAuthFlowResult

Parameters

Returns

TriggerAuthFlowResult

tryGetItemProxy()

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

Parameters

Returns

undefined | BlockProxy | LineProxy | GroupProxy

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

withIntraDocumentMutex()

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

Returns

Promise<boolean>

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

withSilentActions()

withSilentActions(callback): void

Parameters

Returns

void

xhr()

xhr(request)

xhr(request): Promise<TextXHRResponse>

Make a network request

Parameters

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)

xhr(request): Promise<BinaryXHRResponse>

Parameters

Returns

Promise<BinaryXHRResponse>

xhr(request)

xhr(request): Promise<XHRResponse>

Parameters

Returns

Promise<XHRResponse>