## Script settings (extensions 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](/developers/scripting/examples/scriptsettings.md) 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](/developers/scripting/api/config.md#settings-items).

> See also: [Table](/developers/scripting/api/table.md)
> See also: [Field](/developers/scripting/api/field.md)
> See also: [SettingsItem](/developers/scripting/api/config.md#settingsitems)
```js
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. |

```js
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:
- [table](/developers/scripting/api/config.md#input-config-table)
- [field](/developers/scripting/api/config.md#input-config-field)
- [view](/developers/scripting/api/config.md#input-config-view)
- [text](/developers/scripting/api/config.md#input-config-text)
- [number](/developers/scripting/api/config.md#input-config-number)
- [select](/developers/scripting/api/config.md#input-config-select)

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](/developers/scripting/api/table.md).

```js
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. |

```js
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](/developers/scripting/api/field.md).

Requires that a valid `parentTable` has already been defined as a previous setting.

```js
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. |

```js
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](/developers/scripting/api/view.md).

Requires that a valid `parentTable` has already been defined as a previous setting.

```js
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. |

```js
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.

```js
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. |

```js
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.

```js
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. |

```js
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.

```js
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. |

```js
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;
```