# FormElement

<a id="formelement"></a>

# FormElement

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

class FormElement
```

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

> **Subclassed by:** [`Form`](https://auscaster.com/icey/docs/api-reference/icy-smpl-Form.md#form), [`FormField`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormField.md#formfield)

Base element within a Symple form.

[FormElement](#formelement) wraps a reference to an external JSON node and provides typed accessors for the common `type`, `id`, `label`, and `elements` fields. Pages, sections, and fields all derive from this base.

## Public Methods

| Return | Name | Description |
|--------|------|-------------|
|  | [`FormElement`](#formelement-1)  | Constructs an unbound element (root pointer is null). |
|  | [`FormElement`](#formelement-2)  | Constructs an element bound to the given JSON node. |
|  | [`FormElement`](#formelement-3)  | Copy constructor; copies the root pointer reference (shallow). |
| [`FormElement`](#formelement) & | [`operator=`](#operator-246)  | Copy-assigns the root pointer reference. |
|  | [`~FormElement`](#formelement-4) `virtual` |  |
| `std::string` | [`type`](#type-24) `const` | Returns the element type string. |
| `std::string` | [`id`](#id-11) `const` | Returns the element ID string. |
| `std::string` | [`label`](#label) `const` | Returns the display label string. |
| `void` | [`setType`](#settype-1)  | Sets the element type. Possible values: page, section, text, text-multi, list, list-multi, checkbox, media, custom |
| `void` | [`setId`](#setid)  | Sets the element ID field. |
| `void` | [`setLabel`](#setlabel)  | Sets the display label field. |
| `void` | [`setHint`](#sethint)  | Sets the hint/description field shown below the element. |
| `void` | [`setError`](#seterror-8)  | Sets an optional validation error message. |
| [`FormElement`](#formelement) | [`addPage`](#addpage)  | Appends a page child element and returns a handle to it. |
| [`FormElement`](#formelement) | [`addSection`](#addsection)  | Appends a section child element and returns a handle to it. |
| [`FormField`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormField.md#formfield) | [`addField`](#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. |
| [`FormField`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormField.md#formfield) | [`getField`](#getfield)  | Searches child elements for the field with the given ID. |
| `bool` | [`getField`](#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. |
| `bool` | [`hasField`](#hasfield)  | Returns true if any child element has an ID matching the given value. |
| `void` | [`setLive`](#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. |
| `bool` | [`live`](#live) `const` | Returns true if this field is live, meaning the form-processing entity should auto-update this field's value whenever it changes. |
| `bool` | [`clearElements`](#clearelements)  | Removes all child elements whose ID matches the given value. |
| `void` | [`clear`](#clear-10)  | Clears all fields from the underlying JSON node. |
| `bool` | [`valid`](#valid-14) `const` | Returns true if the form element is valid. |
| `int` | [`numElements`](#numelements)  | Returns the number of child elements. |
| `bool` | [`hasErrors`](#haserrors)  | Returns true if any fields have errors. |
| `bool` | [`hasPages`](#haspages)  | Returns true if the form has multiple pages. |
| [`json::Value`](https://auscaster.com/icey/docs/api-reference/icy-json.md#value) & | [`root`](#root-4) `const` | Returns a reference to the underlying JSON node. Throws std::runtime_error if the root pointer is null. |

---

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

### FormElement

```cpp
FormElement()
```

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

Constructs an unbound element (root pointer is null).

---

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

### FormElement

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

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

Constructs an element 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 this element refers to. |
| `type` | `std::string_view` | Optional element type string. |
| `id` | `std::string_view` | Optional element ID string. |
| `label` | `std::string_view` | Optional display label string. |

---

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

### FormElement

```cpp
FormElement(const FormElement & r)
```

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

Copy constructor; copies the root pointer reference (shallow).

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `r` | const [`FormElement`](#formelement) & | Source element. |

---

<a id="operator-246"></a>

### operator=

```cpp
FormElement & operator=(const FormElement & r)
```

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

Copy-assigns the root pointer reference.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `r` | const [`FormElement`](#formelement) & | Source element. |

---

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

### ~FormElement

`virtual`

```cpp
virtual ~FormElement()
```

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

---

<a id="type-24"></a>

### type

`const`

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

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

Returns the element type string.

---

<a id="id-11"></a>

### id

`const`

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

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

Returns the element ID string.

---

<a id="label"></a>

### label

`const`

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

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

Returns the display label string.

---

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

### setType

```cpp
void setType(std::string_view type)
```

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

Sets the element type. Possible values: page, section, text, text-multi, list, list-multi, checkbox, media, custom

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `type` | `std::string_view` | Element type string. |

---

<a id="setid"></a>

### setId

```cpp
void setId(std::string_view id)
```

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

Sets the element ID field.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | `std::string_view` | Element ID string. |

---

<a id="setlabel"></a>

### setLabel

```cpp
void setLabel(std::string_view text)
```

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

Sets the display label field.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `text` | `std::string_view` | Label text. |

---

<a id="sethint"></a>

### setHint

```cpp
void setHint(std::string_view text)
```

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

Sets the hint/description field shown below the element.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `text` | `std::string_view` | Hint text. |

---

<a id="seterror-8"></a>

### setError

```cpp
void setError(std::string_view error)
```

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

Sets an optional validation error message.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `error` | `std::string_view` | [Error](https://auscaster.com/icey/docs/api-reference/icy-Error.md#error) text to display. |

---

<a id="addpage"></a>

### addPage

```cpp
FormElement addPage(std::string_view id = "", std::string_view label = "")
```

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

Appends a page child element and returns a handle to it. 
#### Returns
[FormElement](#formelement) referencing the new page node.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | `std::string_view` | Optional page ID. |
| `label` | `std::string_view` | Optional page label. |

---

<a id="addsection"></a>

### addSection

```cpp
FormElement addSection(std::string_view id = "", std::string_view label = "")
```

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

Appends a section child element and returns a handle to it. 
#### Returns
[FormElement](#formelement) referencing the new section node.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | `std::string_view` | Optional section ID. |
| `label` | `std::string_view` | Optional section label. |

---

<a id="addfield"></a>

### addField

```cpp
FormField addField(std::string_view type, std::string_view id = "", std::string_view label = "")
```

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

Appends a typed field child element and returns a handle to it. Throws std::invalid_argument if type is not a recognised field type. 
#### Returns
[FormField](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormField.md#formfield) referencing the new field node.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `type` | `std::string_view` | Field type (e.g. "text", "list", "boolean"). |
| `id` | `std::string_view` | Optional field ID. |
| `label` | `std::string_view` | Optional field label. |

---

<a id="getfield"></a>

### getField

```cpp
FormField getField(std::string_view id, bool partial = false)
```

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

Searches child elements for the field with the given ID. 
#### Returns
[FormField](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormField.md#formfield) handle (may be invalid if not found).

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | `std::string_view` | Field ID to search for. |
| `partial` | `bool` | If true, performs a substring match. |

---

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

### getField

```cpp
bool getField(std::string_view id, FormField & field, bool partial = false)
```

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

Populates a [FormField](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormField.md#formfield) by searching child elements for the given ID. 
#### Returns
True if the field was found.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | `std::string_view` | Field ID to search for. |
| `field` | [`FormField`](https://auscaster.com/icey/docs/api-reference/icy-smpl-FormField.md#formfield) & | Output field handle. |
| `partial` | `bool` | If true, performs a substring match. |

---

<a id="hasfield"></a>

### hasField

```cpp
bool hasField(std::string_view id, bool partial = false)
```

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

Returns true if any child element has an ID matching the given value.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | `std::string_view` | ID string to search for. |
| `partial` | `bool` | If true, a substring match is sufficient. |

---

<a id="setlive"></a>

### setLive

```cpp
void setLive(bool flag)
```

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

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.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `flag` | `bool` | True to enable live updates. |

---

<a id="live"></a>

### live

`const`

```cpp
bool live() const
```

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

Returns true if this field is live, meaning the form-processing entity should auto-update this field's value whenever it changes.

---

<a id="clearelements"></a>

### clearElements

```cpp
bool clearElements(std::string_view id, bool partial = false)
```

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

Removes all child elements whose ID matches the given value. 
#### Returns
True if at least one element was removed.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | `std::string_view` | ID string to match against. |
| `partial` | `bool` | If true, removes elements whose ID contains the string. |

---

<a id="clear-10"></a>

### clear

```cpp
void clear()
```

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

Clears all fields from the underlying JSON node.

---

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

### valid

`const`

```cpp
bool valid() const
```

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

Returns true if the form element is valid.

---

<a id="numelements"></a>

### numElements

```cpp
int numElements()
```

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

Returns the number of child elements.

---

<a id="haserrors"></a>

### hasErrors

```cpp
bool hasErrors()
```

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

Returns true if any fields have errors.

---

<a id="haspages"></a>

### hasPages

```cpp
bool hasPages()
```

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

Returns true if the form has multiple pages.

---

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

### root

`const`

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

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

Returns a reference to the underlying JSON node. Throws std::runtime_error if the root pointer is null.

## Protected Attributes

| Return | Name | Description |
|--------|------|-------------|
| [`json::Value`](https://auscaster.com/icey/docs/api-reference/icy-json.md#value) * | [`_root`](#_root)  | The root pointer is just a reference to the externally managed JSON value memory. |

---

<a id="_root"></a>

### _root

```cpp
json::Value * _root
```

Type: [`json::Value`](https://auscaster.com/icey/docs/api-reference/icy-json.md#value) *

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

The root pointer is just a reference to the externally managed JSON value memory.