diff --git a/10/umbraco-forms/developer/extending/adding-a-fieldtype.md b/10/umbraco-forms/developer/extending/adding-a-fieldtype.md index a16af90542d..553ca10705d 100644 --- a/10/umbraco-forms/developer/extending/adding-a-fieldtype.md +++ b/10/umbraco-forms/developer/extending/adding-a-fieldtype.md @@ -166,7 +166,7 @@ To reference the file the setting should be configured with a full path to the v [Setting("My Setting", Description = "Help text for the setting", View = "~/App_Plugins/UmbracoFormsCustomFields/backoffice/Common/SettingTypes/mycustomsettingfield.html", - SupportsPlaceholders = "true" + SupportsPlaceholders = true DisplayOrder = 10)] public string MySetting { get; set; } ``` diff --git a/10/umbraco-forms/developer/themes.md b/10/umbraco-forms/developer/themes.md index 99c9d923151..5e9b9509abb 100644 --- a/10/umbraco-forms/developer/themes.md +++ b/10/umbraco-forms/developer/themes.md @@ -21,7 +21,7 @@ Umbraco 10+ distributes these files as part of a Razor class library, so you won You can obtain the latest version of the default theme Forms 10 from the following link: -* [Forms 10 Default Theme](https://umbra.co/umbraco-forms-default-theme) (for 10.5.5 and above) +* [Forms 10 Default Theme](https://umbra.co/umbraco-forms-default-theme) (for 10.5.6 and above) If you are using a lower minor version of Forms than those listed, you should download an older version of the default theme. diff --git a/10/umbraco-forms/release-notes.md b/10/umbraco-forms/release-notes.md index 4419c43acbb..d85522ed22c 100644 --- a/10/umbraco-forms/release-notes.md +++ b/10/umbraco-forms/release-notes.md @@ -21,6 +21,13 @@ This section contains the release notes for Umbraco Forms 8 and 10 including all Version 10 +[**10.5.6**](https://github.com/umbraco/Umbraco.Forms.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F10.5.6) **(July 9th 2024)** + +* Fixed issue with save button UI, when save is canceled via a notification [#1219](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1219). +* Improved date format for data values when using the **Send email** workflow [#1214](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1214). +* Removed unnecessary circular checks for conditions on workflows resolving an issue where workflow would trigger when conditions were not met [#1206](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1206). +* Fixed console error with blank values in data picker fields [#1241](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1241). + [**10.5.5**](https://github.com/umbraco/Umbraco.Forms.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F10.5.5) **(April 16th 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). diff --git a/12/umbraco-forms/developer/extending/adding-a-fieldtype.md b/12/umbraco-forms/developer/extending/adding-a-fieldtype.md index 424abd7abb1..655fa56e2e3 100644 --- a/12/umbraco-forms/developer/extending/adding-a-fieldtype.md +++ b/12/umbraco-forms/developer/extending/adding-a-fieldtype.md @@ -165,7 +165,7 @@ To reference the file the setting should be configured with a full path to the v [Setting("My Setting", Description = "Help text for the setting", View = "~/App_Plugins/UmbracoFormsCustomFields/backoffice/Common/SettingTypes/mycustomsettingfield.html", - SupportsPlaceholders = "true" + SupportsPlaceholders = true DisplayOrder = 10)] public virtual string MySetting { get; set; } ``` diff --git a/13/umbraco-forms/.gitbook/assets/umbraco_forms_swagger.json b/13/umbraco-forms/.gitbook/assets/umbraco_forms_swagger.json index 72ab43653f3..2e77da8be31 100644 --- a/13/umbraco-forms/.gitbook/assets/umbraco_forms_swagger.json +++ b/13/umbraco-forms/.gitbook/assets/umbraco_forms_swagger.json @@ -37,11 +37,22 @@ "schema": { "type": "string" } + }, + { + "name": "additionalData", + "in": "query", + "description": "Additional data provided when rendering the form.", + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } } ], "responses": { "200": { - "description": "Success", + "description": "OK", "content": { "application/json": { "schema": { @@ -124,7 +135,7 @@ } }, "422": { - "description": "Client Error", + "description": "Unprocessable Content", "content": { "application/json": { "schema": { @@ -144,16 +155,14 @@ "Show", "Hide" ], - "type": "integer", - "format": "int32" + "type": "string" }, "FieldConditionLogicType": { "enum": [ "All", "Any" ], - "type": "integer", - "format": "int32" + "type": "string" }, "FieldConditionRuleOperator": { "enum": [ @@ -162,11 +171,19 @@ "GreaterThen", "LessThen", "Contains", + "ContainsIgnoreCase", "StartsWith", - "EndsWith" + "StartsWithIgnoreCase", + "EndsWith", + "EndsWithIgnoreCase", + "NotContains", + "NotContainsIgnoreCase", + "NotStartsWith", + "NotStartsWithIgnoreCase", + "NotEndsWith", + "NotEndsWithIgnoreCase" ], - "type": "integer", - "format": "int32" + "type": "string" }, "FormConditionDto": { "type": "object", @@ -285,6 +302,13 @@ "culture": { "type": "string", "nullable": true + }, + "additionalData": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "nullable": true } }, "additionalProperties": false @@ -305,7 +329,8 @@ }, "placeholder": { "type": "string", - "nullable": true + "nullable": true, + "deprecated": true }, "cssClass": { "type": "string", @@ -359,8 +384,7 @@ "MarkMandatoryFields", "MarkOptionalFields" ], - "type": "integer", - "format": "int32" + "type": "string" }, "FormFieldPrevalueDto": { "type": "object", diff --git a/13/umbraco-forms/developer/ajaxforms.md b/13/umbraco-forms/developer/ajaxforms.md index cfaae9dde4b..560a7f3d41a 100644 --- a/13/umbraco-forms/developer/ajaxforms.md +++ b/13/umbraco-forms/developer/ajaxforms.md @@ -43,7 +43,7 @@ The Open API specification is available from: `/umbraco/swagger/forms/swagger.js To request the definition of a form, the following request can be made: ```none -GET /umbraco/forms/api/v1/definitions/{id}?contentId={contentId}&culture={culture} +GET /umbraco/forms/api/v1/definitions/{id}?contentId={contentId}&culture={culture}&additionalData[{key}]={value}&additionalData[key2]={value2} ``` The GET request requires the Guid identifying the form. @@ -52,6 +52,8 @@ An optional `contentId` parameter can be provided, which can either be the integ A `culture` parameter can also be provided, expected as an ISO code identifying a language used in the Umbraco installation (for example, `en-US`). This will be used to ensure the correct translation for dictionary keys is used. It will also retrieve page content from the appropriate language variant. If the parameter is not provided in the request, the default Umbraco language will be used. +Finally, an `additionalData` parameter can be provided as a dictionary. This information will be made available when rendering the form allowing it to be used as a source for ["magic string" replacements](./magic-strings.md). + If the requested form is not found, a 404 status code will be returned. A successful request will return a 200 status code. An example response is as follows. It will differ depending on the pages, fields and other settings available for the form. @@ -398,7 +400,11 @@ It also requires a `Content-Type` header of `application/json` and accepts a bod "dataConsent": "on" }, "contentId": "ca4249ed-2b23-4337-b522-63cabe5587d1", - "culture": "en-US" + "culture": "en-US", + "additionalData": { + "foo": "bar", + "baz": "buzz", + } } ``` @@ -406,6 +412,8 @@ The `values` collection consists of a set of name/value pairs, where the name is The `contentId` and `culture` parameters are optional. If provided they will be used to customize the response for the current page and language respectively. +Similarly, the `additionalData` dictionary is optional. This data is associated with the created record and made available within workflows. + In the case of a validation error, a 422 "Unprocessable Entity" status code will be returned, along with a response similar to the following: ```json diff --git a/13/umbraco-forms/developer/configuration/type-details.md b/13/umbraco-forms/developer/configuration/type-details.md index 0ad7a1f35bc..723648393c3 100644 --- a/13/umbraco-forms/developer/configuration/type-details.md +++ b/13/umbraco-forms/developer/configuration/type-details.md @@ -130,6 +130,7 @@ The intention is to be able to make available details such as IDs, aliases and p **Settings:** +* `DisplayLayout` * `DefaultValue` * `ShowLabel` @@ -206,6 +207,7 @@ The intention is to be able to make available details such as IDs, aliases and p **Settings:** +* `DisplayLayout` * `DefaultValue` * `ShowLabel` diff --git a/13/umbraco-forms/developer/extending/adding-a-fieldtype.md b/13/umbraco-forms/developer/extending/adding-a-fieldtype.md index 424abd7abb1..7821eecf05c 100644 --- a/13/umbraco-forms/developer/extending/adding-a-fieldtype.md +++ b/13/umbraco-forms/developer/extending/adding-a-fieldtype.md @@ -165,7 +165,7 @@ To reference the file the setting should be configured with a full path to the v [Setting("My Setting", Description = "Help text for the setting", View = "~/App_Plugins/UmbracoFormsCustomFields/backoffice/Common/SettingTypes/mycustomsettingfield.html", - SupportsPlaceholders = "true" + SupportsPlaceholders = true, DisplayOrder = 10)] public virtual string MySetting { get; set; } ``` @@ -174,6 +174,8 @@ public virtual string MySetting { get; set; } `HtmlEncodeReplacedPlaceholderValues` takes effect only if `SupportsPlaceholders` is `true`. It controls whether the replaced placeholder values should be HTML encoded (as is necessary for rendering within content from a rich text editor). +`SupportsHtml` is a flag indicating whether the setting can contain HTML content. When set to `true` it will be treated as HTML content when the value is read from the Forms delivery API. + `IsMandatory` if set to `true` will provide client-side validation in the backoffice to ensure the value is completed. ### Settings when inheriting diff --git a/13/umbraco-forms/developer/extending/setting-types.md b/13/umbraco-forms/developer/extending/setting-types.md index add989cbd80..67bca9efa8b 100644 --- a/13/umbraco-forms/developer/extending/setting-types.md +++ b/13/umbraco-forms/developer/extending/setting-types.md @@ -20,11 +20,12 @@ The following setting types are available and are used for the field, prevalue s | Name | Description | Used in | |---------------------------|-------------------------------------------------------------------|-------------------------------------------------| | Checkbox | Uses a single checkbox for entry | | -| DocumentMapper | Used for selection of a documenttype | The "Save as Umbraco node" workflow | +| DocumentMapper | Used for selection of a documenttype | The "Save as Umbraco node" workflow | | Dropdownlist | Used for selection from a list of options | | | EmailTemplatePicker | Used for selection of an email template | The "Send email with Razor template" workflow | | FieldMapper | Used to map fields from a form to required aliases | The "Send to URL" workflow | | File | Used for selection of a file | The "Send email with XSLT template" workflow | +| MultipleTextString | Uses multiple text boxes for entry | Not used in core types | | NumericField | Uses numerical text box for entry | | | Password | Uses password text box for entry | | | PasswordNoAutocomplete | Uses password text box for entry (with autocomplete disabled) | | @@ -38,7 +39,6 @@ The following setting types are available and are used for the field, prevalue s | Textfield | Used a single-line textbox for entry | | | TextfieldNoAutocomplete | Used a single-line textbox for entry (with autocomplete disabled) | | | TextWithFieldPicker | Used a single-line textbox/form field list for entry | Not used in core types | -| MultipleTextString | Used multiple textboxes for multiple entries | Not used in core types | All of the above setting types are used in one or more field, prevalue source and workflow types available with Umbraco Forms. For the less common ones, a usage has been indicated in the table. diff --git a/13/umbraco-forms/developer/magic-strings.md b/13/umbraco-forms/developer/magic-strings.md index 4ab8372d881..04f5128c2ee 100644 --- a/13/umbraco-forms/developer/magic-strings.md +++ b/13/umbraco-forms/developer/magic-strings.md @@ -50,6 +50,12 @@ Some extra variables are: `[$myRecursiveItem]` this allows you to parse the Umbraco Document Type property myRecursiveItem. So if the current page does not contain a value for this then it will request it from the parent up until the root or until it finds a value. +### Additional data + +When rendering a form, additional data can be provided in the form of a dictionary. As well as being associated with the created record and available within workflows, they can be used for "magic string" replacements. + +They are accessed using this syntax: `[+additionalDataKey]`. + ### Umbraco Form field `{myAliasForFormField}` this allows you to display the entered value for that specific field from the form submission. Used in workflows to send an automated email back to the customer based on the email address submitted in the form. The value here needs to be the alias of the field, and not the name of the field. @@ -82,16 +88,17 @@ For example, to truncate a string value read from an Umbraco page field with ali Umbraco Forms ships with the following filters: -| Filter | Function | Arguments | Example | -| ----------------------------- | ---------- | -------------------- | ------------------------------------ | -| Bound a number | `bound` | min and max bound | `[#field \| bound: 1: 10]` | -| Convert string to lower case | `lower` | | `[#field \| lower]` | -| Convert string to upper case | `upper` | | `[#field \| upper]` | -| Truncate a string | `truncate` | number of characters | `[#field \| truncate: 10]` | -| Format a number | `number` | format string | `[#field \| number: #0.##%]` | -| Format a number as a currency | `currency` | | `[#field \| currency]` | -| Format a date | `date` | format string | `[#field \| date: dd-MM-yyyy HH:mm]` | -| HTML encode a string | `html` | | `[#field \| html]` | +| Filter | Function | Arguments | Example | +| ------------------------------------------------ | ----------------------- | -------------------- | ---------------------------------------------------- | +| Bound a number | `bound` | min and max bound | `[#field \| bound: 1: 10]` | +| Convert string to lower case | `lower` | | `[#field \| lower]` | +| Convert string to upper case | `upper` | | `[#field \| upper]` | +| Format a number | `number` | format string | `[#field \| number: #0.##%]` | +| Format a number as a currency | `currency` | | `[#field \| currency]` | +| Format a date | `date` | format string | `[#field \| date: dd-MM-yyyy HH:mm]` | +| HTML encode a string | `html` | | `[#field \| html]` | +| Truncate a string | `truncate` | number of characters | `[#field \| truncate: 10]` | + The format strings used for formatting dates and numbers are the standard or custom .NET [date](https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings) and [numeric](https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-numeric-format-strings) format strings respectively. diff --git a/13/umbraco-forms/developer/rendering-forms.md b/13/umbraco-forms/developer/rendering-forms.md index 552310534fd..77f17bb3060 100644 --- a/13/umbraco-forms/developer/rendering-forms.md +++ b/13/umbraco-forms/developer/rendering-forms.md @@ -14,18 +14,20 @@ To display a form in your view, you can make a call to a view component: @await Component.InvokeAsync("RenderForm", new { formId = Guid.Parse("
"), theme = "default", includeScripts = false }) ``` -Five parameters can be provided: +Six parameters can be provided: - `formId` is the GUID of a form. - `theme` is the name of a theme. If not provided, the default theme is used (see [Themes](./themes.md)). - `includeScripts` indicates whether scripts should be rendered with the form (see [Rendering Scripts](./rendering-scripts.md). - `recordId` is an optional existing record GUID, used if editing records via the website is [enabled in configuration](../developer/configuration/README.md#alloweditableformsubmissions) - `redirectToPageId` is an optional GUID for a content page that, if provided, is redirected to once the form has been submitted. It will be used in preference to post-submission behavior defined on the form itself. +- `additionalData` is an optional dictionary of string values. When provided it will be used as a source for ["magic string" replacements](./magic-strings.md). The data will be associated with the created record and made available for custom logic or update within workflows. Usually, rather than hard-coding the form's GUID and other details, you'll use a form, theme or content picker on your page: ```csharp -@await Component.InvokeAsync("RenderForm", new { formId = @Model.Form, theme = @Model.Theme, includeScripts = false }) +var additionalData = new Dictionary { { "foo", "bar" }, { "buzz", "baz" } }; +@await Component.InvokeAsync("RenderForm", new { formId = @Model.Form, theme = @Model.Theme, includeScripts = false, additionalData }) ``` ## Rendering Using a Tag Helper @@ -43,7 +45,8 @@ Then in your view you can use: ```csharp @if (Model.Form.HasValue) { - + var additionalData = new Dictionary { { "foo", "bar" }, { "buzz", "baz" } }; + } ``` diff --git a/13/umbraco-forms/release-notes.md b/13/umbraco-forms/release-notes.md index 448d863e8e9..98c635eb605 100644 --- a/13/umbraco-forms/release-notes.md +++ b/13/umbraco-forms/release-notes.md @@ -17,6 +17,30 @@ 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.2.0-rc1**](https://github.com/umbraco/Umbraco.Forms.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F13.2.0) **(July 9th 2024)** + +* Added setting option for single and multiple choice fields to allow for vertical or horizontal display [#1218](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1218). +* Added new setting type for multiple text strings [#1217](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1217) +* Added validation to prevent users defining an email workflow that allows the form's sender email to be defined as that entered by the user [#1210](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1210). +* Allowed for the provision of additional data when rendering and submitting forms. When provided it will be used as a source for ["magic string" replacements](./magic-strings.md). The data will be associated with the created record and made available for custom logic and update within workflows. [#578](https://github.com/umbraco/Umbraco.Forms.Issues/issues/578). +* Added details of workflow type to edit workflow dialog [#1183](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1183). +* Removed an inline prevalue editor that wasn't functional but could surface it's UI when creating forms from templates [#1230](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1230). +* Ensured local links are parsed when HTML fields are returned in the delivery API results for form definitions [#1227](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1227). +* Resolved duplicate approval occurring when the record is approved via a workflow [#1223](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1223). +* Updated themes such that accessibility is improved by having hidden labels remain in markup but be visually hidden [#1220](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1220). +* Fixed issue with save button UI, when save is canceled via a notification [#1219](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1219). +* Improved date format for data values when using the **Send email** workflow [#1214](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1214). +* Removed unnecessary circular checks for conditions on workflows resolving an issue where workflow would trigger when conditions were not met [#1206](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1206). +* Added setting option for the "send to URL" workflow to switch between caption and alias for the field value's XML element [#1202](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1202) +* Allowed for use of prevalue sources that customize based on the current form or field in backoffice editing and preview [#1221](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1221). +* Restored target used to generate local configuration schema information [#1226](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1226). +* Fixed issues with retrieving fields and assigning default values when using the datasource wizard. +* Ensured links to Umbraco pages within rich text fields used for emails are correctly parsed [#1208](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1208). +* Added body rich text field for send email with Razor template workflow [#1198](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1198). +* Fixed console error with blank values in the date picker field [#1241](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1241). +* Ensured placeholders are parsed for accepted entry response from the delivery API [#1238](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1238). +* Improved support for editing large, multi-page forms by retaining scroll position between views and adding a "jump to page" option [#1243](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1243). + #### [**13.1.2**](https://github.com/umbraco/Umbraco.Forms.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F12.2.4) **(April 16th 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). diff --git a/14/umbraco-forms/.gitbook/assets/umbraco_forms_swagger.json b/14/umbraco-forms/.gitbook/assets/umbraco_forms_swagger.json index f86212a522e..360a0c02bf4 100644 --- a/14/umbraco-forms/.gitbook/assets/umbraco_forms_swagger.json +++ b/14/umbraco-forms/.gitbook/assets/umbraco_forms_swagger.json @@ -37,6 +37,17 @@ "schema": { "type": "string" } + }, + { + "name": "additionalData", + "in": "query", + "description": "Additional data provided when rendering the form.", + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } } ], "responses": { @@ -285,6 +296,13 @@ "culture": { "type": "string", "nullable": true + }, + "additionalData": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "nullable": true } }, "additionalProperties": false diff --git a/14/umbraco-forms/developer/ajaxforms.md b/14/umbraco-forms/developer/ajaxforms.md index 83a008b0e95..ba1e678dab6 100644 --- a/14/umbraco-forms/developer/ajaxforms.md +++ b/14/umbraco-forms/developer/ajaxforms.md @@ -43,7 +43,7 @@ The Open API specification is available from: `/umbraco/swagger/forms/swagger.js To request the definition of a form, the following request can be made: ```none -GET /umbraco/forms/delivery/api/v1/definitions/{id}?contentId={contentId}&culture={culture} +GET /umbraco/forms/delivery/api/v1/definitions/{id}?contentId={contentId}&culture={culture}&additionalData[{key}]={value}&additionalData[key2]={value2} ``` The GET request requires the Guid identifying the form. @@ -52,6 +52,8 @@ An optional `contentId` parameter can be provided, which can either be the integ A `culture` parameter can also be provided, expected as an ISO code identifying a language used in the Umbraco installation (for example, `en-US`). This will be used to ensure the correct translation for dictionary keys is used. It will also retrieve page content from the appropriate language variant. If the parameter is not provided in the request, the default Umbraco language will be used. +Finally, an `additionalData` parameter can be provided as a dictionary. This information will be made available when rendering the form allowing it to be used as a source for ["magic string" replacements](./magic-strings.md). + If the requested form is not found, a 404 status code will be returned. A successful request will return a 200 status code. An example response is as follows. It will differ depending on the pages, fields and other settings available for the form. @@ -398,7 +400,11 @@ It also requires a `Content-Type` header of `application/json` and accepts a bod "dataConsent": "on" }, "contentId": "ca4249ed-2b23-4337-b522-63cabe5587d1", - "culture": "en-US" + "culture": "en-US", + "additionalData": { + "foo": "bar", + "baz": "buzz", + } } ``` @@ -406,6 +412,8 @@ The `values` collection consists of a set of name/value pairs, where the name is The `contentId` and `culture` parameters are optional. If provided they will be used to customize the response for the current page and language respectively. +Similarly the `additionalData` dictionary is optional. This data is associated with the created record and made available within workflows. + In the case of a validation error, a 422 "Unprocessable Entity" status code will be returned, along with a response similar to the following: ```json diff --git a/14/umbraco-forms/developer/configuration/type-details.md b/14/umbraco-forms/developer/configuration/type-details.md index 0ad7a1f35bc..723648393c3 100644 --- a/14/umbraco-forms/developer/configuration/type-details.md +++ b/14/umbraco-forms/developer/configuration/type-details.md @@ -130,6 +130,7 @@ The intention is to be able to make available details such as IDs, aliases and p **Settings:** +* `DisplayLayout` * `DefaultValue` * `ShowLabel` @@ -206,6 +207,7 @@ The intention is to be able to make available details such as IDs, aliases and p **Settings:** +* `DisplayLayout` * `DefaultValue` * `ShowLabel` diff --git a/14/umbraco-forms/developer/extending/adding-a-fieldtype.md b/14/umbraco-forms/developer/extending/adding-a-fieldtype.md index 27d0311a728..67f93506c49 100644 --- a/14/umbraco-forms/developer/extending/adding-a-fieldtype.md +++ b/14/umbraco-forms/developer/extending/adding-a-fieldtype.md @@ -142,6 +142,8 @@ The `View` property indicates a property editor UI used for editing the setting `HtmlEncodeReplacedPlaceholderValues` takes effect only if `SupportsPlaceholders` is `true`. It controls whether the replaced placeholder values should be HTML encoded (as is necessary for rendering within content from a rich text editor). +`SupportsHtml` is a flag indicating whether the setting can contain HTML content. When set to `true` it will be treated as HTML content when the value is read from the Forms delivery API. + `IsMandatory` if set to `true` will provide client-side validation in the backoffice to ensure the value is completed. When creating a field or other provider type, you might choose to inherit from an existing class. This could be if one of the types provided with Umbraco Forms almost meets your needs but you want to make some changes. diff --git a/14/umbraco-forms/developer/extending/setting-types.md b/14/umbraco-forms/developer/extending/setting-types.md index 41504f56c12..6bfc825fa49 100644 --- a/14/umbraco-forms/developer/extending/setting-types.md +++ b/14/umbraco-forms/developer/extending/setting-types.md @@ -6,42 +6,47 @@ These settings are completed by the editor when using the type on their form. Each setting type can have it's own user interface. So a string can use a text box but a more complicated JSON structure can use a more appropriate user interface. +From Forms 14, each interface is defined as an Umbraco [property editor UI](https://docs.umbraco.com/umbraco-cms/extending/property-editors/composition/property-editor-ui). + The user interface used for a particular setting is defined by the `View` property: ```csharp -[Umbraco.Forms.Core.Attributes.Setting("Message", View = "TextField")] +[Umbraco.Forms.Core.Attributes.Setting("Message", View = "Umb.PropertyEditorUi.TextBox")] public string Message { get; set; } ``` +If not specified, the default `Umb.PropertyEditorUi.TextBox` is used. + ## Built-in setting types The following setting types are available and are used for the field, prevalue source and workflow types that ship with the package. -| Name | Description | Used in | -|---------------------------|-------------------------------------------------------------------|-------------------------------------------------| -| Checkbox | Uses a single checkbox for entry | | -| DocumentMapper | Used for selection of a documenttype | The "Save as Umbraco node" workflow | -| Dropdownlist | Used for selection from a list of options | | -| EmailTemplatePicker | Used for selection of an email template | The "Send email with Razor template" workflow | -| FieldMapper | Used to map fields from a form to required aliases | The "Send to URL" workflow | -| File | Used for selection of a file | The "Send email with XSLT template" workflow | -| NumericField | Uses numerical text box for entry | | -| Password | Uses password text box for entry | | -| PasswordNoAutocomplete | Uses password text box for entry (with autocomplete disabled) | | -| Pickers.ContentWithXPath | Uses a content picker with the option for XPath entry | The "Save as Umbraco node" workflow | -| Pickers.Datatype | Uses a datatype picker | The "Umbraco prevalues" prevalue source | -| Pickers.DocumentType | Uses a document picker | The "Umbraco nodes" prevalue source | -| Range | Uses a slider for range input | The "reCAPTCHAv3" field type | -| RichText | Uses a rich text editor for input | The "Send email" workflows | -| StandardFieldMapper | Used to map system fields from a form to required aliases | The "Send to URL" workflow | -| Textarea | Used a multiline textbox for entry | | -| Textfield | Used a single-line textbox for entry | | -| TextfieldNoAutocomplete | Used a single-line textbox for entry (with autocomplete disabled) | | -| TextWithFieldPicker | Used a single-line textbox/form field list for entry | Not used in core types | +Some are defined with the Umbraco CMS and some ship with the Forms package. + +| Name | Source | Description | Used in | +|--------------------------------------------------|--------------|-------------------------------------------------------------------|-------------------------------------------------| +| Umb.PropertyEditorUi.ContentPicker.Source | CMS | Uses a content picker with the option for XPath entry | The "Save as Umbraco node" workflow | +| Umb.PropertyEditorUi.Dropdown | CMS | Used for selection from a list of options | | +| Umb.PropertyEditorUi.Integer | CMS | Uses numerical text box for entry | | +| Umb.PropertyEditorUi.MultipleTextString | CMS | Uses multiple text boxes for entry | Not used in core types | +| Umb.PropertyEditorUi.Slider | CMS | Uses a slider for range input | The "reCAPTCHAv3" field type | +| Umb.PropertyEditorUi.TextArea | CMS | Uses a multiline textbox for entry | | +| Umb.PropertyEditorUi.TextBox | CMS | Uses a single-line textbox for entry | | +| Umb.PropertyEditorUi.TinyMCE | CMS | Uses a rich text editor for input | The "Send email" workflows | +| Umb.PropertyEditorUi.Toggle | CMS | Uses a single checkbox for entry | | +| Umb.PropertyEditorUi.UploadField | CMS | Used for selection of a file | The "Send email with XSLT template" workflow | +| Forms.PropertyEditorUi.DataTypePicker | Forms | Uses a datatype picker | The "Umbraco prevalues" prevalue source | +| Forms.PropertyEditorUi.DocumentTypePicker | Forms | Uses a document picker | The "Umbraco nodes" prevalue source | +| Forms.PropertyEditorUi.DocumentMapper | Forms | Used for selection of a documenttype | The "Save as Umbraco node" workflow | +| Forms.PropertyEditorUi.EmailTemplatePicker | Forms | Used for selection of an email template | The "Send email with Razor template" workflow | +| Forms.PropertyEditorUi.FieldMapper | Forms | Used to map fields from a form to required aliases | The "Send to URL" workflow | +| Forms.PropertyEditorUi.Password | Forms | Uses password text box for entry | | +| Forms.PropertyEditorUi.StandardFieldMapper | Forms | Used to map system fields from a form to required aliases | The "Send to URL" workflow | +| Forms.PropertyEditorUi.TextWithFieldPicker | Forms | Uses a single-line textbox/form field list for entry | Not used in core types | All of the above setting types are used in one or more field, prevalue source and workflow types available with Umbraco Forms. For the less common ones, a usage has been indicated in the table. -The one exception is the "TextWithFieldPicker". This one we don't use within the package, but we make it available for developers to use when creating their own types. +The one exception is `Forms.PropertyEditorUi.TextWithFieldPicker`. This one we don't use within the package, but we make it available for developers to use when creating their own types. It offers the option of text field entry or the selection of a field from the form. This can be useful in workflows where you need to reference the value of a specific field. diff --git a/14/umbraco-forms/developer/magic-strings.md b/14/umbraco-forms/developer/magic-strings.md index 4ab8372d881..984580e8125 100644 --- a/14/umbraco-forms/developer/magic-strings.md +++ b/14/umbraco-forms/developer/magic-strings.md @@ -50,6 +50,12 @@ Some extra variables are: `[$myRecursiveItem]` this allows you to parse the Umbraco Document Type property myRecursiveItem. So if the current page does not contain a value for this then it will request it from the parent up until the root or until it finds a value. +### Additional data + +When rendering a form, additional data can be provided in the form of a dictionary. As well as being associated with the created record and available within workflows, they can be used for "magic string" replacements. + +They are accessed using this syntax: `[+additionalDataKey]`. + ### Umbraco Form field `{myAliasForFormField}` this allows you to display the entered value for that specific field from the form submission. Used in workflows to send an automated email back to the customer based on the email address submitted in the form. The value here needs to be the alias of the field, and not the name of the field. @@ -82,16 +88,16 @@ For example, to truncate a string value read from an Umbraco page field with ali Umbraco Forms ships with the following filters: -| Filter | Function | Arguments | Example | -| ----------------------------- | ---------- | -------------------- | ------------------------------------ | -| Bound a number | `bound` | min and max bound | `[#field \| bound: 1: 10]` | -| Convert string to lower case | `lower` | | `[#field \| lower]` | -| Convert string to upper case | `upper` | | `[#field \| upper]` | -| Truncate a string | `truncate` | number of characters | `[#field \| truncate: 10]` | -| Format a number | `number` | format string | `[#field \| number: #0.##%]` | -| Format a number as a currency | `currency` | | `[#field \| currency]` | -| Format a date | `date` | format string | `[#field \| date: dd-MM-yyyy HH:mm]` | -| HTML encode a string | `html` | | `[#field \| html]` | +| Filter | Function | Arguments | Example | +| ------------------------------------------------ | ----------------------- | -------------------- | ---------------------------------------------------- | +| Bound a number | `bound` | min and max bound | `[#field \| bound: 1: 10]` | +| Convert string to lower case | `lower` | | `[#field \| lower]` | +| Convert string to upper case | `upper` | | `[#field \| upper]` | +| Format a number | `number` | format string | `[#field \| number: #0.##%]` | +| Format a number as a currency | `currency` | | `[#field \| currency]` | +| Format a date | `date` | format string | `[#field \| date: dd-MM-yyyy HH:mm]` | +| HTML encode a string | `html` | | `[#field \| html]` | +| Truncate a string | `truncate` | number of characters | `[#field \| truncate: 10]` | The format strings used for formatting dates and numbers are the standard or custom .NET [date](https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings) and [numeric](https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-numeric-format-strings) format strings respectively. diff --git a/14/umbraco-forms/developer/rendering-forms.md b/14/umbraco-forms/developer/rendering-forms.md index 552310534fd..77f17bb3060 100644 --- a/14/umbraco-forms/developer/rendering-forms.md +++ b/14/umbraco-forms/developer/rendering-forms.md @@ -14,18 +14,20 @@ To display a form in your view, you can make a call to a view component: @await Component.InvokeAsync("RenderForm", new { formId = Guid.Parse(""), theme = "default", includeScripts = false }) ``` -Five parameters can be provided: +Six parameters can be provided: - `formId` is the GUID of a form. - `theme` is the name of a theme. If not provided, the default theme is used (see [Themes](./themes.md)). - `includeScripts` indicates whether scripts should be rendered with the form (see [Rendering Scripts](./rendering-scripts.md). - `recordId` is an optional existing record GUID, used if editing records via the website is [enabled in configuration](../developer/configuration/README.md#alloweditableformsubmissions) - `redirectToPageId` is an optional GUID for a content page that, if provided, is redirected to once the form has been submitted. It will be used in preference to post-submission behavior defined on the form itself. +- `additionalData` is an optional dictionary of string values. When provided it will be used as a source for ["magic string" replacements](./magic-strings.md). The data will be associated with the created record and made available for custom logic or update within workflows. Usually, rather than hard-coding the form's GUID and other details, you'll use a form, theme or content picker on your page: ```csharp -@await Component.InvokeAsync("RenderForm", new { formId = @Model.Form, theme = @Model.Theme, includeScripts = false }) +var additionalData = new Dictionary { { "foo", "bar" }, { "buzz", "baz" } }; +@await Component.InvokeAsync("RenderForm", new { formId = @Model.Form, theme = @Model.Theme, includeScripts = false, additionalData }) ``` ## Rendering Using a Tag Helper @@ -43,7 +45,8 @@ Then in your view you can use: ```csharp @if (Model.Form.HasValue) { - + var additionalData = new Dictionary { { "foo", "bar" }, { "buzz", "baz" } }; + } ``` diff --git a/14/umbraco-forms/release-notes.md b/14/umbraco-forms/release-notes.md index cb5e6780603..68ae2f6d69c 100644 --- a/14/umbraco-forms/release-notes.md +++ b/14/umbraco-forms/release-notes.md @@ -17,11 +17,29 @@ If you are upgrading to a new major version, you can find information about the This section contains the release notes for Umbraco Forms 14 including all changes for this version. +#### [**14.1.0-rc1**](https://github.com/umbraco/Umbraco.Forms.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F14.1.0) **(July 9th 2024)** + +* Added setting option for single and multiple choice fields to allow for vertical or horizontal display [#1218](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1218) +* Added new setting type for multiple text strings [#1217](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1217) +* Added validation to prevent users defining an email workflow that allows the form's sender email to be defined as that entered by the user [#1210](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1210) +* Allowed for the provision of additional data when rendering and submitting forms. When provided it will be used as a source for ["magic string" replacements](./magic-strings.md). The data will be associated with the created record and made available for custom logic and update within workflows. [#578](https://github.com/umbraco/Umbraco.Forms.Issues/issues/578) +* Added details of workflow type to edit workflow dialog [#1183](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1183) +* Allowed for use of prevalue sources that customize based on the current form or field in backoffice editing and preview [#1221](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1221) +* Ensured links to Umbraco pages within rich text fields used for emails are correctly parsed [#1208](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1208). +* Added body rich text field for send email with Razor template workflow [#1198](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1198). +* Fixed console error with blank values in the date picker field [#1241](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1241). +* Ensured placeholders are parsed for accepted entry response from the delivery API [#1238](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1238). +* Resolved issues with intermittent failures of the form entries table display [#1239](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1239). + +#### [**14.0.2**](https://github.com/umbraco/Umbraco.Forms.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F14.0.2) **(June 11th 2024)** + +* Fixed issue with upload of text file for the prevalue source based on file contents. + #### [**14.0.1**](https://github.com/umbraco/Umbraco.Forms.Issues/issues?q=is%3Aissue+is%3Aclosed+label%3Arelease%2F14.0.1) **(June 6th 2024)** * Ensured local links are parsed when HTML fields are returned in the delivery API results for form definitions [#1227](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1227). * Restored target used to generate local configuration schema information [#1226](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1226). -* Resolved duplicate approval occuring when record is approved via a workflow [#1223](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1223). +* Resolved duplicate approval occurring when the record is approved via a workflow [#1223](https://github.com/umbraco/Umbraco.Forms.Issues/issues/1223). * Added some missing localization keys and translations. * Fixed description of management API on Swagger UI. * Fixed display of specific form access list for user and group security.