From 0e4aff84202fd6652bbd1ecfd9d08a7e428196f3 Mon Sep 17 00:00:00 2001
From: Martin Ficzel <ficzel@sitegeist.de>
Date: Fri, 10 Dec 2021 17:18:19 +0100
Subject: [PATCH] DOCS: Add tutorial about custom validators

---
 Documentation/Tutorials/CustomValidators.md | 73 +++++++++++++++++++++
 README.md                                   |  1 +
 2 files changed, 74 insertions(+)
 create mode 100644 Documentation/Tutorials/CustomValidators.md

diff --git a/Documentation/Tutorials/CustomValidators.md b/Documentation/Tutorials/CustomValidators.md
new file mode 100644
index 0000000..34a38b0
--- /dev/null
+++ b/Documentation/Tutorials/CustomValidators.md
@@ -0,0 +1,73 @@
+# Custom Validators
+
+Custom Validators allow to implement specific rules and error messages for the submitted values. 
+Validators implement the `\Neos\Flow\Validation\Validator\ValidatorInterface` which is made comfortable with the 
+`\Neos\Flow\Validation\Validator\AbstractValidator` base class that reduces the effort to implementing a single 
+`isValid()` Method. The behavior of validators can be configured via options. All found errors passed to the 
+`addError()` method and will be combined with results other validators may return.  
+
+ATTENTION: The validator resolver searches validators in the namespace `__PackageNamespace__\Validation\Validator\__ValidatorName__Validator` 
+when addressed via `__PackageKey__:__ValidatorName__`.
+
+Flow validation documentation: https://flowframework.readthedocs.io/en/stable/TheDefinitiveGuide/PartIII/Validation.html
+
+```
+<?php
+declare(strict_types=1);
+
+namespace Vendor\Site\Validation\Validator;
+
+use Neos\Flow\Validation\Validator\AbstractValidator;
+
+class AllowedValuesValidator extends AbstractValidator
+{
+    /**
+     * @var boolean
+     */
+    protected $acceptsEmptyValues = false;
+
+    /**
+     * @var mixed[]
+     */
+    protected $supportedOptions = array(
+        'allowedValues' => array([], 'Array of allowed values', 'array', false),
+    );
+
+    /**
+     * @param mixed $value
+     * @return void
+     */
+    protected function isValid($value)
+    {
+        if (!in_array( $value, $this->options['allowedValues'])) {
+            $this->addError('Some values are more correct than others.', 123456789);
+        }
+    }
+}
+```
+
+The custom validator can now be used in fusion forms.
+
+```
+prototype(Vendor.Site:Content.FormExample) < prototype(Neos.Fusion.Form:Runtime.RuntimeForm) {
+
+    process {
+        content = afx`
+            <Neos.Fusion.Form:FieldContainer field.name="favoriteMovie" label="Favorite Movie">
+                <Neos.Fusion.Form:Input />
+            </Neos.Fusion.Form:FieldContainer>
+        `
+
+        schema {
+            #
+            # A custom validator is identified via PackageKey and ValidatorName seperated by a colon. 
+            # The implementation is expected to be in the php namespace `__PackageNamespace__\Validation\Validator\__ValidatorName__Validator`
+            # 
+            favoriteMovie = ${Form.Schema.string().validator('Vendor.Site:AllowedValues', {allowedValues: ['Star Wars', 'Simpsons']})}
+        }
+    }
+    
+    ... 
+    
+```    
+
diff --git a/README.md b/README.md
index 7ee7f16..35519c8 100644
--- a/README.md
+++ b/README.md
@@ -30,6 +30,7 @@ be implemented like this.
   - [Custom form action](Documentation/Tutorials/CustomFormAction.md)
   - [Honeypot field](Documentation/Tutorials/HoneypotField.md)
   - [Conditional fields and steps](Documentation/Tutorials/ConditionalFieldsAndSteps.md)
+  - [Custom Validators](Documentation/Tutorials/CustomValidators.md)
 - Examples
   - [SingleStepForm](Documentation/Examples/SingleStepForm.md)
   - [MultiStepForm](Documentation/Examples/MultiStepForm.md)