Update custom validator section #1028

Author: knstvk

content/modules/flow-ui/examples/onboarding/src/main/java/com/company/onboarding/validators/PostcodeValidator.java

@@ -0,0 +1,27 @@
+package com.company.onboarding.validators;
+
+import io.jmix.flowui.component.validation.AbstractValidator;
+import io.jmix.flowui.exception.ValidationException;
+import org.springframework.beans.factory.config.BeanDefinition;
+import org.springframework.context.annotation.Scope;
+import org.springframework.stereotype.Component;
+
+import java.util.Map;
+
+// tag::validator[]
+@Component
+@Scope(BeanDefinition.SCOPE_PROTOTYPE)
+public class PostcodeValidator extends AbstractValidator<String> {
+
+    private static final String POSTCODE_REGEX =
+            "^[A-Z]{1,2}[0-9][0-9A-Z]?\\s?[0-9][A-Z]{2}$";
+
+    @Override
+    public void accept(String value) throws ValidationException {
+        if (value != null && !value.matches(POSTCODE_REGEX)) {
+            String errorMessage = getTemplateErrorMessage(message, Map.of("value", value));
+            throw new ValidationException(errorMessage);
+        }
+    }
+}
+// end::validator[]

content/modules/flow-ui/examples/onboarding/src/main/java/com/company/onboarding/validators/ZipValidator.java

@@ -2,18 +2,15 @@
 
 import io.jmix.flowui.component.validation.Validator;
 import io.jmix.flowui.exception.ValidationException;
-import org.springframework.beans.factory.config.BeanDefinition;
-import org.springframework.context.annotation.Scope;
 import org.springframework.stereotype.Component;
 
 // tag::ZipValidator[]
 @Component
-@Scope(BeanDefinition.SCOPE_PROTOTYPE)
 public class ZipValidator implements Validator<String> {
     @Override
     public void accept(String value) throws ValidationException {
-        if (value != null && value.length() != 6)
-            throw new ValidationException("Zip must be of 6 characters length");
+        if (value != null && value.length() != 5)
+            throw new ValidationException("Zip code must consist of 5 characters");
     }
 }
 // end::ZipValidator[]

content/modules/flow-ui/examples/onboarding/src/main/java/com/company/onboarding/view/component/validator/ValidatorView.java

@@ -106,8 +106,8 @@ public void onInit(final InitEvent event) {
     private void addCustomValidator(){
         // tag::addCustomValidator[]
         zipField.addValidator(value -> {
-            if (value != null && value.length() != 6)
-                throw new ValidationException("Zip must be of 6 characters length");
+            if (value != null && value.length() != 5)
+                throw new ValidationException("Zip code must consist of 5 characters");
         });
         // end::addCustomValidator[]
     }

content/modules/flow-ui/examples/onboarding/src/main/resources/com/company/onboarding/view/component/validator/validator-view.xml

@@ -21,6 +21,17 @@
                 </textField>
                 <!-- end::zipField[] -->
             </vbox>
+            <vbox>
+                <label text="Custom 2:"/>
+                <!-- tag::postcodeField[] -->
+                <textField id="postcodeField" datatype="string">
+                    <validators>
+                        <custom bean="postcodeValidator"
+                                message="${value} is not a valid UK postcode"/>
+                    </validators>
+                </textField>
+                <!-- end::postcodeField[] -->
+            </vbox>
             <vbox>
                 <label text="DecimalMax:"/>
                 <!-- tag::decimalMax[] -->

content/modules/flow-ui/pages/vc/miscellaneous/validator.adoc

@@ -623,22 +623,32 @@ include::example$/onboarding/src/main/java/com/company/onboarding/view/component
 [[custom-validator]]
 == Creating Custom Validators
 
-A custom validator can be defined by a prototype bean implementing the `Validator` interface.
-
-Example of creating a validator for zip codes:
+A custom validator can be defined by a Spring bean implementing the `Validator` interface. For example:
 
 [source,java,indent=0]
 ----
 include::example$/onboarding/src/main/java/com/company/onboarding/validators/ZipValidator.java[tags=ZipValidator]
 ----
 
-In a view XML descriptor, the custom validator should be defined in the nested `custom` element. For example:
+In a view XML descriptor, the custom validator should be defined in the nested `custom` element. The `bean` attribute should specify the validator bean name. For example:
 
 [source,xml,indent=0]
 ----
 include::example$/onboarding/src/main/resources/com/company/onboarding/view/component/validator/validator-view.xml[tags=zipField]
 ----
 
+You can extend a validator from the `AbstractValidator` base class. Then you can provide a message in XML and use the `getTemplateErrorMessage()` method to create an error message. In this case the bean will have a state (the message from XML), so it must be a prototype. For example:
+
+[source,java,indent=0]
+----
+include::example$/onboarding/src/main/java/com/company/onboarding/validators/PostcodeValidator.java[tags=validator]
+----
+
+[source,xml,indent=0]
+----
+include::example$/onboarding/src/main/resources/com/company/onboarding/view/component/validator/validator-view.xml[tags=postcodeField]
+----
+
 A validator can also be defined by a lambda and added programmatically, for example:
 
 [source,java,indent=0]