Script settings Scripting Extension only
Defines the settings for the script. Users of your script can fill in these settings from the extension.
For example, your script may rely on a interacting with specific table. Rather than hard-coding the
specific table ID or presenting an input.tableAsync
picker for every script run, you can define
a table setting which can be filled in by users of the script. The chosen value will be persisted
between runs, and is shared between all collaborators.
Settings can be defined for tables, fields, views, text, numbers, and select options. By defining these settings, your script users can tweak the script's behavior without needing to edit a single line of code.
You can use the Script settings as a starting point.
input.config
Define settings using the input.config()
method. This should only be called once, at the top
of your script. It returns the values that have been filled in by the users of your script. It
expects a settings object that defines a title, a description, and a list of the settings items.
function (settings: {title: string,description?: string,items?: Array<SettingsItem>}) => { [key: string]: Table | Field | View | string | number };
Parameter name | Description |
---|---|
settings | Settings for your script. |
settings.title | Title of your script. |
settings.description | Optional. Description of what your script does. Markdown is partially supported (e.g. for links). |
settings.items | Optional. List of items used to generate the script settings UI. |
const config = input.config({title: 'Awesome script',description: 'A script that lets you...',items: [input.config.table('ordersTable', {label: 'Orders table',description: 'The table in which you track orders for your store'}),input.config.field('priceField', {label: 'Price field',parentTable: 'ordersTable',}),input.config.view('openOrdersView', {label: 'Open orders',description: 'The view which filters for orders that are currently open',parentTable: 'ordersTable',}),input.config.text('companyName', {label: 'Company name',}),input.config.number('maxItemsPerOrder', {label: 'Maximum number of items per order',}),input.config.select('country', {label: 'Country',description: 'Country in which your business operates',options: [{label: 'USA', value: 'usa'},{label: 'UK', value: 'uk'},{label: 'Australia', value: 'aus'},]})]});// Once the settings have been populated in the "Run script" pane, the returned config object// will contain the actual models for each item.const ordersTable = config.ordersTable;const priceField = config.priceField;const openOrdersView = config.openOrdersView;const companyName = config.companyName;const maxItemsPerOrder = config.maxItemsPerOrder;const country = config.country;
Settings items
There are multiple types of settings that your script can define:
These are defined using helper methods on input.config
, e.g. input.config.table()
. These
methods should only be used when defining settings items in the items
of argument of
input.config()
.
Each item must include a key as its first argument. This is used to identify the setting and access
its value in the returned object. You may also specify a label
and description
, which
will be shown in the extension's settings.
input.config.table
Defines a setting for a Table.
function (key: string,options?: {label?: string,description?: string}) => void;
Parameter name | Description |
---|---|
key | A unique identifier for the table. |
options | Optional. Options for the table setting. |
options.label | Optional. Label for the table picker. |
options.description | Optional. Description for the table picker. |
const config = input.config({title: 'My cool script',description: 'An awesome script that...',items: [input.config.table('ordersTable', {label: 'Orders table',description: 'Table in which you track orders',})]});const ordersTable = config.ordersTable;
input.config.field
Defines a setting for a Field.
Requires that a valid parentTable
has already been defined as a previous setting.
function (key: string,options: {label?: string,description?: string,parentTable: string}) => void;
Parameter name | Description |
---|---|
key | A unique identifier for the field. |
options | Options for the field setting. |
options.label | Optional. Label for the field picker. |
options.description | Optional. Description for the field picker. |
options.parentTable | The key for a previously-defined table setting. |
const config = input.config({title: 'My cool script',description: 'An awesome script that...',items: [input.config.table('ordersTable'),input.config.field('priceField', {label: 'Price field',description: 'The field in which you track order prices',parentTable: 'ordersTable',}),]});const ordersTable = config.ordersTable;const priceField = config.priceField;
input.config.view
Defines a setting for a View.
Requires that a valid parentTable
has already been defined as a previous setting.
function (key: string,options: {label?: string,description?: string,parentTable: string}) => void;
Parameter name | Description |
---|---|
key | A unique identifier for the view. |
options | Options for the view setting. |
options.label | Optional. Label for the view picker. |
options.description | Optional. Description for the view picker. |
options.parentTable | The key for a previously-defined table setting. |
const config = input.config({title: 'My cool script',description: 'An awesome script that...',items: [input.config.table('ordersTable'),input.config.view('openOrdersView', {label: 'Open Orders',description: 'The view which filters for orders that are currently open',parentTable: 'ordersTable',}),]});const ordersTable = config.ordersTable;const openOrdersView = config.openOrdersView;
input.config.text
Defines a setting for a text variable.
function (key: string,options?: {label?: string,description?: string,}) => void;
Parameter name | Description |
---|---|
key | A unique identifier for the text setting. |
options | Optional. Options for the text setting. |
options.label | Optional. Label for the text input. |
options.description | Optional. Description for the text input. |
const config = input.config({title: 'My cool script',description: 'An awesome script that...',items: [input.config.text('companyName', {label: 'Company name',description: 'The name of your business',}),]});const companyName = config.companyName;
input.config.number
Defines a setting for a number variable.
function (key: string,options?: {label?: string,description?: string,}) => void;
Parameter name | Description |
---|---|
key | A unique identifier for the number setting. |
options | Optional. Options for the number setting. |
options.label | Optional. Label for the number input. |
options.description | Optional. Description for the number input. |
const config = input.config({title: 'My cool script',description: 'An awesome script that...',items: [input.config.number('maxNumOrders', {label: 'Maximum number of orders',description: 'Limit for how many orders can be placed in a day',}),]});const maxNumOrders = config.maxNumOrders;
input.config.select
Defines a setting for a select option.
The value returned will be the string value
of the currently selected option.
function (key: string,options: {label?: string,description?: string,options: Array<{ value: string, label?: string }>,}) => void;
Parameter name | Description |
---|---|
key | A unique identifier for the select setting. |
options | Options for the select setting. |
options.label | Optional. Label for the dropdown menu. |
options.description | Optional. Description for the dropdown menu. |
options.options | List of options for the dropdown menu. |
options.options.value | Returned value for a given select option. Will also be used as the option label if no label is defined. |
options.options.label | Optional. Label for a given select option. |
const config = input.config({title: 'My cool script',description: 'An awesome script that...',items: [input.config.select('country', {label: 'Country',description: 'Country in which your business operates',options: [{label: 'USA', value: 'usa'},{label: 'UK', value: 'uk'},{label: 'Australia', value: 'aus'},]})]});const country = config.country;