Wt
3.2.2
|
A basic model class for forms. More...
#include <Wt/WFormModel>
Public Types | |
typedef const char * | Field |
A type to identify a field. | |
Public Member Functions | |
WFormModel (WObject *parent=0) | |
Constructor. | |
void | addField (Field field, const WString &info=WString::Empty) |
Adds a field. | |
void | removeField (Field field) |
Removes a field. | |
std::vector< Field > | fields () const |
Returns the fields. | |
virtual void | reset () |
Resets the model. | |
virtual bool | validate () |
Validates the current input. | |
bool | valid () const |
Returns the current overall validation state. | |
void | setVisible (Field field, bool readOnly) |
Sets whether a field is visible. | |
virtual bool | isVisible (Field field) const |
Returns whether a field is visible. | |
void | setReadOnly (Field field, bool readOnly) |
Sets whether a field is read-only. | |
virtual bool | isReadOnly (Field field) const |
Returns whether a field is read only. | |
virtual WString | label (Field field) const |
Returns a field label. | |
virtual void | setValue (Field field, const boost::any &value) |
Sets the field value. | |
virtual const boost::any & | value (Field field) const |
Returns the field value. | |
virtual WString | valueText (Field field) const |
Returns the field value text. | |
virtual void | setValidator (Field field, WValidator *validator) |
Sets a validator. | |
virtual bool | validateField (Field field) |
Validates a field. | |
virtual void | setValidated (Field field, bool validated) |
Sets whether a field has been validated. | |
virtual bool | isValidated (Field field) const |
Returns whether the field has been validated yet. | |
const WValidator::Result & | validation (Field field) const |
Returns the result of a validation. | |
virtual void | setValidation (Field field, const WValidator::Result &result) |
Sets the validation result for a field. |
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.
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):
const char *NameField = "name"; const char *TelField = "telephone"; Wt::WFormModel *model = new 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::WValidator::Valid) { std::cerr <<< "Invalid name: " << rname.message(); } ... }
typedef const char* Wt::WFormModel::Field |
A type to identify a field.
Fields are identified by a string literal constant.
Wt::WFormModel::WFormModel | ( | WObject * | parent = 0 | ) |
Constructor.
Creates a new form model.
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 lo ng as the field has not yet been validated.
If the field
was already in the model, its data is reset.
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).
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.
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().
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.
Returns a field label.
The default implementation returns the WString::tr(field)
Reimplemented in Wt::Auth::FormBaseModel.
void Wt::WFormModel::removeField | ( | Field | field | ) |
Removes a field.
The field
is removed from the model.
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.
void Wt::WFormModel::setReadOnly | ( | Field | field, |
bool | readOnly | ||
) |
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.
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.
void Wt::WFormModel::setValidator | ( | Field | field, |
WValidator * | validator | ||
) | [virtual] |
Sets a validator.
If the validator has no ownership yet, the form model will take ownership.
void Wt::WFormModel::setValue | ( | Field | field, |
const boost::any & | value | ||
) | [virtual] |
Sets the field value.
void Wt::WFormModel::setVisible | ( | Field | field, |
bool | readOnly | ||
) |
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.
bool Wt::WFormModel::validate | ( | ) | [virtual] |
Validates the current input.
The default implementation calls validateField() for each field and returns true
if all fields validated.
Reimplemented in Wt::Auth::AuthModel.
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.
Reimplemented in Wt::Auth::RegistrationModel, and Wt::Auth::AuthModel.
const WValidator::Result & Wt::WFormModel::validation | ( | Field | field | ) | const |
Returns the result of a validation.
const boost::any & Wt::WFormModel::value | ( | Field | field | ) | const [virtual] |
Returns the field value.
Returns the field value text.
This uses Wt::asString() to interpret the current value as text.