Updating API docs for custom widgets (#272)

- Updating mapping description (mentioning about multiple types) - Adding new section about Widget Linking for custom widgets - Updating API reference
gristlabs · Oct 18, 2023 · e4100c3 · e4100c3
1 parent 80012e5
commit e4100c3
Show file tree

Hide file tree

Showing 10 changed files with 237 additions and 8 deletions.
diff --git a/help/code/interfaces/DocApiTypes.SqlPost.md b/help/code/interfaces/DocApiTypes.SqlPost.md
@@ -0,0 +1,5 @@
+# Interface: SqlPost
+
+[DocApiTypes](../modules/DocApiTypes.md).SqlPost
+
+JSON schema for the body of api /sql POST endpoint
diff --git a/help/code/interfaces/DocApiTypes.TablePost.md b/help/code/interfaces/DocApiTypes.TablePost.md
@@ -0,0 +1,12 @@
+# Interface: TablePost
+
+[DocApiTypes](../modules/DocApiTypes.md).TablePost
+
+Creating tables requires a list of columns.
+`fields` is not accepted because it's not generally sensible to set the metadata fields on new tables.
+
+## Hierarchy
+
+- `ColumnsPost`
+
+  ↳ **`TablePost`**
diff --git a/help/code/interfaces/grist_plugin_api.ColumnToMap.md b/help/code/interfaces/grist_plugin_api.ColumnToMap.md
@@ -12,6 +12,7 @@ API definitions for CustomSection plugins.
 - [description](grist_plugin_api.ColumnToMap.md#description)
 - [name](grist_plugin_api.ColumnToMap.md#name)
 - [optional](grist_plugin_api.ColumnToMap.md#optional)
+- [strictType](grist_plugin_api.ColumnToMap.md#stricttype)
 - [title](grist_plugin_api.ColumnToMap.md#title)
 - [type](grist_plugin_api.ColumnToMap.md#type)
 
@@ -49,6 +50,14 @@ Mark column as optional all columns are required by default.
 
 ___
 
+### strictType
+
+• `Optional` **strictType**: `boolean`
+
+Match column type strictly, so "Any" will require "Any" and not any other type.
+
+___
+
 ### title
 
 • `Optional` **title**: ``null`` \| `string`
@@ -61,4 +70,5 @@ ___
 
 • `Optional` **type**: `string`
 
-Column type, by default ANY.
+Column types (as comma separated list), by default "Any", what means that any type is
+allowed (unless strictType is true).
diff --git a/help/code/interfaces/grist_plugin_api.CursorPos.md b/help/code/interfaces/grist_plugin_api.CursorPos.md
@@ -0,0 +1,46 @@
+# Interface: CursorPos
+
+[grist-plugin-api](../modules/grist_plugin_api.md).CursorPos
+
+Represents the position of an active cursor on a page.
+
+## Table of contents
+
+### Properties
+
+- [fieldIndex](grist_plugin_api.CursorPos.md#fieldindex)
+- [rowId](grist_plugin_api.CursorPos.md#rowid)
+- [rowIndex](grist_plugin_api.CursorPos.md#rowindex)
+- [sectionId](grist_plugin_api.CursorPos.md#sectionid)
+
+## Properties
+
+### fieldIndex
+
+• `Optional` **fieldIndex**: `number`
+
+The index of the selected field in the current view.
+
+___
+
+### rowId
+
+• `Optional` **rowId**: [`UIRowId`](../modules/grist_plugin_api.md#uirowid)
+
+The rowId (value of the `id` column) of the current cursor position, or 'new' if the cursor is on a new row.
+
+___
+
+### rowIndex
+
+• `Optional` **rowIndex**: `number`
+
+The index of the current row in the current view.
+
+___
+
+### sectionId
+
+• `Optional` **sectionId**: `number`
+
+The id of a section that this cursor is in. Ignored when setting a cursor position for a particular view.
diff --git a/help/code/interfaces/grist_plugin_api.GristView.md b/help/code/interfaces/grist_plugin_api.GristView.md
@@ -11,6 +11,7 @@ Interface for the data backing a single widget.
 - [allowSelectBy](grist_plugin_api.GristView.md#allowselectby)
 - [fetchSelectedRecord](grist_plugin_api.GristView.md#fetchselectedrecord)
 - [fetchSelectedTable](grist_plugin_api.GristView.md#fetchselectedtable)
+- [setCursorPos](grist_plugin_api.GristView.md#setcursorpos)
 - [setSelectedRows](grist_plugin_api.GristView.md#setselectedrows)
 
 ## Methods
@@ -19,7 +20,8 @@ Interface for the data backing a single widget.
 
 ▸ **allowSelectBy**(): `Promise`<`void`\>
 
-Allow custom widget to be listed as a possible source for linking with SELECT BY.
+Deprecated now. It was used for filtering selected table by `setSelectedRows` method.
+Now the preferred way it to use ready message.
 
 #### Returns
 
@@ -57,17 +59,35 @@ Like [GristDocAPI.fetchTable](grist_plugin_api.GristDocAPI.md#fetchtable), but g
 
 ___
 
+### 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`](grist_plugin_api.CursorPos.md) |
+
+#### Returns
+
+`Promise`<`void`\>
+
+___
+
 ### setSelectedRows
 
 ▸ **setSelectedRows**(`rowIds`): `Promise`<`void`\>
 
-Set the list of selected rows to be used against any linked widget. Requires `allowSelectBy()`.
+Set the list of selected rows to be used against any linked widget.
 
 #### Parameters
 
 | Name | Type |
 | :------ | :------ |
-| `rowIds` | `number`[] |
+| `rowIds` | ``null`` \| `number`[] |
 
 #### Returns
 

diff --git a/help/code/interfaces/grist_plugin_api.InteractionOptionsRequest.md b/help/code/interfaces/grist_plugin_api.InteractionOptionsRequest.md
@@ -8,12 +8,21 @@ Initial message sent by the CustomWidget with initial requirements.
 
 ### Properties
 
+- [allowSelectBy](grist_plugin_api.InteractionOptionsRequest.md#allowselectby)
 - [columns](grist_plugin_api.InteractionOptionsRequest.md#columns)
 - [hasCustomOptions](grist_plugin_api.InteractionOptionsRequest.md#hascustomoptions)
 - [requiredAccess](grist_plugin_api.InteractionOptionsRequest.md#requiredaccess)
 
 ## Properties
 
+### allowSelectBy
+
+• `Optional` **allowSelectBy**: `boolean`
+
+Show widget as linking source.
+
+___
+
 ### columns
 
 • `Optional` **columns**: `ColumnsToMap`

diff --git a/help/code/interfaces/grist_plugin_api.ReadyPayload.md b/help/code/interfaces/grist_plugin_api.ReadyPayload.md
@@ -14,12 +14,25 @@ Options when initializing connection to Grist.
 
 ### Properties
 
+- [allowSelectBy](grist_plugin_api.ReadyPayload.md#allowselectby)
 - [columns](grist_plugin_api.ReadyPayload.md#columns)
 - [onEditOptions](grist_plugin_api.ReadyPayload.md#oneditoptions)
 - [requiredAccess](grist_plugin_api.ReadyPayload.md#requiredaccess)
 
 ## Properties
 
+### allowSelectBy
+
+• `Optional` **allowSelectBy**: `boolean`
+
+Show widget as linking source.
+
+#### Inherited from
+
+Omit.allowSelectBy
+
+___
+
 ### columns
 
 • `Optional` **columns**: `ColumnsToMap`

diff --git a/help/code/modules/DocApiTypes.md b/help/code/modules/DocApiTypes.md
@@ -11,3 +11,5 @@
 - [RecordsPatch](../interfaces/DocApiTypes.RecordsPatch.md)
 - [RecordsPost](../interfaces/DocApiTypes.RecordsPost.md)
 - [RecordsPut](../interfaces/DocApiTypes.RecordsPut.md)
+- [SqlPost](../interfaces/DocApiTypes.SqlPost.md)
+- [TablePost](../interfaces/DocApiTypes.TablePost.md)
diff --git a/help/code/modules/grist_plugin_api.md b/help/code/modules/grist_plugin_api.md
@@ -7,6 +7,7 @@
 - [AccessTokenOptions](../interfaces/grist_plugin_api.AccessTokenOptions.md)
 - [AccessTokenResult](../interfaces/grist_plugin_api.AccessTokenResult.md)
 - [ColumnToMap](../interfaces/grist_plugin_api.ColumnToMap.md)
+- [CursorPos](../interfaces/grist_plugin_api.CursorPos.md)
 - [GristColumn](../interfaces/grist_plugin_api.GristColumn.md)
 - [GristDocAPI](../interfaces/grist_plugin_api.GristDocAPI.md)
 - [GristTable](../interfaces/grist_plugin_api.GristTable.md)
@@ -20,6 +21,10 @@
 - [WidgetAPI](../interfaces/grist_plugin_api.WidgetAPI.md)
 - [WidgetColumnMap](../interfaces/grist_plugin_api.WidgetColumnMap.md)
 
+### Type Aliases
+
+- [UIRowId](grist_plugin_api.md#uirowid)
+
 ### Variables
 
 - [checkers](grist_plugin_api.md#checkers)
@@ -41,15 +46,25 @@
 - [getTable](grist_plugin_api.md#gettable)
 - [mapColumnNames](grist_plugin_api.md#mapcolumnnames)
 - [mapColumnNamesBack](grist_plugin_api.md#mapcolumnnamesback)
+- [on](grist_plugin_api.md#on)
 - [onNewRecord](grist_plugin_api.md#onnewrecord)
 - [onOptions](grist_plugin_api.md#onoptions)
 - [onRecord](grist_plugin_api.md#onrecord)
 - [onRecords](grist_plugin_api.md#onrecords)
 - [ready](grist_plugin_api.md#ready)
+- [setCursorPos](grist_plugin_api.md#setcursorpos)
 - [setOption](grist_plugin_api.md#setoption)
 - [setOptions](grist_plugin_api.md#setoptions)
 - [setSelectedRows](grist_plugin_api.md#setselectedrows)
 
+## Type Aliases
+
+### 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
@@ -106,7 +121,8 @@ Interface for the state of a custom widget.
 
 ▸ **allowSelectBy**(): `Promise`<`void`\>
 
-Allow custom widget to be listed as a possible source for linking with SELECT BY.
+Deprecated now. It was used for filtering selected table by `setSelectedRows` method.
+Now the preferred way it to use ready message.
 
 #### Returns
 
@@ -301,6 +317,53 @@ we don't attempt to do these transformations automatically.
 
 ___
 
+### 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 `eventName`and `listener` will result in the `listener` being added, and called, multiple
+times.
+
+```js
+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. The`emitter.prependListener()` method can be used as an alternative to add the
+event listener to the beginning of the listeners array.
+
+```js
+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`
@@ -402,6 +465,24 @@ Grist will not attempt to communicate with it until this method is called.
 
 ___
 
+### 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`](../interfaces/grist_plugin_api.CursorPos.md) |
+
+#### Returns
+
+`Promise`<`void`\>
+
+___
+
 ### setOption
 
 ▸ **setOption**(`key`, `value`): `Promise`<`void`\>
@@ -443,13 +524,13 @@ ___
 
 ▸ **setSelectedRows**(`rowIds`): `Promise`<`void`\>
 
-Set the list of selected rows to be used against any linked widget. Requires `allowSelectBy()`.
+Set the list of selected rows to be used against any linked widget.
 
 #### Parameters
 
 | Name | Type |
 | :------ | :------ |
-| `rowIds` | `number`[] |
+| `rowIds` | ``null`` \| `number`[] |
 
 #### Returns