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={}, const QString &defValKey={}, QByteArrayView validatorName=nullptr)

virtual	~ValidatorRule ()
	Deconstructs the ValidatorRule.

Protected Member Functions
	ValidatorRule (ValidatorRulePrivate &dd)

QString	debugString (Context *c) const

void	defaultValue (Context c, ValidatorReturnType result) const

QString	field () const noexcept

virtual QString	genericParsingError (Context *c, const QVariant &errorData={}) const

virtual QString	genericValidationDataError (Context *c, const QVariant &errorData={}) const

virtual QString	genericValidationError (Context *c, const QVariant &errorData={}) const

QString	label (Context *c) const

QString	parsingError (Context *c, const QVariant &errorData={}) const

bool	trimBefore () const noexcept

virtual ValidatorReturnType	validate (Context *c, const ParamsMultiMap &params) const =0

QString	validationDataError (Context *c, const QVariant &errorData={}) const

QString	validationError (Context *c, const QVariant &errorData={}) const

QString	value (const ParamsMultiMap &params) const

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 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>
 
using 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 an optional default value if input field
    //            is empty
    MyValidator::MyValidator(const QString &field,
                             const QString &compareValue,
                             const ValidatorMessages &messages = {},
                             const QString &defValKey = {});
 
    ~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;
};
 
 
MyValidator::MyValidator(const QString &field,
                         const QString &compareValue,
                         const ValidatorMessages &messages,
                         const QString &defValKey)
     : ValidatorRule(field, messages, defValKey, "MyValidator"),
       m_compareValue(compareValue)
{
}
 
MyValidator::~MyValidator() = default;
 
// 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 comparison 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 303 of file validatorrule.h.

Constructor & Destructor Documentation

◆ ValidatorRule() [1/2]

ValidatorRule::ValidatorRule	(	const QString &	field,
		const ValidatorMessages &	messages = `{}`,
		const QString &	defValKey = `{}`,
		QByteArrayView	validatorName = `nullptr`
	)

Constructs a new ValidatorRule object with the given parameters.

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.
vaidatorName	Name of the validator used for debug output.

Definition at line 13 of file validatorrule.cpp.

◆ ValidatorRule() [2/2]

ValidatorRule::ValidatorRule ( ValidatorRulePrivate & dd )

protected

Constructs a new ValidatorRule object with the given private class.

Definition at line 21 of file validatorrule.cpp.

Member Function Documentation

◆ debugString()

QString ValidatorRule::debugString ( Context * c ) const

protected

Returns a string that can be used for debug output if validation fails.

This returns something like MyValidator: Validation failed for field "my_field" at MyController::myAction:

Definition at line 157 of file validatorrule.cpp.

References Cutelyst::Context::actionName, Cutelyst::Context::controllerName, field(), and QString::fromLatin1().

◆ defaultValue()

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

protected

If a defValKey has been set in the constructor, this will try to get the default value from the stash of context c and put it into the result.

Definition at line 144 of file validatorrule.cpp.

References Cutelyst::Context::actionName, Cutelyst::Context::controllerName, field(), QVariant::setValue(), Cutelyst::Context::stash(), and Cutelyst::ValidatorReturnType::value.

◆ field()

QString ValidatorRule::field ( ) const

protectednoexcept

Returns the name of the field to validate.

Definition at line 28 of file validatorrule.cpp.

Referenced by debugString(), defaultValue(), Cutelyst::ValidatorSize::genericValidationDataError(), Cutelyst::Validator::validate(), Cutelyst::ValidatorConfirmed::validate(), Cutelyst::ValidatorFilled::validate(), Cutelyst::ValidatorPresent::validate(), and Cutelyst::ValidatorRequired::validate().

◆ genericParsingError()

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

protectedvirtual

Returns a generic error message if an error occures while parsing input.

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

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

Definition at line 102 of file validatorrule.cpp.

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

Referenced by parsingError().

◆ genericValidationDataError()

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

protectedvirtual

Returns a generic error message if any validation data is missing or invalid.

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

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

Definition at line 130 of file validatorrule.cpp.

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

Referenced by validationDataError().

◆ genericValidationError()

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

protectedvirtual

Returns a generic error mesage if validation failed.

If you want to have a more specifc generic validation error message for your validator if validation fails, reimplment this in 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
{
    const QString _label = label(c);
    // if no label is set, we will return a shorter error message
    if (_label.isEmpty()) {
         return c->translate("MyValidator", "Must contain this value: %1")
                  .arg(m_compareValue);
    } else {
         return c->translate("MyValidator", "The %1 field must contain the following "
                                            "value: %2")
                  .arg(_label, m_compareValue);
    }
}

Definition at line 75 of file validatorrule.cpp.

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

Referenced by validationError().

◆ label()

QString ValidatorRule::label ( Context * c ) const

protected

Returns the human readable field label used for generic error messages. The label can be set in the ValidatorMessages on the constructor.

Definition at line 49 of file validatorrule.cpp.

References Cutelyst::Context::qtTrId(), and Cutelyst::Context::translate().

◆ parsingError()

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

protected

Returns an error message if an error occurred while parsing input.

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 89 of file validatorrule.cpp.

References genericParsingError(), Cutelyst::Context::qtTrId(), and Cutelyst::Context::translate().

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

◆ trimBefore()

bool ValidatorRule::trimBefore ( ) const

protectednoexcept

Returns true if the field value should be trimmed before validation.

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 165 of file validatorrule.cpp.

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

◆ validate()

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

protectedpure virtual

Starts the validation and returns the result.

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;
}

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

◆ validationDataError()

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

protected

Returns an error message if any validation data is missing or invalid.

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 is 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 116 of file validatorrule.cpp.

References genericValidationDataError(), Cutelyst::Context::qtTrId(), and Cutelyst::Context::translate().

◆ validationError()

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

protected

Returns a descriptive error message if validation failed.

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 61 of file validatorrule.cpp.

References genericValidationError(), Cutelyst::Context::qtTrId(), and Cutelyst::Context::translate().

◆ value()

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

protected

Returns the value of the field from the input params.

Definition at line 34 of file validatorrule.cpp.

References QMultiMap::empty(), and QMultiMap::value().

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ValidatorRule() [1/2]

◆ ValidatorRule() [2/2]

Member Function Documentation

◆ debugString()

◆ defaultValue()

◆ field()

◆ genericParsingError()

Example implementation

◆ genericValidationDataError()

Example implementation

◆ genericValidationError()

Example implementation

◆ label()

◆ parsingError()

◆ trimBefore()

◆ validate()

Example

◆ validationDataError()

◆ validationError()

◆ value()