Feel free to edit any code snippet and explore the Custom Widget API yourself. Each snippet is fully editable.
Learn more about the Custom Widget API

grist.ready()

This is initial call a widget needs to make to let Grist know that it is ready to process incoming events.

*Note* Do not paste code that you don't trust or is not yours. If this widget has read access, code you paste could read your table and transmit data elsewhere. If this widget has full access, that code could also modify your document.

Interaction options

The ready method accepts interaction options you may wish to send to Grist. Change current access level to 'none' and run this snippet. Observe how Grist will prompt you to give the widget requested permissions.
Here is a full list of supported option at this moment:

grist.ready() - Column mappings

Here is a snippet showing how to use column mappings feature. Run this snippet, pick columns in the creator panel and observe what are the values sent by Grist.

grist.docApi.listTables()

To list all table ids use the grist.docApi.listTables() method. Your widget needs to have at least 'read table' access level.

grist.docApi.fetchSelectedTable()

This method reads all records from a table this widget is connected to. Your widget needs to have at least 'read table' access level.

grist.docApi.fetchSelectedRecord(rowId)

Reads a single row by its id. Your widget needs to have at least 'read table' access level.

grist.docApi.fetchTable("tableId")

Reads whole table by table id. Your widget needs to have 'full' access level.

grist.onRecords

Subscribes to a table change event. Every time table is changed (either structure or data) this handler will be called with current table's data.

grist.onRecord

Subscribes to a cursor change event. Every time cursor position is changed this handler will be called with current record's data.

grist.onOptions

Subscribes to a options change event.

grist.setOption("key", "value")

Sets an option in the widget's key-value store.

grist.getOption("key")

Reads an option from the widget's key-value store.

grist.getOptions()

Reads all options from the widget's key-value store.

grist.ready() - onEditOptions

To tell Grist to display an additional button Open configuration in the creator panel and the section menu, you need to pass onEditOptions handler to the ready method. When clicked, it will trigger your handler, which you can use to show your own custom configuration screen.