A basic model class for forms. More...

#include <Wt/WFormModel.h>

Inheritance diagram for Wt::WFormModel:

Public Types
typedef const char *	Field
	A type to identify a field. More...

Public Types inherited from Wt::WObject
typedef void(WObject::*	Method) ()
	Typedef for a WObject method without arguments.

Public Member Functions
	WFormModel ()
	Constructor. More...

void	addField (Field field, const WString &info=WString::Empty)
	Adds a field. More...

void	removeField (Field field)
	Removes a field. More...

std::vector< Field >	fields () const
	Returns the fields. More...

virtual void	reset ()
	Resets the model. More...

virtual bool	validate ()
	Validates the current input. More...

bool	valid () const
	Returns the current overall validation state. More...

void	setVisible (Field field, bool visible)
	Sets whether a field is visible. More...

virtual bool	isVisible (Field field) const
	Returns whether a field is visible. More...

void	setReadOnly (Field field, bool readOnly)
	Sets whether a field is read-only. More...

virtual bool	isReadOnly (Field field) const
	Returns whether a field is read only. More...

virtual WString	label (Field field) const
	Returns a field label. More...

virtual void	setValue (Field field, const cpp17::any &value)
	Sets the field value. More...

virtual const cpp17::any &	value (Field field) const
	Returns the field value. More...

virtual WString	valueText (Field field) const
	Returns the field value text. More...

virtual void	setValidator (Field field, const std::shared_ptr< WValidator > &validator)
	Sets a validator.

virtual std::shared_ptr< WValidator >	validator (Field field) const
	Returns a validator. More...

virtual bool	validateField (Field field)
	Validates a field. More...

virtual void	setValidated (Field field, bool validated)
	Sets whether a field has been validated. More...

virtual bool	isValidated (Field field) const
	Returns whether the field has been validated yet. More...

const WValidator::Result &	validation (Field field) const
	Returns the result of a validation. More...

virtual void	setValidation (Field field, const WValidator::Result &result)
	Sets the validation result for a field. More...

Public Member Functions inherited from Wt::WObject
void	addChild (std::unique_ptr< WObject > child)
	Add a child WObject whose lifetime is determined by this WObject.

template<typename Child >
Child *	addChild (std::unique_ptr< Child > child)
	Add a child WObject, returning a raw pointer. More...

std::unique_ptr< WObject >	removeChild (WObject *child)
	Remove a child WObject, so its lifetime is no longer determined by this WObject.

template<typename Child >
std::unique_ptr< Child >	removeChild (Child *child)
	Remove a child WObject, so its lifetime is no longer determined by this WObject. More...

virtual const std::string	id () const
	Returns the (unique) identifier for this object. More...

virtual void	setObjectName (const std::string &name)
	Sets an object name. More...

virtual std::string	objectName () const
	Returns the object name. More...

void	resetLearnedSlots ()
	Resets learned stateless slot implementations. More...

template<class T >
void	resetLearnedSlot (void(T::*method)())
	Resets a learned stateless slot implementation. More...

template<class T >
WStatelessSlot *	implementStateless (void(T::*method)())
	Declares a slot to be stateless and learn client-side behaviour on first invocation. More...

template<class T >
WStatelessSlot *	implementStateless (void(T::method)(), void(T::undoMethod)())
	Declares a slot to be stateless and learn client-side behaviour in advance. More...

void	isNotStateless ()
	Marks the current function as not stateless. More...

template<class T >
WStatelessSlot *	implementJavaScript (void(T::*method)(), const std::string &jsCode)
	Provides a JavaScript implementation for a method. More...

Public Member Functions inherited from Wt::Core::observable
	observable () noexcept
	Default constructor.

virtual	~observable ()
	Destructor. More...

template<typename... Args, typename C >
auto	bindSafe (void(C::*method)(Args...)) noexcept
	Protects a method call against object destruction. More...

template<typename... Args, typename C >
auto	bindSafe (void(C::*method)(Args...) const) const noexcept
	Protects a const method call against object destruction. More...

template<typename Function >
auto	bindSafe (const Function &function) noexcept
	Protects a function against object destruction. More...

Additional Inherited Members
Protected Member Functions inherited from Wt::WObject
virtual WStatelessSlot *	getStateless (Method method)
	On-demand stateless slot implementation. More...

Detailed Description

A basic model class for forms.

This implements field data and validation handling for (simple) form-based views. It provides a standard way for views to perform field validation, and react to validation results.

All fields are uniquely identified using a string literal (which is the Field type). For each field, its value, the visibility, whether the field is read-only, and its current validation status is managed by the model. In addition, you will typically specialize the class to customize the validation and application logic.

Warning: The Field type is 'const char *, and instead of string comparisons to identify fields, pointer comparisons are used. Thus you really should use the same field constant throughout your code to refer to a given field, and you cannot use constexpr for the field constant since that does not have a unique value (since it has no storage).

Although it can be setup to use WValidator objects for individual fields, also other validation where more entered information needs to be considered simultaneously can be implemented.

A model is typically used by a View which renders the fields configured in the model, updates the model values, invokes and reflects the validation status.

Example (a bit contrived since you will usually not use the model directly):

Wt::WFormModel::Field NameField = "name";
Wt::WFormModel::Field TelField = "telephone";
 
auto model = std::make_shared<Wt::WFormModel>();
model->addField(NameField, "Enter your name");
model->addField(TelField, "Phone number");
 
model->setValue(NameField, Wt::WString::fromUTF8("John Doe"));
 
if (model->validate()) {
  ...
} else {
  const Wt::WValidator::Result& rname = model->validation(NameField);
  if (rname.state() != Wt::ValidationState::Valid) {
    std::cerr <<< "Invalid name: " << rname.message();
  }
  ...
}

Member Typedef Documentation

◆ Field

typedef const char* Wt::WFormModel::Field

A type to identify a field.

Fields are identified by a string literal constant.

Constructor & Destructor Documentation

◆ WFormModel()

Wt::WFormModel::WFormModel ( )

Constructor.

Creates a new form model.

Member Function Documentation

◆ addField()

void Wt::WFormModel::addField	(	Field	field,
		const WString &	info = `WString::Empty`
	)

Adds a field.

The field is added to the model, with an optional short informational message that can be used by views to provide a hint on the value that needs to be entered. The message is set as the validation message as long as the field has not yet been validated.

If the field was already in the model, its data is reset.

Note that Field is a const char *. In versions of Wt before 4.5.0, a field would be identified by a string literal and pointer comparison would be used. In Wt 4.5.0 this has changed to string comparison. However, you should still make sure the field argument to this function should either be a string literal like before, or otherwise outlive the WFormModel. Ideally, Field would simply become a std::string in the future.

◆ fields()

std::vector< WFormModel::Field > Wt::WFormModel::fields ( ) const

Returns the fields.

This returns the fields currently configured in the model (added with addField() or for which a value or property has been set).

◆ isReadOnly()

bool Wt::WFormModel::isReadOnly ( Field field ) const

virtual

Returns whether a field is read only.

The default implementation returns the value set by setReadOnly()

Reimplemented in Wt::Auth::RegistrationModel.

◆ isValidated()

bool Wt::WFormModel::isValidated ( Field field ) const

virtual

Returns whether the field has been validated yet.

This is initially false, and set to true by setValidation().

See also: setValidated()

◆ isVisible()

bool Wt::WFormModel::isVisible ( Field field ) const

virtual

Returns whether a field is visible.

In some cases not all fields of the model need to be shown. This may depend on values input for certain fields, and thus change dynamically. You may specialize this method to indicate that a certain field should be invisible.

The default implementation returns the value set by setVisible().

Reimplemented in Wt::Auth::RegistrationModel, and Wt::Auth::AuthModel.

◆ label()

WString Wt::WFormModel::label ( Field field ) const

virtual

Returns a field label.

The default implementation returns the WString::tr(field)

Reimplemented in Wt::Auth::FormBaseModel.

◆ removeField()

void Wt::WFormModel::removeField ( Field field )

Removes a field.

The field is removed from the model.

◆ reset()

void Wt::WFormModel::reset ( )

virtual

Resets the model.

The default implementation clears the value of all fields, and resets the validation state to not validated.

Reimplemented in Wt::Auth::RegistrationModel, and Wt::Auth::AuthModel.

◆ setReadOnly()

void Wt::WFormModel::setReadOnly	(	Field	field,
		bool	readOnly
	)

Sets whether a field is read-only.

Fields are read-write by default.

See also: isReadOnly()

◆ setValidated()

void Wt::WFormModel::setValidated	(	Field	field,
		bool	validated
	)

virtual

Sets whether a field has been validated.

This is usually not used directly, but invoked by setValidation()

A field is initially (or after reset()), not validated.

◆ setValidation()

void Wt::WFormModel::setValidation	(	Field	field,
		const WValidator::Result &	result
	)

virtual

Sets the validation result for a field.

This will also set the field as validated.

See also: validation(), isValidated()

◆ setValue()

void Wt::WFormModel::setValue	(	Field	field,
		const cpp17::any &	value
	)

virtual

Sets the field value.

See also: value(), valueText()

◆ setVisible()

void Wt::WFormModel::setVisible	(	Field	field,
		bool	visible
	)

Sets whether a field is visible.

Fields are visible by default. An invisible field will be ignored during validation (i.e. will be considered as valid).

See also: isVisible()

◆ valid()

bool Wt::WFormModel::valid ( ) const

Returns the current overall validation state.

This checks the validation() of all fields, and returns true if all all fields have been validated and are valid.

See also: validate()

◆ validate()

bool Wt::WFormModel::validate ( )

virtual

Validates the current input.

The default implementation calls validateField() for each field and returns true if all fields validated.

See also: validateField()

Reimplemented in Wt::Auth::AuthModel.

◆ validateField()

bool Wt::WFormModel::validateField ( Field field )

virtual

Validates a field.

The default implementation uses the validator configured for the field to validate the field contents, or if no validator has been configured assumes that the field is valid.

You will typically customize this method for more complex validation cases.

See also: validate(), validationResult()

Reimplemented in Wt::Form::Dbo::FormModel< C >, Wt::Auth::RegistrationModel, and Wt::Auth::AuthModel.

◆ validation()

const WValidator::Result & Wt::WFormModel::validation ( Field field ) const

Returns the result of a validation.

See also: validateField()

◆ validator()

std::shared_ptr< WValidator > Wt::WFormModel::validator ( Field field ) const

virtual

Returns a validator.

Returns the validator for the field.

◆ value()

const cpp17::any & Wt::WFormModel::value ( Field field ) const

virtual

Returns the field value.

See also: valueText(), setValue()

◆ valueText()

WString Wt::WFormModel::valueText ( Field field ) const

virtual

Returns the field value text.

This uses Wt::asString() to interpret the current value as text.

See also: value()

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ Field

Constructor & Destructor Documentation

◆ WFormModel()

Member Function Documentation

◆ addField()

◆ fields()

◆ isReadOnly()

◆ isValidated()

◆ isVisible()

◆ label()

◆ removeField()

◆ reset()

◆ setReadOnly()

◆ setValidated()

◆ setValidation()

◆ setValue()

◆ setVisible()

◆ valid()

◆ validate()

◆ validateField()

◆ validation()

◆ validator()

◆ value()

◆ valueText()