Merge pull request #6731 from AndyButland/forms/release-notes-13.4.0-…

…rc1-and-15.1.0-rc1

Added release notes for Forms 13.4-rc1 and 15.1-rc1

13/umbraco-forms/SUMMARY.md

@@ -19,6 +19,7 @@
 
 * [Creating a Form - The basics](editor/creating-a-form/README.md)
   * [Form Settings](editor/creating-a-form/form-settings.md)
+  * [Form Advanced Options](editor/creating-a-form/form-advanced.md)
   * [Form Information](editor/creating-a-form/form-info.md)
   * [Overview Of The Field Types](editor/creating-a-form/fieldtypes/README.md)
     * [Date](editor/creating-a-form/fieldtypes/date.md)

13/umbraco-forms/developer/configuration/README.md

@@ -94,7 +94,8 @@ For illustration purposes, the following structure represents the full set of op
       "DisableClientSideValidationDependencyCheck": false,
       "DisableRelationTracking": false,
       "TrackRenderedFormsStorageMethod": "TempData",
-      "EnableMultiPageFormSettings": false
+      "EnableMultiPageFormSettings": false,
+      "EnableAdvancedValidationRules": false
     },
     "Security": {
       "DisallowedFileUploadExtensions": "config,exe,dll,asp,aspx",
@@ -456,6 +457,14 @@ By default the value is `false`. This ensures that, in an upgrade scenario, befo
 
 To make the feature available to editors set the value to `true`.
 
+## EnableAdvancedValidationRules
+
+This setting determines whether [advanced form validation rules](../../editor/creating-a-form/form-advanced.md) are available to editors.
+
+By default, the value is `false`.  This is partly because the feature is only considered for "power users", comfortable with crafting rules using the required JSON syntax. And partly as validating the rules on the client requires an additional front-end dependency.
+
+To make the feature available to editors and include the dependency when using `@Html.RenderUmbracoFormDependencies(Url)`, set the value to `true`.
+
 ## Security configuration
 
 ### DisallowedFileUploadExtensions

13/umbraco-forms/editor/creating-a-form/form-advanced.md

@@ -0,0 +1,98 @@
+# Form Advanced Options
+
+In this article, you will find information about accessing the Forms Advanced Options and the features available to customize your Form.
+
+To access the Form Advanced Options:
+
+1. Navigate to the **Forms** section.
+2. Open a Form you wish to customize.
+3.  Click **Advanced** in the top-right corner of the screen.
+
+{% hint style="info" %}
+The advanced options for forms are only available when [configured to display](../../developer/configuration/README.md#enableadvancedvalidationrules).
+{% endhint %}
+
+## Validation Rules
+
+When creating forms you can add validation to individual fields, making them mandatory or applying a regular expression pattern. You can provide validation rules for the entire form via the advanced options. This allows you to validate expressions based on multiple fields. For example, "these two email fields should be the same", or "this date should be after this other one".
+
+![Validation rules](./images/validation-rules.png)
+
+To add new rules, you need to provide the rule definition, an error message and select a field to which the message will be associated.  Once created you can click to edit or delete them from the list.
+
+Crafting the rule definition itself requires use of [JSON logic](https://jsonlogic.com/) along with placeholders for the field or fields that are being validated.
+
+### Examples
+
+One example use case would be ensuring that two fields match each other, perhaps when asking for a user's email address.  Given two fields on the form, one with the alias of `email` and the other `compareEmail`, the rule would be:
+
+```json
+{
+  "==": [
+    "{email}",
+    "{compareEmail}"
+  ]
+}
+```
+
+A slightly more complex example could be with two dates, where, if provided, you want to ensure the second date is later than the first. So given fields with aliases of `startDate` and `endDate` a rule would look like this:
+
+```json
+{
+  "or": [
+    {
+      "==": [
+        "{startDate}",
+        ""
+      ]
+    },
+    {
+      "==": [
+        "{endDate}",
+        ""
+      ]
+    },
+    {
+      ">": [
+        "{endDate}",
+        "{startDate}"
+      ]
+    }
+  ]
+}
+```
+
+Rules can be nested too. In this final illustrative example, we have two fields. One with the alias `choose` is a drop-down list with two values: `A` and `B`. The second field with alias `test` we want to be completed only if the user selects `B`.  So we create a rule that is valid only if A is selected OR B is selected AND `test` is completed.
+
+```json
+{
+  "or": [
+    {
+      "==": [
+        "{choose}",
+        "A"
+      ]
+    },
+    {
+      "and": [
+        {
+          "==": [
+            "{choose}",
+            "B"
+          ]
+        },
+        {
+          "!=": [
+            "{test}",
+            ""
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+Overall, you can create rules of varying complexity, using comparisons between fields and static values.
+
+When the form is rendered, these validation rules will be applied on both the client and server-side. In this way, you can ensure the submission is only accepted if it meets the requirements.

13/umbraco-forms/editor/creating-a-form/form-settings.md

@@ -1,6 +1,6 @@
 # Form Settings
 
-In this article, you will find information about accessing the Forms Settings and the validations available to customize your Form.
+In this article, you will find information about accessing the Forms Settings and the options available to customize your Form.
 
 To access the Form Settings:
 

13/umbraco-forms/release-notes.md

@@ -16,6 +16,38 @@ If you are upgrading to a new major version, you can find information about the
 
 This section contains the release notes for Umbraco Forms 13 including all changes for this version.
 
+#### [**13.4.0-rc1**](https://github.com/umbraco/Umbraco.Forms.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F13.4.0) **(December 17th 2024)**
+
+##### Validation rules across form fields
+
+When creating forms you are able to add validation to individual fields, making them mandatory or applying a regular expression pattern. With the 13.4 release we are looking to make this more powerful, by allowing the addition of validation rules for the entire form. The idea is that this will allow you to validate expressions based on multiple fields. For example, "these two email fields should be the same", or "this date should be after this other one".
+
+Crafting these rules requires use of [JSON logic](https://jsonlogic.com/) so is considered a "power user" feature. They also require an additional front-end dependency for the rendering of forms on the website. As such they are surfaced on a new "Advanced" tab and only visible and used if enabled in configuration. We don't have, and it seems difficult to provide, an intuitive user interface for rule creation taking into account all the flexibility available. Nonetheless, having the ability to use more complex validation rules seems a valuable addition.
+
+When the form is rendered, the validation rules will be applied on the client, where we support both the `aspnet-client-validation` and `jquery.validate` libraries. They are also verified server-side. In this way you can ensure the submission is only accepted if it meets the requirements.
+
+Feedback on this feature in particular is welcome.
+
+Read more about [editing advanced validation rules](./editor/creating-a-form/form-advanced.md) as well as the [configuration option required to enable them](./developer/configuration/README.md#enableadvancedvalidationrules).
+
+##### Tracking editor activity
+
+Whilst previously we tracked and displayed the date a form was created and last edited, we didn't show who had made these updates. With 13.4 installed we will start to track this and display the information where available. You'll find this on the form, data source or prevalue source's "Info" tab [#1315](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1315).
+
+##### Copy of workflows
+
+Forms allows you to make a copy of a form to use as a starting point for a new one. You can choose whether or not to copy workflows along with the form. With the 13.4 release, we've made available a second dialog allowing you to copy workflows to an existing form [#1185](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1185). You can select any or all of the workflows on the current form and copy them to the selected destination form.
+
+We've also resolved an edge case around copying a form. It's possible to [define workflows as mandatory](./developer/extending/customize-default-workflows.md#setting-a-mandatory-default-workflow). Copying the form without workflows excludes the desired workflow. You would have a form that didn't contain the workflow you wanted to be included on all. This has been tightened up now and mandatory workflows will always be assigned to the copied form [#1331](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1331).
+
+##### Form picker enhancements
+
+In the 14.2 release we enhanced the [form picker property editors](./developer/property-editors.md). We introduced support for restriction of which forms can be selected by folder rather than only by individual forms. This has now been backported to Forms 13 [#891](https://github.com/umbraco/Umbraco.Forms.Issues/issues/891).
+
+##### File upload validation messages
+
+Previously the validation messages presented on the website front end when uploading files were hardcoded and always provided in English. We've added settings now to the "File Upload" field type allowing you to customize these. Dictionary keys can be used in order to provide the information in the user's preferred language [#1327](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1327).
+
 #### [**13.3.3**](https://github.com/umbraco/Umbraco.Forms.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F13.3.3) **(December 5th 2024)**
 
 * Fixed regression introduced in 13.3.1 that caused issues for custom field types overriding the `ProcessSubmittedValue` method  [#1328](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1328).

15/umbraco-forms/SUMMARY.md

@@ -19,6 +19,7 @@
 
 * [Creating a Form - The basics](editor/creating-a-form/README.md)
   * [Form Settings](editor/creating-a-form/form-settings.md)
+  * [Form Advanced Options](editor/creating-a-form/form-advanced.md)
   * [Form Information](editor/creating-a-form/form-info.md)
   * [Overview Of The Field Types](editor/creating-a-form/fieldtypes/README.md)
     * [Date](editor/creating-a-form/fieldtypes/date.md)

15/umbraco-forms/developer/configuration/README.md

@@ -93,7 +93,8 @@ For illustration purposes, the following structure represents the full set of op
       "DisableClientSideValidationDependencyCheck": false,
       "DisableRelationTracking": false,
       "TrackRenderedFormsStorageMethod": "HttpContextItems",
-      "EnableMultiPageFormSettings": true
+      "EnableMultiPageFormSettings": true,
+      "EnableAdvancedValidationRules": false
     },
     "Security": {
       "DisallowedFileUploadExtensions": "config,exe,dll,asp,aspx",
@@ -446,6 +447,15 @@ This setting determines whether [multi-page form settings](../../editor/creating
 
 By default the value is `true`. To disable the feature, set the value to `false`.
 
+## EnableAdvancedValidationRules
+
+This setting determines whether [advanced form validation rules](../../editor/creating-a-form/form-advanced.md) are available to editors.
+
+By default, the value is `false`.  This is partly because the feature is only considered for "power users", comfortable with crafting rules using the required JSON syntax. And partly as validating the rules on the client requires an additional front-end dependency.
+
+To make the feature available to editors and include the dependency when using `@Html.RenderUmbracoFormDependencies(Url)`, set the value to `true`.
+
+
 ## Security configuration
 
 ### DisallowedFileUploadExtensions

15/umbraco-forms/editor/creating-a-form/form-advanced.md

@@ -0,0 +1,98 @@
+# Form Advanced Options
+
+In this article, you will find information about accessing the Forms Advanced Options and the features available to customize your Form.
+
+To access the Form Advanced Options:
+
+1. Navigate to the **Forms** section.
+2. Open a Form you wish to customize.
+3.  Click **Advanced** in the top-right corner of the screen.
+
+{% hint style="info" %}
+The advanced options for forms are only available when [configured to display](../../developer/configuration/README.md#enableadvancedvalidationrules).
+{% endhint %}
+
+## Validation Rules
+
+When creating forms you can add validation to individual fields, making them mandatory or applying a regular expression pattern. You can provide validation rules for the entire form via the advanced options. This allows you to validate expressions based on multiple fields. For example, "these two email fields should be the same", or "this date should be after this other one".
+
+![Validation rules](./images/validation-rules.png)
+
+To add new rules, you need to provide the rule definition, an error message and select a field to which the message will be associated.  Once created you can click to edit or delete them from the list.
+
+Crafting the rule definition itself requires use of [JSON logic](https://jsonlogic.com/) along with placeholders for the field or fields that are being validated.
+
+### Examples
+
+One example use case would be ensuring that two fields match each other, perhaps when asking for a user's email address.  Given two fields on the form, one with the alias of `email` and the other `compareEmail`, the rule would be:
+
+```json
+{
+  "==": [
+    "{email}",
+    "{compareEmail}"
+  ]
+}
+```
+
+A slightly more complex example could be with two dates, where, if provided, you want to ensure the second date is later than the first. So given fields with aliases of `startDate` and `endDate` a rule would look like this:
+
+```json
+{
+  "or": [
+    {
+      "==": [
+        "{startDate}",
+        ""
+      ]
+    },
+    {
+      "==": [
+        "{endDate}",
+        ""
+      ]
+    },
+    {
+      ">": [
+        "{endDate}",
+        "{startDate}"
+      ]
+    }
+  ]
+}
+```
+
+Rules can be nested too. In this final illustrative example, we have two fields. One with the alias `choose` is a drop-down list with two values: `A` and `B`. The second field with alias `test` we want to be completed only if the user selects `B`.  So we create a rule that is valid only if A is selected OR B is selected AND `test` is completed.
+
+```json
+{
+  "or": [
+    {
+      "==": [
+        "{choose}",
+        "A"
+      ]
+    },
+    {
+      "and": [
+        {
+          "==": [
+            "{choose}",
+            "B"
+          ]
+        },
+        {
+          "!=": [
+            "{test}",
+            ""
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+Overall, you can create rules of varying complexity, using comparisons between fields and static values.
+
+When the form is rendered, these validation rules will be applied on both the client and server-side. In this way, you can ensure the submission is only accepted if it meets the requirements.

15/umbraco-forms/editor/creating-a-form/form-settings.md

@@ -1,6 +1,6 @@
 # Form Settings
 
-In this article, you will find information about accessing the Form Settings and the validations available to customize your Form.
+In this article, you will find information about accessing the Form Settings and the options available to customize your Form.
 
 To access the Form Settings:
 

15/umbraco-forms/release-notes.md

@@ -18,6 +18,40 @@ If you are upgrading to a new major version, you can find information about the
 
 This section contains the release notes for Umbraco Forms 15 including all changes for this version.
 
+#### [**15.1.0-rc1**](https://github.com/umbraco/Umbraco.Forms.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F15.1.0) **(December 17th 2024)**
+
+##### Validation rules across form fields
+
+When creating forms you are able to add validation to individual fields, making them mandatory or applying a regular expression pattern. With the 13.4 release we are looking to make this more powerful, by allowing the addition of validation rules for the entire form. The idea is that this will allow you to validate expressions based on multiple fields. For example, "these two email fields should be the same", or "this date should be after this other one".
+
+Crafting these rules requires use of [JSON logic](https://jsonlogic.com/) so is considered a "power user" feature. They also require an additional front-end dependency for the rendering of forms on the website. As such they are surfaced on a new "Advanced" tab and only visible and used if enabled in configuration. We don't have, and it seems difficult to provide, an intuitive user interface for rule creation taking into account all the flexibility available. Nonetheless, having the ability to use more complex validation rules seems a valuable addition.
+
+When the form is rendered, the validation rules will be applied on the client, where we support both the `aspnet-client-validation` and `jquery.validate` libraries. They are also verified server-side. In this way you can ensure the submission is only accepted if it meets the requirements.
+
+Feedback on this feature in particular is welcome.
+
+Read more about [editing advanced validation rules](./editor/creating-a-form/form-advanced.md) as well as the [configuration option required to enable them](./developer/configuration/README.md#enableadvancedvalidationrules).
+
+##### Tracking editor activity
+
+Whilst previously we tracked and displayed the date a form was created and last edited, we didn't show who had made these updates. With 15.1 installed we will start to track this and display the information where available. You'll find this on the form, data source or prevalue source's "Info" tab [#1315](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1315).
+
+##### Copy of workflows
+
+Forms allows you to make a copy of a form to use as a starting point for a new one. You can choose whether or not to copy workflows along with the form. With the 15.1 release, we've made available a second dialog allowing you to copy workflows to an existing form [#1185](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1185). You can select any or all of the workflows on the current form and copy them to the selected destination form.
+
+We've also resolved an edge case around copying a form. It's possible to [define workflows as mandatory](./developer/extending/customize-default-workflows.md#setting-a-mandatory-default-workflow). Copying the form without workflows excludes the desired workflow. You would have a form that didn't contain the workflow you wanted to be included on all. This has been tightened up now and mandatory workflows will always be assigned to the copied form [#1331](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1331).
+
+##### File upload validation messages
+
+Previously the validation messages presented on the website front end when uploading files were hardcoded and always provided in English. We've added settings now to the "File Upload" field type allowing you to customize these. Dictionary keys can be used in order to provide the information in the user's preferred language [#1327](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1327).
+
+##### Other
+
+Other bug fixes included in the release:
+
+* Fixed issue with applying links to rich text settings on custom field or workflow types [#1329](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1329).
+
 #### [**15.0.3**](https://github.com/umbraco/Umbraco.Forms.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F15.0.3) **(December 5th 2024)**
 
 * Fixed regression introduced in 15.0.1 that caused issues for custom field types overriding the `ProcessSubmittedValue` method  [#1328](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1328).