Cutelyst  1.5.0
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
Cutelyst::ValidatorRule Class Referenceabstract

Base class for all validators. More...

#include <validatorrule.h>

Inheritance diagram for Cutelyst::ValidatorRule:
Inheritance graph
[legend]

Public Member Functions

 ValidatorRule (const QString &field, const QString &label=QString(), const QString &customError=QString())
 Constructs a new ValidatorRule with given parameters and parent. More...
 
 ~ValidatorRule ()
 Deconstructs the ValidatorRule.
 
QString field () const
 Returns the name of the field to validate. More...
 
QString label () const
 Returns the human readable field label used for generic error messages. More...
 
ParamsMultiMap parameters () const
 Returns the parameters to validate. More...
 
void setCustomError (const QString &customError)
 Sets a cutom error returned with errorMessage() More...
 
void setCustomParsingError (const QString &custom)
 Sets a custom error message that is shown if parsing of input data fails. More...
 
void setCustomValidationDataError (const QString &custom)
 Sets a custom error message if validation data is invalid or missing. More...
 
void setField (const QString &field)
 Sets the name of the field to validate. More...
 
void setLabel (const QString &label)
 Sets human readable field label for generic error messages. More...
 
void setParameters (const ParamsMultiMap &params)
 Sets the request parameters to validate. More...
 
void setTrimBefore (bool trimBefore)
 Set to false to not trim input value before validation. More...
 
bool trimBefore () const
 Returns true if field value should be trimmed before validation. More...
 
virtual QString validate () const =0
 Returns an empty string on success, otherwise a string containing the error message. More...
 
QString value () const
 Returns the field value.
 

Protected Member Functions

 ValidatorRule (ValidatorRulePrivate &dd)
 
virtual QString genericParsingError () const
 Returns a generic error message if an error occures while parsing input. More...
 
virtual QString genericValidationDataError () const
 Returns a generic error message if any validation data is missing or invalid. More...
 
virtual QString genericValidationError () const
 Returns a generic error mesage if validation failed. More...
 
QString parsingError () const
 Returns an error message if an error occured while parsing input. More...
 
QString validationDataError () const
 Returns an error message if any validation data is missing or invalid. More...
 
QString validationError () const
 Returns a descriptive error message if validation failed. More...
 

Protected Attributes

const QScopedPointer< ValidatorRulePrivate > d_ptr
 

Detailed Description

This class can not be used on it's own, you have to create a derived class from it that implements your validator logic. Or use one of the already existing derived classes.

Writing a custom validator

If you want to implement your own validator logic to use with Valiadtor, you have to create a class that derives from ValidatorRule. The simplest implementation only needs a constructor an a reimplementation of the validate() funciton. But for more comfort and usability, you should also reimplement validationError(). If your validator parses the input into a specific type to validate it and/or if you are using additional parameters, you may also want to reimplement parsingError() and validationDataError() to return more appropriate generic error messages.

The most important parameter for every validator is the name of the field to validate. So your own validator should require that field in the constructor. For better error messages you should also add an optional paramter to set a label and maybe a customError message if validation fails.

In the validation logic you have to return an empty QString if validation succeeded. Everything else will be treeted as an error message and that the validation has been failed.

So lets implement a custom validator that can check for a specific value to be set. (Maybe not a realistic example, but it should be enough for demonstration.)

#include <Cutelyst/Plugins/Utils/ValidatorRule>
class MyValidator : public Cutelyst::ValidatorRule
{
public:
// field: name of the input field
// compareValue: our custom value we want compare
// label: an optional human readable label for generic error messages
// customError: a custom error message that is shown if validation fails instead of genericValidationError()
MyValidator::MyValidator(const QString &field, const QString &compareValue, const QString &label = QString(), const QString &customError = QString())
~MyValidator();
// this will contain the validation logic
// and should return an empty QString on success
QString validate() const override;
protected:
// we want to have a generic error message
QString validationError() const override;
private:
// storing our comparison value
QString m_compareValue;
}
MyValidator::MyValidator(const QString &field, const QString &compareValue, const QString &label, const QString &customError) :
Cutelyst::ValidatorRule(field, label, customError), m_compareValue(compareValue)
{
}
MyValidator::~MyValidator()
{
}
// when reimplementing the validate function, keep in mind, that
// an empty returned string is seen as successful validation, everything
// else will be seen as an error
QString MyValidator::validate() const
{
QString result;
// lets get the field value
const QString v = value();
// if our comparision value is empty, the validation should fail and we want
// to return an error message according to this situation
if (m_compareValue.isEmpty()) {
result = validationDataError();
} else {
// if the value is empty or the field is missing, the validation should succeed,
// because we already have the required validators for that purpose
// than we will compare our values and if they are not the same, we
// will return an error string
if (!v.isEmpty() && (m_compareValue != v)) {
result = validationError();
}
}
// now let's return our result, if it is empty, validation was successfull
return result;
}
QString MyValidator::genericValidationError() const
{
QString error;
// if no label is set, we will return a shorter error message
if (label().isEmpty()) {
error = tr("Must contain this value: %1).arg(m_compareValue);
} else {
error = tr("The %1 field must contain the following value: %2").arg(label(), m_compareValue);
}
return error;
}

That's it. Now you can use your own validator in the main Validator.

Definition at line 138 of file validatorrule.h.

Constructor & Destructor Documentation

Cutelyst::ValidatorRule::ValidatorRule ( const QString &  field,
const QString &  label = QString(),
const QString &  customError = QString() 
)
Parameters
fieldName of the field to validate.
labelHuman readable input field label, used for generic error messages.
customErrorHuman readable custom error message if validation fails.

Member Function Documentation

QString Cutelyst::ValidatorRule::field ( ) const
See also
setField()
virtual QString Cutelyst::ValidatorRule::genericParsingError ( ) const
protectedvirtual

If you want to have a more specific generic parsing error message for your validator, reimplement this in a subclass.

virtual QString Cutelyst::ValidatorRule::genericValidationDataError ( ) const
protectedvirtual

If you want to have a more specific generic validation data error message for your validator, reimplement this in a subclass.

virtual QString Cutelyst::ValidatorRule::genericValidationError ( ) const
protectedvirtual
QString Cutelyst::ValidatorRule::label ( ) const
See also
setLabel()
ParamsMultiMap Cutelyst::ValidatorRule::parameters ( ) const
See also
setParameters()
QString Cutelyst::ValidatorRule::parsingError ( ) const
protected

This will either return the custom parsing error message set via setCustomParsingError() or the message returned by genericParsingError(). When writing a new ValidatorRule, use this in your reimplementation of validate() if parsing of input data fails.

void Cutelyst::ValidatorRule::setCustomError ( const QString &  customError)
void Cutelyst::ValidatorRule::setCustomParsingError ( const QString &  custom)
See also
parsingError()
void Cutelyst::ValidatorRule::setCustomValidationDataError ( const QString &  custom)
void Cutelyst::ValidatorRule::setField ( const QString &  field)
See also
field()
void Cutelyst::ValidatorRule::setLabel ( const QString &  label)
See also
label()
void Cutelyst::ValidatorRule::setParameters ( const ParamsMultiMap params)
See also
parameters()
void Cutelyst::ValidatorRule::setTrimBefore ( bool  trimBefore)

By default, this value is set to true and all input values will be trimmed before validation to remove whitespaces from the beginning and the end.

See also
trimBefore()
bool Cutelyst::ValidatorRule::trimBefore ( ) const

By default, this will return true and all input values will be trimmed before validation to remove whitespaces from the beginning and the end.

See also
setTrimBefore()
virtual QString Cutelyst::ValidatorRule::validate ( ) const
pure virtual

This is the main function to reimplement when writing a custom validator. When reimplementing this function in a class derived from ValidatorRule, you have to return an empty string if validation succeeded and the corresponding error if it fails. There are currently three error functions that should be used for different error cases:

  • validationError() - if validation itself fails
  • validationDataError() - if there is a problem with missing or invalid validation data, like comparison values
  • parsingError() - if the parsing of an input data fails in a valiator that not originally checks the parsing, but the parsing result
Example
QString MyValidator::validate() const
{
QString result;
if (m_myComparisonValue.isEmpty()) {
result = validationDataError();
} else {
if (m_myComparisonValue != value()) {
result = validationError();
}
}
return result;
}

Implemented in Cutelyst::ValidatorIp, Cutelyst::ValidatorBetween, Cutelyst::ValidatorSize, Cutelyst::ValidatorUrl, Cutelyst::ValidatorMax, Cutelyst::ValidatorMin, Cutelyst::ValidatorAfter, Cutelyst::ValidatorBefore, Cutelyst::ValidatorAlpha, Cutelyst::ValidatorAlphaDash, Cutelyst::ValidatorAlphaNum, Cutelyst::ValidatorDate, Cutelyst::ValidatorDigitsBetween, Cutelyst::ValidatorDateTime, Cutelyst::ValidatorDigits, Cutelyst::ValidatorEmail, Cutelyst::ValidatorRequiredIf, Cutelyst::ValidatorRequiredWith, Cutelyst::ValidatorTime, Cutelyst::ValidatorDifferent, Cutelyst::ValidatorNotIn, Cutelyst::ValidatorRequiredUnless, Cutelyst::ValidatorRequiredWithAll, Cutelyst::ValidatorRequiredWithout, Cutelyst::ValidatorRequiredWithoutAll, Cutelyst::ValidatorConfirmed, Cutelyst::ValidatorIn, Cutelyst::ValidatorNumeric, Cutelyst::ValidatorInteger, Cutelyst::ValidatorRegularExpression, Cutelyst::ValidatorSame, Cutelyst::ValidatorBoolean, Cutelyst::ValidatorFilled, Cutelyst::ValidatorRequired, Cutelyst::ValidatorAccepted, Cutelyst::ValidatorJson, and Cutelyst::ValidatorPresent.

QString Cutelyst::ValidatorRule::validationDataError ( ) const
protected

Reimplement this in your sublcass to return an error message in case the validation data is missing or invalid. The default implementation returns a generic message unless a custom one is set via setCustomValidationDataError().

When reimplementing this function take into account that there might be a custom validation data error message set by the user.

QString Cutelyst::ValidatorRule::validationError ( ) const
protected

This will either return the custom error message set via setCustomError() or the message returned by genericValidationError(). When writing a new ValidatorRule, use this in your reimplementaion of validate() if validation failed.