#include <icy/symple/form.h>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.
| 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()Constructs an unbound element (root pointer is null).
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.
root JSON node this element refers to.
type Optional element type string.
id Optional element ID string.
label Optional display label string.
FormElement(const FormElement & r)Copy constructor; copies the root pointer reference (shallow).
r Source element.FormElement & operator=(const FormElement & r)Copy-assigns the root pointer reference.
r Source element.const
std::string type() constReturns the element type string.
const
std::string id() constReturns the element ID string.
const
std::string label() constReturns the display label string.
void setType(std::string_view type)Sets the element type. Possible values: page, section, text, text-multi, list, list-multi, checkbox, media, custom
type Element type string.void setId(std::string_view id)Sets the element ID field.
id Element ID string.void setLabel(std::string_view text)Sets the display label field.
text Label text.void setHint(std::string_view text)Sets the hint/description field shown below the element.
text Hint text.void setError(std::string_view error)Sets an optional validation error message.
error Error text to display.FormElement addPage(std::string_view id, std::string_view label)Appends a page child element and returns a handle to it.
id Optional page ID.
label Optional page label.
FormElement referencing the new page node.
FormElement addSection(std::string_view id, std::string_view label)Appends a section child element and returns a handle to it.
id Optional section ID.
label Optional section label.
FormElement referencing the new section node.
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.
type Field type (e.g. "text", "list", "boolean").
id Optional field ID.
label Optional field label.
FormField referencing the new field node.
FormField getField(std::string_view id, bool partial)Searches child elements for the field with the given ID.
id Field ID to search for.
partial If true, performs a substring match.
FormField handle (may be invalid if not found).
bool getField(std::string_view id, FormField & field, bool partial)Populates a FormField by searching child elements for the given ID.
id Field ID to search for.
field Output field handle.
partial If true, performs a substring match.
True if the field was found.
bool hasField(std::string_view id, bool partial)Returns true if any child element has an ID matching the given value.
id ID string to search for.
partial If true, a substring match is sufficient.
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.
flag True to enable live updates.const
bool live() constReturns true if this field is live, meaning the form-processing entity should auto-update this field's value whenever it changes.
bool clearElements(std::string_view id, bool partial)Removes all child elements whose ID matches the given value.
id ID string to match against.
partial If true, removes elements whose ID contains the string.
True if at least one element was removed.
void clear()Clears all fields from the underlying JSON node.
const
bool valid() constReturns 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.
const
json::Value & root() constReturns a reference to the underlying JSON node. Throws std::runtime_error if the root pointer is null.
| Return | Name | Description |
|---|---|---|
json::Value * | _root | The root pointer is just a reference to the externally managed JSON value memory. |
json::Value * _rootThe root pointer is just a reference to the externally managed JSON value memory.