Merge pull request #68 from neos/docs/addTutorialsForHoneypotAndCondi…

…tionalFields

DOCS: Add tutorials for honeypot and conditional fields / steps

Documentation/Tutorials/ConditionalFieldsAndSteps.md

@@ -0,0 +1,54 @@
+# Conditional fields
+
+The data from previous steps can be used to only show fields in certain conditions.
+
+```
+renderer = Neos.Fusion.Form:Runtime.RuntimeForm {
+    process {
+        content = afx`
+            <Neos.Fusion.Form:FieldContainer 
+                @if.hasOtherValue = ${data.otherValue}
+                label="Conditional Field" 
+                field.name="conditionalField"
+            >
+                <Neos.Fusion.Form:Input />
+            </Neos.Fusion.Form:FieldContainer>
+        `
+    }
+}
+```
+
+This also allows to make whole form steps conditional:
+
+```
+renderer = Neos.Fusion.Form:Runtime.RuntimeForm {
+    process = Neos.Fusion.Form:Runtime.MultiStepProcess {
+        steps {
+            address {
+                ...
+            }
+            visa {
+                @if.fromForeignGalaxy = ${data.galaxy != 'milkyway'}
+                ...
+            }
+        }
+    }
+}
+```
+
+If a field shall always be present but required once other fields are filled, the schema can be adjusted via `@process` and `@if`.
+
+```
+renderer = Neos.Fusion.Form:Runtime.RuntimeForm {
+    process {
+        schema {
+            conditionalField = ${Form.Schema.string()}
+            conditionalField.@process.makeRequired = ${value.isRequired()}
+            conditionalField.@process.makeRequired.@if.hasOtherValue = ${data.otherValue || request.arguments.otherValue}
+        }
+    }
+}
+```
+
+The condition checks the submitted data from the current request `request.arguments.otherField` and the 
+successfully submitted data from previous requests `data.otherField`. 

Documentation/Tutorials/HoneypotField.md

@@ -0,0 +1,66 @@
+# Honeypot fields
+
+Honeypot fields are invisible but may be filled by bots and help to identify spam.
+In Fusion Form, they can be implemented by combining an invisible field with a validator 
+that verifies that the field `honey` was not filled.
+
+```
+renderer = Neos.Fusion.Form:Runtime.RuntimeForm {
+    process {
+        content = afx`
+            .... 
+            <Neos.Fusion.Form:FieldContainer 
+                field.name="honey"  
+                attributes.style="display:none; !important"
+                attributes.autocomplete="off"
+                attributes.tabindex="-1"
+                >
+                <Neos.Fusion.Form:Input />
+            </Neos.Fusion.Form:FieldContainer>
+        `
+        schema {
+            ...
+            honey = ${Form.Schema.string().validator('StringLength', {minimum:0, maximum:0})}
+        }
+    }
+}
+```
+
+If you want to handle the spam detection silently, you may still show the success message 
+but not trigger the email action. In this case, instead of the validator, a condition for actions may be used.
+
+```
+renderer = Neos.Fusion.Form:Runtime.RuntimeForm {
+    process {
+        content = afx`
+            .... 
+            <Neos.Fusion.Form:FieldContainer 
+                field.name="honey"  
+                attributes.style="display:none; !important"
+                attributes.autocomplete="off"
+                attributes.tabindex="-1"
+                >
+                <Neos.Fusion.Form:Input />
+            </Neos.Fusion.Form:FieldContainer>
+        `
+        schema {
+            ...
+            honey = ${Form.Schema.string()}
+        }
+    }
+    action {
+        # the message is always shown
+        message {
+            type = 'Neos.Fusion.Form.Runtime:Message'
+            options.message = ${q(node).property('message')}
+        }
+        # but the mail is only sent if no honey is found
+        email {
+            @if.noHoney = ${data.honey ? false : true}
+            type = 'Neos.Fusion.Form.Runtime:Email' {    
+               ...
+            }   
+        }    
+    }    
+}
+```

README.md

@@ -28,6 +28,8 @@ be implemented like this.
 - [Runtime Fusion Form Basics](Documentation/RuntimeFormBasics.md)
 - Tutorials
   - [Custom form action](Documentation/Tutorials/CustomFormAction.md)
+  - [Honeypot field](Documentation/Tutorials/HoneypotField.md)
+  - [Conditional fields and steps](Documentation/Tutorials/ConditionalFieldsAndSteps.md)
 - Examples
   - [SingleStepForm](Documentation/Examples/SingleStepForm.md)
   - [MultiStepForm](Documentation/Examples/MultiStepForm.md)