FormElement

#include <icy/symple/form.h>

class FormElement

Defined in src/symple/include/icy/symple/form.h:33

Subclassed by: Form, FormField

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`	Constructs an unbound element (root pointer is null).
	`FormElement`	Constructs an element bound to the given JSON node.
	`FormElement`	Copy constructor; copies the root pointer reference (shallow).
`FormElement` &	`operator=`	Copy-assigns the root pointer reference.
	`~FormElement` virtual
`std::string`	`type` const	Returns the element type string.
`std::string`	`id` const	Returns the element ID string.
`std::string`	`label` const	Returns the display label string.
`void`	`setType`	Sets the element type. Possible values: page, section, text, text-multi, list, list-multi, checkbox, media, custom
`void`	`setId`	Sets the element ID field.
`void`	`setLabel`	Sets the display label field.
`void`	`setHint`	Sets the hint/description field shown below the element.
`void`	`setError`	Sets an optional validation error message.
`FormElement`	`addPage`	Appends a page child element and returns a handle to it.
`FormElement`	`addSection`	Appends a section child element and returns a handle to it.
`FormField`	`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`	`getField`	Searches child elements for the field with the given ID.
`bool`	`getField`	Populates a FormField by searching child elements for the given ID.
`bool`	`hasField`	Returns true if any child element has an ID matching the given value.
`void`	`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` 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`	Removes all child elements whose ID matches the given value.
`void`	`clear`	Clears all fields from the underlying JSON node.
`bool`	`valid` const	Returns true if the form element is valid.
`int`	`numElements`	Returns the number of child elements.
`bool`	`hasErrors`	Returns true if any fields have errors.
`bool`	`hasPages`	Returns true if the form has multiple pages.
`json::Value` &	`root` const	Returns a reference to the underlying JSON node. Throws std::runtime_error if the root pointer is null.

FormElement

FormElement()

Defined in src/symple/include/icy/symple/form.h:37

Constructs an unbound element (root pointer is null).

FormElement

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

Constructs an element bound to the given JSON node.

Parameters

Parameter	Type	Description
`root`	`json::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.

FormElement

FormElement(const FormElement & r)

Defined in src/symple/include/icy/symple/form.h:49

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

Parameters

Parameter	Type	Description
`r`	const `FormElement` &	Source element.

operator=

FormElement & operator=(const FormElement & r)

Defined in src/symple/include/icy/symple/form.h:53

Copy-assigns the root pointer reference.

Parameters

Parameter	Type	Description
`r`	const `FormElement` &	Source element.

~FormElement

virtual

virtual ~FormElement()

Defined in src/symple/include/icy/symple/form.h:55

type

const

std::string type() const

Defined in src/symple/include/icy/symple/form.h:58

Returns the element type string.

id

const

std::string id() const

Defined in src/symple/include/icy/symple/form.h:61

Returns the element ID string.

label

const

std::string label() const

Defined in src/symple/include/icy/symple/form.h:64

Returns the display label string.

setType

void setType(std::string_view type)

Defined in src/symple/include/icy/symple/form.h:70

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.

setId

void setId(std::string_view id)

Defined in src/symple/include/icy/symple/form.h:74

Sets the element ID field.

Parameters

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

setLabel

void setLabel(std::string_view text)

Defined in src/symple/include/icy/symple/form.h:78

Sets the display label field.

Parameters

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

setHint

void setHint(std::string_view text)

Defined in src/symple/include/icy/symple/form.h:82

Sets the hint/description field shown below the element.

Parameters

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

setError

void setError(std::string_view error)

Defined in src/symple/include/icy/symple/form.h:86

Sets an optional validation error message.

Parameters

Parameter	Type	Description
`error`	`std::string_view`	Error text to display.

addPage

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

Defined in src/symple/include/icy/symple/form.h:92

Appends a page child element and returns a handle to it.

Returns

FormElement referencing the new page node.

Parameters

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

addSection

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

Defined in src/symple/include/icy/symple/form.h:99

Appends a section child element and returns a handle to it.

Returns

FormElement referencing the new section node.

Parameters

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

addField

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

Defined in src/symple/include/icy/symple/form.h:108

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

getField

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

Defined in src/symple/include/icy/symple/form.h:115

Searches child elements for the field with the given ID.

Returns

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.

getField

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

Defined in src/symple/include/icy/symple/form.h:122

Populates a 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` &	Output field handle.
`partial`	`bool`	If true, performs a substring match.

hasField

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

Defined in src/symple/include/icy/symple/form.h:128

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.

setLive

void setLive(bool flag)

Defined in src/symple/include/icy/symple/form.h:134

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.

live

const

bool live() const

Defined in src/symple/include/icy/symple/form.h:139

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

clearElements

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

Defined in src/symple/include/icy/symple/form.h:145

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.

clear

void clear()

Defined in src/symple/include/icy/symple/form.h:148

Clears all fields from the underlying JSON node.

valid

const

bool valid() const

Defined in src/symple/include/icy/symple/form.h:151

Returns true if the form element is valid.

numElements

int numElements()

Defined in src/symple/include/icy/symple/form.h:154

Returns the number of child elements.

hasErrors

bool hasErrors()

Defined in src/symple/include/icy/symple/form.h:157

Returns true if any fields have errors.

hasPages

bool hasPages()

Defined in src/symple/include/icy/symple/form.h:160

Returns true if the form has multiple pages.

root

const

json::Value & root() const

Defined in src/symple/include/icy/symple/form.h:164

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` *	`_root`	The root pointer is just a reference to the externally managed JSON value memory.

_root

json::Value * _root

Type: json::Value *

Defined in src/symple/include/icy/symple/form.h:169

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