Merge pull request #6532 from AndyButland/forms/release-13.3-14.1

Release notes and additional documentation for Forms 13.3 and 14.2.

Author: sofietoft

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 multi-page forms.
+
+### PagingDetailsFormat
+
+Defines the paging details format for multi-page forms.
+
+### PageCaptionFormat
+
+Defines the page caption format for multi-page forms.
+
+### ShowSummaryPageOnMultiPageForms
+
+Defines whether summary pages are on by default for multi-page forms.
+
+### SummaryLabel
+
+Defines the default summary label for 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, so that server-side validation will match the expected format of the entry.
+
 ### reCAPTCHA v2 field type configuration
 
 #### PublicKey & PrivateKey

13/umbraco-forms/developer/configuration/type-details.md

@@ -52,6 +52,8 @@ The intention is to be able to make available details such as IDs, aliases and p
 **Settings:**
 
 * `Placeholder`
+* `ShowLabel`
+* `AriaLabel`
 
 </details>
 
@@ -502,6 +504,7 @@ The intention is to be able to make available details such as IDs, aliases and p
 * `UseCurrentPage`
 * `DocType`
 * `ValueField`
+* `CaptionField`
 * `ListGrandChildren`
 * `OrderBy`
 

13/umbraco-forms/developer/extending/adding-a-fieldtype.md

@@ -106,6 +106,16 @@ If working with Umbraco 9 or earlier versions, you'll find the `Views\Partials\F
 
 For Umbraco 10 and above, we've moved to [distributing the theme as part of a Razor Class Library](../../upgrading/version-specific.md#views-and-client-side-files) so the folder won't exist. However, you can create it for your custom field type. If you would like to reference the partial views of the default theme, you can download them as mentioned in the [Themes](../themes.md) article.
 
+### Read-only partial view
+
+When rendering a multi-page form, editors have the option to display a summary page where the entries can be viewed before submitting.
+
+To support this, a read-only view of the field is necessary.
+
+For most fields, nothing is required here, as the default read-only display defined in the built-in `ReadOnly.cshtml` file suffices.
+
+However, if you want to provide a custom read-only display for your field, you can do so by creating a second partial view. This should be named with a `.ReadOnly` suffix. For this example, you would create `FieldType.Slider.ReadOnly.cshtml`.
+
 ## Umbraco backoffice view
 
 The final step involves building the HTML view which will be rendered in Umbraco as an example of how our end result will look:

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,78 @@ 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 is possible to do this for custom themes.
+
+1. Create a new Razor Class Library project to hold the theme.
+2. Create the necessary Partial Views for your theme within `Views\Partials\Forms\Themes\<my-custom-theme>`.
+3. 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 the code snippet below:
+
+```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"),
+        ];
+}
+```
+
+4. Register the themes you want to use via a composer:
+
+```csharp
+public class MyComposer : IComposer
+{
+    public void Compose(IUmbracoBuilder builder)
+    {
+      builder.Themes()
+          .Add<MyCustomTheme>();
+    }
+}
+```
+
+Your theme will now be available in the Theme Picker and the partial view files will be used when rendering forms.
+
+#### Email Templates
+
+Email templates provided for the send email workflow can be provided in a Razor Class Library similar to the Theme files.
+
+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/fieldtypes/date.md

@@ -4,28 +4,15 @@ The date picker uses a front-end library called [Pikaday](https://github.com/dbu
 
 ![Date picker on frontend](images/date-picker.png)
 
-Pikaday date picker can be localised based on the page the Form is rendered on.
+Pikaday date picker can be localized based on the page the Form is rendered on.
 
 The date picker displays the picked date in the required locale. Using JavaScript, a hidden field is updated with a standard date format to send to the server for storing record submissions. This avoids the locale mixing up the dates.
 
 To achieve localized date, a Razor partial view is included at `/Views/Partials/Forms/Themes/default/DatePicker.cshtml`.
 
 The **DatePicker.cshtml** includes the `moment-with-locales.min.js` library to help with the date locale formatting and the appropriate changes to Pikaday to support the locales. If you wish to use a different DatePicker component, edit the **DatePicker.cshtml** file as per your needs.
 
-## Configure the Year range
+## Configure the date picker
 
-The Date picker has a configuration setting to control the number of years shown in the picker. The default value is 10 years.
+The Date picker has [configuration settings](../../../developer/configuration/README.md#date-picker-field-type-configuration) to control the number of years shown in the picker and the date format.
 
-You can configure the settings in the `appSettings.json` file:
-
-```json
- "Forms": {
-     "FieldTypes": {
-         "DatePicker": {
-             "DatePickerYearRange": 10
-                      }
-                }
-        }
-```
-
-Update `DatePickerYearRange` to a higher number (for example: 100) to increase the numbers of years available in the Date picker.

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/editor/creating-a-form/images/multi-page-forms.png

@@ -17,6 +17,36 @@ 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) **(October 25th 2024)**
+
+##### Multi-step forms
+
+The 13.3 release of Forms contains features that can improve the user experience of completing multi-page forms.
+
+We have 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 be completed. [#281](https://github.com/umbraco/Umbraco.Forms.Issues/issues/281) [#648](https://github.com/umbraco/Umbraco.Forms.Issues/issues/648).
+
+These options are enabled and configured by editors in the Forms settings section on a per-form basis. 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.
+
+##### Ship themes in Razor Class Libraries
+
+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).
+
+##### Date picker field type
+
+We have made a couple of updates to the Date Picker field type. The format for the field can now be provided in configuration [#1276](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1276). And you can now override and localize the aria-label provided for assistive technologies such as screen readers [https://github.com/umbraco/Umbraco.Forms.Issues/issues/1082](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1082).
+
+##### Finer grained entries permissions
+
+To allow finer control over editor permissions, we have introduced a "delete entries" setting for 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
+
+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.
+* Fixed issue where sensitive data flag on a field could not be set for new fields added to a form [#1309](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1309).
+
 #### [**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).

13/umbraco-forms/release-notes.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)