# FormField

<a id="formfield"></a>

# FormField

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

class FormField
```

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

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

[Form](https://auscaster.com/icey/docs/api-reference/icy-smpl-Form.md#form) input field with typed values and selectable options.

Values are stored as strings in a JSON array. Typed accessors (intValue, doubleValue, boolValue) parse the first string on demand.

## List of all members

| Name | Kind | Owner |
|------|------|-------|
| [`FormField`](#formfield-1) | `function` | Declared here |
| [`FormField`](#formfield-2) | `function` | Declared here |
| [`~FormField`](#formfield-3) | `function` | Declared here |
| [`addOption`](#addoption) | `function` | Declared here |
| [`addOption`](#addoption-1) | `function` | Declared here |
| [`setValue`](#setvalue-4) | `function` | Declared here |
| [`setValue`](#setvalue-5) | `function` | Declared here |
| [`setValue`](#setvalue-6) | `function` | Declared here |
| [`setValue`](#setvalue-7) | `function` | Declared here |
| [`addValue`](#addvalue) | `function` | Declared here |
| [`addValue`](#addvalue-1) | `function` | Declared here |
| [`addValue`](#addvalue-2) | `function` | Declared here |
| [`addValue`](#addvalue-3) | `function` | Declared here |
| [`values`](#values) | `function` | Declared here |
| [`value`](#value-4) | `function` | Declared here |
| [`intValue`](#intvalue) | `function` | Declared here |
| [`doubleValue`](#doublevalue) | `function` | Declared here |
| [`boolValue`](#boolvalue) | `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](#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 |
|--------|------|-------------|
|  | [`FormField`](#formfield-1)  | Constructs an unbound field (root pointer is null). |
|  | [`FormField`](#formfield-2)  | Constructs a field bound to the given JSON node. |
|  | [`~FormField`](#formfield-3) `virtual` |  |
| `void` | [`addOption`](#addoption)  | Adds a labelled option for list-based fields. |
| `void` | [`addOption`](#addoption-1)  | Adds an option whose key and display value are identical. |
| `void` | [`setValue`](#setvalue-4)  | Replaces all current values with a single string value. |
| `void` | [`setValue`](#setvalue-5)  | Replaces all current values with a single integer value. |
| `void` | [`setValue`](#setvalue-6)  | Replaces all current values with a single double value. |
| `void` | [`setValue`](#setvalue-7)  | Replaces all current values with a single boolean value. |
| `void` | [`addValue`](#addvalue)  | Appends a string value to the values array. |
| `void` | [`addValue`](#addvalue-1)  | Appends an integer value to the values array. |
| `void` | [`addValue`](#addvalue-2)  | Appends a double value to the values array. |
| `void` | [`addValue`](#addvalue-3)  | Appends a boolean value to the values array. |
| [`json::Value`](https://auscaster.com/icey/docs/api-reference/icy-json.md#value) & | [`values`](#values)  | Returns a reference to the JSON array of all values. |
| `std::string` | [`value`](#value-4) `const` | Returns the first value as a string. Most field types (except multi-value) only use a single value. |
| `int` | [`intValue`](#intvalue) `const` | Returns the first value parsed as an integer. |
| `double` | [`doubleValue`](#doublevalue) `const` | Returns the first value parsed as a double. |
| `bool` | [`boolValue`](#boolvalue) `const` | Returns the first value parsed as a boolean. Treats "1", "true", and "on" as true; all other strings as false. |

---

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

### FormField

```cpp
FormField()
```

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

Constructs an unbound field (root pointer is null).

---

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

### FormField

```cpp
FormField(json::Value & root, std::string_view type = "", std::string_view id = "", std::string_view label = "")
```

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

Constructs a field bound to the given JSON node.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `root` | [`json::Value`](https://auscaster.com/icey/docs/api-reference/icy-json.md#value) & | JSON node to bind to. |
| `type` | `std::string_view` | Field type string (e.g. "text", "list"). |
| `id` | `std::string_view` | Optional field ID. |
| `label` | `std::string_view` | Optional display label. |

---

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

### ~FormField

`virtual`

```cpp
virtual ~FormField()
```

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

---

<a id="addoption"></a>

### addOption

```cpp
void addOption(std::string_view key, std::string_view value)
```

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

Adds a labelled option for list-based fields.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | `std::string_view` | Option key sent on submit. |
| `value` | `std::string_view` | Display label for the option. |

---

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

### addOption

```cpp
void addOption(std::string_view value)
```

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

Adds an option whose key and display value are identical.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `value` | `std::string_view` | Option string. |

---

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

### setValue

```cpp
void setValue(std::string_view value)
```

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

Replaces all current values with a single string value.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `value` | `std::string_view` | String value to set. |

---

<a id="setvalue-5"></a>

### setValue

```cpp
void setValue(int value)
```

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

Replaces all current values with a single integer value.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `value` | `int` | Integer value to set. |

---

<a id="setvalue-6"></a>

### setValue

```cpp
void setValue(double value)
```

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

Replaces all current values with a single double value.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `value` | `double` | Double value to set. |

---

<a id="setvalue-7"></a>

### setValue

```cpp
void setValue(bool value)
```

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

Replaces all current values with a single boolean value.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `value` | `bool` | Boolean value to set. |

---

<a id="addvalue"></a>

### addValue

```cpp
void addValue(std::string_view value)
```

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

Appends a string value to the values array.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `value` | `std::string_view` | String value to append. |

---

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

### addValue

```cpp
void addValue(int value)
```

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

Appends an integer value to the values array.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `value` | `int` | Integer value to append. |

---

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

### addValue

```cpp
void addValue(double value)
```

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

Appends a double value to the values array.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `value` | `double` | Double value to append. |

---

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

### addValue

```cpp
void addValue(bool value)
```

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

Appends a boolean value to the values array.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `value` | `bool` | Boolean value to append. |

---

<a id="values"></a>

### values

```cpp
json::Value & values()
```

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

Returns a reference to the JSON array of all values.

---

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

### value

`const`

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

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

Returns the first value as a string. Most field types (except multi-value) only use a single value.

---

<a id="intvalue"></a>

### intValue

`const`

```cpp
int intValue() const
```

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

Returns the first value parsed as an integer.

---

<a id="doublevalue"></a>

### doubleValue

`const`

```cpp
double doubleValue() const
```

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

Returns the first value parsed as a double.

---

<a id="boolvalue"></a>

### boolValue

`const`

```cpp
bool boolValue() const
```

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

Returns the first value parsed as a boolean. Treats "1", "true", and "on" as true; all other strings as false.