# Form

<a id="form"></a>

# Form

```cpp
#include <icy/symple/form.h>

class Form
```

[Defined in src/symple/include/icy/symple/form.h:178](https://github.com/auscaster/icey/blob/main/src/symple/include/icy/symple/form.h#L178)

> **Inherits:** [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement)

Interactive form with pages, sections, and fields for command data exchange.

Attach a [Form](#form) to a [Command](https://auscaster.com/icey/docs/api-reference/icy-smpl-Command.md#command) message to carry structured input/output. The `action` field governs the exchange direction; `partial` enables live/auto-complete field submission.

## List of all members

| Name | Kind | Owner |
|------|------|-------|
| [`Form`](#form-1) | `function` | Declared here |
| [`Form`](#form-2) | `function` | Declared here |
| [`Form`](#form-3) | `function` | Declared here |
| [`~Form`](#form-4) | `function` | Declared here |
| [`valid`](#valid-13) | `function` | Declared here |
| [`action`](#action-3) | `function` | Declared here |
| [`partial`](#partial) | `function` | Declared here |
| [`setAction`](#setaction-1) | `function` | Declared here |
| [`setPartial`](#setpartial) | `function` | Declared here |
| [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement-1) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement-2) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement-3) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#operator-246) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`~FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement-4) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`type`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#type-24) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`id`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#id-11) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`label`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#label) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`setType`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#settype-1) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`setId`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#setid) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`setLabel`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#setlabel) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`setHint`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#sethint) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`setError`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#seterror-8) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`addPage`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#addpage) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`addSection`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#addsection) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`addField`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#addfield) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`getField`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#getfield) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`getField`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#getfield-1) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`hasField`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#hasfield) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`setLive`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#setlive) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`live`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#live) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`clearElements`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#clearelements) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`clear`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#clear-10) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`valid`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#valid-14) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`numElements`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#numelements) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`hasErrors`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#haserrors) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`hasPages`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#haspages) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`root`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#root-4) | `function` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |
| [`_root`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#_root) | `variable` | Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement) |

## Inherited from [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement)

| Kind | Name | Description |
|------|------|-------------|
| `function` | [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement-1)  | Constructs an unbound element (root pointer is null). |
| `function` | [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement-2)  | Constructs an element bound to the given JSON node. |
| `function` | [`FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement-3)  | Copy constructor; copies the root pointer reference (shallow). |
| `function` | [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#operator-246)  | Copy-assigns the root pointer reference. |
| `function` | [`~FormElement`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#formelement-4) `virtual` |  |
| `function` | [`type`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#type-24) `const` | Returns the element type string. |
| `function` | [`id`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#id-11) `const` | Returns the element ID string. |
| `function` | [`label`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#label) `const` | Returns the display label string. |
| `function` | [`setType`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#settype-1)  | Sets the element type. Possible values: page, section, text, text-multi, list, list-multi, checkbox, media, custom |
| `function` | [`setId`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#setid)  | Sets the element ID field. |
| `function` | [`setLabel`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#setlabel)  | Sets the display label field. |
| `function` | [`setHint`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#sethint)  | Sets the hint/description field shown below the element. |
| `function` | [`setError`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#seterror-8)  | Sets an optional validation error message. |
| `function` | [`addPage`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#addpage)  | Appends a page child element and returns a handle to it. |
| `function` | [`addSection`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#addsection)  | Appends a section child element and returns a handle to it. |
| `function` | [`addField`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#addfield)  | Appends a typed field child element and returns a handle to it. Throws std::invalid_argument if type is not a recognised field type. |
| `function` | [`getField`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#getfield)  | Searches child elements for the field with the given ID. |
| `function` | [`getField`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#getfield-1)  | Populates a [FormField](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormField.md#formfield) by searching child elements for the given ID. |
| `function` | [`hasField`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#hasfield)  | Returns true if any child element has an ID matching the given value. |
| `function` | [`setLive`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#setlive)  | Sets the live flag on this element. Live elements are used to submit partial form sections (e.g. for auto-complete) without sending the entire form. |
| `function` | [`live`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#live) `const` | Returns true if this field is live, meaning the form-processing entity should auto-update this field's value whenever it changes. |
| `function` | [`clearElements`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#clearelements)  | Removes all child elements whose ID matches the given value. |
| `function` | [`clear`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#clear-10)  | Clears all fields from the underlying JSON node. |
| `function` | [`valid`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#valid-14) `const` | Returns true if the form element is valid. |
| `function` | [`numElements`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#numelements)  | Returns the number of child elements. |
| `function` | [`hasErrors`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#haserrors)  | Returns true if any fields have errors. |
| `function` | [`hasPages`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#haspages)  | Returns true if the form has multiple pages. |
| `function` | [`root`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#root-4) `const` | Returns a reference to the underlying JSON node. Throws std::runtime_error if the root pointer is null. |
| `variable` | [`_root`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormElement.md#_root)  | The root pointer is just a reference to the externally managed JSON value memory. |

## Public Methods

| Return | Name | Description |
|--------|------|-------------|
|  | [`Form`](#form-1)  | Constructs an unbound form (root pointer is null). |
|  | [`Form`](#form-2)  | Constructs a form bound to the given JSON node. Sets the `type` field to "form". |
|  | [`Form`](#form-3)  | Constructs a form from a [Command](https://auscaster.com/icey/docs/api-reference/icy-smpl-Command.md#command), binding to `command["form"]`. Sets the `type` field to "form". |
|  | [`~Form`](#form-4) `virtual` |  |
| `bool` | [`valid`](#valid-13)  | Returns true if the element is valid, non-empty, and has no errors. |
| `std::string` | [`action`](#action-3) `const` | Returns the form action string (defaults to "form"). |
| `bool` | [`partial`](#partial) `const` | Returns true if this is a partial form submission. |
| `void` | [`setAction`](#setaction-1)  | Sets the form action field. Throws std::invalid_argument for unrecognised values. Possible values: `form` - Form-processing entity requests form completion. `submit` - Form-submitting entity is sending data. `cancel` - Form-submitting entity cancelled submission. `result` - Form-processing entity is returning data. |
| `void` | [`setPartial`](#setpartial)  | Marks the form as a partial section for live/auto-complete updates. Partial forms transmit only the changed fields rather than the entire form payload. |

---

<a id="form-1"></a>

### Form

```cpp
Form()
```

[Defined in src/symple/include/icy/symple/form.h:182](https://github.com/auscaster/icey/blob/main/src/symple/include/icy/symple/form.h#L182)

Constructs an unbound form (root pointer is null).

---

<a id="form-2"></a>

### Form

```cpp
Form(json::Value & root)
```

[Defined in src/symple/include/icy/symple/form.h:187](https://github.com/auscaster/icey/blob/main/src/symple/include/icy/symple/form.h#L187)

Constructs a form bound to the given JSON node. Sets the `type` field to "form".

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `root` | [`json::Value`](https://auscaster.com/icey/docs/api-reference/icy-json.md#value) & | JSON node to bind to. |

---

<a id="form-3"></a>

### Form

```cpp
Form(Command & root)
```

[Defined in src/symple/include/icy/symple/form.h:192](https://github.com/auscaster/icey/blob/main/src/symple/include/icy/symple/form.h#L192)

Constructs a form from a [Command](https://auscaster.com/icey/docs/api-reference/icy-smpl-Command.md#command), binding to `command["form"]`. Sets the `type` field to "form".

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `root` | [`Command`](https://auscaster.com/icey/docs/api-reference/icy-smpl-Command.md#command) & | Parent command message. |

---

<a id="form-4"></a>

### ~Form

`virtual`

```cpp
virtual ~Form()
```

[Defined in src/symple/include/icy/symple/form.h:194](https://github.com/auscaster/icey/blob/main/src/symple/include/icy/symple/form.h#L194)

---

<a id="valid-13"></a>

### valid

```cpp
bool valid()
```

[Defined in src/symple/include/icy/symple/form.h:197](https://github.com/auscaster/icey/blob/main/src/symple/include/icy/symple/form.h#L197)

Returns true if the element is valid, non-empty, and has no errors.

---

<a id="action-3"></a>

### action

`const`

```cpp
std::string action() const
```

[Defined in src/symple/include/icy/symple/form.h:200](https://github.com/auscaster/icey/blob/main/src/symple/include/icy/symple/form.h#L200)

Returns the form action string (defaults to "form").

---

<a id="partial"></a>

### partial

`const`

```cpp
bool partial() const
```

[Defined in src/symple/include/icy/symple/form.h:203](https://github.com/auscaster/icey/blob/main/src/symple/include/icy/symple/form.h#L203)

Returns true if this is a partial form submission.

---

<a id="setaction-1"></a>

### setAction

```cpp
void setAction(std::string_view action)
```

[Defined in src/symple/include/icy/symple/form.h:213](https://github.com/auscaster/icey/blob/main/src/symple/include/icy/symple/form.h#L213)

Sets the form action field. Throws std::invalid_argument for unrecognised values. Possible values: `form` - Form-processing entity requests form completion. `submit` - Form-submitting entity is sending data. `cancel` - Form-submitting entity cancelled submission. `result` - Form-processing entity is returning data.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `action` | `std::string_view` | Action string. |

---

<a id="setpartial"></a>

### setPartial

```cpp
void setPartial(bool flag)
```

[Defined in src/symple/include/icy/symple/form.h:219](https://github.com/auscaster/icey/blob/main/src/symple/include/icy/symple/form.h#L219)

Marks the form as a partial section for live/auto-complete updates. Partial forms transmit only the changed fields rather than the entire form payload.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `flag` | `bool` | True to mark as partial. |