From 486ae0ad0c589653080b6de552df66a002268e32 Mon Sep 17 00:00:00 2001 From: Andy Butland Date: Sun, 26 May 2024 12:47:42 +0200 Subject: [PATCH 01/10] Docs for intial release of Forms 14 --- .../developer/extending/README.md | 2 +- .../developer/extending/README.md | 2 +- .../developer/extending/README.md | 2 +- 14/umbraco-forms/SUMMARY.md | 1 - .../developer/configuration/README.md | 20 +- 14/umbraco-forms/developer/contentapps.md | 98 --------- .../developer/extending/README.md | 2 +- .../developer/extending/adding-a-fieldtype.md | 188 ++++++++++++++---- 14/umbraco-forms/release-notes.md | 71 +------ .../upgrading/version-specific.md | 53 ++--- 10 files changed, 183 insertions(+), 256 deletions(-) delete mode 100644 14/umbraco-forms/developer/contentapps.md diff --git a/10/umbraco-forms/developer/extending/README.md b/10/umbraco-forms/developer/extending/README.md index c19d21a30b2..7ab60b54097 100644 --- a/10/umbraco-forms/developer/extending/README.md +++ b/10/umbraco-forms/developer/extending/README.md @@ -22,7 +22,7 @@ It is possible to add new Field types, Data Source Types, Prevalue Source Types, ### [Field types](adding-a-fieldtype.md) -A field type handles rendering of the UI for a field in a form. It renders a standard ASP.NET webcontrol and is able to return a list of values when the form is saved. +A field type handles rendering of the UI for a field in a form. It renders a standard ASP.NET Razor partial view and is able to return a list of values when the form is saved. The concept of provider settings, common to the field and other types, is also discussed in this section. diff --git a/12/umbraco-forms/developer/extending/README.md b/12/umbraco-forms/developer/extending/README.md index e79166cfa50..635b9fd8f8e 100644 --- a/12/umbraco-forms/developer/extending/README.md +++ b/12/umbraco-forms/developer/extending/README.md @@ -18,7 +18,7 @@ It is possible to add new Field types, Data Source Types, Prevalue Source Types, ### [Field types](adding-a-fieldtype.md) -A field type handles rendering of the UI for a field in a form. It renders a standard ASP.NET webcontrol and is able to return a list of values when the form is saved. +A field type handles rendering of the UI for a field in a form. It renders a standard ASP.NET Razor partial view and is able to return a list of values when the form is saved. The concept of provider settings, common to the field and other types, is also discussed in this section. diff --git a/13/umbraco-forms/developer/extending/README.md b/13/umbraco-forms/developer/extending/README.md index e79166cfa50..635b9fd8f8e 100644 --- a/13/umbraco-forms/developer/extending/README.md +++ b/13/umbraco-forms/developer/extending/README.md @@ -18,7 +18,7 @@ It is possible to add new Field types, Data Source Types, Prevalue Source Types, ### [Field types](adding-a-fieldtype.md) -A field type handles rendering of the UI for a field in a form. It renders a standard ASP.NET webcontrol and is able to return a list of values when the form is saved. +A field type handles rendering of the UI for a field in a form. It renders a standard ASP.NET Razor partial view and is able to return a list of values when the form is saved. The concept of provider settings, common to the field and other types, is also discussed in this section. diff --git a/14/umbraco-forms/SUMMARY.md b/14/umbraco-forms/SUMMARY.md index ec4db5da9d8..4f4f02187de 100644 --- a/14/umbraco-forms/SUMMARY.md +++ b/14/umbraco-forms/SUMMARY.md @@ -62,7 +62,6 @@ * [Apply keys and indexes](developer/healthchecks/apply-keys.md) * [Apply keys and indexes for forms in the database](developer/healthchecks/forms-in-the-database-apply-keys.md) * [Localization](developer/localization.md) -* [Content Apps](developer/contentapps.md) * [Headless/AJAX Forms](developer/ajaxforms.md) * [Block List Filters](developer/blocklistfilters.md) * [Field Types](developer/field-types.md) diff --git a/14/umbraco-forms/developer/configuration/README.md b/14/umbraco-forms/developer/configuration/README.md index f81c03bc45f..bbc5f665be3 100644 --- a/14/umbraco-forms/developer/configuration/README.md +++ b/14/umbraco-forms/developer/configuration/README.md @@ -88,7 +88,7 @@ For illustration purposes, the following structure represents the full set of op "UseSemanticFieldsetRendering": false, "DisableClientSideValidationDependencyCheck": false, "DisableRelationTracking": false, - "TrackRenderedFormsStorageMethod": "TempData" + "TrackRenderedFormsStorageMethod": "HttpContextItems" }, "Security": { "DisallowedFileUploadExtensions": "config,exe,dll,asp,aspx", @@ -119,7 +119,7 @@ For illustration purposes, the following structure represents the full set of op "DataTypeId": "ca90c950-0aff-4e72-b976-a30b1ac57dad" }, "TitleAndDescription": { - "AllowUnsafeHtmlRendering": true + "AllowUnsafeHtmlRendering": false } } } @@ -411,13 +411,9 @@ If you would like to disable this feature, you can set the value of this setting Forms tracks the forms rendered on a page in order that the associated scripts can be placed in a different location within the HTML. Usually this is used to [render the scripts](../rendering-scripts.md)) at the bottom of the page. -By default, `TempData` is used as the storage mechanism for this tracking. +By default, `HttpContext.Items` is used as the storage mechanism for this tracking. -This can cause some issues when applying a Content Delivery Network (CDN) to your website, and as such an alternative is available using `HttpContext.Items`. - -To switch to this storage mechanism change the value of this setting from the default of `TempData` to `HttpContextItems`. - -We expect `HttpContextItems` to be the default option from Forms 14 onwards. +You can optionally revert to the legacy behavior of using `TempData` by changing this setting from the default of `HttpContextItems` to `TempData`. ## Security configuration @@ -517,10 +513,6 @@ Sets the Data Type Guid to use to obtain the configuration for the rich text fie #### AllowUnsafeHtmlRendering -When using the "title and description" field type, editors can provide HTML in the "description" field and have that rendered on the website. - -As a tightened security measure, you can set this value to `false` which will ensure HTML is no longer rendered. - -As some installations may be relying on HTML rendering, to preserve backward compatible behavior the default value of this setting is `true`. +When using the "title and description" field type, if editors provide HTML in the "description" field it will be encoded when rendering on the website. -We expect to make the default value of this option `false` from Forms 14 onwards. \ No newline at end of file +If you understand the risks and want to allow HTML to be displayed, you can set this value to `false`. diff --git a/14/umbraco-forms/developer/contentapps.md b/14/umbraco-forms/developer/contentapps.md deleted file mode 100644 index 520ec67c75a..00000000000 --- a/14/umbraco-forms/developer/contentapps.md +++ /dev/null @@ -1,98 +0,0 @@ -# Content Apps - -[Umbraco Content Apps](https://docs.umbraco.com/umbraco-cms/extending/content-apps) can be configured to appear alongside forms in the Umbraco Forms backoffice section. - -They will appear after the default "Design" and "Settings" apps when editing a form in the backoffice: - -![Umbraco Forms Content App](<../../../10/umbraco-forms/developer/images/content-app (1).png>) - -A content app such as the following would display only in the forms section: - -```csharp - public class TestFormsContentApp : IContentAppFactory - { - public ContentApp GetContentAppFor(object source, IEnumerable userGroups) - { - // Only show app on forms - if (source is FormDesign) - { - return new ContentApp - { - Alias = "testFormsContentApp", - Name = "Test App", - Icon = "icon-calculator", - View = "/App_Plugins/TestFormsContentApp/testformscontentapp.html", - Weight = 0, - }; - } - - return null; - } - } -``` - -Within the `/App_Plugins/TestFormsContentApp/` folder we need the client-side files, for which an example is shown below: - -`package.manifest`: - -```json -{ - "contentApps": [ - { - "name": "Test Forms Content App", - "alias": "TestFormsContentApp", - "weight": 0, - "icon": "icon-calculator", - "view": "~/App_Plugins/TestFormsContentApp/testformscontentapp.html", - "show": [ - "+content/*", - "+media/*", - "+member/*", - "+forms/*" - ] - } - ], - "javascript": [ - "~/App_Plugins/TestFormsContentApp/testformscontentapp.controller.js" - ] -} -``` - -`testformscontentapp.html`: - -```html -
- - - -

Current form: {{vm.formName}}

- - -
-``` - -`testformscontentapp.controller.js`: - -```js -angular.module("umbraco") - .controller("My.TestFormsContentApp", function ($routeParams, formResource) { - var vm = this; - formResource.getWithWorkflowsByGuid($routeParams.id) - .then(function (response) { - vm.formName = response.data.name; - }); - }); -``` - -Finally, it needs to be registered via a composer: - -```csharp - public class TestSiteComposer : IComposer - { - public void Compose(IUmbracoBuilder builder) - { - builder.ContentApps().Append(); - } - } -} -``` diff --git a/14/umbraco-forms/developer/extending/README.md b/14/umbraco-forms/developer/extending/README.md index e79166cfa50..635b9fd8f8e 100644 --- a/14/umbraco-forms/developer/extending/README.md +++ b/14/umbraco-forms/developer/extending/README.md @@ -18,7 +18,7 @@ It is possible to add new Field types, Data Source Types, Prevalue Source Types, ### [Field types](adding-a-fieldtype.md) -A field type handles rendering of the UI for a field in a form. It renders a standard ASP.NET webcontrol and is able to return a list of values when the form is saved. +A field type handles rendering of the UI for a field in a form. It renders a standard ASP.NET Razor partial view and is able to return a list of values when the form is saved. The concept of provider settings, common to the field and other types, is also discussed in this section. diff --git a/14/umbraco-forms/developer/extending/adding-a-fieldtype.md b/14/umbraco-forms/developer/extending/adding-a-fieldtype.md index 424abd7abb1..3e0555f99ee 100644 --- a/14/umbraco-forms/developer/extending/adding-a-fieldtype.md +++ b/14/umbraco-forms/developer/extending/adding-a-fieldtype.md @@ -29,6 +29,8 @@ namespace MyFormsExtensions SortOrder = 10; SupportsRegex = true; FieldTypeViewName = "FieldType.MyCustomField.cshtml"; + EditView = "Umb.PropertyEditorUi.TextBox"; + PreviewView = "Forms.FieldPreview.TextBox"; } // You can do custom validation in here which will occur when the form is submitted. @@ -63,6 +65,8 @@ In the constructor, or via overridden properties, we can specify details of the - `SupportsRegex` - indicates whether pattern based validation using regular expressions can be used with the field (defaults to `false`). - `SupportsPreValues` - indicates whether prevalues are supported by the field (defaults to `false`). - `FieldTypeViewName` - indicates the name of the partial view used to render the field. +- `EditView` - indicates the name of a property editor UI that is used for editing the field in the backoffice. If nothing is provided, the built-in label will be used and the field won't be editable. +- `PreviewView` - indicates the name of a manifest registered client-side resource that is used for previewing the field in the backoffice. If nothing is provided, the name of the field type will be used as the preview. - `RenderInputType`- indicates how the field should be rendered within the theme, as defined with the `RenderInputType` enum. The default is `Single` for a single input field. `Multiple` should be used for multiple input fields such as checkbox lists. `Custom` is used for fields without visible input fields. You will then need to register this new field as a dependency. @@ -106,27 +110,61 @@ 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. -## Umbraco backoffice view +## Umbraco backoffice components -The final step involves building the HTML view which will be rendered in Umbraco as an example of how our end result will look: +Two aspects of the presentation and functionality of the custom field are handled by client-side components, registered via manifests: -```html - -``` +- The preview, displayed on the form definition editor. +- The property editor UI used for editing the the submitted values via the backoffice. -In the HTML you can access settings via `field.settings`, e.g. `{{field.settings.Caption}}` to render a "Caption" setting. It is also possible to access prevalues via `field.parsedPreValues`. +These are referenced server-side using the `PreviewView` and `EditView` respectively. -For built-in field types, Umbraco Forms look for this file in the virtual folder: `App_Plugins\UmbracoForms\backoffice\Common\FieldTypes\`. It will expect to find a file with a name matching the class's name, i.e. `mycustomfield.html`. To add custom fields and themes, **create a folder at the specified path** (also known as the virtual folder). This is because the client-side code is included in the Razor Class Library. As a result, these files are available as if they're stored at a specific location on disk. +For the edit view, you can use a built-in property editor UI, one from a package, or a custom one registered with your solution. -To store in a different location, you can apply the following override to the custom field type's C# representation: +To help with creating your own preview element, the following example shows the built-in text field preview: -```csharp -public override string GetDesignView() => - "~/App_Plugins/UmbracoFormsCustomFields/backoffice/Common/FieldTypes/mycustomfield.html"; +```javascript +import { + html, + customElement, + property, +} from "@umbraco-cms/backoffice/external/lit"; + +const elementName = "forms-field-preview-text-box" +@customElement(elementName) +export class FormsFieldPreviewTextBox extends UmbLitElement { + + @property() + settings: Record = {} + + #getSettingValue(alias: string) : string { + return this.settings[alias]; + } + + render() { + return html``; + } +} + +export default FormsFieldPreviewTextBox; + +declare global { + interface HTMLElementTagNameMap { + [elementName]: FormsFieldPreviewTextBox; + } +} +``` + +It's registered using a manifest as follows: + +```javascript +export const manifest: ManifestFormsFieldPreview = + { + type: "formsFieldPreview", + alias: "Forms.FieldPreview.TextBox", + name: "Text Box Field Preview", + element: () => import('./text-box-field-preview.element.js'), + }; ``` ## Field settings @@ -134,7 +172,7 @@ public override string GetDesignView() => Field settings that will be managed in the backoffice by editors creating forms using the custom field type can be added to the C# class as properties with a `Setting` attribute: ```csharp -[Setting("My Setting", Description = "Help text for the setting", View = "TextField", SupportsPlaceholders = "true", DisplayOrder = 10)] +[Setting("My Setting", Description = "Help text for the setting", View = "Umb.PropertyEditorUi.TextBox", SupportsPlaceholders = "true", DisplayOrder = 10)] public virtual string MySetting { get; set; } ``` @@ -155,19 +193,105 @@ The area aliases for the other provider types are as follows: - Recordset actions - `formRecordSetActions` - Workflows - `formProviderWorkflows` -The `View` attribute defines the client-side view used when rendering a preview of the field in the form's designer. Umbraco Forms ships with a number of these, found in a virtual path of `App_Plugins\UmbracoForms\backoffice\Common\SettingTypes\`. +The `View` property indicates a property editor UI used for editing the setting value. You can use a built-in property editor UI, one from a package, or a custom one registered with your solution. The default value if not provided is `Umb.PropertyEditorUi.TextBox`, which will use the standard Umbraco text box property editor UI. + +You may optionally want to register a settings value converter. This is a client-side, manifest registered component, that converts between the setting value required for the editor and that persisted with the form definition. A converter defines three methods: -Again though, you can use your own location, and configure with a full path to the view, e.g.: +- `getSettingValueForEditor` - converts the persisted string value into one suitable for the editor +- `getSettingValueForPersistence` - converts the editor value into the string needed for persistence +- `getSettingPropertyConfig` - creates the configuration needed for the property editor -To reference the file the setting should be configured with a full path to the view, e.g.: +As an example, the following code shows how the built-in slider setting element used for selecting a number within a range for the reCAPTCHA field is defined. ```csharp -[Setting("My Setting", - Description = "Help text for the setting", - View = "~/App_Plugins/UmbracoFormsCustomFields/backoffice/Common/SettingTypes/mycustomsettingfield.html", - SupportsPlaceholders = "true" +[Setting( + "Score threshold", + Description = "A reCAPTCHA v3 determined score between 0 and 10, above which form submissions are accepted. A higher value will catch more spam submissions, but also increase the risk of rejections of valid entries. For most sites, 5 is a sensible choice.", + View = "Umb.PropertyEditorUi.Slider", + PreValues = "0.0,1.0,0.1,0.5", DisplayOrder = 10)] -public virtual string MySetting { get; set; } +public virtual string ScoreThreshold { get; set; } = string.Empty; +``` + +```javascript +import { UmbPropertyValueData } from "@umbraco-cms/backoffice/property"; +import { FormsSettingValueConverterApi } from "./manifests"; +import { Setting } from "@umbraco-forms/generated"; +import { UmbPropertyEditorConfig } from "@umbraco-cms/backoffice/property-editor"; + +export class FormsSliderSettingValueConverter implements FormsSettingValueConverterApi { + getSettingValueForEditor(setting: Setting, alias: string, value: string) { + // Multiply by 10 to get the integer value we need for the editor. + const editorValue = Math.trunc(parseFloat(value) * 10); + return { from: editorValue, to: editorValue }; + } + + getSettingValueForPersistence(valueData: UmbPropertyValueData) { + // Divide by 10 to get the 0.0 to 1.0 range we actually want. + return ((valueData.value ? parseInt(valueData.value["from"]) : 5) / 10).toFixed(1); + } + + async getSettingPropertyConfig(setting: Setting, alias: string, values: UmbPropertyValueData[]) { + const config: UmbPropertyEditorConfig = []; + + // Min, max, step and default are provided in prevalues. + // As the slider only supports integers, we have to multiply by 10 for the UI and then divide again when we save. + config.push({ + alias: "enableRange", + value: false, + }); + + const settingValue = values.find(s => s.alias === alias)?.value?.toString() || ""; + + if (setting.prevalues.length >= 1) { + config.push({ + alias: "minVal", + value: parseFloat(setting.prevalues[0]) * 10, + }); + if (setting.prevalues.length >= 2) { + config.push({ + alias: "maxVal", + value: parseFloat(setting.prevalues[1]) * 10, + }); + if (setting.prevalues.length >= 3) { + config.push({ + alias: "step", + value: parseFloat(setting.prevalues[2]) * 10, + }); + if (setting.prevalues.length >= 3 && settingValue.length === 0) { + config.push({ + alias: "initVal1", + value: parseFloat(setting.prevalues[3]) * 10, + }); + } else { + config.push({ + alias: "initVal1", + value: parseFloat(settingValue), + }); + } + } + } + } + + return Promise.resolve(config); + } + + destroy() { + } +} +``` + +It's registered using a manifest as follows. Note that we provide the `propertyEditorUiAlias` to associated the converter with the appropriate property editor UI. + +```javascript +export const manifest: ManifestFormsSettingValueConverterPreview = + { + type: "formsSettingValueConverter", + alias: "Forms.SettingValueConverter.Slider", + name: "Number Slider Value Converter", + propertyEditorUiAlias: "Umb.PropertyEditorUi.Slider", + api: FormsSliderSettingValueConverter, + }; ``` `SupportsPlaceholders` is a flag indicating whether the setting can contain ["magic string" placeholders](../magic-strings.md) and controls whether they are parsed on rendering. @@ -183,7 +307,7 @@ When creating a field or other provider type, you might choose to inherit from a All setting properties for the Forms provider types are marked as `virtual`, so you can override them and change the setting values: ```csharp -[Setting("My Setting", Description = "My custom help text for the setting", View = "TextField", SupportsPlaceholders = "true", DisplayOrder = 10)] +[Setting("My Setting", Description = "My custom help text for the setting", View = "Umb.PropertyEditorUi.TextBox", SupportsPlaceholders = "true", DisplayOrder = 10)] public override string MySetting { get; set; } ``` @@ -193,17 +317,3 @@ If you want to hide a setting in your derived class you can use the `IsHidden` p [Setting("My Setting", IsHidden = true)] public override string MySetting { get; set; } ``` - -## Backoffice entry rendering - -The third and final client-side view file used for settings is in the rendering of the submitted values for the field in the "Entries" section of the backoffice. - -These are defined by the `RenderView` property of a field type and are found in `App_Plugins\UmbracoForms\backoffice\Common\RenderTypes\`. - -As for the other files, if you require a custom render type view, it's better to host them in a different location, such as `App_Plugins\UmbracoFormsCustomFields\backoffice\Common\RenderTypes\mycustomrenderfield.html`. - -To reference the file you should override the `RenderView` property, e.g.: - -```csharp -public override string RenderView => "~/App_Plugins/UmbracoFormsCustomFields/backoffice/Common/RenderTypes/mycustomrenderfield.html"; -``` diff --git a/14/umbraco-forms/release-notes.md b/14/umbraco-forms/release-notes.md index 12ec8ae0a6e..39376ec2602 100644 --- a/14/umbraco-forms/release-notes.md +++ b/14/umbraco-forms/release-notes.md @@ -15,77 +15,18 @@ If you are upgrading to a new major version, you can find information about the ## Release History -This section contains the release notes for Umbraco Forms 13 including all changes for this version. +This section contains the release notes for Umbraco Forms 14 including all changes for this version. -#### [**13.1.2**](https://github.com/umbraco/Umbraco.Forms.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F12.2.4) **(April 16th 2024)** +#### [**14.0.0**](https://github.com/umbraco/Umbraco.Forms.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F14.0.0) **(May 30th 2024)** -* Corrected alignment of label `for` and input `id` attributes in the date picker field [#1200](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1200). -* Corrected permission check such that users with only "view entries" permissions can see form details on the dashboard [#1192](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1192). -* Used `requestSubmit` when submitting forms [#1199](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1199). -* Tightened path check used in middleware for restriction of access to form file uploads. - -#### [**13.1.1**](https://github.com/umbraco/Umbraco.Forms.Issues/issues?q=label%3Arelease%2F13.1.1+is%3Aclosed) **(March 22nd 2024)** - -* Fixes regression issue with form validation where two forms are rendered on a single page [#1189](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1189). - -#### [**13.1.0**](https://github.com/umbraco/Umbraco.Forms.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F13.1.0) **(March 19th 2024)** - -With the introduction of webhooks in Umbraco 13, we've made an update to Forms to allow workflow execution events to trigger webhooks. Workflows are operations that you can associate with form submission, approval, or rejection actions. You can use these where you need to notify external systems of the success or failure of a workflow. Read more on [Umbraco Forms Webhooks](./developer/webhooks.md). - -We've added an update that will help customers using Forms within locked down production environments. - -And there are a couple of further additions to improve the performance and accessibility of the product. - -**Features implemented and issues resolved in 13.1.0** - -* Added webhooks for workflow execution events [#1151](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1151). -* Added support for a proxied request when using reCAPTCHA 3 [#1159](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1159). -* Added a configurable option to ensure accessibility requirements with regard to fieldsets are adhered to [#1163](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1163). - * Read more about this configuration setting [here](./developer/configuration/README.md#mandatoryfieldsetlegends). -* Added a cachebuster querystring based on the current product version to rendered script dependencies [#773](https://github.com/umbraco/Umbraco.Forms.Issues/issues/773). -* Ensured that client-side conditions logic correctly implements "is" with multiple values, such that the condition passes if one and only one matching value is found [#1173](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1173). -* Fixed closing of theme picker dialog [#1174](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1174). -* Fixed rendering of translated dictionary items used for form captions [#1175](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1175). -* Applied multiple click protection for form submissions for installations using the aspnet-validation library [#1182](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1182). - -#### [**13.0.2**](https://github.com/umbraco/Umbraco.Forms.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F13.0.2) **(February 20th 2024)** - -* Ensured UI for the upload of a text file for a prevalue source only allows the selection of expected .txt files. -* Handled potential null value for prevalues for a form definition following an upgrade [#1157](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1157) -* Fixed handling of API and traditional form posts in reCAPTCHA 3 checks [#1150](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1150) -* Fixed display of validation error when a duplicate form field alias is created [#1152](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1152) -* Fixed issue where file uploads weren't removed as records were deleted. -* Updated Microsoft.Data.SqlClient dependency due to reported security advisory. - -#### [**13.0.1**](https://github.com/umbraco/Umbraco.Forms.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F13.0.1) **(January 16th 2024)** - -* Added configuration value `TitleAndDescription:AllowUnsafeHtmlRendering` to allow tighter security for HTML rendering of text entered in the "Title and description" field type. - * See further details on the [configuration page](./developer/configuration/README.md#AllowUnsafeHtmlRendering). -* Rendered dictionary translations of field captions in backoffice entries view [#1131](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1131). -* Ensured valid format string before rendering validation methods with placeholders [#1132](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1132). -* Ensured the creation of the forms to content relation type is idempotent and created with consistent GUID [#1137](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1137). -* Ensured Examine re-index user interface completes when no records are available for indexing [#1137](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1137). -* Fixed issue where use of a custom field HTML ID attribute prefix breaks conditional logic in multi-page forms [#1138](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1138). -* Added support for record based magic string replacement in the post-submission message [#1133](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1133). -* Tightens up the null checks when reading form definition JSON for prevalue captions [#1140](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1140). -* Added configuration value `DisableRelationTracking` to allow relation tracking between forms and content to be disabled. - * See further details on the [configuration page](./developer/configuration/README.md#DisableRelationTracking). -* Added configuration value `TrackRenderedFormsStorageMethod` to allow use of `HttpContext.Items` over `TempData` when tracking rendered forms [#1144](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1144). - * See further details on the [configuration page](./developer/configuration/README.md#TrackRenderedFormsStorageMethod) and the [rendering scripts page](./developer//rendering-scripts.md). -* Resolved an out of range exception when a condition hides all fields on the final page of a multi-page form. -* Fixed issue with swapping between plain and rich text when configuring the post-submission message [#1145](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1145). - -#### [**13.0.0**](https://github.com/umbraco/Umbraco.Forms.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F13.0.0) **(December 14th 2023)** - -* Compatibility with Umbraco 13 - * See full details of breaking changes under the [version specific upgrade guide](upgrading/version-specific.md#version-13). -* Ran registered server-side file validators on file uploads. +* Compatibility with Umbraco 14 + * See full details of breaking changes under the [version specific upgrade guide](upgrading/version-specific.md). ## Umbraco.Forms.Deploy -#### [13.0.1] (March 19th 2024) +#### **14.0.0** **(May 30th 2024)** -* Added migrator to support changes in Form field prevalues when importing from older Umbraco versions +* Compatibility with Umbraco 13, Forms 13 and Deploy 13. ## Legacy release notes diff --git a/14/umbraco-forms/upgrading/version-specific.md b/14/umbraco-forms/upgrading/version-specific.md index be13ec112d8..a89bb9d89e1 100644 --- a/14/umbraco-forms/upgrading/version-specific.md +++ b/14/umbraco-forms/upgrading/version-specific.md @@ -5,7 +5,7 @@ description: >- # Version Specific Upgrade Notes -This page covers specific upgrade documentation for when migrating to major 13 of Umbraco Forms. +This page covers specific upgrade documentation for when migrating to major 14 of Umbraco Forms. {% hint style="info" %} If you are upgrading to a new minor or patch version, you can find information about the breaking changes in the [Release Notes](../release-notes.md) article. @@ -13,54 +13,37 @@ If you are upgrading to a new minor or patch version, you can find information a ## Version Specific Upgrade Notes History -Version 13 of Umbraco Forms has a minimum dependency on Umbraco CMS core of `13.0.0`. It runs on .NET 8. - -Deploy add-on for Umbraco Forms has been renamed from `Umbraco.Deploy.Forms` to `Umbraco.Forms.Deploy`. +Version 14 of Umbraco Forms has a minimum dependency on Umbraco CMS core of `14.0.0`. It runs on .NET 8. #### **Breaking changes** -Version 13 contains a number of breaking changes. If you do run into any, they should be straightforward to adjust and recompile. - -For reference, the full details are listed here: +Version 14 contains a number of breaking changes, primarily due to the new backoffice introduced in Umbraco 14. The details are listed here: #### **Behavior** -* The configuration option `UseSemanticFieldsetRendering` was removed and considered as `true`. This means the improved, semantic fieldset rendering is now used in the default theme for all installations. -* The `ExecuteWorkflowAsync` configuration option was removed. +* A new management API has been introduced at `umbraco/forms/management/api`. +* The root of the existing delivery API used for headless/AJAX solutions has moved to `umbraco/forms/delivery/api`. +* The HTML helper `RenderUmbracoFormDependencies` no longer renders the promises polyfill, which isn't needed in modern browsers. +* Server-side registration of content apps has been removed as this is now a client-side concern. +* Creation of custom field, workflow and other provider types remains primarily a server-side task. However they no longer require the provision of angularjs views and controllers. Instead these reference registered client-side manifests. Read more on this under [extending Umbraco Forms](../developer/extending/README.md). + +#### **Configuration** + +* The setting `FieldSettings:TitleAndDescription:AllowUnsafeHtmlRendering` has a new default of `false`. +* The setting `PageOptions:TrackRenderedFormsStorageMethod` has a new default of `HttpContextItems`. #### **Dependencies** -* Umbraco CMS dependency was updated to `13.0.0`. +* Umbraco CMS dependency was updated to `14.0.0`. #### **Code** The following updates describe the more significant changes to the codebase and public API: -* Amended `IWorkflowExecutionService`, `IRecordService`, `IRecordSetActionType` and `IWorkflowType` methods related to workflow execution to be asynchronous. These methods now have an `Async` suffix and will return a awaitable `Task`. -* An overload for the HTML helper `RenderUmbracoFormDependencies` that internally required service location was removed. It should now be called providing the parameter for an `IUrlHelper`, with `@Html.RenderUmbracoFormDependencies(Url)`. - -These updates are more minor. We don't expect many projects to be affected by them as they are in areas that are not typical extension points: - -* `DataSourceCacheRefresher` was made internal. -* `HideField` was removed from `FieldType` and `IFieldType`. `RenderInputType` with a value of `RenderInputType.Hidden` can be used here instead. -* The default implementation for the `Exists` method previously added to `IBaseService` was removed. -* The obsolete overload for method `AddDataConsentField` on `FieldsetContainerExtensions` was removed. -* The method `CanUserViewEntries` was added to the `IFormsSecurity` interface. -* The static methods `TryCreateAttachment`, `TrackAttachmentFileStream` and `DisposeAttachmentFileStreams` on `BaseEmailWorkflowType` were removed (instance methods are available to use instead). -* The obsolete constructor on the `SaveAsFile` workflow type was removed. -* The obsolete overload for method `TransformXML` on `XsltHelper` was removed. -* The obsolete overloads for method `ValidateField` on `FieldType` were removed. -* The obsolete overload for method `GetFormSecurityByUserId` on `FormSecurityControllerBase` was removed. -* The `PopulatePageElements` method was added to the `IFormRenderingService` interface. -* The `Setting` class was renamed to `SettingAttribute`. -* `PreValueFileController` has a changed constructor. -* `FileUpload` has a changed constructor. -* `ExecuteWorkflowsWithResult` on `IWorkflowExecutionService` was renamed to `ExecuteWorkflows` and the void method with that name was removed. -* The string constants used to define GUIDs for each provider type were made consistently upper-case. -* `FileUpload` and `PreValueFileController` have changed constructors to add support for server-side file validation. -* HTML helpers such as `RenderFormsScripts` now return `IHtmlContent`. -* The constructor for workflow notifications was amended to add a parameter for the current `Record`. -* The `IType` interface now defines a `Created` property. +* All controllers relating to backoffice trees and editors have been removed and their functionality replaced by the management API. +* The serialization library has been changed from `Newtonsoft.Json` to `System.Text.Json`. Among other updates this involved removing the public class `FormsJsonSerializerSettings` and replacing it with `FormsJsonSerializerOptions`. +* The obsolete methods `GetFieldsNotDisplayed` and `Build` on `FormViewModel` have been removed. +* The unused `RetryWorkflow` class has been removed. ## Legacy version specific upgrade notes From 40d7cd6a0be0f304f5afabe83082213e20ba4661 Mon Sep 17 00:00:00 2001 From: Andy Butland Date: Sun, 26 May 2024 13:40:57 +0200 Subject: [PATCH 02/10] Linting --- 14/umbraco-forms/developer/extending/adding-a-fieldtype.md | 6 +++--- 14/umbraco-forms/upgrading/version-specific.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/14/umbraco-forms/developer/extending/adding-a-fieldtype.md b/14/umbraco-forms/developer/extending/adding-a-fieldtype.md index 3e0555f99ee..ec42451727c 100644 --- a/14/umbraco-forms/developer/extending/adding-a-fieldtype.md +++ b/14/umbraco-forms/developer/extending/adding-a-fieldtype.md @@ -195,13 +195,13 @@ The area aliases for the other provider types are as follows: The `View` property indicates a property editor UI used for editing the setting value. You can use a built-in property editor UI, one from a package, or a custom one registered with your solution. The default value if not provided is `Umb.PropertyEditorUi.TextBox`, which will use the standard Umbraco text box property editor UI. -You may optionally want to register a settings value converter. This is a client-side, manifest registered component, that converts between the setting value required for the editor and that persisted with the form definition. A converter defines three methods: +You may optionally want to register a settings value converter. This is a client-side, manifest registered component, that converts between the setting value required for the editor and that persisted with the form definition. A converter defines three methods: - `getSettingValueForEditor` - converts the persisted string value into one suitable for the editor - `getSettingValueForPersistence` - converts the editor value into the string needed for persistence - `getSettingPropertyConfig` - creates the configuration needed for the property editor -As an example, the following code shows how the built-in slider setting element used for selecting a number within a range for the reCAPTCHA field is defined. +The following code shows how the built-in slider setting element used for selecting a number within a range for the reCAPTCHA field is defined. ```csharp [Setting( @@ -281,7 +281,7 @@ export class FormsSliderSettingValueConverter implements FormsSettingValueConver } ``` -It's registered using a manifest as follows. Note that we provide the `propertyEditorUiAlias` to associated the converter with the appropriate property editor UI. +It's registered using a manifest as follows. We provide the `propertyEditorUiAlias` to associated the converter with the appropriate property editor UI. ```javascript export const manifest: ManifestFormsSettingValueConverterPreview = diff --git a/14/umbraco-forms/upgrading/version-specific.md b/14/umbraco-forms/upgrading/version-specific.md index a89bb9d89e1..cbf67dec759 100644 --- a/14/umbraco-forms/upgrading/version-specific.md +++ b/14/umbraco-forms/upgrading/version-specific.md @@ -25,7 +25,7 @@ Version 14 contains a number of breaking changes, primarily due to the new backo * The root of the existing delivery API used for headless/AJAX solutions has moved to `umbraco/forms/delivery/api`. * The HTML helper `RenderUmbracoFormDependencies` no longer renders the promises polyfill, which isn't needed in modern browsers. * Server-side registration of content apps has been removed as this is now a client-side concern. -* Creation of custom field, workflow and other provider types remains primarily a server-side task. However they no longer require the provision of angularjs views and controllers. Instead these reference registered client-side manifests. Read more on this under [extending Umbraco Forms](../developer/extending/README.md). +* Creation of custom field, workflow and other provider types remains primarily a server-side task. However they no longer require the provision of AngularJS views and controllers. Instead these reference registered client-side manifests. Read more on this under [extending Umbraco Forms](../developer/extending/README.md). #### **Configuration** From 60f6255e516dc709c7e3c62e59b1afb957a22018 Mon Sep 17 00:00:00 2001 From: Andy Butland Date: Mon, 27 May 2024 08:29:57 +0200 Subject: [PATCH 03/10] Added replacement for XPath node selection --- 14/umbraco-forms/upgrading/version-specific.md | 1 + 1 file changed, 1 insertion(+) diff --git a/14/umbraco-forms/upgrading/version-specific.md b/14/umbraco-forms/upgrading/version-specific.md index cbf67dec759..f67ce411b4a 100644 --- a/14/umbraco-forms/upgrading/version-specific.md +++ b/14/umbraco-forms/upgrading/version-specific.md @@ -26,6 +26,7 @@ Version 14 contains a number of breaking changes, primarily due to the new backo * The HTML helper `RenderUmbracoFormDependencies` no longer renders the promises polyfill, which isn't needed in modern browsers. * Server-side registration of content apps has been removed as this is now a client-side concern. * Creation of custom field, workflow and other provider types remains primarily a server-side task. However they no longer require the provision of AngularJS views and controllers. Instead these reference registered client-side manifests. Read more on this under [extending Umbraco Forms](../developer/extending/README.md). +* With the removal of node selection by XPath support in Umbraco 14, the "Save as Umbraco node" workflow now uses [dynamic root](https://docs.umbraco.com/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/multinode-treepicker). #### **Configuration** From 9ea30fc67c5d20714c0b86381b242e999d53c4f9 Mon Sep 17 00:00:00 2001 From: Andy Butland Date: Mon, 27 May 2024 10:44:33 +0200 Subject: [PATCH 04/10] Updated code sample --- .../developer/extending/adding-a-fieldtype.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/14/umbraco-forms/developer/extending/adding-a-fieldtype.md b/14/umbraco-forms/developer/extending/adding-a-fieldtype.md index ec42451727c..a328d76b7b8 100644 --- a/14/umbraco-forms/developer/extending/adding-a-fieldtype.md +++ b/14/umbraco-forms/developer/extending/adding-a-fieldtype.md @@ -220,15 +220,15 @@ import { Setting } from "@umbraco-forms/generated"; import { UmbPropertyEditorConfig } from "@umbraco-cms/backoffice/property-editor"; export class FormsSliderSettingValueConverter implements FormsSettingValueConverterApi { - getSettingValueForEditor(setting: Setting, alias: string, value: string) { + async getSettingValueForEditor(setting: Setting, alias: string, value: string) { // Multiply by 10 to get the integer value we need for the editor. const editorValue = Math.trunc(parseFloat(value) * 10); - return { from: editorValue, to: editorValue }; + return Promise.resolve({ from: editorValue, to: editorValue }); } - getSettingValueForPersistence(valueData: UmbPropertyValueData) { + async getSettingValueForPersistence(setting: Setting, valueData: UmbPropertyValueData) { // Divide by 10 to get the 0.0 to 1.0 range we actually want. - return ((valueData.value ? parseInt(valueData.value["from"]) : 5) / 10).toFixed(1); + return Promise.resolve(((valueData.value ? parseInt(valueData.value["from"]) : 5) / 10).toFixed(1)); } async getSettingPropertyConfig(setting: Setting, alias: string, values: UmbPropertyValueData[]) { From 42fc84721b38605644b17e49d5c56e8972917dac Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Mon, 27 May 2024 11:31:07 +0200 Subject: [PATCH 05/10] Update 14/umbraco-forms/release-notes.md --- 14/umbraco-forms/release-notes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/14/umbraco-forms/release-notes.md b/14/umbraco-forms/release-notes.md index 39376ec2602..d0c441339ed 100644 --- a/14/umbraco-forms/release-notes.md +++ b/14/umbraco-forms/release-notes.md @@ -20,7 +20,7 @@ This section contains the release notes for Umbraco Forms 14 including all chang #### [**14.0.0**](https://github.com/umbraco/Umbraco.Forms.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F14.0.0) **(May 30th 2024)** * Compatibility with Umbraco 14 - * See full details of breaking changes under the [version specific upgrade guide](upgrading/version-specific.md). + * See full details of breaking changes under the [Version-specific Upgrade Guide](upgrading/version-specific.md). ## Umbraco.Forms.Deploy From 0418579178950b1369c7bf5e1b67af0fbde8448f Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Mon, 27 May 2024 11:31:19 +0200 Subject: [PATCH 06/10] Update 14/umbraco-forms/release-notes.md --- 14/umbraco-forms/release-notes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/14/umbraco-forms/release-notes.md b/14/umbraco-forms/release-notes.md index d0c441339ed..61f9ef0a743 100644 --- a/14/umbraco-forms/release-notes.md +++ b/14/umbraco-forms/release-notes.md @@ -26,7 +26,7 @@ This section contains the release notes for Umbraco Forms 14 including all chang #### **14.0.0** **(May 30th 2024)** -* Compatibility with Umbraco 13, Forms 13 and Deploy 13. +* Compatibility with Umbraco 13, Forms 13, and Deploy 13. ## Legacy release notes From ff31b9623c0fd09061208f8fede3c90ca89f0ac6 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Mon, 27 May 2024 11:31:30 +0200 Subject: [PATCH 07/10] Update 14/umbraco-forms/upgrading/version-specific.md --- 14/umbraco-forms/upgrading/version-specific.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/14/umbraco-forms/upgrading/version-specific.md b/14/umbraco-forms/upgrading/version-specific.md index f67ce411b4a..9bf0b878713 100644 --- a/14/umbraco-forms/upgrading/version-specific.md +++ b/14/umbraco-forms/upgrading/version-specific.md @@ -5,7 +5,7 @@ description: >- # Version Specific Upgrade Notes -This page covers specific upgrade documentation for when migrating to major 14 of Umbraco Forms. +This page provides specific upgrade documentation for migrating to Umbraco Forms version 14. {% hint style="info" %} If you are upgrading to a new minor or patch version, you can find information about the breaking changes in the [Release Notes](../release-notes.md) article. From 81728e0ace940bca0a18162c64977a88c449727a Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Mon, 27 May 2024 11:31:41 +0200 Subject: [PATCH 08/10] Update 14/umbraco-forms/upgrading/version-specific.md --- 14/umbraco-forms/upgrading/version-specific.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/14/umbraco-forms/upgrading/version-specific.md b/14/umbraco-forms/upgrading/version-specific.md index 9bf0b878713..9450b4ea93b 100644 --- a/14/umbraco-forms/upgrading/version-specific.md +++ b/14/umbraco-forms/upgrading/version-specific.md @@ -23,7 +23,7 @@ Version 14 contains a number of breaking changes, primarily due to the new backo * A new management API has been introduced at `umbraco/forms/management/api`. * The root of the existing delivery API used for headless/AJAX solutions has moved to `umbraco/forms/delivery/api`. -* The HTML helper `RenderUmbracoFormDependencies` no longer renders the promises polyfill, which isn't needed in modern browsers. +* The HTML helper `RenderUmbracoFormDependencies` no longer renders the promises polyfill, which is not needed in modern browsers. * Server-side registration of content apps has been removed as this is now a client-side concern. * Creation of custom field, workflow and other provider types remains primarily a server-side task. However they no longer require the provision of AngularJS views and controllers. Instead these reference registered client-side manifests. Read more on this under [extending Umbraco Forms](../developer/extending/README.md). * With the removal of node selection by XPath support in Umbraco 14, the "Save as Umbraco node" workflow now uses [dynamic root](https://docs.umbraco.com/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/multinode-treepicker). From 2ab6efa7d5984d2605dc5881e8e0f05a71ad4521 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Mon, 27 May 2024 11:31:55 +0200 Subject: [PATCH 09/10] Update 14/umbraco-forms/upgrading/version-specific.md --- 14/umbraco-forms/upgrading/version-specific.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/14/umbraco-forms/upgrading/version-specific.md b/14/umbraco-forms/upgrading/version-specific.md index 9450b4ea93b..b8f85f8c7ee 100644 --- a/14/umbraco-forms/upgrading/version-specific.md +++ b/14/umbraco-forms/upgrading/version-specific.md @@ -25,7 +25,7 @@ Version 14 contains a number of breaking changes, primarily due to the new backo * The root of the existing delivery API used for headless/AJAX solutions has moved to `umbraco/forms/delivery/api`. * The HTML helper `RenderUmbracoFormDependencies` no longer renders the promises polyfill, which is not needed in modern browsers. * Server-side registration of content apps has been removed as this is now a client-side concern. -* Creation of custom field, workflow and other provider types remains primarily a server-side task. However they no longer require the provision of AngularJS views and controllers. Instead these reference registered client-side manifests. Read more on this under [extending Umbraco Forms](../developer/extending/README.md). +* Creation of custom fields, workflow, and other provider types remains primarily a server-side task. However, they no longer require the provision of AngularJS views and controllers. Instead, these reference registered client-side manifests. For more information, see the [extending Umbraco Forms](../developer/extending/README.md) article. * With the removal of node selection by XPath support in Umbraco 14, the "Save as Umbraco node" workflow now uses [dynamic root](https://docs.umbraco.com/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/multinode-treepicker). #### **Configuration** From f0040cd27cceef67d8764a27145562c5c764638d Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Mon, 27 May 2024 12:21:26 +0200 Subject: [PATCH 10/10] Update 14/umbraco-forms/developer/extending/adding-a-fieldtype.md --- 14/umbraco-forms/developer/extending/adding-a-fieldtype.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/14/umbraco-forms/developer/extending/adding-a-fieldtype.md b/14/umbraco-forms/developer/extending/adding-a-fieldtype.md index a328d76b7b8..619be0a5bca 100644 --- a/14/umbraco-forms/developer/extending/adding-a-fieldtype.md +++ b/14/umbraco-forms/developer/extending/adding-a-fieldtype.md @@ -195,7 +195,7 @@ The area aliases for the other provider types are as follows: The `View` property indicates a property editor UI used for editing the setting value. You can use a built-in property editor UI, one from a package, or a custom one registered with your solution. The default value if not provided is `Umb.PropertyEditorUi.TextBox`, which will use the standard Umbraco text box property editor UI. -You may optionally want to register a settings value converter. This is a client-side, manifest registered component, that converts between the setting value required for the editor and that persisted with the form definition. A converter defines three methods: +You may want to consider registering a settings value converter. This is a client-side component that is registered in a manifest. It converts between the setting value required for the editor and the value persisted with the form definition. A converter defines three methods: - `getSettingValueForEditor` - converts the persisted string value into one suitable for the editor - `getSettingValueForPersistence` - converts the editor value into the string needed for persistence