Release notes and additional documentation for Forms 13.3 and 14.1.

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

@@ -57,7 +57,12 @@ For illustration purposes, the following structure represents the full set of op
         "AutocompleteAttribute": "",
         "DaysToRetainSubmittedRecordsFor": 0,
         "DaysToRetainApprovedRecordsFor": 0,
-        "DaysToRetainRejectedRecordsFor": 0
+        "DaysToRetainRejectedRecordsFor": 0,
+        "ShowPagingOnMultiPageForms": "None",
+        "PagingDetailsFormat": "Page {0} of {1}",
+        "PageCaptionFormat": "Page {0}",
+        "ShowSummaryPageOnMultiPageForms": false,
+        "SummaryLabel": "Summary of Entry"
       },
       "RemoveProvidedEmailTemplate": false,
       "RemoveProvidedFormTemplates": false,
@@ -88,7 +93,8 @@ For illustration purposes, the following structure represents the full set of op
       "UseSemanticFieldsetRendering": false,
       "DisableClientSideValidationDependencyCheck": false,
       "DisableRelationTracking": false,
-      "TrackRenderedFormsStorageMethod": "TempData"
+      "TrackRenderedFormsStorageMethod": "TempData",
+      "EnableMultiPageFormSettings": false
     },
     "Security": {
       "DisallowedFileUploadExtensions": "config,exe,dll,asp,aspx",
@@ -104,7 +110,9 @@ For illustration purposes, the following structure represents the full set of op
     },
     "FieldTypes": {
       "DatePicker": {
-        "DatePickerYearRange": 10
+        "DatePickerYearRange": 10,
+        "DatePickerFormat": "LL",
+        "DatePickerFormatForValidation": ""
       },
       "Recaptcha2": {
         "PublicKey": "",
@@ -305,6 +313,26 @@ Applies as per `DaysToRetainSubmittedRecordsFor` but for records in the 'approve
 
 Applies as per `DaysToRetainSubmittedRecordsFor` but for records in the 'rejected' state.
 
+### ShowPagingOnMultiPageForms
+
+Defines whether and where paging details are displayed for new multi-page forms.
+
+### PagingDetailsFormat
+
+Defines the paging details format for new multi-page forms.
+
+### PageCaptionFormat
+
+Defines the page caption format for new multi-page forms.
+
+### ShowSummaryPageOnMultiPageForms
+
+Defines whether summary pages are on by default for new multi-page forms.
+
+### SummaryLabel
+
+Defines the default summary label for new multi-page forms.
+
 ## Package options configuration
 
 ### IgnoreWorkFlowsOnEdit
@@ -420,6 +448,14 @@ To switch to this storage mechanism change the value of this setting from the de
 
 We expect `HttpContextItems` to be the default option from Forms 14 onwards.
 
+## EnableMultiPageFormSettings
+
+This setting determines whether [multi-page form settings](../../editor/creating-a-form/form-settings.md#multi-page-forms) are available to editors.
+
+By default the value is `false`. This ensures that, in an upgrade scenario, before the feature is used the necessary styling and/or theme updates can be prepared.
+
+To make the feature available to editors set the value to `true`.
+
 ## Security configuration
 
 ### DisallowedFileUploadExtensions
@@ -484,6 +520,14 @@ For more information, see the [Headless/AJAX Forms](../ajaxforms.md) article.
 
 This setting is used to configure the Date Picker form field range of years that is available in the date picker. By default this is a small range of 10 years.
 
+#### DatePickerFormat
+
+A custom date format can be provided in [momentjs format](https://momentjscom.readthedocs.io/en/latest/moment/01-parsing/03-string-format/) if you want to override the default.
+
+#### DatePickerFormatForValidation
+
+If a custom date format is provided it will be used on the client-side. A matching string in [C# date format](https://learn.microsoft.com/en-us/dotnet/standard/base-types/custom-date-and-time-format-strings) should be provided, in order that server-side validation will match the expected format of the entry.
+
 ### reCAPTCHA v2 field type configuration
 
 #### PublicKey & PrivateKey

13/umbraco-forms/developer/security.md

@@ -13,6 +13,7 @@ Within the _Form Security_ tree, each user with a backoffice account is listed.
 * _Manage forms_ - user can create and edit form definitions
 * _View entries_ - user can view the submitted entries
 * _Edit entries_ - user can edit the submitted entries
+* _Delete entries_ - user can delete the submitted entries
 * _Manage datasources_ - user can create and edit datasource definitions
 * _Manage prevalue sources_ - user can create and edit prevalue source definitions
 

13/umbraco-forms/developer/themes.md

@@ -41,6 +41,77 @@ Umbraco Forms conditional JavaScript logic depends on some CSS classes currently
 
 If adding or amending client-side scripts, you need to copy the `Script.cshtml` file from the `default` themes folder. In your copy, amend the `.js` references to reference your own script files.
 
+### Shipping Themes in a Razor Class Library
+
+Umbraco Forms provides it's built-in themes as part of a Razor Class Library for ease of distribution. This can be useful for custom themes, particularly those used in multiple solutions or released as an Umbraco package.
+
+From Forms 13.3 it's possible to do this for custom themes.
+
+Firstly you'll create a new Razor Class Library project to hold the theme.  You then create the necessary partial views for your theme as usual within `Views\Partials\Forms\Themes\<my-custom-theme>`.
+
+You then need to provide the names of the files in your theme via an implementation of `ITheme`. For example, if only overriding a single file, your class would look like this:
+
+```csharp
+using Umbraco.Forms.Core.Interfaces;
+
+public class MyCustomTheme : ITheme
+{
+    private const string FilePathFormat = "{0}/{1}/{2}.cshtml";
+
+    public virtual string Name => "my-custom-theme";
+
+    public virtual IEnumerable<string> Files =>
+        [
+            string.Format(FilePathFormat, Core.Constants.System.ThemesPath, Name, "FieldTypes/FieldType.Textfield"),
+        ];
+}
+```
+
+In your project that consumes the theme, you register the ones you want to use via a composer:
+
+```csharp
+public class MyComposer : IComposer
+{
+    public void Compose(IUmbracoBuilder builder)
+    {
+      builder.Themes()
+          .Add<MyCustomTheme>();
+    }
+}
+```
+
+With that in place your theme will be picked up for selection in the theme picker. And the partial view files included will be used when rendering forms.
+
+#### Email Templates
+
+Email templates provided for the send email workflow can be provided in a Razor Class Library in a similar way.
+
+The partial view will be created in `Views\Partials\Forms\Emails`.
+
+It's made available via an implementation of `IEmailTemplate`:
+
+```csharp
+using Umbraco.Forms.Core.Interfaces;
+
+public class MyCustomEmailTemplate : IEmailTemplate
+{
+    public virtual string FileName => "My-Custom-Email-Template.cshtml";
+}
+```
+
+And registered with:
+
+```csharp
+public class MyComposer : IComposer
+{
+    public void Compose(IUmbracoBuilder builder)
+    {
+      builder.EmailTemplates()
+          .Add<MyCustomEmailTemplate>();
+    }
+}
+```
+
 ## Using a Theme
 
 To use a theme with a Form use the "Insert Form" macro where you will be presented with the options of the form you wish to insert along with an option to pick a theme. This displays the list of theme folders found at `Views/Partials/Forms/Themes`.

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

@@ -57,6 +57,24 @@ The autocomplete setting for the overall form can be changed from the default of
 
 <figure><img src="images/FormSettingsAutocomplete.png" alt=""><figcaption><p>Form Settings Autocomplete</p></figcaption></figure>
 
+### Multi-page forms
+
+The settings available in this section allow you to customize how multi-page forms are presented to site visitors.
+
+<figure><img src="images/multi-page-forms.png" alt=""><figcaption><p>Multi-Page Form Settings</p></figcaption></figure>
+
+| Option                           | Description                                                                                                                                                                                                     |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **Paging display**               | Select whether paging information is displayed at the top and/or bottom of the form.                                                                                                                            |
+| **Paging display format**        | Provide a format string for the paging details. By default `Page {0} of {1}` is used which will be replaced as, for example, `Page 1 of 4`.                                                                     |
+| **Page caption format**          | Provide a format string for rendering the page captions. By default `Page {0}` is used which will be replaced as, for example, `Page 1`. If a caption for the page has been provided, it will be used instead.  |
+| **Show summary page**            | Select whether a summary page is displayed at the end of multi-page forms, where a user can review their entry before submitting.                                                                               |
+| **Summary heading**              | Provide the heading for the summary page.                                                                                                                                                                       |
+
+{% hint style="info" %}
+These options will only be available if [the feature is configured for display](../../developer/configuration/README.md#enablemultipageformsettings).
+{% endhint %}
+
 ### Moderation
 
 Enabling this feature allows the moderator to manage the approval status of a form. This can be used in a number of scenarios. For example, if the form submission will be publicly shown, you can control which are published.

13/umbraco-forms/release-notes.md

@@ -17,6 +17,25 @@ 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.3.0-rc1**](https://github.com/umbraco/Umbraco.Forms.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F13.3.0) **To Be Confirmed**
+
+The 13.3 release of Forms contains features that can improve the user experience of completing multi-page forms.
+
+We've added the option for [editors to choose to display paging details on the forms](./editor/creating-a-form/form-settings.md#multi-page-forms). This will allow those completing forms to get a better understanding of progress as well as see details of the pages still to complete. [#281](https://github.com/umbraco/Umbraco.Forms.Issues/issues/281) [#648](https://github.com/umbraco/Umbraco.Forms.Issues/issues/648).
+
+These can be options are enabled and configured on a per-form basis by editors in the form settings section. We also provide a [configuration based toggle for the feature as a whole](./developer/configuration/README.md#enablemultipageformsettings). In this way editors can be given access to use the feature only once the styling or theme is prepared.
+
+Forms ships it's themes and email templates as part of a razor class library for ease of distribution. With this release we make that feature [available to your own custom themes and templates](./developer/themes.md#shipping-themes-in-a-razor-class-library) (or those created by package developers) [#795](https://github.com/umbraco/Umbraco.Forms.Issues/issues/795).
+
+The format for the date field can now be provided in configuration [#1276](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1276).
+
+To allow finer control over editor permissions, we've introduced a "delete entries" setting available on users and user groups. Thus you can now give editors explicit permissions to view, edit or delete entries [#1303](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1303).
+
+Other bug fixes included in the release:
+
+* Fix issue with single checkbox triggering a condition on a field on a subsequent page [#1304](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1304).
+* Improve cross-platform check when exporting to Excel.
+
 #### [**13.2.5**](https://github.com/umbraco/Umbraco.Forms.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F13.2.5) **(October 3rd 2024)**
 
 * Handled "chunked" authentication cookie in protection of file uploads saved in the media file system [#11](https://github.com/umbraco/Umbraco.Forms.Issues/issues/11#issuecomment-2376788751).

14/umbraco-forms/SUMMARY.md

@@ -34,6 +34,7 @@
 
 ## Developer
 
+* [Property Editors](developer/property-editors.md)
 * [Preparing Your Frontend](developer/prepping-frontend.md)
 * [Rendering Forms](developer/rendering-forms.md)
 * [Rendering Forms Scripts](developer/rendering-scripts.md)

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

@@ -57,7 +57,12 @@ For illustration purposes, the following structure represents the full set of op
         "AutocompleteAttribute": "",
         "DaysToRetainSubmittedRecordsFor": 0,
         "DaysToRetainApprovedRecordsFor": 0,
-        "DaysToRetainRejectedRecordsFor": 0
+        "DaysToRetainRejectedRecordsFor": 0,
+        "ShowPagingOnMultiPageForms": "None",
+        "PagingDetailsFormat": "Page {0} of {1}",
+        "PageCaptionFormat": "Page {0}",
+        "ShowSummaryPageOnMultiPageForms": false,
+        "SummaryLabel": "Summary of Entry"
       },
       "RemoveProvidedEmailTemplate": false,
       "RemoveProvidedFormTemplates": false,
@@ -88,7 +93,8 @@ For illustration purposes, the following structure represents the full set of op
       "UseSemanticFieldsetRendering": false,
       "DisableClientSideValidationDependencyCheck": false,
       "DisableRelationTracking": false,
-      "TrackRenderedFormsStorageMethod": "HttpContextItems"
+      "TrackRenderedFormsStorageMethod": "HttpContextItems",
+      "EnableMultiPageFormSettings": false
     },
     "Security": {
       "DisallowedFileUploadExtensions": "config,exe,dll,asp,aspx",
@@ -104,7 +110,9 @@ For illustration purposes, the following structure represents the full set of op
     },
     "FieldTypes": {
       "DatePicker": {
-        "DatePickerYearRange": 10
+        "DatePickerYearRange": 10,
+        "DatePickerFormat": "LL",
+        "DatePickerFormatForValidation": ""
       },
       "Recaptcha2": {
         "PublicKey": "",
@@ -305,6 +313,26 @@ Applies as per `DaysToRetainSubmittedRecordsFor` but for records in the 'approve
 
 Applies as per `DaysToRetainSubmittedRecordsFor` but for records in the 'rejected' state.
 
+### ShowPagingOnMultiPageForms
+
+Defines whether and where paging details are displayed for new multi-page forms.
+
+### PagingDetailsFormat
+
+Defines the paging details format for new multi-page forms.
+
+### PageCaptionFormat
+
+Defines the page caption format for new multi-page forms.
+
+### ShowSummaryPageOnMultiPageForms
+
+Defines whether summary pages are on by default for new multi-page forms.
+
+### SummaryLabel
+
+Defines the default summary label for new multi-page forms.
+
 ## Package options configuration
 
 ### IgnoreWorkFlowsOnEdit
@@ -417,6 +445,14 @@ By default, `HttpContext.Items` is used as the storage mechanism for this tracki
 
 You can optionally revert to the legacy behavior of using `TempData` by changing this setting from the default of `HttpContextItems` to `TempData`.
 
+## EnableMultiPageFormSettings
+
+This setting determines whether [multi-page form settings](../../editor/creating-a-form/form-settings.md#multi-page-forms) are available to editors.
+
+By default the value is `false`. This ensures that, in an upgrade scenario, before the feature is used the necessary styling and/or theme updates can be prepared.
+
+To make the feature available to editors set the value to `true`.
+
 ## Security configuration
 
 ### DisallowedFileUploadExtensions
@@ -481,6 +517,14 @@ For more information, see the [Headless/AJAX Forms](../ajaxforms.md) article.
 
 This setting is used to configure the Date Picker form field range of years that is available in the date picker. By default this is a small range of 10 years.
 
+#### DatePickerFormat
+
+A custom date format can be provided in [momentjs format](https://momentjscom.readthedocs.io/en/latest/moment/01-parsing/03-string-format/) if you want to override the default.
+
+#### DatePickerFormatForValidation
+
+If a custom date format is provided it will be used on the client-side. A matching string in [C# date format](https://learn.microsoft.com/en-us/dotnet/standard/base-types/custom-date-and-time-format-strings) should be provided, in order that server-side validation will match the expected format of the entry.
+
 ### reCAPTCHA v2 field type configuration
 
 #### PublicKey & PrivateKey

14/umbraco-forms/developer/property-editors.md

@@ -0,0 +1,39 @@
+# Property Editors
+
+When forms are created, editors will want to add them to pages in Umbraco. To do this they need a Document Type with a property that uses a datatype based on a form picker property editor.
+
+Umbraco Forms provides three variations of a form picker.
+
+<figure><img src="images/form-pickers.png" alt=""><figcaption><p>Form Pickers</p></figcaption></figure>
+
+Most commonly used is **Form Picker (single)**. This will allow the editor to select a single form for display on page.
+
+Rarely but feasibly, you'll have a requirement to present multiple forms on a page. Should this be appropriate, you can use **Form Picker (multiple)**.
+
+{% hint style="info" %}
+Internally this is used for presenting the list of "Allowed forms" you can select when setting up a form picker datatype.
+{% endhint %}
+
+Finally you can provide further flexibility for the editor to select not only a form, but also the theme and redirect as well. For this you'll use the **Form Details Picker**.
+
+## Configuring the Data Type
+
+Each property editor allows you to restrict the forms that can be chosen with the datatype. You do this by setting either or both of the list of "Allowed folders" or "Allowed forms".
+
+<figure><img src="images/form-picker-config.png" alt=""><figcaption><p>Form Picker DataType Configuration</p></figcaption></figure>
+
+THe "Form Details Picker" also allow you to select whether theme or redirect selection is available.
+
+## Property Value Conversion
+
+The type of a property based on the form picker presented in a Razor class library is as followes:
+
+| Option                           | Description                                                                                                                                                                                                     |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| **Form Picker (single)**         | Single GUID representing the form's identifier.                                                                                         |
+| **Form Picker (multiple)**       | Collection of GUIDs representing the form identifiers.                                                                                  |
+| **Form Details Picker**          | Instance of the `Umbraco.Forms.Core.PropertyEditors.Models.FormDetails` object, which has properties for the form, theme and redirect.  |
+
+## Content Delivery API Expansion
+
+Each reference to a form supports expansion via the Umbraco Content Delivery API, as described [here](./ajaxforms.md#working-with-the-cms-content-delivery-api).

14/umbraco-forms/developer/security.md

@@ -13,6 +13,7 @@ Within the _Forms_ > _Security_ tree, each user with a backoffice account is lis
 * Manage Forms - user can create and edit form definitions
 * View Entries - user can view the submitted entries
 * Edit Entries - user can edit the submitted entries
+* Delete entries - user can delete the submitted entries
 * Manage Workflows - user can create and edit workflow items
 * Manage Datasources - user can create and edit datasource definitions
 * Manage Prevalue Sources - user can create and edit prevalue source definitions