Base class for all validator rules. More...

#include <Cutelyst/Plugins/Utils/ValidatorRule>

Inheritance diagram for Cutelyst::ValidatorRule:

[legend]

Public Member Functions
	ValidatorRule (const QString &field, const ValidatorMessages &messages=ValidatorMessages(), const QString &defValKey=QString())
	Constructs a new ValidatorRule with the given parameters.
virtual	~ValidatorRule ()
	Deconstructs the ValidatorRule.

Protected Member Functions
	ValidatorRule (ValidatorRulePrivate &dd)
	Constructs a new ValidatorRule object with the given private class.
void	defaultValue (Context c, ValidatorReturnType result, const char *validatorName) const
	I a defValKey has been set in the constructor, this will try to get the default value from the stash and put it into the result.
QString	field () const
	Returns the name of the field to validate.
virtual QString	genericParsingError (Context *c, const QVariant &errorData=QVariant()) const
	Returns a generic error message if an error occures while parsing input.
virtual QString	genericValidationDataError (Context *c, const QVariant &errorData=QVariant()) const
	Returns a generic error message if any validation data is missing or invalid.
virtual QString	genericValidationError (Context *c, const QVariant &errorData=QVariant()) const
	Returns a generic error mesage if validation failed.
QString	label (Context *c) const
	Returns the human readable field label used for generic error messages.
QString	parsingError (Context *c, const QVariant &errorData=QVariant()) const
	Returns an error message if an error occurred while parsing input.
bool	trimBefore () const
	Returns true if the field value should be trimmed before validation.
virtual ValidatorReturnType	validate (Context *c, const ParamsMultiMap &params) const =0
	Starts the validation and returns the result.
QString	validationDataError (Context *c, const QVariant &errorData=QVariant()) const
	Returns an error message if any validation data is missing or invalid.
QString	validationError (Context *c, const QVariant &errorData=QVariant()) const
	Returns a descriptive error message if validation failed.
QString	value (const ParamsMultiMap &params) const
	Returns the value of the field from the input params.

Friends
class	Validator
class	ValidatorPrivate

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 validator rules.

Writing a custom validator

If you want to implement your own validator logic to use with Validator, you have to create a class that derives from ValidatorRule. The simplest implementation only needs a constructor and a reimplementation of the validate() function. But for more comfort and usability, you should also reimplement genericValidationError(). 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 genericParsingError() and genericValidationDataError() to return more appropriate generic error messages.

The most important parameter for every validator rule 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 custom ValidatorMessages if validation fails.

In the validation logic implemented in the validate() function you have to return a ValidatorReturnType struct that contains information about the validation. It has three members, errorMessages is the most important one. If that returns true for QString::isNull(), the validation has succeeded.

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>
 
namespace Cutelyst {
 
class MyValidator : public ValidatorRule
{
public:
    // field: name of the input field
    // compareValue: our custom value we want compare
    // messages: struct containing custom messages
    // defValKey: name of a stash key containing a default value if input field is empty
    MyValidator::MyValidator(const QString &field,
                             const QString &compareValue,
                             const ValidatorMessages &messages = ValidatorMessages(),
                             const QString &defValKey = QString());
 
    ~MyValidator();
 
    // this will contain the validation logic and should return
    // a ValidatorResult with a null errorMessage string on success
    ValidatorReturnType validate(Context *c, const ParamsMultiMap &params) const override;
 
protected:
    // we want to have a generic error message
    QString validationError(Context *c) const override;
 
private:
    // storing our comparison value
    QString m_compareValue;
};
 
}
 
using namespace Cutelyst;
 
MyValidator::MyValidator(const QString &field, const QString &compareValue, const
ValidatorMessages &messages, const QString &defValKey) : Cutelyst::ValidatorRule(field, messages,
defValKey), m_compareValue(compareValue)
{
}
 
MyValidator::~MyValidator()
{
}
 
// when reimplementing the validate function, keep in mind, that a null errorMessage
// string in the ValidatorReturnType is seen as successful validation, everything
// else will be seen as an error
ValidatorReturnType MyValidator::validate(Context *c, const ParamsMultiMap &params) const
{
    ValidatorReturnType result;
 
    // lets get the field value
    const QString v = value(params);
 
    // 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.errorMessage = validationDataError(c);
    } 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.errorMessage = validationError(c);
        } else {
             result.value.setValue(v);
        }
    }
 
    // now let's return our result, if the errorMessage member is null, validation was
successfull return result;
}
 
 
QString MyValidator::genericValidationError(Context *c) const
{
    QString error;
    const QString _label = label(c);
    // if no label is set, we will return a shorter error message
    if (_label.isEmpty()) {
         c->translate("MyValidator", "Must contain this value: %1").arg(m_compareValue);
    } else {
         c->translate("MyValidator", "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 rule in the main Validator.

Definition at line 292 of file validatorrule.h.

Constructor & Destructor Documentation

◆ ValidatorRule() [1/2]

ValidatorRule::ValidatorRule	(	const QString &	field,
		const ValidatorMessages &	messages = ValidatorMessages(),
		const QString &	defValKey = QString() )

Parameters

field	Name of the field to validate.
messages	Custom error messages if validation fails.
defValKey	Stash key containing a default value if input field is empty. This value will NOT be validated.

Definition at line 13 of file validatorrule.cpp.

References field().

◆ ~ValidatorRule()

ValidatorRule::~ValidatorRule ( )

virtual

Definition at line 25 of file validatorrule.cpp.

◆ ValidatorRule() [2/2]

ValidatorRule::ValidatorRule ( ValidatorRulePrivate & dd )

protected

Definition at line 20 of file validatorrule.cpp.

Member Function Documentation

◆ defaultValue()

void ValidatorRule::defaultValue	(	Context *	c,
		ValidatorReturnType *	result,
		const char *	validatorName ) const

protected

Parameters

c	Current Context to get the default value from.
result	The result struct to put the default value in.
validatorName	Name of the validator used for logging.

Definition at line 162 of file validatorrule.cpp.

References ValidatorRule(), field(), QVariant::setValue(), Cutelyst::Context::stash(), QVariant::toString(), and Cutelyst::ValidatorReturnType::value.

◆ field()

QString ValidatorRule::field ( ) const

protected

Returns: The name of the field to validate that has been set in the constructor.

Definition at line 29 of file validatorrule.cpp.

References ValidatorRule().

◆ genericParsingError()

QString ValidatorRule::genericParsingError	(	Cutelyst::Context *	c,
		const QVariant &	errorData = QVariant() ) const

protectedvirtual

If you want to have a more specific generic parsing error message for your validator if parsing of input data failes, reimplement this in your derived class. The default implementation simply returns a maybe translated version of "The input data in the “%1“ field could not be parsed." if there has been a label set or "The input data could not be parsed." if the label is empty.

The pointer to the current Context c can be used to translate error strings. If you have some more data to use for the error messages, put them into errorData.

Example implementation

QString MyValidator::genericParsingError(Context *c) const
{
    QString error;
    const QString _label = label(c);
    // if no label is set, we will return a shorter error message
    if (_label.isEmpty()) {
         c->translate("MyValidator", "Could not be parsed into a valid date.");
    } else {
         c->translate("MyValidator", "The value of the %1 field could not be parsed into a
valid date.").arg(_label);
    }
    return error;
}

Reimplemented in Cutelyst::ValidatorAfter, Cutelyst::ValidatorBefore, Cutelyst::ValidatorBetween, Cutelyst::ValidatorMax, Cutelyst::ValidatorMin, and Cutelyst::ValidatorSize.

Definition at line 115 of file validatorrule.cpp.

References QString::arg(), QString::isEmpty(), label(), and Cutelyst::Context::translate().

Referenced by parsingError(), and validate().

◆ genericValidationDataError()

QString ValidatorRule::genericValidationDataError	(	Context *	c,
		const QVariant &	errorData = QVariant() ) const

protectedvirtual

If you want to have a more specific generic validation data error message for your validator if data needed for the validation is missing or invalid, reimplement this in your derived class. The default implementation simply returns a maybe translated version of "Missing or invalid validation data for the “%1” field." if there has been a label set or "Missing or invalid validation data." if the label is empty.

The pointer to the current Context c can be used to translate error strings. If you have some more data to use for the error messages, put them into errorData.

Example implementation

QString MyValidator::genericValidationDataError(Context *c) const
{
    QString error;
    const QString _label = label(c);
    // if no label is set, we will return a shorter error message
    if (_label.isEmpty()) {
         c->translate("MyValidator", "There is no value to compare against.");
    } else {
         c->translate("MyValidator", "For the “%1” field there is no value to compare
against.").arg(_label);
    }
    return error;
}

Reimplemented in Cutelyst::ValidatorAfter, Cutelyst::ValidatorBefore, Cutelyst::ValidatorBetween, Cutelyst::ValidatorCharNotAllowed, Cutelyst::ValidatorFileSize, Cutelyst::ValidatorIn, Cutelyst::ValidatorMax, Cutelyst::ValidatorMin, Cutelyst::ValidatorNotIn, and Cutelyst::ValidatorSize.

Definition at line 147 of file validatorrule.cpp.

References QString::arg(), QString::isEmpty(), label(), and Cutelyst::Context::translate().

Referenced by validate(), and validationDataError().

◆ genericValidationError()

QString ValidatorRule::genericValidationError	(	Context *	c,
		const QVariant &	errorData = QVariant() ) const

protectedvirtual

If you want to have a more specifc generic validation error message for your validator if validation fails, reimplment this your derived class. The default implementation simply returns a maybe translated version of "The input data in the “%1” field is not acceptable." if there has been a label set or "The input data is not acceptable." if the label is empty.

The pointer to the current Context c can be used to translate error strings. If you have some more data to use for the error messages, put them into errorData.

Example implementation

QString MyValidator::genericValidationError(Context *c) const
{
    QString error;
    const QString _label = label(c);
    // if no label is set, we will return a shorter error message
    if (_label.isEmpty()) {
         c->translate("MyValidator", "Must contain this value: %1").arg(m_compareValue);
    } else {
         c->translate("MyValidator", "The %1 field must contain the following value:
%2").arg(_label, m_compareValue);
    }
    return error;
}

Definition at line 83 of file validatorrule.cpp.

References QString::arg(), QString::isEmpty(), label(), and Cutelyst::Context::translate().

Referenced by validate(), and validationError().

◆ label()

QString ValidatorRule::label ( Context * c ) const

protected

The label can be set in the ValidatorMessages on the constructor.

Returns: Human readable field label used for generic error messages.

Definition at line 52 of file validatorrule.cpp.

References ValidatorRule(), QString::fromUtf8(), and Cutelyst::Context::translate().

◆ parsingError()

QString ValidatorRule::parsingError	(	Cutelyst::Context *	c,
		const QVariant &	errorData = QVariant() ) const

protected

This will either return the customParsingError message provided via the ValidatorMessages in the messages argument of the constructor or the message returned by genericValidationError() if there is no customParsingError message availabe.

When writing a new ValidatorRule, use this in your reimplementation of validate() if parsing of input data fails.

The pointer to the current Context c will be used to translate error strings. If you have some more data to use for the error messages, put them into errorData.

Definition at line 98 of file validatorrule.cpp.

References ValidatorRule(), QString::fromUtf8(), genericParsingError(), and Cutelyst::Context::translate().

Referenced by Cutelyst::ValidatorAfter::validate(), Cutelyst::ValidatorBefore::validate(), Cutelyst::ValidatorBetween::validate(), Cutelyst::ValidatorMax::validate(), Cutelyst::ValidatorMin::validate(), validate(), and Cutelyst::ValidatorSize::validate().

◆ trimBefore()

bool ValidatorRule::trimBefore ( ) const

protected

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

Definition at line 182 of file validatorrule.cpp.

References ValidatorRule().

Referenced by Cutelyst::ValidatorConfirmed::validate(), Cutelyst::ValidatorDifferent::validate(), Cutelyst::ValidatorRequiredIf::validate(), Cutelyst::ValidatorRequiredUnless::validate(), validate(), and Cutelyst::ValidatorSame::validate().

◆ validate()

virtual ValidatorReturnType Cutelyst::ValidatorRule::validate	(	Context *	c,
		const ParamsMultiMap &	params ) const

protectedpure 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 errorMessage 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 validator that not originally checks the parsing, but the parsed result

If validation succeeded, you should put the extracted and validated value into the ValidatorReturnType::value. After the validation you can get the extracted values from ValidatorResult::values().

Example

ValidatorReturnType MyValidator::validate(Context *c, const ParamsMultiMap &params) const
{
    ValidatorReturnType result;
 
    if (!m_myComparisonDate.isValid()) {
        result.errorMessage = validationDataError(c);
    } else {
        const QString v = value(params);
        const QDate inputDate = QDate::fromString(v, Qt::ISODate);
        if (!inputDate.isValie()) {
            result.errorMessage = parsingError(c);
        } else {
            if (inputDate > m_myComparisonDate) {
                result.value.setValue<QDate>(inputDate);
            } else {
                result.errorMessage = validationError(c);
            }
        }
    }
 
    return result;
}

References ValidatorRule(), defaultValue(), field(), genericParsingError(), genericValidationDataError(), genericValidationError(), label(), parsingError(), trimBefore(), validate(), validationDataError(), validationError(), and value().

Referenced by Cutelyst::Validator::validate(), and validate().

◆ validationDataError()

QString ValidatorRule::validationDataError	(	Context *	c,
		const QVariant &	errorData = QVariant() ) const

protected

This will either return the customValidationDataError message provided via the ValidatorMessages in the messages argument of the contstructor or the message returned by genericValidationDataError() if there is no customValidationDataError message available.

When writing a new ValidatorRule, use this in your reimplementation of validate() if validation data like compare values are missing or invalid.

The pointer to the current Context c will be used to translate error strings. If you have some more data to use for the error messages, put them into errorData.

Definition at line 130 of file validatorrule.cpp.

References ValidatorRule(), QString::fromUtf8(), genericValidationDataError(), and Cutelyst::Context::translate().

◆ validationError()

QString ValidatorRule::validationError	(	Cutelyst::Context *	c,
		const QVariant &	errorData = QVariant() ) const

protected

This will either return the customValidationError message provided via the ValidatorMessages in the messages argument of the constructor or the message returned by genericValidationError() if there is no customValidationError message availabe.

When writing a new ValidatorRule, use this in your reimplementaion of validate() if validation failed.

The pointer to the current Context c will be used to translate error strings. If you have some more data to use for the error messages, put them into errorData.

Definition at line 66 of file validatorrule.cpp.

References ValidatorRule(), QString::fromUtf8(), genericValidationError(), and Cutelyst::Context::translate().

◆ value()

QString ValidatorRule::value ( const ParamsMultiMap & params ) const

protected

Definition at line 35 of file validatorrule.cpp.

References ValidatorRule().

◆ Validator

friend class Validator

friend

Definition at line 562 of file validatorrule.h.

◆ ValidatorPrivate

friend class ValidatorPrivate

friend

Definition at line 563 of file validatorrule.h.

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ValidatorRule() [1/2]

◆ ~ValidatorRule()

◆ ValidatorRule() [2/2]

Member Function Documentation

◆ defaultValue()

◆ field()

◆ genericParsingError()

Example implementation

◆ genericValidationDataError()

Example implementation

◆ genericValidationError()

Example implementation

◆ label()

◆ parsingError()

◆ trimBefore()

◆ validate()

Example

◆ validationDataError()

◆ validationError()

◆ value()

Friends And Related Symbol Documentation

◆ Validator

◆ ValidatorPrivate