Module: grist-plugin-api#
Table of contents#
Interfaces#
- ColumnToMap
- GristColumn
- GristDocAPI
- GristTable
- GristView
- InteractionOptions
- InteractionOptionsRequest
- ParseOptionSchema
- ParseOptions
- ReadyPayload
- RenderOptions
- WidgetAPI
- WidgetColumnMap
Variables#
Functions#
- allowSelectBy
- clearOptions
- fetchSelectedRecord
- fetchSelectedTable
- getOption
- getOptions
- getTable
- mapColumnNames
- mapColumnNamesBack
- onOptions
- onRecord
- onRecords
- ready
- setOption
- setOptions
- setSelectedRows
Variables#
checkers#
• Const checkers: Pick<ICheckerSuite, "ParseOptions" | "ParseFileResult" | "FileSource" | "ParseOptionSchema" | "GristTables" | "RenderTarget" | "RenderOptions" | "GristColumn" | "GristTable" | "ImportSource" | "FileContent" | "FileListItem" | "URL" | "CustomSectionAPI" | "EditOptionsAPI" | "ParseFileAPI" | "ComponentKind" | "GristAPI" | "GristDocAPI" | "GristView" | "ImportSourceAPI" | "ImportProcessorAPI" | "InternalImportSourceAPI" | "Storage" | "WidgetAPI">
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#
▸ Const allowSelectBy(): Promise<void>
Shortcut for GristView.allowSelectBy.
Returns#
Promise<void>
clearOptions#
▸ Const clearOptions(): Promise<void>
Shortcut for WidgetAPI.clearOptions
Returns#
Promise<void>
fetchSelectedRecord#
▸ fetchSelectedRecord(rowId, options?): Promise<any>
Fetches current selected record as for GristView.fetchSelectedRecord,
but decoding data by default, replacing e.g. [‘D’, timestamp] with
a moment date. Option keepEncoded skips the decoding step.
Parameters#
| Name | Type |
|---|---|
rowId |
number |
options? |
Object |
Returns#
Promise<any>
fetchSelectedTable#
▸ fetchSelectedTable(options?): Promise<any>
Fetches data backing the widget as for GristView.fetchSelectedTable,
but decoding data by default, replacing e.g. [‘D’, timestamp] with
a moment date. Option keepEncoded skips the decoding step.
Parameters#
| Name | Type |
|---|---|
options? |
Object |
Returns#
Promise<any>
getOption#
▸ Const getOption(key): Promise<any>
Shortcut for WidgetAPI.getOption
Parameters#
| Name | Type |
|---|---|
key |
string |
Returns#
Promise<any>
getOptions#
▸ Const getOptions(): Promise<null | object>
Shortcut for WidgetAPI.getOptions
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#
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 |
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 |
Returns#
any
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): 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. TODO: currently this will be called even if the content of a different row changes.
Parameters#
| Name | Type |
|---|---|
callback |
(data: RowRecord | null, mappings: WidgetColumnMap | null) => unknown |
Returns#
void
onRecords#
▸ onRecords(callback): void
For custom widgets, add a handler that will be called whenever the selected records change. Handler will be called with a list of records.
Parameters#
| Name | Type |
|---|---|
callback |
(data: RowRecord[], mappings: WidgetColumnMap | null) => unknown |
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
setOption#
▸ Const setOption(key, value): Promise<void>
Shortcut for WidgetAPI.setOption
Parameters#
| Name | Type |
|---|---|
key |
string |
value |
any |
Returns#
Promise<void>
setOptions#
▸ Const setOptions(options): Promise<void>
Shortcut for WidgetAPI.setOptions
Parameters#
| Name | Type |
|---|---|
options |
Object |
Returns#
Promise<void>
setSelectedRows#
▸ Const setSelectedRows(rowIds): Promise<void>
Shortcut for GristView.setSelectedRows.
Parameters#
| Name | Type |
|---|---|
rowIds |
number[] |
Returns#
Promise<void>