Module: grist-plugin-api#

Table of contents#

Interfaces#

Type Aliases#

Variables#

Functions#

Type Aliases#

ColumnsToMap#

Ƭ ColumnsToMap: (string | ColumnToMap)[]

Tells Grist what columns a Custom Widget expects and allows users to map between existing column names and those requested by the Custom Widget.

UIRowId#

Ƭ UIRowId: number | "new"

Represents the id of a row in a table. The value of the id column. Might be a number or ‘new’ value for a new row.

Variables#

checkers#

We also create and export a global checker object that includes all of the types above.

docApi#

• Const docApi: GristDocAPI & GristView

A collection of methods for fetching document data. The fetchSelectedTable and fetchSelectedRecord methods are overridden to decode data by default.

sectionApi#

• Const sectionApi: CustomSectionAPI

Interface for the mapping of a custom widget.

selectedTable#

• Const selectedTable: TableOperations

Get the current selected table (for custom widgets).

viewApi#

• Const viewApi: GristView

Interface for the records backing a custom widget.

widgetApi#

• Const widgetApi: WidgetAPI

Interface for the state of a custom widget.

Functions#

allowSelectBy#

▸ allowSelectBy(): Promise<void>

Deprecated now. It was used for filtering selected table by setSelectedRows method. Now the preferred way it to use ready message.

Returns#

Promise<void>

clearOptions#

▸ clearOptions(): Promise<void>

Clears all the options.

Returns#

Promise<void>

fetchSelectedRecord#

▸ fetchSelectedRecord(rowId, options?): Promise<any>

Same as GristView.fetchSelectedRecord, but the option keepEncoded is false by default.

Parameters#

Name	Type
`rowId`	`number`
`options`	`FetchSelectedOptions`

Returns#

Promise<any>

fetchSelectedTable#

▸ fetchSelectedTable(options?): Promise<any>

Same as GristView.fetchSelectedTable, but the option keepEncoded is false by default.

Parameters#

Name	Type
`options`	`FetchSelectedOptions`

Returns#

Promise<any>

getAccessToken#

▸ getAccessToken(options?): Promise<AccessTokenResult>

Get an access token, for making API calls outside of the custom widget API. There is no caching of tokens. The returned token can be used to authorize regular REST API calls that access the content of the document. For example, in a custom widget for a table with a Photos column containing attachments, the following code will update the src of an image with id the_image to show the attachment:

grist.onRecord(async (record) => {
  const tokenInfo = await grist.docApi.getAccessToken({readOnly: true});
  const img = document.getElementById('the_image');
  const id = record.Photos[0];  // get an id of an attachment - there could be several
                                // in a cell, for this example we just take the first.
  const src = `${tokenInfo.baseUrl}/attachments/${id}/download?auth=${tokenInfo.token}`;
  img.setAttribute('src', src);
});

Parameters#

Name	Type
`options?`	`AccessTokenOptions`

Returns#

Promise<AccessTokenResult>

getOption#

▸ getOption(key): Promise<any>

Get single value from Widget options object.

Parameters#

Name	Type
`key`	`string`

Returns#

Promise<any>

getOptions#

▸ getOptions(): Promise<null | object>

Gets all options stored by the widget. Options are stored as plain JSON object.

Returns#

Promise<null | object>

getTable#

▸ getTable(tableId?): TableOperations

Get access to a table in the document. If no tableId specified, this will use the current selected table (for custom widgets). If a table does not exist, there will be no error until an operation on the table is attempted.

Parameters#

Name	Type
`tableId?`	`string`

Returns#

TableOperations

mapColumnNames#

▸ mapColumnNames(data, options?): any

Renames columns in the result using columns mapping configuration passed in ready method. Returns null if not all required columns were mapped or not widget doesn’t support custom column mapping.

Parameters#

Name	Type
`data`	`any`
`options?`	`Object`
`options.columns?`	`ColumnsToMap`
`options.mappings?`	`null` \| `WidgetColumnMap`
`options.reverse?`	`boolean`

Returns#

any

mapColumnNamesBack#

▸ mapColumnNamesBack(data, options?): any

Offer a convenient way to map data with renamed columns back into the form used in the original table. This is useful for making edits to the original table in a widget with column mappings. As for mapColumnNames(), we don’t attempt to do these transformations automatically.

Parameters#

Name	Type
`data`	`any`
`options?`	`Object`
`options.columns?`	`ColumnsToMap`
`options.mappings?`	`null` \| `WidgetColumnMap`

Returns#

any

on#

▸ on(eventName, listener): Rpc

Adds the listener function to the end of the listeners array for the event named eventName. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of eventNameand listener will result in the listener being added, and called, multiple times.

server.on('connection', (stream) => {
  console.log('someone connected!');
});

Returns a reference to the EventEmitter, so that calls can be chained.

By default, event listeners are invoked in the order they are added. Theemitter.prependListener() method can be used as an alternative to add the event listener to the beginning of the listeners array.

const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a

Since

v0.1.101

Parameters#

Name	Type	Description
`eventName`	`string` \| `symbol`	The name of the event.
`listener`	(…`args`: `any`[]) => `void`	The callback function

Returns#

Rpc

onNewRecord#

▸ onNewRecord(callback): void

For custom widgets, add a handler that will be called whenever the new (blank) row is selected.

Parameters#

Name	Type
`callback`	(`mappings`: `null` \| `WidgetColumnMap`) => `unknown`

Returns#

void

onOptions#

▸ onOptions(callback): void

For custom widgets, add a handler that will be called whenever the widget options change (and on initial ready message). Handler will be called with an object containing saved json options, or null if no options were saved. The second parameter has information about the widgets relationship with the document that contains it.

Parameters#

Name	Type
`callback`	(`options`: `any`, `settings`: `InteractionOptions`) => `unknown`

Returns#

void

onRecord#

▸ onRecord(callback, options?): void

For custom widgets, add a handler that will be called whenever the row with the cursor changes - either by switching to a different row, or by some value within the row potentially changing. Handler may in the future be called with null if the cursor moves away from any row. By default, options.keepEncoded is false.

Parameters#

Name	Type
`callback`	(`data`: `null` \| `RowRecord`, `mappings`: `null` \| `WidgetColumnMap`) => `unknown`
`options`	`FetchSelectedOptions`

Returns#

void

onRecords#

▸ onRecords(callback, options?): void

For custom widgets, add a handler that will be called whenever the selected records change. By default, options.format is 'rows' and options.keepEncoded is false.

Parameters#

Name	Type
`callback`	(`data`: `RowRecord`[], `mappings`: `null` \| `WidgetColumnMap`) => `unknown`
`options`	`FetchSelectedOptions`

Returns#

void

ready#

▸ ready(settings?): void

Declare that a component is prepared to receive messages from the outside world. Grist will not attempt to communicate with it until this method is called.

Parameters#

Name	Type
`settings?`	`ReadyPayload`

Returns#

void

setCursorPos#

▸ setCursorPos(pos): Promise<void>

Sets the cursor position to a specific row and field. sectionId is ignored. Used for widget linking.

Parameters#

Name	Type
`pos`	`CursorPos`

Returns#

Promise<void>

setOption#

▸ setOption(key, value): Promise<void>

Store single value in the Widget options object (and create it if necessary).

Parameters#

Name	Type
`key`	`string`
`value`	`any`

Returns#

Promise<void>

setOptions#

▸ setOptions(options): Promise<void>

Replaces all options stored by the widget.

Parameters#

Name	Type
`options`	`Object`

Returns#

Promise<void>

setSelectedRows#

▸ setSelectedRows(rowIds): Promise<void>

Set the list of selected rows to be used against any linked widget.

Parameters#

Name	Type
`rowIds`	`null` \| `number`[]

Returns#

Promise<void>

Give Feedback

Was this article helpful?

Thank you for letting us know!