# FormFields

## Introduction

`FormFields` are components of a [Form](https://docs.api.intratool.de/api-reference/forms/forms). They describe the input fields that are available in a specific [Form](https://docs.api.intratool.de/api-reference/forms/forms).

Further information about the `FormFields` behaviour is described by the [FormFieldType](https://docs.api.intratool.de/api-reference/forms/form-field-types) and attached [FormFieldValidations](https://docs.api.intratool.de/api-reference/forms/form-field-validations).

## Model Definition

**Alias**

`formField`

**Relations**

| Relation                                                                                         | Key             | Type            | Relation Field(s)                      |
| ------------------------------------------------------------------------------------------------ | --------------- | --------------- | -------------------------------------- |
| [Form](https://docs.api.intratool.de/api-reference/forms/forms)                                  | `form`          | Belongs to      | `form_id`                              |
| [FormFieldType](https://docs.api.intratool.de/api-reference/forms/form-field-types)              | `fieldType`     | Belongs to      | `form_field_type_id`                   |
| [FormFieldValidations](https://docs.api.intratool.de/api-reference/forms/form-field-validations) | `validations`   | Has many        | `form_field_validations.form_field_id` |
| [LayoutColumns](https://docs.api.intratool.de/api-reference/layouts/layout-columns)              | `layoutColumns` | Belongs to many | Intermediate table                     |

**Traits**

* [Restrictable](https://docs.api.intratool.de/introduction/entity-permissions/restricted-scope)
* `Sortable`
* `LayoutElement`

## List

Get a list of all `FormFields` the current authenticated [User](https://docs.api.intratool.de/api-reference/users) is allowed to view.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/forms/fields`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/forms/fields', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 2,
    "form_id": 1,
    "form_type": "form",
    "form_field_type_id": "text",
    "name": "Field-1",
    "key": "field-1",
    "default_value": "",
    "placeholder": null,
    "description": null,
    "config": {},
    "sort_number": 1,
    "created_at": "2019-01-22 10:44:30",
    "updated_at": "2019-01-24 14:43:41",
    "field_validation_string": "",
    "field_validations": []
  },
  {
    "id": 4,
    "form_id": 1,
    "form_type": "task",
    "form_field_type_id": "text",
    "name": "Field 1",
    "key": "field-1",
    "default_value": "",
    "placeholder": null,
    "description": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr.",
    "config": {},
    "sort_number": 1,
    "created_at": "2019-01-24 14:10:17",
    "updated_at": "2019-01-24 14:10:17",
    "field_validation_string": "required",
    "field_validations": [
      {
        "id": 1,
        "form_field_id": 4,
        "form_field_validation_type_id": "required",
        "config": {},
        "created_at": "2019-01-24 14:10:17",
        "updated_at": "2019-01-24 14:10:17",
        "validation_string": "required",
        "form_field_validation_type": {
          "id": "required",
          "default_config": {},
          "sort_number": 1,
          "created_at": "2019-01-21 00:00:00",
          "updated_at": "2019-01-21 00:00:00"
        }
      }
    ]
  }
]
```

## List by Form

Get a list of all `FormFields` the current authenticated [User](https://docs.api.intratool.de/api-reference/users) is allowed to view by [Form](https://docs.api.intratool.de/api-reference/forms/forms).

**Definition**

<mark style="color:green;">`GET`</mark> `/api/forms/{formId}/fields`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/forms/1/fields', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 2,
    "form_id": 1,
    "form_type": "form",
    "form_field_type_id": "text",
    "name": "Field-1",
    "key": "field-1",
    "default_value": "",
    "placeholder": null,
    "description": null,
    "config": {},
    "sort_number": 1,
    "created_at": "2019-01-22 10:44:30",
    "updated_at": "2019-01-24 14:43:41",
    "field_validation_string": "",
    "field_validations": []
  },
  {
    "id": 4,
    "form_id": 1,
    "form_type": "task",
    "form_field_type_id": "text",
    "name": "Field 1",
    "key": "field-1",
    "default_value": "",
    "placeholder": null,
    "description": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr.",
    "config": {},
    "sort_number": 1,
    "created_at": "2019-01-24 14:10:17",
    "updated_at": "2019-01-24 14:10:17",
    "field_validation_string": "required",
    "field_validations": [
      {
        "id": 1,
        "form_field_id": 4,
        "form_field_validation_type_id": "required",
        "config": {},
        "created_at": "2019-01-24 14:10:17",
        "updated_at": "2019-01-24 14:10:17",
        "validation_string": "required",
        "form_field_validation_type": {
          "id": "required",
          "default_config": {},
          "sort_number": 1,
          "created_at": "2019-01-21 00:00:00",
          "updated_at": "2019-01-21 00:00:00"
        }
      }
    ]
  }
]
```

## Show

Show a single `FormField` by `id`.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/forms/fields/{id}`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/forms/fields/2', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 2,
  "form_id": 1,
  "form_type": "form",
  "form_field_type_id": "text",
  "name": "Field-1",
  "key": "field-1",
  "default_value": "",
  "placeholder": null,
  "description": null,
  "config": {},
  "sort_number": 1,
  "created_at": "2019-01-22 10:44:30",
  "updated_at": "2019-01-24 14:43:41",
  "field_validation_string": "",
  "field_validations": []
}
```

## \[Adm.] List

Get a list of all `FormFields`.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/administration/forms/fields`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/administration/forms/fields', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);

```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 2,
    "form_id": 1,
    "form_type": "form",
    "form_field_type_id": "text",
    "name": "Field-1",
    "key": "field-1",
    "default_value": "",
    "placeholder": null,
    "description": null,
    "config": {},
    "sort_number": 1,
    "created_at": "2019-01-22 10:44:30",
    "updated_at": "2019-01-24 14:43:41",
    "field_validation_string": "",
    "field_validations": []
  },
  {
    "id": 4,
    "form_id": 1,
    "form_type": "task",
    "form_field_type_id": "text",
    "name": "Field 1",
    "key": "field-1",
    "default_value": "",
    "placeholder": null,
    "description": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr.",
    "config": {},
    "sort_number": 1,
    "created_at": "2019-01-24 14:10:17",
    "updated_at": "2019-01-24 14:10:17",
    "field_validation_string": "required",
    "field_validations": [
      {
        "id": 1,
        "form_field_id": 4,
        "form_field_validation_type_id": "required",
        "config": {},
        "created_at": "2019-01-24 14:10:17",
        "updated_at": "2019-01-24 14:10:17",
        "validation_string": "required",
        "form_field_validation_type": {
          "id": "required",
          "default_config": {},
          "sort_number": 1,
          "created_at": "2019-01-21 00:00:00",
          "updated_at": "2019-01-21 00:00:00"
        }
      }
    ]
  }
]
```

## \[Adm.] List referring to Forms

Get a list of all `FormFields` that refer to a [Form](https://docs.api.intratool.de/api-reference/forms/forms).

**Definition**

<mark style="color:green;">`GET`</mark> `/api/administration/forms/fields/form`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/administration/forms/fields/form', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);


```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 2,
    "form_id": 1,
    "form_type": "form",
    "form_field_type_id": "text",
    "name": "Field-1",
    "key": "field-1",
    "default_value": "",
    "placeholder": null,
    "description": null,
    "config": {},
    "sort_number": 1,
    "created_at": "2019-01-22 10:44:30",
    "updated_at": "2019-01-24 14:43:41",
    "field_validation_string": "",
    "field_validations": []
  },
  {
    "id": 5,
    "form_id": 2,
    "form_type": "form",
    "form_field_type_id": "radio",
    "name": "Field-1",
    "key": "field-1",
    "default_value": null,
    "placeholder": null,
    "description": null,
    "config": {
      "options": {
        "option-1": "Option-1",
        "option-2": "Option-2",
        "option-3": "Option-3",
        "option-4": "Option-4"
      },
      "inline": false
    },
    "sort_number": 1,
    "created_at": "2019-01-25 11:30:43",
    "updated_at": "2019-01-25 11:30:43",
    "field_validation_string": "",
    "field_validations": []
  }
]
```

## \[Adm.] List referring to TaskTemplates

Get a list of all `FormFields` that refer to a [TaskTemplate](https://docs.api.intratool.de/api-reference/tasks-2/task-templates).

**Definition**

<mark style="color:green;">`GET`</mark> `/api/administration/tasks-2/templates/fields/`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/administration/tasks-2/templates/fields/', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);


```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 6,
    "form_id": 3,
    "form_type": "taskTemplate",
    "form_field_type_id": "text",
    "name": "Field-1",
    "key": "field-1",
    "default_value": "",
    "placeholder": null,
    "description": null,
    "config": {},
    "sort_number": 1,
    "created_at": "2021-05-25 11:14:23",
    "updated_at": "2021-05-25 11:14:23",
    "field_validation_string": "",
    "field_validations": []
  },
  {
    "id": 7,
    "form_id": 3,
    "form_type": "taskTemplate",
    "form_field_type_id": "radio",
    "name": "Field-2",
    "key": "field-2",
    "default_value": null,
    "placeholder": null,
    "description": null,
    "config": {
      "options": {
        "option-1": "Option-1",
        "option-2": "Option-2",
        "option-3": "Option-3",
        "option-4": "Option-4"
      },
      "inline": false
    },
    "sort_number": 1,
    "created_at": "2021-05-25 11:15:23",
    "updated_at": "2021-05-25 11:15:23",
    "field_validation_string": "",
    "field_validations": []
  }
]
```

## \[Adm.] Create

Create a new `FormField`.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/administration/forms/fields`

**Request Keys**

| Key                  |   Type  |                                               Default                                              | Description                                                                                                                                                       |
| -------------------- | :-----: | :------------------------------------------------------------------------------------------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `form_id` \*         | integer |                                                  -                                                 | The related [Form](https://docs.api.intratool.de/api-reference/forms/forms) or [TaskTemplate](https://docs.api.intratool.de/api-reference/tasks-2/task-templates) |
| `form_type` \*       |  string |                                                  -                                                 | The `type` of the `Form` relation (either `form` or `task`)                                                                                                       |
| `form_field_type_id` |  string |                                               `text`                                               | The related [FormFieldType](https://docs.api.intratool.de/api-reference/forms/form-field-types)                                                                   |
| `name` \*            |  string |                                                  -                                                 | The name of the `FormField` (unique by `Form`)                                                                                                                    |
| `key`                |  string |                                           Slugged `name`                                           | The key to identify the `FormField` (unique by `Form`)                                                                                                            |
| `config`             |   json  | Default [FormFieldType](https://docs.api.intratool.de/api-reference/forms/form-field-types) config | The config that is used to setup the FormField                                                                                                                    |
| `default_value`      |  mixed  |                                               `null`                                               | The default value of the `FormField`                                                                                                                              |
| `placeholder`        |  string |                                               `null`                                               | The placeholder of the `FormField`                                                                                                                                |
| `description`        |  string |                                               `null`                                               | The description of the `FormField`                                                                                                                                |

Keys with `*` are required.

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/administration/forms/fields', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'form_id' => 2,
        'form_type' => 'form',
        'name' => 'Field-4'
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "form_id": 2,
    "form_field_type_id": "text",
    "name": "Field-4",
    "key": "field-4",
    "default_value": null,
    "placeholder": null,
    "description": null,
    "config": {},
    "sort_number": 4,
    "form_type": "form",
    "updated_at": "2019-01-25 12:32:46",
    "created_at": "2019-01-25 12:32:46",
    "id": 9,
    "field_validation_string": "",
    "field_validations": []
  }
}
```

## \[Adm.] Update

Update an existing `FormField` by `id`.

**Definition**

<mark style="color:blue;">`PUT`</mark> `/api/administration/forms/fields/{id}`

**Request Keys**

| Key                  |  Type  | Description                                                                                     |
| -------------------- | :----: | ----------------------------------------------------------------------------------------------- |
| `form_field_type_id` | string | The related [FormFieldType](https://docs.api.intratool.de/api-reference/forms/form-field-types) |
| `name`               | string | The name of the `FormField` (unique by `Form`)                                                  |
| `key`                | string | The key to identify the `FormField` (unique by `Form`)                                          |
| `config`             |  json  | The config that is used to setup the FormField                                                  |
| `default_value`      |  mixed | The default value of the `FormField`                                                            |
| `placeholder`        | string | The placeholder of the `FormField`                                                              |
| `description`        | string | The description of the `FormField`                                                              |

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/administration/forms/fields/9', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'form_field_type_id' => 'rich-text'
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 9,
    "form_id": 2,
    "form_type": "form",
    "form_field_type_id": "rich-text",
    "name": "Field-4",
    "key": "field-4",
    "default_value": null,
    "placeholder": null,
    "description": null,
    "config": {},
    "sort_number": 4,
    "created_at": "2019-01-25 12:32:46",
    "updated_at": "2019-01-25 12:45:49",
    "field_validation_string": "",
    "field_validations": []
  }
}
```

## \[Adm.] Delete

Delete an existing `FormField` by `id`.

**Definition**

<mark style="color:red;">`DELETE`</mark> `/api/administration/forms/fields/{id}`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('DELETE', '/api/administration/forms/fields/9', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": 1
}
```