Scripting
config

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
function (
settings: {
title: string,
description?: string,
items?: Array<SettingsItem>
}
) => { [key: string]: Table | Field | View | string | number };
Parameter nameDescription
settingsSettings for your script.
settings.titleTitle of your script.
settings.descriptionOptional. Description of what your script does. Markdown is partially supported (e.g. for links).
settings.itemsOptional. List of items used to generate the script settings UI.
Example
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
function (
key: string,
options?: {
label?: string,
description?: string
}
) => void;
Parameter nameDescription
keyA unique identifier for the table.
optionsOptional. Options for the table setting.
options.labelOptional. Label for the table picker.
options.descriptionOptional. Description for the table picker.
Example
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
function (
key: string,
options: {
label?: string,
description?: string,
parentTable: string
}
) => void;
Parameter nameDescription
keyA unique identifier for the field.
optionsOptions for the field setting.
options.labelOptional. Label for the field picker.
options.descriptionOptional. Description for the field picker.
options.parentTableThe key for a previously-defined table setting.
Example
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
function (
key: string,
options: {
label?: string,
description?: string,
parentTable: string
}
) => void;
Parameter nameDescription
keyA unique identifier for the view.
optionsOptions for the view setting.
options.labelOptional. Label for the view picker.
options.descriptionOptional. Description for the view picker.
options.parentTableThe key for a previously-defined table setting.
Example
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
function (
key: string,
options?: {
label?: string,
description?: string,
}
) => void;
Parameter nameDescription
keyA unique identifier for the text setting.
optionsOptional. Options for the text setting.
options.labelOptional. Label for the text input.
options.descriptionOptional. Description for the text input.
Example
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
function (
key: string,
options?: {
label?: string,
description?: string,
}
) => void;
Parameter nameDescription
keyA unique identifier for the number setting.
optionsOptional. Options for the number setting.
options.labelOptional. Label for the number input.
options.descriptionOptional. Description for the number input.
Example
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
function (
key: string,
options: {
label?: string,
description?: string,
options: Array<{ value: string, label?: string }>,
}
) => void;
Parameter nameDescription
keyA unique identifier for the select setting.
optionsOptions for the select setting.
options.labelOptional. Label for the dropdown menu.
options.descriptionOptional. Description for the dropdown menu.
options.optionsList of options for the dropdown menu.
options.options.valueReturned value for a given select option. Will also be used as the option label if no label is defined.
options.options.labelOptional. Label for a given select option.
Example
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;