Symple module

FormElement

Base element within a Symple form.

FormElement

#include <icy/symple/form.h>

Subclassed by: Form, FormField

Base element within a Symple form.

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.
`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()

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)

Constructs an element bound to the given JSON node.

Parameters

root JSON node this element refers to.
type Optional element type string.
id Optional element ID string.
label Optional display label string.

FormElement

FormElement(const FormElement & r)

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

Parameters

r Source element.

operator=

FormElement & operator=(const FormElement & r)

Copy-assigns the root pointer reference.

Parameters

r Source element.

type

const

std::string type() const

Returns the element type string.

id

const

std::string id() const

Returns the element ID string.

label

const

std::string label() const

Returns the display label string.

setType

void setType(std::string_view type)

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

Parameters

type Element type string.

setId

void setId(std::string_view id)

Sets the element ID field.

Parameters

id Element ID string.

setLabel

void setLabel(std::string_view text)

Sets the display label field.

Parameters

text Label text.

setHint

void setHint(std::string_view text)

Sets the hint/description field shown below the element.

Parameters

text Hint text.

setError

void setError(std::string_view error)

Sets an optional validation error message.

Parameters

error Error text to display.

addPage

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

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

Parameters

id Optional page ID.
label Optional page label.

Returns

FormElement referencing the new page node.

addSection

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

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

Parameters

id Optional section ID.
label Optional section label.

Returns

FormElement referencing the new section node.

addField

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

Appends a typed field child element and returns a handle to it. Throws std::invalid_argument if type is not a recognised field type.

Parameters

type Field type (e.g. "text", "list", "boolean").
id Optional field ID.
label Optional field label.

Returns

FormField referencing the new field node.

getField

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

Searches child elements for the field with the given ID.

Parameters

id Field ID to search for.
partial If true, performs a substring match.

Returns

FormField handle (may be invalid if not found).

getField

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

Populates a FormField by searching child elements for the given ID.

Parameters

id Field ID to search for.
field Output field handle.
partial If true, performs a substring match.

Returns

True if the field was found.

hasField

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

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

Parameters

id ID string to search for.
partial If true, a substring match is sufficient.

setLive

void setLive(bool flag)

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

flag True to enable live updates.

live

const

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.

clearElements

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

Removes all child elements whose ID matches the given value.

Parameters

id ID string to match against.
partial If true, removes elements whose ID contains the string.

Returns

True if at least one element was removed.

clear

void clear()

Clears all fields from the underlying JSON node.

valid

const

bool valid() const

Returns true if the form element is valid.

numElements

int numElements()

Returns the number of child elements.

hasErrors

bool hasErrors()

Returns true if any fields have errors.

hasPages

bool hasPages()

Returns true if the form has multiple pages.

root

const

json::Value & root() const

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

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

Built with