The reactive state of one form: a controller over a FormModel. More...

#include <form_session.hpp>

Public Member Functions
	FormSession (reactive::Runtime &runtime, FormModel model, Submitter submit, ChoiceFetcher choices, FormSessionOptions options={})
	FormSession (FormSession const &)=delete
FormSession &	operator= (FormSession const &)=delete
	FormSession (FormSession &&)=delete
FormSession &	operator= (FormSession &&)=delete
FormModel const &	model () const noexcept
	The form model.
reactive::Runtime &	runtime () const noexcept
	The runtime.
SubmitMode	submitMode () const noexcept
	When the form submits.
FormSessionOptions const &	options () const noexcept
	The session options.
std::span< std::unique_ptr< FieldState > const >	fields () const noexcept
	The top-level fields, in x-order.
FieldState &	field (std::string_view path) const
	A field by path: name, parent.member, or rows[i].member (a row by position).
bool	ready () const
	Whether the form can submit. Tracked.
std::optional< std::string >	body () const
	The body the form would submit. Tracked.
void	submit ()
	Submits the current body; does nothing while not ready, or while a submission is in flight (the submission is Exclusive). The explicit-mode trigger; in automatic mode it forces a resubmission of an unchanged body.
void	prefill (std::string_view bodyJson)
	Loads a stored payload for editing. Every field is replaced (an absent member starts blank), every unit returns to the canonical one, and nothing is submitted. Text that is not a JSON object changes nothing.
void	refill (std::string_view bodyJson)
	Loads a stored payload like prefill, except that a top-level field the user changed since the form was last loaded keeps what they entered: a later value of the record being edited, such as its first value arriving after the user started typing, or a refetch, does not discard the edit. Nothing is submitted. Text that is not a JSON object changes nothing.
void	assign (std::string_view path, std::string_view jsonValue)
	Sets one field from a JSON value, programmatically (nothing is submitted).
void	reset ()
	Blanks every field, programmatically (nothing is submitted).
bool	pending () const
	Whether a submission is in flight. Tracked.
std::optional< std::string > const &	lastReply () const
	The last successful reply. Tracked.
std::exception_ptr	lastError () const
	The last failure. Tracked.
std::uint64_t	successCount () const
	How many submissions have succeeded. Tracked; each success ticks it, so an observer sees every submission even when two replies are equal.
std::uint64_t	submitAttempts () const
	How many submissions have been sent, automatic and explicit. Tracked; a submission the Exclusive mutation refused while another was in flight does not count.
reactive::Signal< bool > &	groupCollapsed (std::size_t group) const
	An accordion group's collapsed state.
reactive::Signal< std::size_t > &	tabSelection (std::size_t group) const
	A tab run's selected tab, keyed by the run's first group index.
std::string	groupTitle (std::size_t group) const
	A group's title, resolved through the translations (key <action>.group.<index>).

Static Public Member Functions
static std::optional< std::size_t >	rowIndexOf (std::string_view digits)
	A row position written in a path's brackets.

Detailed Description

The reactive state of one form: a controller over a FormModel.

Non-copyable and non-movable: fields, bindings and in-flight replies point into it. Destroy a mounted view of it before the session.

Definition at line 777 of file form_session.hpp.

Constructor & Destructor Documentation

◆ FormSession()

morph::forms::FormSession::FormSession	(	reactive::Runtime &	runtime,
		FormModel	model,
		Submitter	submit,
		ChoiceFetcher	choices,
		FormSessionOptions	options = {} )

inline

Parameters

runtime	The runtime. Borrowed: it must outlive the session.
model	The form model.
submit	Executes the form's action. Required.
choices	Fetches Choice options; may be empty when no field is a Choice.
options	Locale, translations, display zone, extra readiness gate.

Exceptions

std::invalid_argument when submit is empty.

Definition at line 785 of file form_session.hpp.

Member Function Documentation

◆ model()

FormModel const & morph::forms::FormSession::model ( ) const

inlinenodiscardnoexcept

The form model.

Returns: The model.

Definition at line 831 of file form_session.hpp.

◆ runtime()

reactive::Runtime & morph::forms::FormSession::runtime ( ) const

inlinenodiscardnoexcept

The runtime.

Returns: The runtime passed at construction.

Definition at line 835 of file form_session.hpp.

◆ submitMode()

SubmitMode morph::forms::FormSession::submitMode ( ) const

inlinenodiscardnoexcept

When the form submits.

Returns: The model's submit mode.

Definition at line 839 of file form_session.hpp.

◆ options()

FormSessionOptions const & morph::forms::FormSession::options ( ) const

inlinenodiscardnoexcept

The session options.

Returns: The options.

Definition at line 843 of file form_session.hpp.

◆ fields()

std::span< std::unique_ptr< FieldState > const > morph::forms::FormSession::fields ( ) const

inlinenodiscardnoexcept

The top-level fields, in x-order.

Returns: The fields.

Definition at line 847 of file form_session.hpp.

◆ rowIndexOf()

std::optional< std::size_t > morph::forms::FormSession::rowIndexOf ( std::string_view digits )

inlinestaticnodiscard

A row position written in a path's brackets.

Parameters

digits The text between the brackets.

Returns: The position, or std::nullopt unless the text is all decimal digits.

Definition at line 852 of file form_session.hpp.

◆ field()

FieldState & morph::forms::FormSession::field ( std::string_view path ) const

inlinenodiscard

A field by path: name, parent.member, or rows[i].member (a row by position).

Parameters

path The path.

Returns: The field.

Exceptions

std::out_of_range when no field has that path.

Definition at line 866 of file form_session.hpp.

◆ ready()

bool morph::forms::FormSession::ready ( ) const

inlinenodiscard

Whether the form can submit. Tracked.

Returns: true when every required field encodes, no field has an error, no gating rule is False, and options().accepts (when set) accepts the body.

Definition at line 916 of file form_session.hpp.

◆ body()

std::optional< std::string > morph::forms::FormSession::body ( ) const

inlinenodiscard

The body the form would submit. Tracked.

Returns: The JSON body, fields in x-order, while ready; std::nullopt otherwise.

Definition at line 920 of file form_session.hpp.

◆ submit()

void morph::forms::FormSession::submit ( )

inline

Submits the current body; does nothing while not ready, or while a submission is in flight (the submission is Exclusive). The explicit-mode trigger; in automatic mode it forces a resubmission of an unchanged body.

Definition at line 925 of file form_session.hpp.

◆ prefill()

void morph::forms::FormSession::prefill ( std::string_view bodyJson )

inline

Loads a stored payload for editing. Every field is replaced (an absent member starts blank), every unit returns to the canonical one, and nothing is submitted. Text that is not a JSON object changes nothing.

Parameters

bodyJson The payload.

Definition at line 940 of file form_session.hpp.

◆ refill()

void morph::forms::FormSession::refill ( std::string_view bodyJson )

inline

Loads a stored payload like prefill, except that a top-level field the user changed since the form was last loaded keeps what they entered: a later value of the record being edited, such as its first value arriving after the user started typing, or a refetch, does not discard the edit. Nothing is submitted. Text that is not a JSON object changes nothing.

Parameters

bodyJson The payload.

Definition at line 959 of file form_session.hpp.

◆ assign()

void morph::forms::FormSession::assign	(	std::string_view	path,
		std::string_view	jsonValue )

inline

Sets one field from a JSON value, programmatically (nothing is submitted).

Parameters

path	The field's path (see field).
jsonValue	The value as JSON; text that is not JSON changes nothing.

Exceptions

std::out_of_range when no field has that path.

Definition at line 985 of file form_session.hpp.

◆ reset()

void morph::forms::FormSession::reset ( )

inline

Blanks every field, programmatically (nothing is submitted).

Definition at line 1006 of file form_session.hpp.

◆ pending()

bool morph::forms::FormSession::pending ( ) const

inlinenodiscard

Whether a submission is in flight. Tracked.

Returns: true while one is.

Definition at line 1018 of file form_session.hpp.

◆ lastReply()

std::optional< std::string > const & morph::forms::FormSession::lastReply ( ) const

inlinenodiscard

The last successful reply. Tracked.

Returns: The reply JSON, or std::nullopt before the first success.

Definition at line 1022 of file form_session.hpp.

◆ lastError()

std::exception_ptr morph::forms::FormSession::lastError ( ) const

inlinenodiscard

The last failure. Tracked.

Returns: The exception, or null; cleared by the next success.

Definition at line 1026 of file form_session.hpp.

◆ successCount()

std::uint64_t morph::forms::FormSession::successCount ( ) const

inlinenodiscard

How many submissions have succeeded. Tracked; each success ticks it, so an observer sees every submission even when two replies are equal.

Returns: The count.

Definition at line 1031 of file form_session.hpp.

◆ submitAttempts()

std::uint64_t morph::forms::FormSession::submitAttempts ( ) const

inlinenodiscard

How many submissions have been sent, automatic and explicit. Tracked; a submission the Exclusive mutation refused while another was in flight does not count.

Returns: The count.

Definition at line 1036 of file form_session.hpp.

◆ groupCollapsed()

reactive::Signal< bool > & morph::forms::FormSession::groupCollapsed ( std::size_t group ) const

inlinenodiscard

An accordion group's collapsed state.

Parameters

group Index into model().groups().

Returns: The signal.

Exceptions

std::out_of_range for an index past the groups.

Definition at line 1042 of file form_session.hpp.

◆ tabSelection()

reactive::Signal< std::size_t > & morph::forms::FormSession::tabSelection ( std::size_t group ) const

inlinenodiscard

A tab run's selected tab, keyed by the run's first group index.

Parameters

group Index into model().groups() of the run's first tab group.

Returns: The signal holding the selected tab's position in the run.

Exceptions

std::out_of_range for an index past the groups.

Definition at line 1048 of file form_session.hpp.

◆ groupTitle()

std::string morph::forms::FormSession::groupTitle ( std::size_t group ) const

inlinenodiscard

A group's title, resolved through the translations (key <action>.group.<index>).

Parameters

group Index into model().groups().

Returns: The title; empty for the implicit trailing group.

Exceptions

std::out_of_range for an index past the groups.

Definition at line 1054 of file form_session.hpp.

The documentation for this class was generated from the following file:

morph/forms/engine/form_session.hpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ FormSession()

Member Function Documentation

◆ model()

◆ runtime()

◆ submitMode()

◆ options()

◆ fields()

◆ rowIndexOf()

◆ field()

◆ ready()

◆ body()

◆ submit()

◆ prefill()

◆ refill()

◆ assign()

◆ reset()

◆ pending()

◆ lastReply()

◆ lastError()

◆ successCount()

◆ submitAttempts()

◆ groupCollapsed()

◆ tabSelection()

◆ groupTitle()